Update Navigation and Routing sample (#851)

* Add duration parameter to FadeTransitionPage

* Use didChangeDependencies instead of didUpdateWidget

* Don't notify listeners if the path hasn't changed

* Update navigation sample WIP

* Use Link and RouteStateScope in settings screen

* update README

* use named parameters for Library.addBook()

* Make _handleAuthStateChanged synchronous

* add missing copyright headers

* Address code review comments

* Address code review comments

navigation_and_routing/lib/src/routing/parsed_route.dart

@@ -9,9 +9,16 @@ import 'parser.dart';
 
 /// A route path that has been parsed by [TemplateRouteParser].
 class ParsedRoute {
+  /// The current path location without query parameters. (/book/123)
   final String path;
+
+  /// The path template (/book/:id)
   final String pathTemplate;
+
+  /// The path parameters ({id: 123})
   final Map<String, String> parameters;
+
+  /// The query parameters ({search: abc})
   final Map<String, String> queryParameters;
 
   static const _mapEquality = MapEquality<String, String>();

navigation_and_routing/lib/src/routing/parser.dart

@@ -7,6 +7,11 @@ import 'package:path_to_regexp/path_to_regexp.dart';
 
 import 'parsed_route.dart';
 
+/// Used by [TemplateRouteParser] to guard access to routes.
+///
+/// Override this class to change the route that is returned by
+/// [TemplateRouteParser.parseRouteInformation] if a condition is not met, for
+/// example, if the user is not signed in.
 abstract class RouteGuard<T> {
   Future<T> redirect(T from);
 }
@@ -17,11 +22,16 @@ class TemplateRouteParser extends RouteInformationParser<ParsedRoute> {
   RouteGuard<ParsedRoute>? guard;
   final ParsedRoute initialRoute;
 
-  TemplateRouteParser(List<String> pathTemplates,
-      {String? initialRoute = '/', this.guard})
-      : initialRoute =
+  TemplateRouteParser({
+    /// The list of allowed path templates (['/', '/users/:id'])
+    required List<String> allowedPaths,
+    /// The initial route
+    String? initialRoute = '/',
+    ///  [RouteGuard] used to redirect.
+    this.guard,
+  }) : initialRoute =
             ParsedRoute(initialRoute ?? '/', initialRoute ?? '/', {}, {}) {
-    for (var template in pathTemplates) {
+    for (var template in allowedPaths) {
       _addRoute(template);
     }
   }

navigation_and_routing/lib/src/routing/route_state.dart

@@ -8,11 +8,11 @@ import 'package:flutter/widgets.dart';
 import 'parsed_route.dart';
 import 'parser.dart';
 
-/// The current route state. To change the current route, call obtain the state using
-/// `RouteState.of(context)` and call `go()`:
+/// The current route state. To change the current route, call obtain the state
+/// using `RouteStateScope.of(context)` and call `go()`:
 ///
 /// ```
-/// RouteState.of(context).go('/book/2');
+/// RouteStateScope.of(context).go('/book/2');
 /// ```
 class RouteState extends ChangeNotifier {
   TemplateRouteParser parser;
@@ -24,6 +24,9 @@ class RouteState extends ChangeNotifier {
   ParsedRoute get route => _route;
 
   set route(ParsedRoute route) {
+    // Don't notify listeners if the path hasn't changed.
+    if (_route == route) return;
+
     _route = route;
     notifyListeners();
   }