@lwrjs/router 0.12.0-alpha.2 → 0.12.0-alpha.4

package/README.md

@@ -0,0 +1,795 @@
+# LWR Routing & Navigation
+
+-   [Introduction](#introduction)
+-   [App Configuration](#app-configuration)
+-   [Router](#router)
+    -   [Locations](#locations)
+    -   [Route Definitions](#route-definitions)
+    -   [Route Matching](#route-matching)
+    -   [Route Handlers](#route-handlers)
+    -   [Generated Routers](#generated-routers)
+        -   [Configuration](#configuration)
+        -   [Router JSON](#router-json)
+        -   [Usage](#usage)
+    -   [Server-side Rendering](#server-side-rendering)
+-   [Router Container](#router-container)
+    -   [Nesting Router Containers](#nesting-router-containers)
+-   [Outlet](#outlet)
+    -   [Multiple Outlets](#multiple-outlets)
+-   [Navigation Wires](#navigation-wires)
+    -   [`CurrentPageReference`](#currentpagereference)
+    -   [`CurrentView`](#currentview)
+    -   [`NavigationContext`](#navigationcontext)
+-   [Navigation APIs](#navigation-apis)
+    -   [`navigate()`](#navigate)
+    -   [`generateUrl()`](#generateurl)
+-   [Lightning Navigation](#lightning-navigation)
+    -   [`NavigationMixin`](#navigationmixin)
+
+## Introduction
+
+The `@lwrjs/router` package provides modules for client-side routing (`lwr/router`) and navigation (`lwr/navigation`), which export APIs to create a router, navigate, generate URLs and subscribe to navigation events. Client-side routing enables the creation of a Single Page Application (SPA).
+
+LWR routers can be customized with configuration and hooks. They can also be nested, to create a hierarchy in an application.
+
+> See the RFC on LWR routing APIs [here](https://github.com/salesforce-emu/lwr-rfcs/blob/master/text/0003-router-api-baseline.md).
+
+## Router
+
+A router is a piece of code that manages client-side navigation changes. All navigation events flow through a router for processing. Use the `createRouter(config: RouterConfig)` API to initialize a LWR router:
+
+```ts
+import { createRouter } from 'lwr/router';
+createRouter({
+    routes: [
+        /* see Route Definitions section */
+    ],
+    basePath: '/my-site',
+    i18n: {
+        locale: 'es',
+        defaultLocale: 'en-US'
+    }
+    caseSensitive: true,
+});
+```
+
+It takes a configuration object as an argument:
+
+```ts
+type RouterConfig = {
+    routes?: RouteDefinition[]; // see Route Definitions section, default = []
+    basePath?: string; // a path prefix applied to all URIs, default = ''
+    i18n?: I18NRouterConfig; // a i18n config that may effect the path prefix applied to all URIs, default = {locale: 'en-US', defaultLocale: 'en-US'}
+    caseSensitive?: boolean; // true if URIs should be processed case sensitively, default = false
+};
+```
+
+### Locations
+
+The router processes incoming navigation events (i.e. location changes), which enter the router in one of two forms:
+
+1. **page references**: location in JSON form, passed to the router via the [`navigate()` API](#navigate)
+
+```ts
+interface PageReference {
+    type: string;
+    attributes: { [key: string]: string | null };
+    state: { [key: string]: string | null };
+}
+```
+
+2. **URI**: location in string form, as seen in a browser's address bar, and captured by the router via the [`popstate` event](https://developer.mozilla.org/en-US/docs/Web/API/Window/popstate_event)
+
+The router uses its [route definitions](#route-definitions) to determine if a location is valid. If so, the navigation event is accepted and a user will see updated content in their browser.
+
+The router can and does convert locations between forms. For example, the following URI and page reference are equivalent:
+
+```json
+// URI -> https://www.somewhere.com/animals/abc?view=compact&dark-mode
+
+// page reference:
+{
+    "type": "animal_page",
+    "attributes": {
+        "animalId": "abc"
+    },
+    "state": {
+        "view": "compact",
+        "dark-mode": ""
+    }
+}
+```
+
+### Route Definitions
+
+The most important part of the `RouterConfig` is the array of route definitions. The router uses these to verify and process incoming [location](#locations) changes. A location is only valid if it can be matched to a `RouteDefinition`. The application will fail to navigate given an invalid location. Each `RouteDefinition` has this shape:
+
+```ts
+interface RouteDefinition<TMetadata = Record<string, any>> {
+    id: string;
+    uri: string;
+    page: Partial<PageReference>;
+    handler: () => Promise<{ default: RouteHandler }>;
+    patterns?: { [paramName: string]: string };
+    exact?: boolean;
+    metadata?: TMetadata;
+}
+```
+
+containing the following properties:
+
+-   `id`: each `RouteDefinition` must have a unique identifier
+-   `uri`: a string pattern for URI locations which match this `RouteDefinition`; the grammar is fully defined [in an RFC](https://github.com/salesforce-emu/lwr-rfcs/blob/master/text/0006-route-binding-and-serialization.md#uri-grammar-syntax) and includes these characters:
+    -   `/`: path separator
+    -   `:parameter`: captures a variable from a path or query parameter; must be alpha-numeric (i.e. [a-zA-Z0-9])
+    -   `?`: denotes the beginning of the query string
+    -   `&`: query parameter separator
+-   `page`: shape for page references which match this `RouteDefinition`; the usage is detailed [in an RFC](https://github.com/salesforce-emu/lwr-rfcs/blob/master/text/0006-route-binding-and-serialization.md#pagereference-binding) and allows:
+    -   `:parameter` bindings: map a path or query parameter from the `uri` to an `attributes` or `state` property
+    -   literal bindings: hard-code the `type`, an `attribute`, or `state` property to a literal value
+-   `handler`: a `Promise` to a module which is called when a `RouteDefinition` is matched by a location; see the [Route Handlers section](#route-handlers)
+-   `patterns` (optional): a regular expression which a parameter must match in order to be valid; described in an RFC [here](https://github.com/salesforce-emu/lwr-rfcs/blob/master/text/0006-route-binding-and-serialization.md#parameter-validation-patterns)
+-   `exact` (optional, default = `true`): see the [Nesting Router Containers section](#nesting-router-containers)
+-   `metadata` (optional): developer-defined metadata attached to `RouteDefinition`; see the RFC [here](https://github.com/salesforce-emu/lwr-rfcs/blob/master/text/0000-route-definition-meta.md) and a recipe [here](https://github.com/salesforce-experience-platform-emu/lwr-recipes/tree/main/packages/routing-extended-metadata)
+
+> _Important_: The `routes` array seen in [LWR app configuration](./config.md) is for **server-side** routes (see RFC [here](https://github.com/salesforce-emu/lwr-rfcs/blob/master/text/0000-lwr-app-config.md#application-routes)), and is unrelated to the `@lwrjs/router` package.
+
+### Route Matching
+
+Here is an example `RouteDefinition` for a recipe:
+
+```js
+// RouteDefinition for a page in a recipe website
+{
+    id: 'recipe',
+    uri: '/recipes/:category/:recipeId?units=:units&yummy=yes',
+    patterns: {
+        recipeId: '[0-9]{3}',      // "recipeId" must be a 3 digit number
+    },
+    page: {
+        type: 'recipe_page',       // matching page references must be of type "recipe_page"
+        attributes: {
+            recipeId: ':recipeId', // straightforward attribute binding
+            cat: ':category',      // bind the "category" path parameter to the "cat" attribute
+            units: ':units',       // bind the "units" query parameter to an attribute
+        },
+        state: {
+            code: 'abc123',        // hard-coded state literal
+        },
+    },
+    handler: () => import('my/recipeHandler'),
+}
+```
+
+This URI and page reference match the recipe `RouteDefinition`:
+
+```js
+// URI -> https://www.somewhere.com/recipes/desserts/010?units=metric&yummy=yes&extra=foo (extra query params are allowed)
+
+// page reference:
+{
+    "type": "recipe_page", // type matches
+    "attributes": {
+        // all bound attributes have values
+        "recipeId": "010", // the "recipeId" matches the pattern
+        "cat": "desserts",
+        "units": "metric"
+    },
+    "state": {
+        "code": "abc123", // the state literal matches
+        "extra": "foo"    // extra state properties are allowed
+    }
+}
+```
+
+This URI and page reference **do not** match:
+
+```js
+// URI -> https://www.somewhere.com/r/desserts/abc (parameters and literals are missing or malformed)
+
+// page reference:
+{
+    "type": "awful_page", // type DOES NOT match
+    "attributes": {
+        "recipeId": "lol", // the "recipeId" DOES NOT match the pattern
+        "extra": "bad" // extra attributes ARE NOT allowed
+        // the "cat" and "units" attributes are missing
+    },
+    "state": {
+        "code": "fail" // the state literal IS NOT equal
+    }
+}
+```
+
+> See more `RouteDefinition` examples with [matching](https://github.com/salesforce-emu/lwr-rfcs/blob/master/text/0006-route-binding-and-serialization.md#positively-matching-pagereferences) and [non-matching](https://github.com/salesforce-emu/lwr-rfcs/blob/master/text/0006-route-binding-and-serialization.md#failing-matching-pagereferences) page references in the RFC.
+
+### Route Handlers
+
+When the router [matches](#route-matching) an incoming [location (i.e. URI or page reference)](#locations) to a [`RouteDefinition`](#route-definitions), it accesses its `RouteDefinition.handler` to determine the associated "view". A view is the component to display when the application navigates to a location.
+
+```ts
+// types related to the RouteHandler
+interface RouteDefinition {
+    handler: () => Promise<{ default: RouteHandler }>; // `export default` a RouteHandler module
+    // other properties...
+}
+interface RouteHandler {
+    new (callback: (routeDestination: RouteDestination) => void): void; // denotes a Class
+    dispose(): void;
+    update(routeInfo: RouteInstance): void;
+}
+interface RouteDestination {
+    // provided by `RouteHandler.update()` via a callback
+    viewset: ViewSet;
+}
+interface ViewSet {
+    [namedView: string]: (() => Promise<Module>) | ViewInfo;
+}
+interface ViewInfo {
+    module: () => Promise<Module>;
+    specifier: string;
+}
+interface RouteInstance {
+    // location information passed to `RouteHandler.update()`
+    id: string; // RouteDefinition.id
+    attributes: { [key: string]: string | null };
+    state: { [key: string]: string | null };
+    pageReference: PageReference;
+}
+```
+
+> _Note_: Modules are always provided via promises. This allows the module code to be lazily loaded, which improves performance of the application.
+
+Given information on the current location (i.e. a `RouteInstance`), the job of the `RouteHandler` module is to provide a set of views via a callback from its `update()` function:
+
+```ts
+// "my/recipeHandler" RouteHandler module
+import type { Module, RouteHandlerCallback } from 'lwr/router';
+
+export default class RecipeHandler {
+    callback: RouteHandlerCallback;
+
+    constructor(callback: RouteHandlerCallback) {
+        this.callback = callback; // Important: maintain a reference to the callback
+    }
+
+    dispose(): void {
+        // perform cleanup tasks
+    }
+
+    update(routeInfo: RouteInstance): void {
+        // called every time a RouteDefinition with this handler matches a location during processing
+        const {
+            attributes: { cat }, // location information
+        } = routeInfo;
+        const category = cat || 'entree'; // cat may be null
+        const viewSpecifier = `my/${category}Recipe`; // e.g. "my/dessertRecipe"
+        this.callback({
+            viewset: {
+                // return view component info based on the recipe's category
+                default: {
+                    module: (): Promise<Module> => import(viewSpecifier),
+                    specifier: viewSpecifier,
+                },
+            },
+        });
+    }
+}
+```
+
+> See the `RouteHandler` RFC [here](https://rfcs.lwc.dev/rfcs/lwr/0002-route-handler) and some example handlers [here](https://github.com/salesforce-experience-platform-emu/lwr-recipes/tree/main/packages/simple-routing/src/modules/example).
+
+### Generated Routers
+
+The Router Module Provider can generate a router based on a static JSON file. A generated router consumes its [configuration](#router) from a portable JSON file rather than a JavaScript module. Static configuration can be easier to author and to maintain. This approach is most helpful for straightforward use cases.
+
+#### Configuration
+
+The Router Module Provider is not a default module provider, so it must be added to the project configuration. Learn more in [Configure a LWR Project](https://github.com/salesforce-experience-platform-emu/lwr-recipes/blob/main/doc/config.md#providers).
+
+Add `"@lwrjs/router/module-provider" as a dependency in `package.json`.
+
+```json
+// package.json
+{
+    "dependencies": {
+        "@lwrjs/router/module-provider": "0.7.1"
+    }
+}
+```
+
+Register the Router Module Provider in `lwr.config.json`.
+
+```json
+// lwr.config.json with the Router Module Provider and the LWR default module providers
+{
+    "moduleProviders": [
+        "@lwrjs/router/module-provider",
+        "@lwrjs/app-service/moduleProvider",
+        "@lwrjs/lwc-module-provider",
+        "@lwrjs/npm-module-provider"
+    ]
+}
+```
+
+When registering the module provider, optionally configure the directory location of the router JSON files.
+
+```json
+// lwr.config.json
+{
+    "moduleProviders": [
+        ["@lwrjs/router/module-provider", { "routesDir": "$rootDir/config/router" }],
+        "@lwrjs/app-service/moduleProvider",
+        "@lwrjs/lwc-module-provider",
+        "@lwrjs/npm-module-provider"
+    ]
+}
+```
+
+If a configuration is not specified when registering the Router Module Provider, it uses this default configuration.
+
+```json
+{
+    "routesDir": "$rootDir/src/routes"
+}
+```
+
+To automatically register **client-side** routes with the **server**, specify them as "sub routes" by pointing to their [Route JSON file](#router-json).
+
+```json
+// lwr.config.json
+{
+    "routes": [
+        {
+            "id": "spa",
+            "path": "/site",
+            "rootComponent": "my/spa",
+            "subRoutes": "$rootDir/src/routes/client.json"
+        }
+    ]
+}
+```
+
+If the client-side routes contain these `uri`s:
+
+-   "/"
+-   "/about"
+-   "/:id"
+    Then the LWR server will automatically register these `path`s:
+-   "_/site_"
+-   "_/site_/about"
+-   "_/site_/:id"
+
+This allows users to do a full page refresh on a client-side route without getting a 404.
+
+#### Router JSON
+
+The Router Module Provider generates a router module based on JSON configuration: `LwrRouterConfig`.
+
+```ts
+interface LwrRouterConfig {
+    basePath?: string;
+    caseSensitive?: boolean;
+    routes: LwrConfigRouteDefinition[];
+}
+
+interface LwrConfigRouteDefinition<TMetadata = Record<string, any>> {
+    // These properties are the same as in RouteDefinition
+    id: string;
+    uri: string;
+    page?: Partial<PageReference>;
+    patterns?: { [paramName: string]: string };
+    exact?: boolean;
+    metadata?: TMetadata;
+    // These properties are different than RouteDefinition
+    // A Route Definition must have 1 or the other, but not both
+    handler?: string; // a STRING reference to the handler class
+    component?: string; // a STRING reference to a page component
+}
+```
+
+The `LwrRouterConfig` contains the same properties which are passed to [`createRouter()`](#router). The `LwrConfigRouteDefinition` contains the same properties as [`RouteDefinition`](#route-definitions), except for:
+
+-   `handler`: A **string** reference to the [`RouteHandler`](#route-handlers) class specifier, rather than a function.
+-   `component`: A **string** reference to the view component specifier. This is a shortcut so the view component can be specified directly, without authoring a `RouteHandler`. A `LwrConfigRouteDefinition` must contain a `handler` or a `component`, but not both.
+
+> Note: `LwrConfigRouteDefinition` is pure JSON, which is why it cannot contain any functions like `RouteDefinition` does.
+
+Here is a Router config example.
+
+```json
+// src/routes/website.json
+{
+    "routes": [
+        {
+            "id": "home",
+            "uri": "/",
+            "component": "examples/home",
+            "page": {
+                "type": "home"
+            },
+            "metadata": {
+                "title": "Home"
+            }
+        },
+        {
+            "id": "namedPage",
+            "uri": "/:pageName",
+            "handler": "examples/namedPageHandler",
+            "page": {
+                "type": "namedPage",
+                "attributes": {
+                    "pageName": ":pageName"
+                }
+            }
+        }
+    ]
+}
+```
+
+#### Usage
+
+Import and use a router generated using the JSON above.
+
+```js
+// src/modules/my/app/app.js
+import { LightningElement } from 'lwc';
+import { createRouter } from '@lwrjs/router/website'; // "website" refers to src/routes/website.json
+
+export default class MyApp extends LightningElement {
+    router = createRouter();
+}
+```
+
+```html
+<!-- src/modules/my/app/app.html -->
+<template>
+    <lwr-router-container router="{router}">
+        <lwr-outlet></lwr-outlet>
+    </lwr-router-container>
+</template>
+```
+
+The generated router module specifier is: `@lwrjs/router/<name of the JSON config file>`. It provides a `createRouter()` function that is identical to the [static `createRouter()` function](#router), except that it does not take a `routes` array, since the routes are configured in the JSON file instead. If `basePath` or `caseSensitive` is specified in both the JSON file and the `createRouter()` call, then the latter takes precedence.
+
+### Server-side Rendering
+
+See [this documentation](../lwc-ssr/README.md#routing) to learn about routing during server-side rendering.
+
+## Router Container
+
+In order to use a [router](#router) in an application, it must be attached to the DOM. This is done with a router container, provided by the `lwr-router-container` component.
+
+A router container provides "navigation context", meaning that it is responsible for [processing](#route-matching) all navigation [wires](#navigation-wires) and [events](#navigation-apis) from its descendants in the DOM (e.g. `my-nav` and `lwr-outlet` in the example code below).
+
+```html
+<!-- my/app/app.html -->
+<template>
+    <lwr-router-container
+        router="{router}"
+        onhandlenavigation="{handleNavigation}"
+        onprenavigate="{preNavigate}"
+        onpostnavigate="{postNavigate}"
+        onerrornavigate="{errorNavigate}"
+    >
+        <my-nav></my-nav>
+        <lwr-outlet><!-- See the Outlet section below --></lwr-outlet>
+    </lwr-router-container>
+</template>
+```
+
+```ts
+// my/app/app.ts
+import { LightningElement } from 'lwc';
+import { createRouter } from 'lwr/router';
+import { ROUTE_DEFINITIONS } from './routeDefinitions';
+
+export default class MyApp extends LightningElement {
+    router = createRouter({ routes: ROUTE_DEFINITIONS });
+    approvedCategories = ['apps', 'entrees', 'sides', 'desserts'];
+
+    handleNavigation(e: CustomEvent): void {
+        console.log('navigate() called with page reference:', e.detail);
+    }
+
+    preNavigate(e: CustomEvent): void {
+        const {
+            next: {
+                route: { pageReference },
+            },
+        } = e.detail;
+        const {
+            attributes: { cat },
+        } = pageReference;
+        console.log('navigation event incoming with page reference:', pageReference);
+        if (!this.approvedCategories.includes(cat)) {
+            // REJECT unapproved recipe categories
+            e.preventDefault();
+        }
+    }
+
+    postNavigate(e: CustomEvent): void {
+        const {
+            route: { pageReference },
+        } = e.detail;
+        console.log('navigated to page reference:', pageReference);
+    }
+
+    errorNavigate(e: CustomEvent): void {
+        const { code, message } = e.detail;
+        console.error(`navigation error -> ${code}: ${message}`);
+    }
+}
+```
+
+A router container requires a [router](#router), and fires these [events](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/events_handling):
+
+-   `onhandlenavigation`: dispatched when [`navigate(pageRef)`](#navigate) is called; `event.preventDefault()` **cancels** the navigation event; `event.detail` is the `PageReference`
+-   `onprenavigate`: dispatched when a navigation event is received and a `RouteDefinition` match is found; `event.preventDefault()` **cancels** the navigation event; `event.detail` is a `RouteChange`
+-   `onpostnavigate`: dispatched when a navigation event has completed; `event.detail` is a `DomRoutingMatch` for the current location
+-   `onerrornavigate`: dispatched when there is an error processing a navigation event (e.g. no `RouteDefinition` match, `prenavigate` cancelation); `event.detail` is a `MessageObject`
+
+```ts
+// router container event payload types
+interface DomRoutingMatch {
+    url: string; // e.g. "/recipes/desserts/010?units=metric&yummy=yes"
+    route: RouteInstance;
+    routeDefinition: RouteDefinition;
+}
+interface RouteChange {
+    current?: DomRoutingMatch; // the current location info
+    next: DomRoutingMatch; // location info for the incoming nav event
+}
+interface MessageObject {
+    code: string | number;
+    message: string;
+    level: number; // Fatal = 0, Error = 1, Warning = 2, Log = 3
+}
+```
+
+> See a simple routing recipe [here](https://github.com/salesforce-experience-platform-emu/lwr-recipes/tree/main/packages/simple-routing).
+
+### Nesting Router Containers
+
+A router container can have up to 1 child router. Each router is responsible for processing the navigation events from its descendants. Every [`RouteDefinition`](#route-definitions) resolving to a view component which includes a child router must set `exact` to `false`:
+
+```js
+// parent RouteDefinition for a page which includes a child router
+{
+    id: 'root',
+    uri: '/parent/path',
+    exact: false, // allow the parent and child router to resolve a URI together (i.e. "/parent/path/child/path&params)
+    page: { type: 'home' },
+    handler: () => import('my/someHandler'), // resolves a view containing a child router container
+}
+```
+
+> See a nested routing recipe [here](https://github.com/salesforce-experience-platform-emu/lwr-recipes/tree/main/packages/nested-routing).
+
+## Outlet
+
+It is the router's job to [resolve view components](#route-handlers) for a given location, and it is the outlet's job to _display_ those view components:
+
+```html
+<!-- my/app/app.html -->
+<template>
+    <lwr-router-container>
+        <lwr-outlet refocus-off onviewchange="{onViewChange}" onviewerror="{onViewError}">
+            <div slot="error">View component cannot display</div>
+        </lwr-outlet>
+    </lwr-router-container>
+</template>
+```
+
+The outlet uses the [`CurrentView` wire](#currentview) to get the current view component, then displays it in the DOM. It has:
+
+-   [properties](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.create_components_data_binding):
+    -   `view-name`: the key of the `ViewSet` entry to display; the default value is `"default"`
+    -   `refocus-off` boolean: if present, the outlet will **not** put the browser focus on the view component when it loads; refocusing is on by default as an accessibility feature
+-   [events](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/events_handling):
+    -   `onviewchange` event: dispatched whenever the view component changes; `event.detail` is the view component class:
+    ```ts
+    type Constructor<T = object> = new (...args: any[]) => T;
+    interface Constructable<T = object> {
+        constructor: Constructor<T>;
+    }
+    interface ViewChangePayload {
+        detail: Constructable;
+    }
+    ```
+    -   `onviewerror` event: dispatched whenever the view component fails to mount; `event.detail` is the error and stack:
+    ```ts
+    interface ViewErrorPayload {
+        detail: {
+            error: Error;
+            stack: string;
+        };
+    }
+    ```
+-   [slots](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.create_components_slots):
+    -   "error": The contents of the error slot are shown whenever the view component fails to mount
+
+> See the RFC for the outlet [here](https://github.com/salesforce-emu/lwr-rfcs/blob/master/text/0003-router-api-baseline.md#lwroutlet) and the `viewchange` and `viewerror` events [here](https://github.com/salesforce-emu/lwr-rfcs/blob/master/text/0000-router-viewChange-event.md).
+
+### Multiple Outlets
+
+A [`RouteHandler`](#route-handlers) may return multiple views:
+
+```ts
+import type { Module, RouteHandlerCallback } from 'lwr/router';
+
+export default class HomeHandler {
+    callback: RouteHandlerCallback;
+
+    constructor(callback: RouteHandlerCallback) {
+        this.callback = callback;
+    }
+
+    dispose(): void {}
+
+    update(): void {
+        this.callback({
+            viewset: {
+                // return multiple views
+                default: (): Promise<Module> => import('my/home'),
+                nav: (): Promise<Module> => import('my/homeNav'),
+                footer: (): Promise<Module> => import('my/homeInfo'),
+            },
+        });
+    }
+}
+```
+
+Multiple outlets can be used to display all the current view components by setting different `view-names`:
+
+```html
+<!-- my/app/app.html -->
+<template>
+    <lwr-router-container>
+        <lwr-outlet view-name="nav"></lwr-outlet>
+        <lwr-outlet><!-- default view --></lwr-outlet>
+        <lwr-outlet view-name="footer"></lwr-outlet>
+    </lwr-router-container>
+</template>
+```
+
+## Navigation Wires
+
+The `lwr/navigation` module provides [wire adapters](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.data_wire_service_about) from which components can receive information about navigation events.
+
+### `CurrentPageReference`
+
+Get the current page reference from the [router container](#router-container):
+
+```js
+import { LightningElement, wire } from 'lwc';
+import { CurrentPageReference } from 'lwr/navigation';
+
+export default class Example extends LightningElement {
+    // Subscribe to page reference updates
+    @wire(CurrentPageReference)
+    printPageName(pageRef) {
+        console.log(`Page name: ${pageRef ? pageRef.attributes.name : ''}`);
+    }
+}
+```
+
+> _Note_: This wire is also available in [Lightning Experience](https://developer.salesforce.com/docs/component-library/bundle/lightning-navigation/documentation).
+
+### `CurrentView`
+
+Get a reference to the current view component. The `viewName` configuration property is optional, and falls back to `"default"` if unspecified.
+
+```js
+import { LightningElement, wire } from 'lwc';
+import { CurrentView } from 'lwr/navigation';
+
+export default class MyFooter extends LightningElement {
+    // Subscribe to view component updates
+    @wire(CurrentView, { viewName: 'footer' })
+    viewCtor;
+}
+```
+
+### `NavigationContext`
+
+Get a reference to a component's navigation context (i.e. its closest ancestor [router container](#router-container)), for use with the [navigation APIs](#navigation-apis):
+
+```ts
+import { LightningElement, wire } from 'lwc';
+import { NavigationContext } from 'lwr/navigation';
+import type { ContextId } from 'lwr/navigation';
+
+export default class Example extends LightningElement {
+    @wire(NavigationContext as any)
+    navContext?: ContextId;
+}
+```
+
+## Navigation APIs
+
+### `navigate()`
+
+Navigate programmatically:
+
+```ts
+import { LightningElement, api, wire } from 'lwc';
+import { NavigationContext, navigate } from 'lwr/navigation';
+import type { ContextId } from 'lwr/navigation';
+
+export default class AboutLink extends LightningElement {
+    @wire(NavigationContext as any)
+    navContext?: ContextId;
+
+    handleClick(event: Event): void {
+        event.preventDefault();
+        if (this.navContext) {
+            navigate(this.navContext, {
+                type: 'named_page',
+                attributes: { name: 'about' },
+            });
+        }
+    }
+}
+```
+
+### `generateUrl()`
+
+Generate a URL for a page reference:
+
+```ts
+import { LightningElement, api, wire } from 'lwc';
+import { NavigationContext, generateUrl } from 'lwr/navigation';
+import type { ContextId, PageReference } from 'lwr/navigation';
+
+export default class UrlGenerator extends LightningElement {
+    @api pageReference?: PageReference;
+
+    @wire(NavigationContext as any)
+    navContext?: ContextId;
+
+    connectedCallback(): void {
+        if (this.pageReference && this.navContext) {
+            const url = generateUrl(this.navContext, this.pageReference);
+            console.log(`"${url}" is the URL for this page reference:`, this.pageReference);
+        }
+    }
+}
+```
+
+## Lightning Navigation
+
+The `@lwrjs/router` package provides an implementation of [`lightning/navigation`](http://component-library-dev.herokuapp.com/docs/component-library/bundle/lightning-navigation/documentation), which defines the `NavigationMixin` and the `CurrentPageReference` wire adapter. This allows a component to be written once and plugged in anywhere that supports the `lightning/navigation` contracts.
+
+The `lightning/navigation` module is an [alias](https://github.com/salesforce/lwc-rfcs/blob/master/text/0020-module-resolution.md#aliasmodulerecord) for the `lwr/navigation` module, so it includes the same [wires](#navigation-wires) and [APIs](#navigation-apis), along with the [`NavigationMixin`](#navigationmixin).
+
+> **Important** Pick either `lightning/navigation` or `lwr/navigation` to use throughout your app. Otherwise, there could be JavaScript bundling clashes when running in `prod` mode.
+
+### `NavigationMixin`
+
+Some developers may prefer to use the `NavigationMixin` over the [`navigate()` and `generateUrl()` APIs](#navigation-apis). Both offer the same functionality, but only the `NavigationMixin` is compatible with Lightning Experience (LEX). So a developer writing a component for use in both LWR and LEX should choose the `NavigationMixin`.
+
+```js
+import { LightningElement } from 'lwc';
+import { NavigationMixin } from 'lightning/navigation';
+
+const pageRef = {
+    type: 'standard__recordPage',
+    attributes: {
+        recordId: '001xx000003DGg0AAG',
+        objectApiName: 'Account',
+        actionName: 'view',
+    },
+};
+
+export default class Example extends NavigationMixin(LightningElement) {
+    // Navigate to a page reference
+    navPageRef() {
+        this[NavigationMixin.Navigate](pageRef);
+    }
+    // Generate a URL for a page reference
+    getUrl() {
+        this[NavigationMixin.GenerateUrl](pageRef).then((url) => console.log(url));
+    }
+}
+```