alembic 0.6.0
alembic: ^0.6.0 copied to clipboard
Declarative Navigator 2.0 navigation for Flutter. The navigation state is a list of pages, guarded by pure rules and owned by one controller.
Alembic #
Declarative Navigator 2.0 navigation for Flutter. The navigation state is a list of pages owned by one controller: every change goes through pure guard rules, and a thin widget renders it.
controller.change((state) => [...state, const SettingsPage()]);
Features #
- ✅ The navigation state is a plain
List<AlembicPage>; rewrite it and the screens follow - ✅ One owner,
AlembicController, that works and tests without widgets - ✅ Guards: pure
(from, to) => torules applied to every change, re-run by aListenable - ✅ Results:
await controller.pushForResult<bool>(page), completed bypop(result)orNavigator.pop(context, result) - ✅ Dialogs and bottom sheets as pages (
AlembicDialogPage,AlembicSheetPage) - ✅ Nested Alembics with innermost, newest-first system back handling and correct Android predictive back
- ✅ One
NotificationListenerat the root hears every navigator of the app - ✅ No Material dependency: pages build any
Route(Material, Cupertino or custom)
Getting Started #
dependencies:
alembic:
git:
url: https://github.com/gthe-miracle/alembic.git
Usage #
1. Aliases #
enum Routes implements AlembicAlias {
app('app'), // names the root Alembic
home('home'),
product('product'),
settings('settings'),
confirm('confirm'),
filters('filters');
const Routes(this.alias);
@override
final String alias;
}
2. Pages #
A page is an immutable value and also the Page given to the Navigator. Implement alias and createRoute, usually
once in a sealed base page:
@immutable
sealed class AppPage extends AlembicPage {
const AppPage({required super.child, super.arguments, super.key});
@override
Route<Object?> createRoute(BuildContext context) => AppPageRoute(this);
}
/// Material transitions from the theme. Page-based: a new page under the same key updates the screen.
final class AppPageRoute extends PageRoute<Object?> with MaterialRouteTransitionMixin<Object?> {
AppPageRoute(AppPage page) : super(settings: page);
@override
Widget buildContent(BuildContext context) => (settings as AppPage).child;
@override
bool get maintainState => true;
}
// Or Cupertino transitions with the swipe-back gesture on every platform; `title` is required by the mixin:
// final class AppPageRoute extends PageRoute<Object?> with CupertinoRouteTransitionMixin<Object?> {
// ...same as above, plus:
// @override
// String? get title => null;
// }
final class HomePage extends AppPage {
const HomePage() : super(child: const HomeScreen());
@override
AlembicAlias get alias => Routes.home;
}
final class ProductPage extends AppPage {
ProductPage(this.id) : super(child: ProductScreen(id: id));
final int id;
// Parameters kept in fields need their own key, otherwise every product is one screen.
@override
LocalKey get key => ValueKey<String>('product/$id');
@override
AlembicAlias get alias => Routes.product;
}
Without Material, AlembicPageRoute(this) is a widgets-only page-based route with a transitionsBuilder hook.
The route must be page-based: it reads (settings as AlembicPage).child on every build. A MaterialPageRoute(builder:)
captures the first child, so a new instance of the page with the same key would never reach the screen.
3. Controller and widget #
class _AppState extends State<App> {
late final AlembicController _controller = AlembicController(
[const HomePage()],
guards: const [RootGuard(HomePage()), ModalGuard()],
name: Routes.app,
);
@override
void dispose() {
_controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) => MaterialApp(
builder: (context, _) => Alembic(controller: _controller),
);
}
4. Navigate #
context.alembic is the controller of the closest Alembic:
context.alembic.push(const SettingsPage()); // a page already in the state moves to the top
context.alembic.pop(); // never removes the last page
context.alembic.popUntil(Routes.home); // to the topmost page with the alias
context.alembic.removeTag('checkout');
context.alembic.reset(); // back to the initial state, through the guards
context.alembic.change((state) => [state.first, ProductPage(1)]);
final confirmed = await context.alembic.pushForResult<bool>(const ConfirmPage());
Inside a page, the usual Navigator.maybePop(context) and Navigator.pop(context, result) work too: the controller
learns about every page the user closes.
Guards #
A guard receives the committed state from and the requested state to, and returns the state to commit. Return
to, a redirect, or from to cancel. Guards see neither the controller nor a BuildContext: they are pure rules,
testable as functions. Their dependencies go to their constructor, and revalidate re-runs them:
final controller = AlembicController(
[const HomePage()],
guards: [
const RootGuard(HomePage()),
AlembicGuard((from, to) => auth.isSignedIn ? to : [const SignInPage()]),
],
revalidate: auth, // a Listenable
);
Every change runs this pipeline:
- dedupe by key, keeping the last page;
- the guards in order;
- dedupe again.
An empty result is reported and rejected. A result equal to the current state is ignored. A guard that throws is
reported to FlutterError and skipped. A guard with state of its own implements AlembicGuard.
Built-in guards:
RootGuard(page)keeps a page at the bottom.ModalGuard()keeps dialogs and sheets above the screens.
To stop the user from closing a page, use PopScope.
Dialogs and sheets #
A modal is a page: add a mixin to it.
final class ConfirmPage extends AppPage with AlembicDialogPage {
const ConfirmPage() : super(child: const ConfirmDialog());
@override
AlembicAlias get alias => Routes.confirm;
}
final class FiltersPage extends AppPage with AlembicSheetPage {
const FiltersPage() : super(child: const FiltersSheet());
@override
AlembicAlias get alias => Routes.filters;
}
Both mixins tag the page AlembicPage.modalTag, so controller.removeTag(AlembicPage.modalTag) closes every modal at
once. Their routes are widgets-only and page-based. The mixins expose these getters:
barrierDismissiblebarrierColorbarrierLabelenableDrag,isScrollControlledanduseSafeArea(sheet only)
A sheet works like Flutter's showModalBottomSheet: it spans the width, may take the full height (isScrollControlled
is true by default; set it to false to cap the sheet at 9/16 of the height), and closes on a downward fling or when
dragged below half its height. It draws nothing itself, so its child brings the background, shape and bottom padding.
Observing navigation #
Every committed change is dispatched as an AlembicNotification that bubbles up through the outer Alembics. listener
on an Alembic hears that Alembic and every Alembic nested inside it, so listener on the root hears the whole app:
Alembic(
controller: controller,
listener: (n) => analytics.screens(n.controller.name, added: n.added, removed: n.removed),
)
controller.name tells the Alembics apart. listener never stops the notification, and an error it throws is reported
instead of breaking the listeners above.
listener is a shortcut for a NotificationListener<AlembicNotification> wrapped around the Alembic. Use the
NotificationListener directly to hear the changes from a widget above the Alembic, or to stop one by returning true.
You can also watch the state directly:
AlembicControlleris aValueListenable<List<AlembicPage>>, so it works withListenableBuilderand with code outside the widget tree.Alembic.stackOf(context)rebuilds a widget on every change.
For debug logs, Alembic.treeView draws every mounted Alembic, nested ones under their pages, each page with its
arguments as JSON and the pages on screen in green (ANSI colors):
Alembic(controller: controller, listener: (_) => log(Alembic.treeView));
app
├─ home
├─ profile {"id": 1}
└─ settings
└─ notifications
For analytics, Alembic.treeLine is the same tree on one line, without colors:
app(home, profile {"id": 1}, settings(notifications)). Read it after the frame, so the Alembic nested in a page that was
just pushed is already mounted:
listener: (_) => WidgetsBinding.instance.addPostFrameCallback((_) => analytics.log(Alembic.treeLine)),
Back button #
The system back button goes to the visible nested Alembics first, newest first, then to navigator.maybePop(). So:
- an open dialog or sheet closes first;
PopScopeis respected;- a nested Alembic with one page hands the press to its parent;
- the root page lets the platform close the app.
A nested Alembic under a covered route, or in a hidden IndexedStack tab, is skipped. The root Alembic reports one
canHandlePop for the whole tree, so Android's predictive back gesture only closes the app when nothing can go back.
Alembic(
controller: controller,
onBackButtonPressed: (navigator) async {
if (controller.state.last.tags.contains('checkout')) {
controller.popUntil(Routes.home);
return true;
}
return navigator.maybePop();
},
)
iOS swipe-back gesture #
The example has a widgets-only port of Flutter's iOS edge swipe for custom routes: copy
example/lib/src/common/cupertino_back/cupertino_back_gesture.dart and see how
example/lib/src/common/routes/custom_route_transitions.dart uses it. Routes built with
CupertinoRouteTransitionMixin always have the swipe, and those built with MaterialRouteTransitionMixin get it from
a theme that uses CupertinoPageTransitionsBuilder.
Like the back button, the swipe respects a nested Alembic: while it is visible and can pop, the route hosting it can't be
swiped away. The swipe goes to its top page, and over an open dialog or sheet it does nothing. A nested Alembic with
onBackButtonPressed doesn't block its route, since the callback may decline the press.
Core API #
AlembicPage #
| Member | Type | Description |
|---|---|---|
child |
Widget |
The content of the page |
alias |
AlembicAlias |
Required; usually an enum value |
name |
String |
alias.alias |
tags |
Set<String> |
Optional marks, used by removeTag and ModalGuard |
arguments |
Map<String, Object?> |
Optional; empty by default |
key |
LocalKey |
The given key, else name or name?a=1&b (escaped) |
createRoute() |
Route<Object?> |
Required; must be page-based |
Pages compare by identity; the controller identifies them by key.
AlembicController #
| Member | Description |
|---|---|
AlembicController(initial, …) |
guards, revalidate (Listenable), name (AlembicAlias) |
state / value |
The current pages, unmodifiable |
change(fn) |
Rewrites the state; every other method is a shortcut for it |
push(page) |
Adds a page on top, or moves its key to the top |
pushForResult<T>(page) |
Pushes and completes when the page leaves, with its result or null |
pop([result]) |
Removes the top page unless it is the last one |
remove(page, [result]) |
Removes the page with that key |
popUntil(alias) |
Removes the pages above the topmost page with the alias |
removeTag(tag) |
Removes the pages with the tag |
reset() |
Returns to the initial state, through the guards |
revalidate() |
Runs the guards on the current state again |
A change requested while another one is committed (from a listener, for example) is queued and applied after it. After 64 changes in a row the rest are reported and dropped.
Alembic #
| Parameter | Type | Description |
|---|---|---|
controller |
AlembicController |
Required |
listener |
AlembicListener? |
Changes of this Alembic and of the nested ones |
observers |
List<NavigatorObserver> |
Observers of the underlying Navigator |
transitionDelegate |
TransitionDelegate<Object?> |
Defaults to DefaultTransitionDelegate |
onBackButtonPressed |
AlembicBackHandler? |
Replaces navigator.maybePop() |
restorationScopeId |
String? |
Enables state restoration of the navigator |
reportsRouteUpdateToEngine |
bool |
Defaults to false |
Static access works as follows:
Alembic.of(context)andAlembic.maybeOf(context)return the controller, the same ascontext.alembicandcontext.maybeAlembic;Alembic.stackOf(context)returns the pages and rebuilds on every change;Alembic.treeViewreturns the pages of every Alembic as a tree, nested Alembics under their pages;Alembic.treeLinereturns the same tree on one line, for analytics.
Design #
| Rule | What it means |
|---|---|
| Guards are pure business rules | They run only inside the controller, never during a build, so no change is ever committed mid-frame. |
| Data flows one way | The controller knows no widgets. The widget renders the pages, and reports back only the pages the user closed. |
| Back is the Navigator's back | Dialogs, PopScope and Page.canPop work without special cases. |
The page is the Page |
The Navigator's own key diff keeps routes and their state. |
| A change carries its results | A pop result travels with the change that removed the page. |
Migrating from elixir 0.5 #
The package was renamed from elixir to alembic in 0.6.0, because elixir is taken on pub.dev. The API is the same:
- the dependency is
alembic, fromhttps://github.com/gthe-miracle/alembic.git; package:elixir/elixir.dartbecomespackage:alembic/alembic.dart;- every
Elixir*type becomesAlembic*(ElixirController→AlembicController,Elixir→Alembic, …); context.elixir/context.maybeElixirbecomecontext.alembic/context.maybeAlembic.
Migrating from elixir 0.4 #
| elixir 0.4 | alembic 0.6 |
|---|---|
ValueNotifier<ElixirNavigationState> + Elixir.controlled(controller:) / Elixir(pages:) |
AlembicController(pages, guards:, revalidate:, name:) + Alembic(controller:) |
guards: [(context, state) => …] on the widget |
guards: [AlembicGuard((from, to) => …)] on the controller; read dependencies when you create the controller |
state.toSet().toList() guard |
Built in: the last page of each key wins |
context.elixir → ElixirState |
context.alembic → AlembicController |
listeners: [(elixir, previous, next) {}] |
listener: (notification) {} |
context.elixir.observer.addListener(…) |
listener on the root Alembic, or a NotificationListener<AlembicNotification> above it |
onBackButtonPressed: (state) => (state:, handled:) |
onBackButtonPressed: (navigator) async => … |
super(name: …, child: …), required tags, == override |
super(child: …); tags optional; no == override |
Route<void> createRoute with MaterialPageRoute(builder:) |
Route<Object?> createRoute with a page-based route |
reset(page) |
reset() |
Elixir.stateOf / Elixir.navigatorOf |
Alembic.stackOf / Navigator.of(pageContext) |
Example #
See example/ for an app with:
- a nested Alembic;
- a dialog page that returns a result;
- a sheet page;
- a custom swipe-back route.
License #
MIT, see LICENSE.
Author #
Created and maintained by Miracle.