orbital_router 0.1.0

Flutter router integration for Orbital modules, scopes and deep links.

orbital_router

Flutter router integration for Orbital modules, scopes and navigation guards.

Imports

orbital_router exports the routing API plus the core Orbital contracts used by route declarations.

If you want the default scope runtime, import orbital_injector as well:

import 'package:orbital_injector/orbital_injector.dart';
import 'package:orbital_router/orbital_router.dart';

If you prefer a single import surface, use package:orbital/orbital.dart.

What this package contains

orbital_router connects the Orbital scope model to Flutter navigation:

• OrbitalApp.router(...)
• OrbitalModule, OrbitalPageRoute and OrbitalModuleRoute
• OrbitalRouterDelegate
• OrbitalRouteContext
• OrbitalMiddleware
• OrbitalRetentionPolicy
• OrbitalScopeFactory
• OrbitalScopeProvider and BuildContext extensions
• router debug snapshots that can be consumed by orbital_devtools

Quick start

MaterialApp.router(
  routerConfig: OrbitalApp.router(
    scopeFactory: const DefaultOrbitalScopeFactory(),
    initialUri: Uri.parse('/'),
    modules: [
      OrbitalModule(
        path: '/',
        routes: [
          OrbitalPageRoute(
            path: '/home',
            builder: (context, routeContext) => const HomePage(),
          ),
        ],
      ),
    ],
  ),
);

Route tree model

Orbital composes navigation from modules and page routes.

OrbitalModule(
  path: '/account',
  bindings: [
    OrbitalBinding.singleton<AccountService>((resolver) => AccountService()),
  ],
  routes: [
    OrbitalPageRoute(
      path: '/profile',
      builder: (context, routeContext) => const ProfilePage(),
    ),
  ],
)

Modules contribute:

• base path
• module-level bindings
• module-level middlewares
• nested pages or submodules

Pages contribute:

• page path
• page-level bindings
• page-level middlewares
• widget builder
• optional persistent scope retention rules

Async navigation UI

The router supports async transitions driven by bindings or middleware.

Use:

• asyncNavigationBuilder to build the visual loading surface
• asyncNavigationPageFactory to control the transition Page
• pageFactory for normal route pages

Precedence is:

• page
• nearest module
• app-level default

Route matching prefers more specific branches first. Static segments outrank parameterized segments; declaration order is used only as a tiebreaker.

Middleware

OrbitalMiddleware can:

• continue navigation
• block navigation
• redirect to another URI

Middlewares also expose hook points:

• onBeforeRun
• onAfterRun

Middlewares that may await must implement OrbitalAsyncMiddleware. Orbital uses that marker to decide when a branch should advertise async navigation UI.

Loading UI is controlled by asyncNavigationBuilder plus asyncNavigationPageFactory.

Route context and scope access

Pages can read route data and scope state from:

• OrbitalRouteContext
• context.orbitalRouteContext
• context.orbitalScope
• context.getOrbital<T>()

When persistentScope is enabled on a page, Orbital retains the page scope by default using path + query + fragment. Use persistentScopeKeyBuilder to override that key when retention should follow app-specific semantics.

Retention is bounded by OrbitalRetentionPolicy, configured at OrbitalApp.router(...) or OrbitalRouterDelegate(...). The default policy keeps up to 32 retained module scopes and 32 retained page scopes. When a limit is exceeded, the oldest retained scope is evicted and disposed.

OrbitalApp.router(...) also accepts:

• scopeFactory to plug a custom root scope implementation
• maxRedirects to fail fast on redirect loops

More detail

See doc.md for the complete routing lifecycle, scope creation and disposal model, async navigation behavior, middleware flow and debug snapshot integration points.