juice_routing library

Declarative, state-driven navigation for Juice applications.

juice_routing provides Navigator 2.0 integration with route guards, deep linking support, and automatic scope management.

Quick Start

// 1. Define routes
final config = RoutingConfig(
  routes: [
    RouteConfig(
      path: '/',
      builder: (ctx) => HomeScreen(),
    ),
    RouteConfig(
      path: '/profile/:userId',
      builder: (ctx) => ProfileScreen(userId: ctx.params['userId']!),
      guards: [AuthGuard()],
    ),
  ],
);

// 2. Register and initialize
BlocScope.register<RoutingBloc>(
  () => RoutingBloc(),
  lifecycle: BlocLifecycle.permanent,
);
final routingBloc = BlocScope.get<RoutingBloc>();
routingBloc.send(InitializeRoutingEvent(config: config));

// 3. Use with MaterialApp.router
MaterialApp.router(
  routerDelegate: JuiceRouterDelegate(routingBloc: routingBloc),
  routeInformationParser: const JuiceRouteInformationParser(),
);

// 4. Navigate
routingBloc.navigate('/profile/123');

Contract Guarantees

  • Atomicity: Navigation either commits fully or not at all
  • Concurrency: One pending navigation; new ones queue (latest wins)
  • Redirect cap: Max 5 redirects before RedirectLoopError
  • Guard errors: Exception → GuardExceptionError, navigation aborted
  • Pop behavior: Pop events bypass guards, execute immediately

Classes

AllowResult
Navigation is allowed to proceed.
AuthGuard
Built-in guard that redirects unauthenticated users to a login path.
BlockResult
Navigation is blocked.
GuardResult
Result of a guard check.
GuestGuard
Built-in guard that redirects authenticated users away from guest-only pages (e.g., login, register).
HistoryEntry
Entry in navigation history
InitializeRoutingEvent
Initialize the routing system with configuration.
JuiceNavigatorObserver
Navigator observer that tracks route visibility for time-on-route metrics.
JuiceRouteInformationParser
Route information parser for Navigator 2.0.
JuiceRouterDelegate
Router delegate for Navigator 2.0 integration.
Navigate to a new path.
PathResolver
Resolves URL paths to route configurations.
PendingNavigation
Tracks pending navigation state during guard execution
PopEvent
Pop the current route from the stack.
PopToRootEvent
Pop all routes except the root.
PopUntilEvent
Pop routes until a condition is met.
RedirectResult
Navigation should redirect to a different path.
ResetStackEvent
Reset the entire stack to a single new route.
ResolvedRoute
Result of resolving a path to a route.
RoleGuard
Built-in guard that blocks users who lack a required role.
RouteBuildContext
Context passed to route builders when constructing widgets.
RouteConfig
Configuration for a single route.
RouteContext
Context passed to route guards during navigation checks.
RouteGuard
Abstract base class for route guards.
RouteHiddenEvent
Notify that a route became hidden.
RoutePath
Value object representing a route path for Navigator 2.0.
RouteVisibleEvent
Notify that a route became visible.
RoutingBloc
Bloc for managing declarative, state-driven navigation.
RoutingConfig
Top-level routing configuration.
RoutingEvent
Base class for all routing events.
RoutingGroups
Rebuild groups for efficient UI updates.
RoutingState
The complete routing state.
StackEntry
An entry in the navigation stack.

Enums

Type of navigation action for history tracking
RouteTransition
Route transition animation types

Functions

generateEntryKey() → String
Generate a unique key for a stack entry

Typedefs

PageBuilder = Page Function(RouteBuildContext context, Widget child)
Builder function for custom page transitions.
RouteWidgetBuilder = Widget Function(RouteBuildContext context)
Builder function for creating route widgets.

Exceptions / Errors

CannotPopError
Thrown when attempting to pop with only one route on the stack.
GuardBlockedError
Thrown when a guard blocks navigation without redirecting.
GuardExceptionError
Thrown when a guard throws an exception during execution.
InvalidPathError
Thrown when a navigation path is malformed.
RedirectLoopError
Thrown when redirect chain exceeds maximum allowed redirects.
RouteNotFoundError
Thrown when attempting to navigate to a path that doesn't match any route.
RoutingError
Base class for all routing errors.