add tag filter argument to of() and maybeOf()

Author: LucasAschenbach

CHANGELOG.md

@@ -1,3 +1,6 @@
+# 0.2.1
+* Add `tag` argument to `of()` and `maybeOf()` for reliably accessing navigators with a particular tag
+
 # 0.2.0+1
 * Port for Flutter v2.8.0
 

README.md

@@ -129,7 +129,7 @@ Furthermore, a *path navigations* operation performed at a given navigator can a
 
 Paths are in most cases declared through the `paths` argument which provides a simple and clear interface for fully customizable page stack manipulations. It maps a set of URIs to path builder functions which will be invoked whenever `AdvancedNavigator.openNamed(context, <uri>)` with the associated URI is called. The returned path (list of pages) then replaces the navigators current page stack.
 
-> `AdvancedNavigator` expects each requested path name to be in the standard [URI](https://tools.ietf.org/html/rfc2396) format and will parse it as such. Therefore, to take full advantage of this widget it is recommended to design path names with that format in mind.
+> `AdvancedNavigator` expects each requested path name to be in the standard [URI](https://tools.ietf.org/html/rfc2396) format and will parse it as such. Therefore, to take full advantage of this widget it is recommended to choose path names with that format in mind.
 
 There is built in argument parsing for extracting arguments such as id's directly from the provided URI. In the path name, arguments are marked with enclosing parentheses `.../{argName}/...` and can be read from the args argument in the path builder function to be used for building the page stack.
 
@@ -256,7 +256,7 @@ TextButton(
 ),
 ```
 
-The `of()` function also provides the option to specify a `skip` parameter which allows you to access navigators which are further up in the widget tree above other navigators without having to pass down the build context.
+The `of()` function also provides the option to specify a `skip` parameter which allows you to access navigators which are further up in the widget tree above other navigators or even a `tag` filter argument for precise control over which navigator is returned without having to pass down any build contexts across widgets.
 
 ## Nesting
 

example/pubspec.lock

@@ -7,7 +7,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "0.2.0+1"
+    version: "0.2.1"
   async:
     dependency: transitive
     description:
@@ -81,6 +81,13 @@ packages:
       url: "https://pub.dartlang.org"
     source: hosted
     version: "0.12.11"
+  material_color_utilities:
+    dependency: transitive
+    description:
+      name: material_color_utilities
+      url: "https://pub.dartlang.org"
+    source: hosted
+    version: "0.1.3"
   meta:
     dependency: transitive
     description:
@@ -155,7 +162,7 @@ packages:
       name: test_api
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "0.4.3"
+    version: "0.4.8"
   typed_data:
     dependency: transitive
     description:

lib/src/advanced_navigator.dart

@@ -66,7 +66,7 @@ class AdvancedNavigator extends StatefulWidget {
     this.reportsRouteUpdateToEngine = false,
     this.observers = const <NavigatorObserver>[],
     this.restorationScopeId,
-    required this.tag,
+    this.tag,
   }) : super(key: key);
 
   /// The navigator instance to which all navigation events from this navigator
@@ -133,7 +133,7 @@ class AdvancedNavigator extends StatefulWidget {
   final bool reportsRouteUpdateToEngine;
   final List<NavigatorObserver> observers;
   final String? restorationScopeId;
-  final String tag;
+  final String? tag;
 
   static const String defaultPathName = '/';
 
@@ -220,23 +220,30 @@ class AdvancedNavigator extends StatefulWidget {
   ///
   /// The `skip` argument denominates the number of instances to be skipped when
   /// searching up the widget tree for an instance of [AdvancedNavigator].
-  ///
-  /// If `rootNavigator` is set to true, `skip` is ignored and the state from
-  /// the furthest instance of this class is given instead. Useful for pushing
-  /// contents above all subsequent instances of [AdvancedNavigator].
-  ///
-  /// If there is no [AdvancedNavigator] in the give `context`, this function
-  /// will throw a [FlutterError] in debug mode, and an exception in release
-  /// mode.
+  /// 
+  /// With the `tag` argument specified, only navigators with a matching tag
+  /// will be considered. Should multiple navigators carry a matching tag, the
+  /// closest instance after skipping `skip` instances will be returned.
+  ///
+  /// If `rootNavigator` is set to true, both `skip` and `tag` are ignored and
+  /// the state from the furthest instance of this class is given instead.
+  /// Useful for pushing contents above all subsequent instances of
+  /// [AdvancedNavigator].
+  /// 
+  /// If there is no mathcing [AdvancedNavigator] in the give `context`, this
+  /// function will throw a [FlutterError] in debug mode, and an exception in
+  /// release mode.
   static AdvancedNavigatorState of(
     BuildContext context, {
     bool rootNavigator = false,
     int skip = 0,
+    String? tag,
   }) {
     var navigator = AdvancedNavigator.maybeOf(
       context,
       rootNavigator: rootNavigator,
       skip: skip,
+      tag: tag,
     );
     assert(() {
       if (navigator == null) {
@@ -267,17 +274,23 @@ class AdvancedNavigator extends StatefulWidget {
   ///
   /// The `skip` argument denominates the number of instances to be skipped when
   /// searching up the widget tree for an instance of [AdvancedNavigator].
-  ///
-  /// If `rootNavigator` is set to true, `skip` is ignored and the state from
-  /// the furthest instance of this class is given instead. Useful for pushing
-  /// contents above all subsequent instances of [AdvancedNavigator].
-  ///
-  /// Will return null if there is no ancestor [AdvancedNavigator] in the
-  /// `context`.
+  /// 
+  /// With the `tag` argument specified, only navigators with a matching tag
+  /// will be considered. Should multiple navigators carry a matching tag, the
+  /// closest instance after skipping `skip` instances will be returned.
+  ///
+  /// If `rootNavigator` is set to true, both `skip` and `tag` are ignored and
+  /// the state from the furthest instance of this class is given instead.
+  /// Useful for pushing contents above all subsequent instances of
+  /// [AdvancedNavigator].
+  ///
+  /// Will return null if there is no matching ancestor [AdvancedNavigator] in
+  /// the `context`.
   static AdvancedNavigatorState? maybeOf(
     BuildContext context, {
     bool rootNavigator = false,
     int skip = 0,
+    String? tag,
   }) {
     assert(rootNavigator || skip >= 0);
     AdvancedNavigatorState? navigator;
@@ -289,12 +302,17 @@ class AdvancedNavigator extends StatefulWidget {
       navigator = context.findRootAncestorStateOfType<AdvancedNavigatorState>();
     } else {
       context.visitAncestorElements((element) {
-        if (element is StatefulElement && element.state is AdvancedNavigatorState) {
-          if (skip <= 0) {
-            navigator = element.state as AdvancedNavigatorState;
-            return false;
+        if (element is StatefulElement) {
+          var state = element.state;
+          if (state is AdvancedNavigatorState) {
+            if (tag == null || tag == state.tag) {
+              if (skip == 0) {
+                navigator = state;
+                return false;
+              }
+              skip--;
+            }
           }
-          skip--;
         }
         return true;
       });
@@ -396,6 +414,8 @@ class AdvancedNavigatorState extends State<AdvancedNavigator> with RouteInformat
 
   Set<AdvancedNavigatorState> _children = {};
 
+  String? get tag => widget.tag;
+
   RouteInformation? get currentNestedPath => _routerDelegate._currentNestedPath;
 
   @override
@@ -646,7 +666,7 @@ class DefaultRouterDelegate extends RouterDelegate<RouteInformation>
   final bool reportsRouteUpdateToEngine;
   final List<NavigatorObserver> observers;
   final String? restorationScopeId;
-  final String tag;
+  final String? tag;
 
   RouteInformation _currentInternalPath = RouteInformation();
   RouteInformation? _currentNestedPath;

pubspec.lock

@@ -67,6 +67,13 @@ packages:
       url: "https://pub.dartlang.org"
     source: hosted
     version: "0.12.11"
+  material_color_utilities:
+    dependency: transitive
+    description:
+      name: material_color_utilities
+      url: "https://pub.dartlang.org"
+    source: hosted
+    version: "0.1.3"
   meta:
     dependency: transitive
     description:
@@ -134,7 +141,7 @@ packages:
       name: test_api
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "0.4.3"
+    version: "0.4.8"
   typed_data:
     dependency: transitive
     description:

pubspec.yaml

@@ -1,6 +1,6 @@
 name: advanced_navigator
 description: Flutter's Navigator 2.0 as one easy-to-use widget with full page history manipulation operations, simplified pop event delegation and powerful nesting. 
-version: 0.2.0+1
+version: 0.2.1
 repository: https://github.com/LucasAschenbach/advanced_navigator
 
 environment: