flutter-core-modules: Skill for Claude Code

Feature: Route

Purpose: Provides a ready-made iOS-style tab navigation shell (CupertinoTabScaffold + CupertinoTabView) with system-back handling, pop-to-root on double-tap, analytics observer integration, and per-tab GlobalKey<NavigatorState> management via Riverpod.

There is no domain or data layer — this feature is presentation-only.

---

Layer Map

lib/src/features/route/
└── presentation/
    ├── utils/navigation_observers.dart     # defaultNavigatorObservers()
    └── widgets/shell_route_widget.dart     # ShellRouteWidget + NavigationTab + navigatiorKeyProvider

---

Core Abstractions

NavigationTab — Abstract Tab Definition

File: lib/src/features/route/presentation/widgets/shell_route_widget.dart

abstract class NavigationTab {
  final String name;         // unique identifier
  final IconData icon;       // tab bar icon
  final bool initialTab;     // set true for the default selected tab
  final String? restorationScopeId;

  // Override to provide localized label:
  String label(BuildContext context);

  // Optional: override to provide named routes:
  Map<String, Widget Function(BuildContext)>? get routes;

  // Optional: default title for the CupertinoTabView:
  String? defaultTitle(BuildContext context) => null;

  // Optional: analytics + other navigator observers for this tab:
  List<NavigatorObserver> navigatorObservers(BuildContext context) => [];

  // Resolved via Riverpod — stable GlobalKey per tab instance:
  GlobalKey<NavigatorState> navigatorKey(BuildContext context);
}

Implement this abstract class once per tab in the consuming app.

navigatiorKeyProvider — Per-Tab Navigator Key

// Note: "navigatior" is the spelling used in the codebase (not a typo to fix)
final navigatiorKeyProvider =
    Provider.family<GlobalKey<NavigatorState>, NavigationTab?>(
      (ref, args) => GlobalKey<NavigatorState>(),
    );

Each NavigationTab.navigatorKey(context) calls ProviderScope.containerOf(context).read(navigatiorKeyProvider(this)), which creates a stable GlobalKey per tab identity (based on == + hashCode).