Опенсорсим yx_navigation — декларативную навигацию для Flutter

• Разнобой подходов. Одна команда работала с go_router, другая — напрямую с Navigator 1.0, третья экспериментировала с Navigator 2.0. Единого подхода не было, и при стыковке модулей возникали «интересные» баги.

• Непрозрачность состояния навигации. В произвольный момент было невозможно понять, что сейчас вообще открыто, какие экраны в стеке. Синхронизировать бизнес‑логику с состоянием навигации было крайне затруднительно — интерактор мог запросить переход, не зная, в каком контексте находится приложение.
  
• Несколько способов открыть один и тот же экран. Разные вызовы давали разное поведение: анимация, свайп, стиль перехода. Разработчик должен был помнить, какой способ «правильный» для конкретного контекста. Material в одном месте, Cupertino в другом — и да пребудет с вами знание, где, что и как.
  
• Проблемы сpop()и выходом из фичи. Закрыть экран и вернуться назад — казалось бы, всё тривиально. Но при вложенных навигаторах, модальных окнах и табах логика pop() становилась непредсказуемой: выход из фичи мог сломать стек родительского навигатора или повлиять на соседнюю вкладку. «Почему после закрытия диалога закрылся соседний экран?» — классический вопрос при разборе багов.

• go_router перешёл в maintenance mode: только баг‑фиксы, никакого развития. Для нас это неприемлемо — мы вкладываемся в архитектуру на годы вперёд. Помимо этого, go_router не поддерживает изоляцию фич: все маршруты живут в едином дереве, и любая часть приложения может навигироваться куда угодно. Навигация привязана к BuildContext — из бизнес‑логики управлять ею нельзя.

• auto_route — зрелый пакет, но завязан на кодогенерацию. В крупном проекте build_runner — это боль: десятки секунд на каждый запуск, конфликты сгенерированных файлов при мёржах, дополнительный шаг в CI/CD. И те же проблемы: нет изоляции фич, нет управления навигацией из бизнес‑логики без BuildContext.
  
• beamer и routemaster — интересные альтернативы, но ни одна не решает ключевую для нас задачу: дать нескольким командам возможность работать над изолированными фичами с собственной навигацией, вкладывать их друг в друга, иметь единое реактивное состояние и не зависеть от UI‑контекста.
  
• Octopus заслуживает отдельного упоминания: декларативный роутер с деревом состояния, вложенной навигацией и guards — по духу нам близок, пакет сделан грамотно. Но на pub.dev он до сих пор версии 0.0.9, то есть без гарантий стабильности API для продукта нашего масштаба. И главное: он не закрывает весь набор наших требований — ту же изоляцию фич между командами приходится добивать снаружи.

• Универсальность. Решение должно одинаково работать в отдельной фиче и в корневом приложении.
  
• Модульность. Навигационный модуль одной фичи можно вложить в другой — и получить общее дерево навигации.
  
• Изолированность. Модуль знает только о своих маршрутах и не может влиять на состояние навигации родителя или соседей.
  
• Реактивность. В любой момент можно получить текущее состояние навигации, подписаться на его изменения и управлять навигацией через мутации состояния.
  
• Business Logic First. Управлять навигацией можно из бизнес‑логики, без зависимости от BuildContext.
  
• Guards. Контроль мутаций состояния: проверка авторизации, прав доступа, валидация данных перед переходом.
  
• Поддержка диплинков. Связь URI и навигации: восстановление состояния из ссылки и произвольная обработка входящих URI, в том числе без смены экрана.
  
• Поддержка диалогов и оверлеев. Bottom sheet'ы, диалоги и оверлеи управляются аналогично стеку навигации.
  
• Поддержка табов. Управление табами и nested‑навигация в пределах табов или PageView.
  
• Совместимость с Navigator 1.0. Legacy‑код с Navigator.push() и showDialog() продолжает работать без переписывания.

• yx_navigation — чистый Dart без зависимостей на Flutter (то, что принято называть flutter agnostic). Маршруты, состояние, мутации, guards, сериализация — всё, что можно покрыть unit‑тестами без запуска приложения.
  
• yx_navigation_flutter — Flutter‑обвязка: виджеты, Router delegate, page factories, debug‑инструменты и прочее.

• route — идентификатор маршрута (YxRoute);
  
• arguments — сериализуемые параметры (например, {'orderId': '123'});
  
• extra — несериализуемые объекты (полезно на период миграции);
  
• children — список дочерних узлов.

Root
└── Main (IndexedStack: tabs)
    ├── Messages
    ├── Map
    └── Profile (активный таб)

Root
└── Main (Outlet: pages)
    ├── Messages
    ├── Map
    └── Profile (активный экран)

const YxRoute(id: 'main').toNode(
  children: [
    const YxRoute(id: 'messages').toNode(),
    const YxRoute(id: 'map').toNode(),
    const YxRoute(id: 'profile').toNode(),
  ],
)

abstract class ProfileRoutes {
  static const home = YxRoute(id: 'profile-home');
  static const driverProfile = YxRoute(id: 'profile-driver');
  static const tripsHistory = YxRoute(id: 'profile-trips-history');
  static const statistics = YxRoute(id: 'profile-statistics');
  static const settings = YxRoute(id: 'profile-settings');
  static const documents = YxRoute(id: 'profile-documents');
}

final driverProfileDeclaration = RouteDeclaration.routeBuilder(
  route: ProfileRoutes.driverProfile,
  routeBuilder: RouteBuilder.widget(
    builder: (context, state) => const DriverProfilePage(),
  ),
);

class ProfileNavigationSchema extends RouterSchema {
  ProfileNavigationSchema()
      : super(
          //  здесь получаем корень дерева и задаём начальное состояние
          //  в данном случае будет единственный дочерний узел ProfileRoutes.home
          initialNodeBuilder: (node) => node
            ..setChildren([
                ProfileRoutes.home.toNode(),
            ]),
        );
  @override
  List<RouteDeclaration> get declarations => [
        //  тут определим декларацию для маршрута ProfileRoutes.home
        RouteDeclaration.routeBuilder(
          route: ProfileRoutes.home,
          routeBuilder: RouteBuilder.widget(
            builder: (context, state) => const ProfileHomePage(),
          ),
        ),
        driverProfileDeclaration, //  декларация профиля и другие
        tripsHistoryDeclaration,
        statisticsDeclaration,
        settingsDeclaration,
        documentsDeclaration,
      ];
}

class _ProfileAppState extends State<ProfileApp> {
  late YxRouterConfig config;
  @override
  void initState() {
    super.initState();
    final profileSchema = ProfileNavigationSchema();
    config = profileSchema.build(); //  строим RouterConfig
  }
  @override
  Widget build(BuildContext context) => MaterialApp.router(
        routerConfig: config,
      );
  @override
  void dispose() {
    config.dispose(); //  не забываем очистить ресурсы
    super.dispose();
  }
}

final routeNavigator = YxNavigation.navigatorOf(context);
// Перейти на экран
routeNavigator.push(ProfileRoutes.driverProfile);
// Вернуться назад
routeNavigator.pop();
// Проверить, можно ли вернуться
final canPop = routeNavigator.canPop();

• чтение текущего состояния RouteNode и его обновления (state/stream из RouteNodeReadable); 
  
• мутации (mutate из RouteMutator); 
  
• все операции‑примитивы, такие как push и pop (RouteNavigator); 
  
• функции ActiveRouteController, которые отвечают за активный маршрут, — полезно для работы с табами.

// Так реализован push — добавляем узел к children текущей ноды
void push(YxRoute route, {Map<String, String>? arguments}) =>
    mutate((routeNode) {
      routeNode.add(RouteNode.fromRoute(
        route: route,
        arguments: arguments ?? const {},
      ));
      return routeNode;
    });

class ProfileNavigationInteractor {
  late final RouteNodeStateManager _stateManager;
  RouteNavigator get navigator => _stateManager;
  ProfileNavigationInteractor() {
    //  Здесь указываем корневую ноду (root) в дереве состояния. В нашем примере — ProfileRoutes.root
    _stateManager = RouteNodeStateManager(
      routeNode: ProfileRoutes.root.toNode(),
    );
  }
  /// Открыть страницу профиля
  void openDriverProfile() => navigator.push(ProfileRoutes.driverProfile);
  /// Открыть страницу настроек
  void openSettings() => navigator.push(ProfileRoutes.settings);
}

final stateManager = coreScope.stateManager;  //  coreScope — ссылка на Scope, но это может быть любой провайдер зависимости из DI в UI
final profileSchema = ProfileNavigationSchema();
config = profileSchema.build(
  stateManagerConfiguration: StateManagerConfiguration(
    stateManager: stateManager,
  ),
);

abstract interface class RouteNodeGuard {
  GuardResult call(
    RouteNode origin,
    RouteNode target,
    GuardContext context,
  );
}

class AuthGuard implements RouteNodeGuard {
  final AuthService authService;
  const AuthGuard(this.authService);
  @override
  GuardResult call(
    RouteNode origin,
    RouteNode target,
    GuardContext context,
  ) {
    if (isInLoginNode(target)) {
      return const GuardResult.next();
    }
    if (!authService.isAuthorized()) {
      return GuardResult.redirect(
        target: AppRoutes.login.toNode(),
      );
    }
    return const GuardResult.next();
  }
}

class TabInitGuard implements RouteNodeGuard {
  final YxRoute tabRoute;
  final YxRoute childRoute;
  const TabInitGuard({
    required this.tabRoute,
    required this.childRoute,
  });
  @override
  GuardResult call(
    RouteNode origin,
    RouteNode target,
    GuardContext context,
  ) {
    final mutableTarget = target.toMutable();
    final tabNode = mutableTarget.findByRoute(tabRoute);
    if (tabNode != null && tabNode.children.isEmpty) {
      //  Как только нода найдена, автоматически добавляем в неё детей
      tabNode.setChildren([childRoute.toNode()]);
      return GuardResult.redirect(target: mutableTarget);
    }
    return const GuardResult.next();
  }
}

final someDeclaration = RouteDeclaration.routeBuilder(
  route: AppRoutes.protectedPage,
  guards: const [
    AuthGuard(),
    PermissionGuard(),
    DataValidationGuard(),
  ],
  routeBuilder: /* ... */,
)

class RouterSchema {
 @internal
 final Iterable<RouteDeclaration> declarations;
 @internal
 final Iterable<RouteNodeGuard> guards;
 @internal
 final InitialRouteNodeBuilder initialNodeBuilder;
...

RouteDeclaration.routeBuilder(
  route: AppRoutes.profile,
  routeBuilder: RouteBuilder.widget(
    builder: (context, routeNode) => ProfilePage(),
  ),
)

RouteDeclaration.routeBuilder(
  route: AppRoutes.home,
  routeBuilder: RouteBuilder.outlet(
    outletBuilder: (context, routeNode, outlet) {
      return Scaffold(
        appBar: AppBar(title: Text('Home')),
        body: outlet,
      );
    },
  ),
  declarations: [dashboardDeclaration, settingsDeclaration],
)

RouteDeclaration.routeBuilder(
  route: AppRoutes.home,
  routeBuilder: RouteBuilder.indexed(
    indexedBuilder: (context, routeNode, indexedStack, controller) {
      return Scaffold(
        body: indexedStack,
        bottomNavigationBar: BottomNavigationBar(
          currentIndex: tabs.indexOf(controller.activeRoute),
          onTap: (index) => controller.setActiveRoute(tabs[index]),
          items: [/* ... */],
        ),
      );
    },
  ),
  declarations: [mapTabDeclaration, messagesTabDeclaration],
)

inal homeDeclaration = RouteDeclaration.indexedStack(
  route: AppRoutes.home,
  routeBuilder: RouteIndexedStackBuilder(
    indexedBuilder: (context, routeNode, indexedStack, controller) {
      return Scaffold(
        body: indexedStack,
        bottomNavigationBar: BottomNavigationBar(
          currentIndex: tabs.indexOf(controller.activeRoute ?? AppRoutes.map),
          onTap: (index) => controller.setActiveRoute(tabs[index]),
          items: [/* ... */],
        ),
      );
    },
  ),
  //  Все дочерние декларации будут рассматриваться как табы
  declarations: [
    mapTabDeclaration,
    messagesTabDeclaration,
    profileTabDeclaration,
    settingsTabDeclaration,
  ],
);

final profileSchemaDeclaration = RouteDeclaration.scheme(
  route: DriverRoutes.profile,
  schema: ProfileNavigationSchema(),
);

routeNavigator.push(DriverRoutes.profile);

// Фича «Заказы» включает в себя фичу «Карточка заказа» как вложенный модуль
final orderCardDeclaration = RouteDeclaration.scheme(
  route: OrderRoutes.orderCard,
  schema: OrderCardNavigationSchema(),
);
base class OrdersNavigationSchema extends RouterSchema {
  OrdersNavigationSchema() : super(/* ... */);
  @override
  List<RouteDeclaration> get declarations => [
    ordersListDeclaration,
    orderCardDeclaration, // вложенная фича
  ];
}
// Дальше фича «Заказы» сама переиспользуется, например, на уровне хоста
final ordersDeclaration = RouteDeclaration.scheme(
  route: ApplicationRoutes.orders,
  schema: OrdersNavigationSchema(),
);

• Собственный навигатор. У фичи свой вложенный Navigator, управляемый через изолированный NavigationController.
  
• Изолированное состояние. Фича видит и мутирует только свою ветвь дерева состояния. Повлиять на состояние родителя или соседних фич невозможно.
  
• Standalone‑ и Embedded‑режим. Одна и та же фича может работать самостоятельно (например, в example‑приложении) или быть встроенной в родительское приложение. Переключение между режимами — через фабрику зависимостей.

final profileNavigationController = NavigationController.node(
  stateManager: stateManager,
  nodeResolver: RouteNodeResolver.id(route: DriverRoutes.profile),
);

final profileSchemaDeclaration = RouteDeclaration.scheme(
  route: DriverRoutes.profile,
  schema: ProfileNavigationSchema(),
  navigationController: profileNavigationController,
);

final profileSchemaDeclaration = RouteDeclaration.scheme(
  route: DriverRoutes.profile,
  schema: ProfileNavigationSchema(),
  outletBuilder: (context, routeNode, outlet) {
    final appDependencies = DriverAppDependenciesScope.of(context);
    return ProfileFeatureDependenciesScope.embedded(
      navigationController: appDependencies.profileNavigationController,
      child: outlet,
    );
  },
);

• Основное приложение не импортирует внутренние зависимости фичи.
  
• Фича не знает о существовании родительского приложения.
  
• Обе стороны работают через абстракцию NavigationController.
  
• Фича может быть подключена в любое другое приложение без изменений.

// Приходит заказ — хотим добавить его во вкладку «Заказы» БЕЗ переключения.
// С go_router единственный способ — go(), который ПЕРЕКЛЮЧАЕТ вкладку, делая её активной:
_router.go('/orders/order/${order.id}?pickup=...&dropoff=...&price=...');
// Пользователя прервут и переключат на «Заказы». push() в неактивную ветвь невозможен.

// Контроллер, привязанный к неактивной вкладке «Заказы»
final ordersController = NavigationController.node(
  stateManager: stateManager,
  //  Тут указываем, за какой частью дерева «следим»
  nodeResolver: RouteNodeResolver.id(route: AppRoutes.ordersTab),
);
// Push в неактивную ветвь — штатная операция
ordersController.push(
  AppRoutes.orderCard,
  arguments: {'orderId': 'ORD-001', 'price': '500'},
);

// Material (по умолчанию)
RouteBuilder.widget(
  builder: (context, routeNode) => MyPage(),
  pageFactory: const PagesFactory.material(),
)
// Cupertino
RouteBuilder.widget(
  builder: (context, routeNode) => SettingsPage(),
  pageFactory: const PagesFactory.cupertino(),
)

// Кастомная анимация
RouteBuilder.widget(
  builder: (context, routeNode) => MyPage(),
  pageFactory: PagesFactory.custom(
    builder: (context, routeNode, key, child) {
      return CustomTransitionPage(
        key: key,
        child: child,
        transitionsBuilder: (context, animation, secondaryAnimation, child) {
          return FadeTransition(opacity: animation, child: child);
        },
      );
    },
  ),
)

// Модальный диалог
RouteBuilder.widget(
  builder: (context, routeNode) => ConfirmDialog(),
  pageFactory: PagesFactory.custom(
    builder: (context, routeNode, key, child) {
      return DialogPage(key: key, child: child);
    },
  ),
)

config = schema.build(
  routerConfiguration: RouterConfiguration(
    serialization: const PrettyUriStateSerialization(),
  ),
);

• PrettyUriStateSerialization (используется по умолчанию) — читаемый формат, удобен для отладки. Сегменты пути отражают иерархию: / — переход к ребёнку, . / .. / ... — уровень вложенности. У каждого узла свои параметры: после идентификатора маршрута пишут $?key=value (несколько пар — через &). Пример URL, где аргументы заданы на трёх уровнях:

#/driver-home$?tab=orders/.driver-documents$?folder=work/..document-detail$?documentId=dl-789

• UriStringStateSerialization — компактный формат для длинных путей. Дерево кодируется в base64-строку, что даёт короткий URL при большом количестве узлов. Пример:

#('cnQ' 'aWQ':'cm9vdA'),'YXJncw':{})

abstract interface class PlatformStateSerialization {
  Uri convert(RouteNode node);   // дерево → URI
  RouteNode parse(Uri data);     // URI → дерево
}

NavigationConfigProvider(
  navigatorOverrides: const NavigatorCompatibilityOverrides(),
  child: MaterialApp.router(routerConfig: config),
)

// Всё это продолжает работать
Navigator.of(context).push(MaterialPageRoute(builder: (_) => OldScreen()));
Navigator.of(context).pushReplacement(MaterialPageRoute(builder: (_) => NewScreen()));
showDialog(context: context, builder: (_) => MyDialog());
showModalBottomSheet(context: context, builder: (_) => MySheet());

• MaterialPageRoute, CupertinoPageRoute — полная поддержка.
  
• DialogRoute, CupertinoDialogRoute, RawDialogRoute — специализированные адаптеры.
  
• CupertinoModalPopupRoute — специализированный адаптер.
  
• ModalBottomSheetRoute — полная поддержка.
  
• Любой ModalRoute — fallback через modalRouteProxy.

class MigrationTrackingObserver extends CompatibilityObserver {
  final Map<String, int> _routeTypeStats = {};
  @override
  void didCreatePagelessRoute({
    required RouteNodeReadable routeNodeReadable,
    required Route<dynamic> route,
    required String routeId,
    required String routeType,
    required RouteNode routeNode,
  }) {
    //  Собрали статистику
    _routeTypeStats[routeType] = (_routeTypeStats[routeType] ?? 0) + 1;
  }
  //  Распечатали список legacy-роутов
  void printReport() {
    for (final entry in _routeTypeStats.entries) {
      debugPrint('${entry.key}: ${entry.value}');
    }
  }
}

NavigatorCompatibilityOverrides(
  observer: MigrationTrackingObserver(),
)

config = schema.build(
  debugConfiguration: NavigationDebugConfiguration(
    debugPanelModeNotifier: DebugPanelModeNotifier(enableDebugPanel: true),
  ),
);

• полное дерево RouteNode с аргументами/extra;
  
• активный маршрут на каждом уровне вложенности (это просто последняя нода в children);
  
• сериализованное представление состояния в адресной строке;
  
• историю изменений при каждой мутации.

• yx_scope управляет жизненным циклом зависимостей. Скоуп фичи создаётся при авторизации и удаляется при выходе — вместе со всеми зависимостями.
  
• yx_state управляет состоянием внутри фичи. StateManager живёт в скоупе и предоставляет реактивный стейт с очередью операций.
  
• yx_navigation управляет навигацией между фичами и внутри них. RouteNodeStateManager навигации живёт в скоупе, интеракторы используют его для программного управления переходами.

• Чистый Dart в основе, Flutter‑обвязка отдельно. У каждого пакета есть Dart‑ядро без зависимости от Flutter. Скоупы зависимостей, операции состояния, мутации навигации — всё это тестируется unit‑тестами без запуска приложения.
  
• Без кодогенерации.Никакого build_runner ни в одном из пакетов: нет лишних шагов в CI/CD и конфликтов сгенерированных файлов при мёржах.
  
• Простота для базовых сценариев, гибкость для сложных. Каждый пакет минимален для старта, но масштабируется до enterprise‑задач: изоляция фич, вложенные скоупы, сложные цепочки guards и прочее.
  
• Обкатка в продакшене Яндекс Про. Все три пакета работают под реальной нагрузкой в приложении с десятками команд и сотнями фич.

• Исходный код на GitHub
  
• yx_navigation 
  
• yx_navigation_flutter
  
• yx_scope
  
• yx_state