feature-route

Feature: Route — Rules

What Is Already Implemented — Check Before Building

Capability	Status
iOS tab scaffold (CupertinoTabScaffold)	✅ ShellRouteWidget
Pop-to-root on active tab double-tap	✅ Built into ShellRouteWidget
System back handling	✅ PopScope in ShellRouteWidget
Per-tab isolated navigator	✅ CupertinoTabView per tab
Stable GlobalKey<NavigatorState> per tab	✅ navigatiorKeyProvider (family provider)
Analytics screen tracking (Firebase + PostHog)	✅ defaultNavigatorObservers()
Deep-link / go_router integration	❌ Not in package — implement in consuming app
Bottom tab badge / notification dot	❌ Not in package — extend NavigationTab
Custom tab bar beyond activeColor	❌ Uses CupertinoTabBar — only activeColor is configurable

Before building navigation infrastructure, verify whether ShellRouteWidget already covers the requirement.

---

Layer Structure

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

This feature is presentation-only — no domain or data layers.

---

Implementing a Tab

class HomeTab extends NavigationTab {
  const HomeTab() : super(
    name: 'home',          // unique string identifier
    icon: CupertinoIcons.house_fill,
    initialTab: true,      // only one tab should have initialTab: true
  );

  @override
  String label(BuildContext context) => AppLocalizations.of(context)!.home;

  @override
  Map<String, Widget Function(BuildContext)>? get routes => {
    '/': (context) => const HomeScreen(),
    '/detail': (context) => const DetailScreen(),
  };

  @override
  List<NavigatorObserver> navigatorObservers(BuildContext context) =>
      defaultNavigatorObservers(context); // always include for analytics
}

Rules for NavigationTab subclasses:

• name must be unique across all tabs in the app
• Only one tab per ShellRouteWidget should have initialTab: true
• Always override navigatorObservers to return defaultNavigatorObservers(context) unless you have a specific reason not to track screen views