Add state restoration topic to documentation

Author: LukasMirbt

packages/go_router/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 16.2.1
+
+- Adds state restoration topic to documentation
+
 ## 16.2.0
 
 - Adds `RelativeGoRouteData` and `TypedRelativeGoRoute`.

packages/go_router/dartdoc_options.yaml

@@ -33,6 +33,9 @@ dartdoc:
     "Error handling":
       markdown: doc/error-handling.md
       name: Error handling
+    "State restoration":
+      markdown: doc/state-restoration.md
+      name: State restoration
   categoryOrder:
     - "Get started"
     - "Upgrading"
@@ -45,6 +48,7 @@ dartdoc:
     - "Type-safe routes"
     - "Named routes"
     - "Error handling"
+    - "State restoration"
   showUndocumentedCategories: true
   ignore:
     - broken-link

packages/go_router/doc/state-restoration.md

@@ -0,0 +1,127 @@
+## What is state restoration?
+
+State restoration refers to the process of persisting and restoring serialized state 
+after the app has been killed by the operating system in the background. 
+For more information, see [Restore state on Android](https://docs.flutter.dev/platform-integration/android/restore-state-android)
+and [Restore state on iOS](https://docs.flutter.dev/platform-integration/ios/restore-state-ios).
+
+State restoration does not refer to general purpose state persistence.
+For keeping multiple navigation branches in memory at the same time, 
+see [StatefulShellRoute](https://pub.dev/documentation/go_router/latest/go_router/StatefulShellRoute-class.html).
+
+## Support
+
+GoRouter fully supports state restoration. 
+
+To enable state restoration, a top-level configuration is needed
+as well as additional configuration depending on the types of routes used.
+
+## Top-level configuration
+
+Add `restorationScopeId`s to `GoRouter` and `MaterialApp.router`:
+
+```dart
+final _router = GoRouter(
+  restorationScopeId: 'router',
+  routes: [
+    ...
+  ],
+);
+```
+
+```dart
+class MyApp extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp.router(
+      restorationScopeId: 'app',
+      routerConfig: _router,
+    );
+  }
+}
+```
+
+## Route-specific configuration
+
+### GoRoute
+
+For a `GoRoute` that uses `pageBuilder`, supply a `restorationId` to the page:
+
+```dart
+GoRoute(
+    pageBuilder: (context, state) {
+      return MaterialPage(
+        restorationId: 'detailsPage',
+        path: '/details',
+        child: DetailsPage(),
+      );
+    }
+)
+```
+
+For a `GoRoute` that does not use `pageBuilder`, no additional configuration
+is needed.
+
+For a runnable example with tests, see the [GoRoute state restoration example](https://github.com/flutter/packages/tree/main/packages/go_router/example/lib/state_restoration/go_route_state_restoration.dart).
+
+### ShellRoute
+
+Add a unique `restorationScopeId` to the `ShellRoute`. 
+
+Additionally, add a `pageBuilder` and supply a `restorationId` to the page.
+
+A `pageBuilder` which returns a page with `restorationId` must be supplied for state restoration to work.
+
+For a runnable example with tests, see the [ShellRoute state restoration example](https://github.com/flutter/packages/tree/main/packages/go_router/example/lib/state_restoration/shell_route_state_restoration.dart).
+
+```dart
+ShellRoute(
+  restorationScopeId: 'onboardingShell',
+  pageBuilder: (context, state, child) {
+    return MaterialPage(
+      restorationId: 'onboardingPage',
+      child: OnboardingScaffold(child: child),
+    );
+  },
+  routes: [
+    ...
+  ],
+)
+```
+
+### StatefulShellRoute
+
+Add a `restorationScopeId` to the `StatefulShellRoute` and a
+`pageBuilder` which returns a page with a `restorationId`.
+
+Additionally, add a `restorationScopeId` to each `StatefulShellBranch`.
+
+A `pageBuilder` which returns a page with `restorationId` must be supplied for state restoration to work.
+
+For a runnable example with tests, see the [StatefulShellRoute state restoration example](https://github.com/flutter/packages/tree/main/packages/go_router/example/lib/state_restoration/stateful_shell_route_state_restoration.dart).
+
+```dart
+StatefulShellRoute.indexedStack(
+  restorationScopeId: 'appShell',
+  pageBuilder: (context, state, navigationShell) {
+    return MaterialPage(
+      restorationId: 'appShellPage',
+      child: AppShell(navigationShell: navigationShell),
+    );
+  },
+  branches: [
+    StatefulShellBranch(
+      restorationScopeId: 'homeBranch',
+      routes: [
+        ...
+      ],
+    ),
+    StatefulShellBranch(
+      restorationScopeId: 'profileBranch',
+      routes: [
+        ...
+      ],
+    ),
+  ],
+)
+```