@nxgt/material 3.79.1 → 3.80.0

package/docs/components/navigation-and-layout.md

@@ -7,15 +7,20 @@ documentation-site shell. Everything is imported from
 
 | | Component | What it does |
 | --- | --- | --- |
-| <img src="../previews/navigation-layout-appshell.webp" width="96" alt=""> | [ActivityLayout](#activitylayout) | App shell: sidebar, header, breadcrumbs, titled page; a route's `handle.title` is the page's `h1` in the app bar (it labels `main`; `usePageTitleFocus()` focuses it after a navigation), `handle.titleAfter` / `titleAfter` a node right after it, outside the `h1` (a record's `Switcher`, or `<Switcher size="compact">` for an icon-only one), `headerContext` a small tenant line after it from md up, `breadcrumbRoot` a text root crumb or (`icon: true`) the home icon with its own target and name, `breadcrumb={false}` no trail, `context` the tenant line atop the phone's menu sheet; `menuOpen` / `onMenuOpenChange` control the phone's menu sheet, which closes itself on a followed link or any location change |
+| <img src="../previews/navigation-layout-appshell.webp" width="96" alt=""> | [ActivityLayout](#activitylayout) | App shell: sidebar, header, breadcrumbs, titled page; `header` sets the app bar (small, center, medium or large collapsing on scroll, hide on scroll, a route's `handle.header`, tabs under it, a route's `handle.back` arrow); a route's `handle.title` is the page's `h1` in the app bar (it labels `main`; `usePageTitleFocus()` focuses it after a navigation), `handle.titleAfter` / `titleAfter` a node right after it, outside the `h1` (a record's `Switcher`, or `<Switcher size="compact">` for an icon-only one), `headerContext` a small tenant line after it from md up, `breadcrumbRoot` a text root crumb or (`icon: true`) the home icon with its own target and name, `breadcrumb={false}` no trail, `context` the tenant line atop the phone's menu sheet; `menuOpen` / `onMenuOpenChange` control the phone's menu sheet, which closes itself on a followed link or any location change |
 | <img src="../previews/navigation-layout-accountmenu.webp" width="96" alt=""> | [AccountMenu](#accountmenu) | The app bar's avatar menu: the account, the app's links, Sign out |
 | <img src="../previews/navigation-layout-authcard.webp" width="96" alt=""> | [AuthCard](#authcard) | Signed-out page frame: one `main`, a centred card, its title the `h1` |
 | <img src="../previews/navigation-layout-sidebar.webp" width="96" alt=""> | [Sidebar](#sidebar) | Collapsible navigation sidebar |
-| <img src="../previews/navigation-layout-topappbar.webp" width="96" alt=""> | [TopAppBar, BottomAppBar](#topappbar) | Top and bottom bars |
+| <img src="../previews/navigation-layout-topappbar.webp" width="96" alt=""> | [TopAppBar, BottomAppBar](#topappbar) | Top (small, center, medium, large) and bottom bars |
+| | [AppSearchBar, SearchView](#appsearchbar) | The app bar's search: a pill with a docked results panel from 768px, a full-screen search view on a phone |
 | <img src="../previews/navigation-layout-stickyactionbar.webp" width="96" alt=""> | [StickyActionBar](#stickyactionbar) | A page's main decision, stuck to the bottom on a phone, inline from `md` |
 | <img src="../previews/navigation-layout-breadcrumb.webp" width="96" alt=""> | [Breadcrumb](#breadcrumb) | Breadcrumb primitives |
 | <img src="../previews/navigation-layout-listdetailslayout.webp" width="96" alt=""> | [ListDetailsLayout, PaneLayout, ThreadLayout](#listdetailslayout) | Page layouts that adapt to phones |
-| <img src="../previews/navigation-layout-responsivegrid.webp" width="96" alt=""> | [ResponsiveGrid](#responsivegrid) | Container-query grid, 1 to 5 columns, or `auto-fill` columns by a minimum tile width (`minItem`) |
+| <img src="../previews/navigation-layout-settingslayout.webp" width="96" alt=""> | [SettingsLayout](#settingslayout) | Grouped settings sections beside the selected section's page; list then page on a phone, the section kept in the URL |
+| <img src="../previews/navigation-layout-landinglayout.webp" width="96" alt=""> | [LandingLayout, LandingSection, SiteFooter](#landinglayout) | The frame of a public landing page outside the app shell: a top bar on `TopNav` (a drawer on a phone), a hero and bands on the theme's surfaces, a footer of link columns |
+| <img src="../previews/navigation-layout-responsivegrid.webp" width="96" alt=""> | [ResponsiveGrid](#responsivegrid) | Container-query grid, 1 to 5 columns, or `auto-fill` columns by a minimum tile width (`minItem`); `ResponsiveGrid.Item` spans, `dense` packing, `flow="masonry"` |
+| <img src="../previews/navigation-layout-dashboardgrid.webp" width="96" alt=""> | [DashboardGrid, DashboardTile](#dashboardgrid) | Tiles with spans that the user rearranges in an edit mode, by drag or keyboard; the order is the app's |
+| <img src="../previews/navigation-layout-editorlayout.webp" width="96" alt=""> | [EditorLayout](#editorlayout) | The editor page: toolbar, canvas that scrolls alone, properties at the end (a bottom sheet on a phone), optional outline at the start |
 | <img src="../previews/navigation-layout-sectioncolumns.webp" width="96" alt=""> | [SectionColumns](#sectioncolumns) | Short page sections side by side from a viewport breakpoint, stacked below it |
 | <img src="../previews/navigation-layout-recordpage.webp" width="96" alt=""> | [RecordPage, RecordDetails](#recordpage) | The page of one record: header card, content, facts as a side panel from `xl` |
 | <img src="../previews/navigation-layout-resizable.webp" width="96" alt=""> | [ResizableGroup](#resizablegroup) | Resizable panels |
@@ -26,9 +31,14 @@ documentation-site shell. Everything is imported from
 | <img src="../previews/navigation-layout-stepper.webp" width="96" alt=""> | [Stepper](#stepper) | Clickable steps with progress: shaped indicators, optional steps, a phone header |
 | <img src="../previews/navigation-layout-steps.webp" width="96" alt=""> | [Steps](#steps) | Numbered editorial steps |
 | <img src="../previews/navigation-layout-hero.webp" width="96" alt=""> | [Hero](#hero) | Landing band, or a compact greeting band, with an optional `Background` |
-| <img src="../previews/navigation-layout-doc.webp" width="96" alt=""> | [Doc](#doc) | Documentation site shell |
+| <img src="../previews/navigation-layout-doc.webp" width="96" alt=""> | [Doc](#doc) | Documentation site shell, standalone or inside the app shell |
 | <img src="../previews/navigation-layout-background.webp" width="96" alt=""> | [Background](#background) | Gradient backdrop with colour blobs; the `/backgrounds` one takes its unset props from the nearest theme |
-| | [NavigationRail](#navigationrail) | Placeholder, no props yet |
+| | [NavigationBar](#navigationbar) | Bottom bar of 3 to 5 destinations with badges and a More sheet |
+| | [TopNav](#topnav) | Top bar of destinations with dropdowns |
+| | [NavigationDrawer](#navigationdrawer) | Drawer in sections, standard or modal |
+| | [NavigationRail](#navigationrail) | Rail with a FAB slot, badges and an expanded state |
+| | [NavigationRailPanel](#navigationrailpanel) | Second-level panel beside the rail, listing the current entry's children |
+| | [NavigationToolbar](#navigationtoolbar) | Floating pill of navigation links at the bottom centre, optionally sliding away on scroll |
 
 ## ActivityLayout
 
@@ -59,7 +69,11 @@ const items: MenuItem[] = [
 
 Parts: `ActivityLayout` (the chrome), `ActivityContent` (one screen),
 `AppSidebar`, `AppHeader` and `AppBreadcrumb`, which the layout composes and
-which work alone. `usePageTitleFocus()` returns a function that focuses the app bar's page title (the content region without one) after a navigation; see the guide.
+which work alone. `AppHeader` also takes `tabs` (`ReactNode`, default none: a
+`TabsNav` as a row at the foot of the bar, pinned when the bar hides) and `back`
+(`ShellBack`, default none: the back arrow, named "Back" or "Back to <label>"
+and drawn before the menu button); a complete example with a `MemoryRouter` is in
+the [app shell guide](../guides/app-shell.md#using-the-parts). `usePageTitleFocus()` returns a function that focuses the app bar's page title (the content region without one) after a navigation; see the guide.
 
 Under `viewport-fit=cover` the frame, the sticky rail and header, and the
 phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
@@ -67,7 +81,7 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `items` | `MenuItem[]` | — | `label` (already translated), `url`, `icon`, `footer`, `display` (`'icon'`: a round icon-only button, the label as tooltip and name; see the [app shell guide](../guides/app-shell.md)), `badge` (`true` a dot, a number a count up to "99+"), `badgeLabel` (see [Badges](../guides/app-shell.md#badges)) |
+| `items` | `MenuItem[]` | — | `label` (already translated), `url`, `icon`, `footer`, `display` (`'icon'`: a round icon-only button, the label as tooltip and name; see the [app shell guide](../guides/app-shell.md)), `badge` (`true` a dot, a number a count up to "99+"), `badgeLabel` (see [Badges](../guides/app-shell.md#badges)), and `children` (read by `navigation="top"`, which opens them in a dropdown under a parent that is then only a trigger; by `navigation="two-level"`, which lists them in the panel beside the rail, one level deep; by the phone's menu sheet and the expanded sidebar, which nest them under the parent's own link), `group`, `bar`, `priority` for the navigation presets that read them (the drawer reads `group`, the bar `bar` and `priority`; the floating toolbar, not drawn yet, is the only preset still to read them) |
 | `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href`; see the [app shell guide](../guides/app-shell.md). Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 | `logo`, `name` | `AppLogo` (`ReactNode \| string \| AppLogoImage`, `AppLogoImage` = `{ src, alt? }`), `string` | — | the app's logo alone in the collapsed rail, named by `name` (also its tooltip); logo and name side by side in the phone's menu sheet |
 | `context` | `ReactNode` | — | a line at the top of the phone's menu sheet, above the brand: the current tenant's name; `name` stays the app's brand; `AppHeader` and `AppSidebar` take it too (see the [app shell guide](../guides/app-shell.md#the-brand-logo-and-name)) |
@@ -90,6 +104,10 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 | `notice` | `ReactNode` | — | `ActivityContent`: a notice above the column and the side panel, at their width, taking its own height; first on a phone |
 | `aside`, `asideLabel` / `asideLabelledBy` | `ReactNode`, `string` | — | `ActivityContent`: a side panel, a named `complementary` landmark, beside the content from 1280px (CSS only), stacked below; sticky under the app bar |
 | `asideSide` / `asideWidth` / `asideFrom` / `asideSticky` / `asideStack` | `'start' \| 'end'` / `'sm' \| 'md' \| 'lg' \| string` / `'lg' \| 'xl' \| '2xl'` / `boolean` / `'before' \| 'after'` | `'end'` / `'md'` / `'xl'` / `true` / `'after'` | `ActivityContent`: the panel's side, width (16, 20, 24rem), breakpoint, stickiness and stacking order (see the [app shell guide](../guides/app-shell.md#a-side-panel-and-a-readable-width)) |
+| `navigation` | `ShellNavigation \| { phone?, tablet?, desktop?, hideOnScroll?, persistKey? }` | `{ phone: 'modal-drawer', tablet: 'rail', desktop: 'rail' }` | `ActivityLayout`: the navigation per window size (phone below 768px, tablet to 1279px, desktop from 1280px). Every `ShellNavigation` name is drawn: `'modal-drawer'`, `'rail'`, `'rail-expanded'`, `'drawer'`, `'sidebar'`, `'top'`, `'two-level'`, `'floating'`, `'bar'` and `'none'`. `hideOnScroll` (a field of this object, `false` by default) slides the `'floating'` toolbar away on scroll; no other preset reads it. `persistKey` (a field of this object) remembers the `'rail-expanded'` rail's, the `'sidebar'`'s and the `'two-level'` panel's state. A name alone (`navigation="sidebar"`, `"drawer"`, `"top"`, `"two-level"`) leaves a phone its default navigation; `{ phone: 'sidebar' }` draws it there. A phone never draws `'rail'` or `'rail-expanded'`: it keeps its menu sheet. `navigation="bar"` alone is phone-only (hidden from 768px, where the default rail shows; `{ tablet: 'bar' }` keeps it there). `'floating'` is drawn at every size, the phone included. See [`navigation` and `header`](../guides/app-shell.md#navigation-and-header) |
+| `navigationFab` | `ReactNode \| ({ expanded }) => ReactNode` | — | `ActivityLayout`: the screen's primary action, at the top of the `'rail-expanded'` rail (a `Fab`; the function form receives the rail's state). The other presets do not draw it |
+| `sidebarExpanded` / `defaultSidebarExpanded` / `onSidebarExpandedChange` | `boolean` / `boolean` / `(expanded: boolean) => void` | — / `false` / — | `ActivityLayout`: the `'sidebar'`'s expanded state (labels beside the icons; it starts collapsed), controlled or not; with `navigation.persistKey` the last choice is kept and read after hydration |
+| `header` | `'small' \| 'center' \| 'medium' \| 'large' \| 'none' \| { variant, collapse?, hideOnScroll?, tabs?, search? }` | `'small'` | `ActivityLayout`: the app bar's size. The five variants and `hideOnScroll` are drawn; `search` draws an `AppSearchBar` (see [AppSearchBar](#appsearchbar)); `tabs` (a `TabsNav`) draws a row stuck under the bar, which stays pinned when the bar hides (see [Tabs under the app bar](../guides/app-shell.md#tabs-under-the-app-bar)); a route's `handle.back` (`ShellBack`: `{ to, label? }` or `true`) draws a back arrow before the title, the phone's menu button following it while the phone has the menu sheet (see [The back arrow](../guides/app-shell.md#the-back-arrow)). A route's `handle.header` overrides it; a `'medium'` or `'large'` header needs a `handle.title`, else it stays small; `'none'` also drops the phone's menu button, so pair it with `navigation="bar"`. See [The app bar variants](../guides/app-shell.md#the-app-bar-variants), [Scroll direction](../guides/app-shell.md#scroll-direction) and [Room at the bottom](../guides/app-shell.md#room-at-the-bottom) |
 | `align` | `'start' \| 'center'` | `'start'` | `ActivityLayout`, `AppSidebar`: the collapsed rail's entries sit right under the brand, or `'center'` for centred in the height below it |
 | `backdrop` | `ReactNode \| false` | — | `ActivityLayout`: an exception to the theme's background (drawn by default; Lavande's is the built-in gradient and blobs); `false` draws a plain page. A node is a decorative background behind the frame: a `Background` preset from `@nxgt/material/backgrounds`. Rendered in an `inert`, `aria-hidden` layer as wide as the content column and one viewport high, fixed in the viewport while the content scrolls; the chrome (app bar, breadcrumb, tabs strip) is lightly translucent and frosted over it (80%, 87% for the sidebar, breadcrumb and tabs strip, 92% and no blur under `prefers-reduced-transparency` or without `backdrop-filter`), and the lists, tables and cards stay opaque; `--nxgt-backdrop-chrome` sets the chrome's fill and `--nxgt-backdrop-surface` the lists'. See [Use a background preset behind the shell](../guides/app-shell.md#use-a-background-preset-behind-the-shell) |
 | `routeTransition` | `boolean \| Omit<ViewTransitionProps, 'children' \| 'ref'>` | `true` | `ActivityLayout`: React's `<ViewTransition>` around the content region, so a navigation cross-fades it (by default only when the pathname changes, not on a search change, a fetcher or a revalidation). `false` renders none (your app has its own boundary); an object passes `default` / `update` classes, `name`, callbacks through. `ROUTE_TRANSITION_CLASS` (`'nxgt-route'`) is exported for nested boundaries. See [Route transitions](../guides/app-shell.md#route-transitions) |
@@ -212,6 +230,8 @@ import { AuthCard, Button, EmailField, LanguageSwitcher, PasswordField } from '@
 | `banner` | `ReactNode` | — | above that row (an update notice) |
 | `footer` | `ReactNode` | — | under the card |
 | `backdrop` | `ReactNode \| false` | the theme's background | what is drawn behind the page: a `Background` preset or any node; `false` for none. Without a theme provider nothing is drawn |
+| `layout` | `'card' \| 'split'` | `'card'` | `'split'`: two columns from 768px, the `visual` side and the form side; a phone shows the form alone under the brand row |
+| `visual` | `ReactNode` | — | with `layout="split"`: the side beside the form (a `Background` preset with `className="absolute inset-0"`, a picture, a tagline); hidden below 768px |
 | `keepClear` | `boolean \| 'gaps'` | `true` | glyphs (shapes or icons) of the backdrop that would meet the brand row, the card or the page's surfaces, text or controls are dropped (never moved); `false` lets them run under the card; `'gaps'` also keeps a glyph that fits in a gap of 24px or more between two surfaces |
 
 ```tsx
@@ -234,6 +254,28 @@ fade, a glyph crossing the layer's edge too; none is cut or moved. Where `Resize
 is drawn as it is. The server renders the layer and no measurement, so there
 is no hydration mismatch. Under `prefers-reduced-motion` the fade is off.
 
+**Split page.** `layout="split"` (unset is the centred card) makes the `main`
+a two-column grid from 768px by CSS classes only, so the server and the
+client render the same markup. The `visual` side (`data-slot="auth-card-visual"`)
+takes the first column, is hidden below 768px and is `bg-muted` with
+`text-foreground`; put a `Background` preset or a picture in it, and mark
+a purely decorative node `aria-hidden`. The form side
+(`data-slot="auth-card-form-side"`) is opaque (`bg-background`) and carries
+the safe-area padding, so text and controls never sit on a backdrop, in light
+or in dark. The brand row, the `h1`, the form and the footer are all in the
+form side: a phone loses nothing but the visual.
+
+```tsx
+<AuthCard
+  layout="split"
+  title="Sign in"
+  brand={<Logo />}
+  visual={<Background className="absolute inset-0" aria-hidden="true" />}
+>
+  {form}
+</AuthCard>
+```
+
 A non-error notice goes into a `role="status"` region that is always
 rendered (zero height while empty), so a screen reader announces a notice
 that appears later; an error is a `role="alert"` inserted when it shows.
@@ -338,14 +380,133 @@ import { BottomAppBar, IconButton, TopAppBar, Typography } from '@nxgt/material/
 </BottomAppBar>
 ```
 
-Both are layout surfaces with no props of their own (they take a `div`'s):
-`TopAppBar` is a bordered row, `BottomAppBar` spaces its children and styles
-the one with `data-state="active"`.
+`BottomAppBar` spaces its children and styles the one with
+`data-state="active"`; both take a `div`'s props. `TopAppBar` is a bordered row
+with a `variant`: `'small'` (the default), `'center'` (the row's content
+centred), and `'medium'` or `'large'`, which draw the `headline` on a second
+row in display type (without a `headline` they are small). It does not scroll
+by itself: `ActivityLayout`'s `header` does that for the shell's own bar (see
+the [app shell guide](../guides/app-shell.md#the-app-bar-variants)).
+
+```tsx
+import { Menu } from 'lucide-react';
+import { IconButton, TopAppBar } from '@nxgt/material/components';
+
+<TopAppBar variant="large" headline={<h1>Projects</h1>}>
+  <IconButton variant="ghost" aria-label="Open menu"><Menu /></IconButton>
+</TopAppBar>
+```
 
 **Storybook:** `Navigation & layout/TopAppBar`, `Navigation & layout/BottomAppBar` · **Vue:** `TopAppBar`, `BottomAppBar`
 
 ---
 
+## AppSearchBar
+
+The app bar's search. From 768px it is a pill (a filled, fully rounded search
+field) with the `results` in a panel docked under it, as wide as the pill; on a
+phone it is a search button that opens `SearchView`, a full-screen dialog with a
+back arrow, the field and the results. Both are rendered, one hidden by a breakpoint class, so the server's and the
+client's markup match; the shortcut acts on the visible one. The text is shared
+by the two, so a window resize keeps it, and a dialog open on a phone closes when
+the window grows to 768px. Draw it in the shell with `header.search`:
+
+```tsx
+import { useState } from 'react';
+import { ActivityLayout, ListTile } from '@nxgt/material/components';
+
+function Shell() {
+  const [query, setQuery] = useState('');
+  const hits = search(query); // your own: returns { id, title }[]
+  return (
+    <ActivityLayout
+      items={items}
+      header={{
+        variant: 'small',
+        search: {
+          value: query,
+          onValueChange: setQuery,
+          shortcut: '/',
+          resultCount: hits.length,
+          onSubmit: (text) => goToResults(text),
+          results: ({ close }) => (
+            <ul className="m-0 list-none p-0">
+              {hits.map((hit) => (
+                <ListTile
+                  key={hit.id}
+                  as="li"
+                  variant="divided"
+                  title={hit.title}
+                  href={`/records/${hit.id}`}
+                  onClick={close}
+                />
+              ))}
+            </ul>
+          ),
+        },
+      }}
+    />
+  );
+}
+```
+
+A route sets it with `handle.header`, like any header option (`search: false`
+hides it there). `AppSearchBar` and `SearchView` also stand on their own, for a
+bar of your own or a search button of your choice:
+
+```tsx
+import { useState } from 'react';
+import { Button, SearchView } from '@nxgt/material/components';
+
+function Finder() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Find</Button>
+      <SearchView open={open} onOpenChange={setOpen} label="Find a page" results={<Pages />} />
+    </>
+  );
+}
+```
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` / `onValueChange` | `string` / `string` / `(value: string) => void` | — / `''` / — | The text, controlled or not. `onValueChange` is called for every change, not debounced: debounce the lookup yourself |
+| `placeholder` | `string` | `'Search'` (`material.search-field.placeholder`) | The field's placeholder |
+| `label` | `string` | `'Search'` (`material.app-header.search`) | The accessible name of the form, the field, the phone's button and the dialog |
+| `onSubmit` | `(value: string) => void` | — | Enter in the field. The panel and the phone's view close after it |
+| `results` | `ReactNode \| ({ value, close }) => ReactNode` | — | Under the pill in a panel (named `material.app-header.search-results`), below the field in the view. Unset: no panel on desktop, an empty view on a phone. Call `close` when a result is chosen |
+| `resultCount` | `number` | — | Announced politely ("3 results", `material.app-header.result-count`) when it changes. Unset: nothing is announced |
+| `loading` | `boolean` | `false` | A spinner in the field in place of the clear button |
+| `shortcut` | `string` | — | A key such as `"/"` or `"Ctrl+K"` (`mod` is Ctrl or Cmd): shown as a hint while the field is empty, set as `aria-keyshortcuts`, and bound on the document. It focuses the pill, or opens the view on a phone. A bare key is ignored while the focus is in another field |
+| `leading` / `trailing` | `ReactNode` | — | Controls before / after the pill (desktop). `trailing` also sits after the field in the phone's view |
+| `className` | `string` | — | On the bar (desktop) or the phone's button |
+| `open` / `onOpenChange` | `boolean` / `(open: boolean) => void` | — | `SearchView` only: required, it is controlled |
+
+Behaviour, all of it stated so it can be relied on:
+
+- The pill opens its panel when it is clicked, typed in or given ArrowDown, and
+  only when `results` is set; focus put there by the `shortcut` does not open
+  it. Focus stays in the field. ArrowDown moves into the panel (the portal is
+  not in the tab order after the field), Escape closes the panel and brings the
+  focus back to the field, a click outside closes it. Escape in a field that
+  holds text clears it and closes the panel in the same press.
+  Clearing the text (the button, Escape) does not reopen the panel.
+- `SearchView` mounts only while open (the server draws nothing). It is a modal
+  `role="dialog"` named by `label`, the page behind it is inert and its focus
+  is trapped. Opening puts the focus in the field; closing (the back arrow, Escape,
+  Enter, a link; Escape in a field that holds text clears it and closes in the same press, as the field's own Escape does) returns it to the element that opened it. Targets are 48px,
+  the sizes come from `--nxgt-search-h` in `app-search.css` (2.75rem in the bar,
+  3rem in the view). It animates like any dialog and not under reduced motion.
+- The pill is 44px high and takes up to 28rem, giving way to the title when the
+  bar is narrow. On a phone the button is 48px.
+- Strings are `material.app-header.*` and `material.search-field.*`, in English
+  and French; the library is React only for this part.
+
+**Storybook:** `Navigation & layout/AppSearchBar`, `Navigation & layout/AppShell` (header search) · **Vue:** not yet
+
+---
+
 ## StickyActionBar
 
 ![StickyActionBar](../previews/navigation-layout-stickyactionbar.webp)
@@ -468,30 +629,259 @@ open the pane (`ListDetailsTrigger` takes the `view` to show), and their
 `children` / `className` can be functions of the layout state. A server, which
 has no screen width, renders the wide layout, as does a hydrating client; a
 phone switches right after hydrating. `PaneLayout`'s inline pane is hidden by
-CSS at 648 px and narrower, so a phone never sees it flash before the sheet
+CSS at 648 px and narrower (768 px with `phone` set), so a phone never sees it flash before the sheet
 takes over. A page rendered only in the browser starts on the real layout.
+
+`PaneLayout` takes three opt-in props for how the pane behaves on a phone
+(#2103); left unset, nothing above changes:
+
+```tsx
+<PaneLayout phone="bottom" breakpoint="container" paneWidth="lg" paneSide="right">
+  <PaneLayout.Content>
+    <PaneLayout.Trigger aria-label="Filters" className={({ isMobile }) => (isMobile ? '' : 'hidden')}>…</PaneLayout.Trigger>
+    {results}
+  </PaneLayout.Content>
+  <PaneLayout.Pane sheetTitle="Filters">{filters}</PaneLayout.Pane>
+</PaneLayout>
+```
+
+- `phone`: `'sheet'` (side sheet), `'bottom'` (bottom sheet) or `'stack'` (the
+  pane sits under the content, no overlay; the trigger shows or hides it).
+  Once set, the switch is at 768 px (`md`) instead of 648 px. The sheets are
+  the library `Sheet`: focus moves in, Escape and the close button close it,
+  and focus returns to the trigger.
+- `breakpoint`: `'viewport'` (default) or `'container'`, which measures the
+  `PaneLayout` itself (a CSS container, 48rem = 768 px), so a layout in a
+  narrow column of a wide screen gets the phone layout. The root becomes the
+  container and the flex row moves to an inner `data-slot="pane-layout-body"`.
+- `paneWidth`: `'sm'` (16rem), `'md'` (20rem, default) or `'lg'` (24rem) for
+  the inline pane; no style attribute, so it holds under a strict CSP.
+- With `phone` or `breakpoint` set, the inline pane is an `<aside>` named by
+  `sheetTitle` (default `Side Panel`), a landmark; the historical markup is a
+  `div`. `usePaneLayout()` and the function children also get `phone`,
+  `breakpoint` and `paneWidth`.
 `ThreadLayout` is a centred column over the app
 [background](#background) on the page ground (`bg-ground`, so a `bg-card` card stands apart) for focused flows (sign-in, onboarding), with no
-app bar.
+app bar. `width`, `stepperPlacement` and a sticky `footer` make it a centred form or a wizard with a side rail (see "A centred form or a wizard" below).
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `activeView` / `defaultActiveView` / `onActiveViewChange` | `'list' \| 'details'` | `'list'` | `ListDetailsLayout`: which view a phone shows |
+| `phone` | `'sheet' \| 'bottom' \| 'stack'` | unset | `PaneLayout`: how the pane shows below 768 px (unset: side sheet at 648 px and narrower) |
+| `paneWidth` | `'sm' \| 'md' \| 'lg'` | `'md'` | `PaneLayout`: width of the inline pane |
 | `listPosition` | `'left' \| 'right'` | `'left'` | `ListDetailsLayout` |
 | `breakpoint` | `'viewport' \| 'container'` | `'viewport'` | `ListDetailsLayout`: what the 648 px phone layout follows, the window or the layout's own width |
+| `breakpoint` | `'viewport' \| 'container'` | `'viewport'` | `PaneLayout`: measure the viewport or the layout's own width |
+| `inspector` | `boolean` | `false` | `ListDetailsLayout`: a third pane (`ListDetailsLayout.Inspector`); `activeView` then also takes `'inspector'`; `ListDetailsLayout.Trigger view="inspector"` needs `inspector` as well |
+| `history` / `historyParam` | `'push' \| 'replace'` / `string` | — / `'view'` | `ListDetailsLayout`: keep the view in the URL (`?view=details`), through React Router |
+| `listWidth` / `resizable` / `onListWidthChange` | `number` / `boolean` / `(width) => void` | `320` / `false` | `ListDetailsLayout`: the list pane's width in px; `resizable` adds a keyboard and pointer separator, 240 to 480 px |
 | `back` | `boolean \| ReactNode` | — | `ListDetailsLayout.Details`: a bar with the way back to the list, on a phone only; `true` is the translated "Back to the list" (`material['list-details'].back`), a node is its label |
 | `open` / `defaultOpen` / `onOpenChange` | `boolean` | `false` | `PaneLayout`: pane shown |
 | `paneSide` | `'left' \| 'right'` | `'left'` | `PaneLayout` |
 | `sheetTitle` | `string` | "Side Panel" (translated, `material['pane-layout']['sheet-title']`) | `PaneLayout.Pane`: screen-reader title of the sheet on phones |
-| `header`, `stepper` | `ReactNode` | — | `ThreadLayout`: above the column, and directly above the content |
+| `header` | `ReactNode` | — | `ThreadLayout`: above the column |
+| `stepper` | `ReactNode \| (placement) => ReactNode` | — | `ThreadLayout`: directly above the content; with `stepperPlacement` it is wrapped in a named `nav` and a function is called once with `'top'` or `'side'` |
+| `width` | `'form' \| 'reading' \| 'wide'` | unset | `ThreadLayout`: a centred column of 32, 48 or 72 rem, its content stretched to fill it (unset: the 14-of-16-column track, children centred at their own width) |
+| `footer` | `ReactNode` | — | `ThreadLayout`: a sticky action bar (`data-slot="thread-layout-footer"`) that stays in view and clear of `--nxgt-bottom-chrome` and the home bar |
+| `stepperPlacement` | `'top' \| 'side'` | unset | `ThreadLayout`: with a `stepper`, wraps it in a `nav` named "Progress" (`material.navigation.steps`); `'side'` makes it a sticky rail beside the column from 1280 px, above it below |
+
+`useListDetails()` and `usePaneLayout()` read the state from inside (`useListDetails()` also gives `inspectorOpen`, `listWidth` and `setListWidth`).
 
-`useListDetails()` and `usePaneLayout()` read the state from inside.
+**A centred form or a wizard.** `ThreadLayout` is the page for both:
 
-**The way back on a phone.** With `back` on `ListDetailsLayout.Details` the details open under a bar with a labelled back button (`ListDetailsLayout.Back`, also usable in your own header; it renders nothing on a wide screen or when the list shows). On a phone the layout also moves the focus: to the details when a row opens them, then back to that row when the way back is taken, also when `activeView` is controlled by the screen (a URL-driven list and detail). A wide screen shows both panes, with no bar and no focus moves. Leave `back` out and `ListDetailsTrigger view="list"` still works as before.
+```tsx
+<ThreadLayout
+  width="form"
+  stepperPlacement="side"
+  stepper={() => <Stepper steps={steps} active={step} orientation="vertical" />}
+  footer={<><Button variant="ghost">Back</Button><Button>Next</Button></>}
+>
+  {stepForm}
+</ThreadLayout>
+```
+
+The column, the rail and the footer are placed by CSS breakpoint classes only
+(no hook, no style attribute), so the server and the client render the same
+markup. `stepper` is a node or a function called once with the placement (`'side'` or `'top'`), so the caller picks the `Stepper`'s orientation; the element is placed by CSS, so with `'side'` a vertical `Stepper` is a rail from 1280px and sits above the form below it. With `stepperPlacement` unset a node is rendered as it always was. The footer's `bottom` offset and the page's bottom
+padding use `max(var(--nxgt-bottom-chrome, …), env(safe-area-inset-bottom))`,
+so a bottom navigation bar or a docked media bar never covers it. With none
+of `width`, `footer` and `stepperPlacement` the markup is the historical one.
+
+**The way back on a phone.** With `back` on `ListDetailsLayout.Details` the details open under a bar with a labelled back button (`ListDetailsLayout.Back`, also usable in your own header; it renders nothing on a wide screen or when the list shows). On a phone the layout also moves the focus: to the details when a row opens them, then back to that row when the way back is taken, also when `activeView` is controlled by the screen (a URL-driven list and detail). A wide screen shows both panes, with no bar and no focus moves. A heading (or any element) in the details marked `data-pane-focus` takes that focus instead of the pane; it needs `tabIndex={-1}`: `<h2 tabIndex={-1} data-pane-focus>Record</h2>`. `SettingsLayout` uses it for its page heading. Leave `back` out and `ListDetailsTrigger view="list"` still works as before.
+
+**Inspector, a third pane.** `<ListDetailsLayout inspector>` with a `ListDetailsLayout.Inspector title="Properties"` after the details. It is open while the view is `'inspector'` (`setActiveView('inspector')`, a `<ListDetailsLayout.Trigger inspector view="inspector">`, or `activeView`); It renders nothing otherwise. `useListDetails()` keeps `activeView` to `'list' | 'details'` (`'details'` while it is open) and gives `inspectorOpen`. From 1280 px it sits beside the details (three panes); below 1280 px it overlays them (a CSS switch, so the server's markup is the right one and nothing flips after hydration), and Escape or its close button closes the overlay; on a phone it is one more step after the details, with a back button to them. Its `title` is a heading that also names the `complementary` landmark: the focus moves to it when the inspector opens, and goes back to the control that opened it when it closes. Without `inspector` the types stay `'list' | 'details'` and the markup is unchanged. `breakpoint="container"` makes the 1280 px threshold follow the layout's own width too (container queries).
+
+**Selection and view in the URL.** `history="push"` keeps the view in `?view=details` / `?view=inspector` (the list is no param), so the browser's Back button goes from the details to the list on a phone, and a reload or a shared link opens the same pane; the layout's own Back and the inspector's close take that Back when the entry before is theirs, so the history does not pile up. `history="replace"` rewrites the entry instead. The layout then owns `activeView`; `onActiveViewChange` is still called. `useListDetailsParam({ name = 'item', viewName = 'view', history = 'push' })` is the same for the selected record: `const [id, select] = useListDetailsParam()`, and `select(id, { open: 'details' })` writes the id and the view in one `setSearchParams` call. Both need a React Router above them.
+
+```tsx
+const [id, select] = useListDetailsParam();
+<ListDetailsLayout history="push" inspector resizable listWidth={300}>
+  <ListDetailsLayout.List>{rows.map((r) => (
+    <Row key={r.id} onClick={() => select(r.id, { open: 'details' })} />
+  ))}</ListDetailsLayout.List>
+  <ListDetailsLayout.Details back><Record id={id} /></ListDetailsLayout.Details>
+  <ListDetailsLayout.Inspector title="Properties"><Fields id={id} /></ListDetailsLayout.Inspector>
+</ListDetailsLayout>
+```
+
+**Resizable list.** `listWidth` sets the list pane's width in px (default `w-80`, 320 px; a `resizable` list with no `listWidth` starts at 320 px) and `resizable` adds a separator between the panes (`role="separator"`, `aria-valuenow`, `aria-valuemin` 240, `aria-valuemax` 480, named "Resize the list"): Arrow keys move it by 16 px (Shift: 64), Home and End go to the narrowest and the widest, a pointer drag resizes (a 16 px grab area on coarse pointers), and `onListWidthChange` is told. The width reaches the CSS as a custom property set from script (the CSP allows no `style` attribute), so the server renders the default width and a set width applies right after hydrating. The separator shows on a wide screen only. Strings: `material['list-details']` (`inspector-back`, `inspector-close`, `resize`).
 
 **Sizing.** The layout fills the box it is in: `h-full` and, in a flex column, `flex-1 min-h-0`, so a header above it and the layout under it share the height with no `h-dvh`. `breakpoint="container"` makes the single-view layout follow the layout's own width (a dialog, a column of a split view) rather than the window; the first render is the wide one, as on a server.
 
-**Storybook:** `Navigation & layout/ListDetailsLayout`, `Navigation & layout/PaneLayout`, `Navigation & layout/ThreadLayout` · **Vue:** `ListDetailsLayout`, `PaneLayout`, `ThreadLayout`
+**Storybook:** `Navigation & layout/ListDetailsLayout` (also `/Phone`, `/Inspector`), `Navigation & layout/PaneLayout`, `Navigation & layout/ThreadLayout` · **Vue:** `ListDetailsLayout`, `PaneLayout`, `ThreadLayout`
+
+---
+
+## SettingsLayout
+
+![SettingsLayout](../previews/navigation-layout-settingslayout.webp)
+
+The canonical settings screen, built on `ListDetailsLayout`: sections grouped
+in a list (an icon in a tinted well, a title, one line of description), and the
+page of the selected one beside it, with its heading and description above the
+rows. On a phone the list shows first; a tap opens the page, the focus moves to
+its heading, and Back (the bar over the page, or the browser's) returns to the
+tapped row. The selected section is the `?section=` search param, so a reload or
+a shared link opens the same page (on a phone too), and the other params are
+kept. It needs a router above it.
+
+```tsx
+import { ListTile, SettingsLayout } from '@nxgt/material/components';
+
+<SettingsLayout
+  search
+  sections={[
+    {
+      id: 'profile',
+      group: 'Account',
+      title: 'Profile',
+      description: 'Name, photo and language',
+      icon: <User />,
+      content: <ProfileForm />,
+    },
+    {
+      id: 'notifications',
+      group: 'Preferences',
+      title: 'Notifications',
+      description: 'Email and push',
+      icon: <Bell />,
+      keywords: 'mute quiet',
+      content: (
+        <ul className="m-0 grid list-none gap-1 p-0">
+          <ListTile as="li" title="Email" subtitle="A digest each morning" toggle={{ defaultChecked: true }} />
+        </ul>
+      ),
+    },
+  ]}
+/>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `sections` | `SettingsSection[]` (exported type) | required | `id`, `title`, `description`, `icon`, `group`, `keywords`, `disabled`, `content`. Sections with the same `group` sit together under its heading, in the order the groups first appear. Only the selected section's `content` renders; a missing or disabled `?section=` falls back to the first usable section |
+| `title` | `ReactNode` | "Settings" | The list's heading, the name of its `nav` landmark and the label of the phone's Back bar |
+| `search` | `boolean` | `false` | A search field over the sections (string title, description, group and `keywords`; every word must match) |
+| `param` / `viewParam` | `string` | `'section'` / `'view'` | The search params holding the section and the phone's view |
+| `breakpoint` | `'viewport' \| 'container'` | `'viewport'` | What the one-pane phone layout (648px or less) follows |
+| `listWidth` | `number` | 320 | The list pane's width in px |
+
+The section links are real links (`aria-current="page"` on the current one),
+all ending in `view=details`, beside the page too: a link must be the same on
+the server and the client, and a URL shared to a phone opens the page:
+beside the page a choice rewrites the history entry, on a phone it adds one.
+Build the page from the library's rows: `ListTile` (`toggle` for a switch row,
+`variant="divided"` in a card), the `*Field`s and `Banner`. The strings are
+`material.settings-layout.*` (English and French).
+
+## LandingLayout
+
+![LandingLayout](../previews/navigation-layout-landinglayout.webp)
+
+The frame of a public marketing or landing page, outside the app shell: a top
+bar, a `main` with the hero then the sections, and a footer. Three parts, all
+imported from `@nxgt/material/components`:
+
+- `LandingLayout`: the frame. The bar holds the brand (a link to `brandHref`),
+  your `items` as a `TopNav` from 768px (the same links open in a drawer from a
+  menu button below it, closing when one is followed) and your `actions` (a
+  sign-in link, a filled button) at every width. A skip link comes first and
+  `main` is the target. It needs a router above it, like `TopNav`.
+- `LandingSection`: one band: `eyebrow`, `title`, `description` and `actions`
+  over its children, on a `tone`, with a `width` and an `align`.
+- `SiteFooter`: the brand and a line about it, columns of links under headings,
+  a legal line and a slot beside it.
+
+```tsx
+import {
+  LandingLayout,
+  LandingSection,
+  LinkButton,
+  SiteFooter,
+} from '@nxgt/material/components';
+
+<LandingLayout
+  name="Acme"
+  items={[
+    { label: 'Features', url: '/features', icon: 'sparkles' },
+    { label: 'Pricing', url: '/pricing', icon: 'tag' },
+  ]}
+  actions={<LinkButton to="/start" variant="filled">Get started</LinkButton>}
+  hero={
+    <LandingSection
+      variant="hero"
+      tone="ground"
+      eyebrow="New"
+      title="Plan the work"
+      description="One calm place for the plan and the people."
+      actions={<LinkButton to="/start" variant="filled" size="lg">Start for free</LinkButton>}
+    />
+  }
+  footer={
+    <SiteFooter
+      brand="Acme"
+      groups={[{ title: 'Product', links: [{ label: 'Pricing', href: '/pricing' }] }]}
+      legal="© 2026 Acme"
+    />
+  }
+>
+  <LandingSection title="Everything in one place" align="center">…</LandingSection>
+  <LandingSection tone="muted" title="How it works">…</LandingSection>
+</LandingLayout>
+```
+
+| `LandingLayout` prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `MenuItem[]` | none | The destinations (top level only), in the bar and the phone's drawer |
+| `logo` / `name` / `brand` | `AppLogo` / `string` / `ReactNode` | none | The brand; `brand` replaces the logo and name and needs its own accessible name |
+| `brandHref` | `string` | `'/'` | Where the brand links |
+| `actions` | `ReactNode` | none | The end of the bar, at every width |
+| `hero` / `footer` | `ReactNode` | none | The first band and the footer |
+| `stickyHeader` | `boolean` | `true` | Keeps the bar in view while the page scrolls |
+| `navigationLabel` | `string` | "Navigation" | The bar's landmark name, already translated |
+| `linkComponent` | `AppShellLinkComponent` | provider's, else React Router's | The links' component |
+
+| `LandingSection` prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `tone` | `'background' \| 'muted' \| 'ground' \| 'primary'` | `'background'` | The surface: the page, a calm tint, the page ground, the primary container |
+| `width` | `'narrow' \| 'medium' \| 'default' \| 'full'` | `'default'` | The content's max width: 48rem, 64rem, 80rem, the whole band |
+| `align` | `'start' \| 'center'` | `'start'` | Where the intro (and its actions) sit |
+| `variant` | `'section' \| 'hero'` | `'section'` | `hero` is the page's first band: its title is the `h1`, set larger, with more room |
+| `media` | `ReactNode` | none | A visual beside the intro from `lg` (an illustration, a product card), under it below; mark decorative content `aria-hidden` |
+| `eyebrow`, `title`, `description`, `actions` | `ReactNode` | none | The intro; a `title` names the section as a region (`aria-labelledby`) |
+
+| `SiteFooter` prop | Type | Effect |
+| --- | --- | --- |
+| `brand`, `description` | `ReactNode` | The brand block and a line under it |
+| `groups` | `{ title: string; links: { label, href, external? }[] }[]` | Columns under `h2` headings, in one `nav` named by `label` (default "Footer"). A link to another site (`http(s):`) opens in a new tab with `rel="noopener noreferrer"`, a small arrow and a hidden "(opens in a new tab)" in its name; `mailto:` and `tel:` are plain links; the others use the link component. `external` overrides this automatic choice either way |
+| `linkComponent` | `AppShellLinkComponent` | The internal links' component: the prop, else `LinkComponentProvider`'s, else React Router's |
+| `legal`, `extra` | `ReactNode` | The legal line, and a slot beside it for social links, a language switcher or a theme toggle |
+
+Chrome, light and dark: in light the bar uses the page's surface and the footer a
+calm tint of it; in dark both take the card surface, one tone above the page. A
+band's text stays `foreground` on every tone, so the contrast holds in any theme.
+On a phone the footer's columns stack two by two, the brand first. The brand node (`brand`) is drawn twice, in the bar and in the phone's drawer, so keep it free of ids. The strings
+are `material.landing.*` (English and French). A whole page built from these
+parts is the `Guides/Recipes/Landing page` story.
 
 ---
 
@@ -529,12 +919,186 @@ their narrow width instead of stretching, and a wide screen gains columns
 variable; a custom length sets that variable in a `style` attribute (the
 variable only, never a grid style), so prefer a preset under a strict CSP
 (`style-src` without `'unsafe-inline'`). The `ResponsiveGrid` props are the
-`div`'s plus these two.
+`div`'s plus these.
+
+### Spans, dense packing and masonry
+
+```tsx
+<ResponsiveGrid minItem="sm" dense>
+  <ResponsiveGrid.Item span={{ base: 1, md: 2, xl: 3 }}>
+    <Chart />
+  </ResponsiveGrid.Item>
+  <ResponsiveGrid.Item rowSpan={2}>
+    <TaskList />
+  </ResponsiveGrid.Item>
+  <StatCard label="Orders" value="1,284" />
+</ResponsiveGrid>
+
+// A wall of notes of different heights, packed in columns.
+<ResponsiveGrid flow="masonry" minItem="md" gap="md">
+  {notes.map((note) => <NoteCard key={note.id} note={note} />)}
+</ResponsiveGrid>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `flow` | `'grid' \| 'masonry'` | `'grid'` | `'masonry'` packs tiles of any height in CSS columns, with no gaps; the column count follows `minItem` or the width, as above |
+| `dense` | `boolean` | `false` | `grid-auto-flow: dense`: later, smaller tiles move up into the holes a wide tile leaves |
+| `Item` `span` | `1 \| … \| 6 \| 'full'`, or `{ base?, md?, xl? }` | 1 | Columns the tile covers; each width applies from there up |
+| `Item` `rowSpan` | `1 \| … \| 4`, or `{ base?, md?, xl? }` | 1 | Rows the tile covers |
+
+`ResponsiveGrid.Item` is a `div`; a plain child needs no wrapper, only a tile
+with a span does. The widths are the grid's own, not the window's: `md` is a
+768px-wide grid (`@3xl`) and `xl` a 1280px one (`@7xl`). A span wider than the
+columns at that width adds implicit columns, so keep it within them
+(`span={{ base: 1, md: 2 }}`, not `span={2}` in a one-column grid).
+
+Two caveats are about reading order. With `dense` the eye reads the tiles in a
+different order than the keyboard and a screen reader (the source order). With
+`flow="masonry"` the tiles fill the first column top to bottom, then the next:
+Tab and the screen reader run down each column while the eye reads across.
+Use masonry for browsing (notes, a gallery), not for a sequence, and keep
+anything with an order in the default grid. Masonry ignores `span`, `rowSpan`
+and `dense`. It is CSS multi-column, which every browser supports; no
+JavaScript measures the tiles.
 
 **Storybook:** `Navigation & layout/ResponsiveGrid` · **Vue:** `ResponsiveGrid` (without `minItem` and `gap`)
 
 ---
 
+## DashboardGrid
+
+![DashboardGrid](../previews/navigation-layout-dashboardgrid.webp)
+
+Tiles in a responsive grid that the user can rearrange. A button turns on an
+edit mode; in it each tile shows a handle to drag with a pointer, or to pick up
+with Space, move with the arrow keys and drop with Space. The order belongs to
+the app: it stores it and passes it back.
+
+```tsx
+import { DashboardGrid, DashboardTile } from '@nxgt/material/components';
+
+const [order, setOrder] = useState(savedLayout); // string[] of tile ids
+
+<DashboardGrid aria-label="Dashboard" order={order} onOrderChange={setOrder}>
+  <DashboardTile id="revenue" title="Revenue" span={{ base: 1, md: 2 }}>
+    <RevenueChart />
+  </DashboardTile>
+  <DashboardTile id="orders" title="Orders">
+    <OrdersCount />
+  </DashboardTile>
+  <DashboardTile id="activity" title="Activity" span="full" rowSpan={2}>
+    <ActivityFeed />
+  </DashboardTile>
+</DashboardGrid>
+```
+
+| Prop (`DashboardGrid`) | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `order` / `defaultOrder` / `onOrderChange` | `string[]` / `string[]` / `(order) => void` | written order | The tiles' ids in display order. A tile the order does not list goes last; an id with no tile is ignored. `onOrderChange` gets the whole new order after a drop, a keyboard move or a move button |
+| `editing` / `defaultEditing` / `onEditingChange` | `boolean` | `false` | Edit mode, controlled or not |
+| `editButton` | `boolean` | `true` | The "Edit layout" / "Done" button above the grid; `false` for an app that toggles `editing` from its own control |
+| `columns` | `{ base?: 1 \| 2; md?: 1..6; xl?: 1..6 }` | `{ 1, 2, 4 }` | Columns at the container widths 0, 768px and 1280px |
+| `gap` | `'sm' \| 'md' \| 'lg'` | `'md'` | The space between tiles |
+| `dense` | `boolean` | `false` | Pack later tiles into the holes a wide tile leaves |
+
+| Prop (`DashboardTile`) | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `id` | `string` | required | The tile's name in `order`; unique in the grid |
+| `title` | `ReactNode` | none | An `h3` at the top, the tile's accessible name and its handle's name |
+| `span` / `rowSpan` | as `ResponsiveGrid.Item` | 1 | Columns and rows covered, held to the grid's columns at each width |
+| `plain` | `boolean` | `false` | No card of its own (border, background, padding), for a child that is a card already |
+| `label` | `string` | the title, else the id | The name used by the handle and the announcements when `title` is not text |
+
+Write the `DashboardTile`s directly inside the grid (not in a fragment or a
+wrapper component): the grid reads their `id`s to place them. Tile content keeps its
+state when a tile moves.
+
+**Keyboard.** In edit mode each handle is a Tab stop. Space or Enter picks the
+tile up, the arrows move it (left and up earlier, right and down later, the
+reverse of left and right in a right-to-left page), Home and End send it first
+or last, Space, Enter or Tab drops it, Escape puts it back where it was. A
+live region says "Orders picked up, position 2 of 6", where it moved, and
+whether it was dropped or cancelled. A pointer drag is announced the same way.
+
+**Phone.** Below 768px the tiles stack in one column and each shows "earlier"
+and "later" buttons beside its handle, so a touch user needs no drag.
+
+The strings are `material.dashboard.*` in English and French (React only).
+
+**Storybook:** `Navigation & layout/DashboardGrid` · **Vue:** none yet
+
+---
+
+## EditorLayout
+
+![EditorLayout](../previews/navigation-layout-editorlayout.webp)
+
+The page of an editor (an image, a slide, a form builder): a toolbar, a canvas
+that scrolls on its own, a properties panel at the end and an optional panel
+at the start (layers, outline). It is built on [`PaneLayout`](#listdetailslayout) (documented with
+ListDetailsLayout) and follows the layout's own container width, not the window's: from 768px the properties
+are an inline panel; below it they open in a bottom sheet from a toolbar button.
+
+```tsx
+import { EditorLayout } from '@nxgt/material/components';
+
+// UndoRedoButtons, LayerList, SelectionForm, Artboard: your components
+<EditorLayout
+  toolbar={
+    <>
+      <EditorLayout.StartTrigger />
+      <UndoRedoButtons />
+      <span className="flex-1" />
+      <EditorLayout.PropertiesTrigger />
+    </>
+  }
+  start={<LayerList />}
+  properties={<SelectionForm />}
+  ground="neutral"
+  className="h-dvh"
+>
+  <Artboard />
+</EditorLayout>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | required | The canvas, in a scrolling region (it takes focus, so arrows and Page keys scroll it) |
+| `toolbar` | `ReactNode` | none | The bar above the canvas and the outline; it stays in view while the canvas scrolls and scrolls sideways when it overflows |
+| `start` | `ReactNode` | none | Inline panel from 1280px; a side sheet below, opened by `EditorLayout.StartTrigger` |
+| `properties` | `ReactNode` | none | Inline panel at the end from 768px; a bottom sheet below |
+| `ground` | `'plain' \| 'tinted' \| 'neutral'` | `'plain'` | What the canvas sits on: the page, the tinted page ground (`bg-ground`) or a grey |
+| `propertiesWidth` | `'sm' \| 'md' \| 'lg'` | `'md'` | Inline panel width: 16, 20 or 24rem |
+| `propertiesOpen` / `defaultPropertiesOpen` / `onPropertiesOpenChange` | `boolean` | open | Whether the properties panel is shown, controlled or not. It applies from 768px of the layout's own width, where the panel is inline. Below that the properties live in a bottom sheet that starts closed, is opened by `EditorLayout.PropertiesTrigger` and ignores these props |
+| `toolbarLabel`, `startLabel`, `propertiesLabel`, `canvasLabel` | `string` | `material.editor-layout.*` | The names of the regions |
+
+`EditorLayout.PropertiesTrigger` toggles the inline panel (a way to give the
+canvas the whole width) or the sheet; `EditorLayout.StartTrigger` shows only
+below 1280px. Both are `Button`s whose label is the icon alone on a phone, and
+take `Button` props and a `children` label. `useEditorLayout()` gives the start
+panel's state; the properties' is `usePaneLayout()`.
+
+**Accessibility.** The toolbar is a named `group`, not `role="toolbar"`: it holds
+whatever the app puts there, and a toolbar role would promise arrow-key
+navigation between its buttons. The canvas is a `region`, the properties a
+`complementary` landmark (a labelled dialog in its sheet, with focus moved in
+and back to the button on close), the outline a `complementary` landmark too.
+In the source the canvas comes before the properties, so Tab reaches it first.
+The canvas is a tab stop because it is the keyboard route to scroll it; an app
+that wants a real arrow-key toolbar can put `<Toolbar>` in the `toolbar` slot.
+
+**SSR.** The server renders the desktop markup and hides the panels with
+container-query classes; the phone sheet takes over right after hydrating, and
+no `style` attribute is written. The panel state is the app's to persist (read it
+after hydrating, then pass `defaultPropertiesOpen`).
+
+The strings are `material.editor-layout.*` in English and French (React only).
+
+**Storybook:** `Navigation & layout/EditorLayout` · **Vue:** none yet
+
+---
+
 ## SectionColumns
 
 ![SectionColumns](../previews/navigation-layout-sectioncolumns.webp)
@@ -934,7 +1498,7 @@ Tooltip or Link wrapping a Button is not covered.
 
 ![Doc](../previews/navigation-layout-doc.webp)
 
-Documentation site shell: sidebar from `md`, TOC rail from `xl`. Reading bar, copy-page / markdown, child cards, see also, and a 404 slot. Storybook `UI/Doc/Api` composes an API page from `DocPage`, `AnchorHeading`, `ApiOperation`, `ParamTable` and `CodeGroup`.
+Documentation site shell: sidebar from `md`, TOC rail from `xl`, or drawn inside the app shell with `chrome="embedded"`. Reading bar, copy-page / markdown, child cards, see also, and a 404 slot. Storybook `UI/Doc/Api` composes an API page from `DocPage`, `AnchorHeading`, `ApiOperation`, `ParamTable` and `CodeGroup`.
 
 <img src="../previews/navigation-layout-doc-api.webp" height="96" alt="Doc API page">
 <img src="../previews/navigation-layout-doc-blocks.webp" height="96" alt="Doc blocks">
@@ -971,7 +1535,7 @@ the pieces it composes — `DocTopbar`, `DocSidebar`, `DocToc`, `DocPager`,
 `DocSearch`, `DocSeeAlso`, `DocChildCards`, `DocProgress`, `DocSkipLink`,
 `DocHeader`, `DocCopyPage`, `DocCopyMarkdown` — and `DocEmpty` for a 404. `DocEmpty` is an `EmptyState` (`kind` defaults to `not-found`; `size` is `default` or `compact`): see [EmptyState](./feedback-and-status.md#emptystate).
 `useDoc` / `DocProvider` / `useDocContext` expose the state for a shell of
-your own.
+your own. `useDoc` takes the same `chrome` and returns it as `frame` (type `DocChrome`, exported).
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
@@ -979,15 +1543,28 @@ your own.
 | `pathname` | `string` | — | current page; drives active item, pager, see also |
 | `toc` | `DocTocItem[]` | `[]` | the page's outline |
 | `onNavigate` / `linkComponent` | `(href) => void` / link component | — / `<a>` | wire your router |
+| `chrome` | `DocChrome` (`'standalone' \| 'embedded'`) | `'standalone'` | `'embedded'` draws the page inside `ActivityLayout`: see below |
 | `searchable` | `boolean` | `true` | search field and ⌘K |
-| `brand`, `actions` | `ReactNode` | — | top bar, left and right |
+| `brand`, `actions` | `ReactNode` | — | top bar, left and right (embedded: `actions` only, in the row under the shell's header) |
 | `previous`, `next` | `DocPagerLink \| null` | from `items` | override the pager; `null` hides one side |
 
+**Inside the app shell.** `chrome="embedded"` is for a docs page that lives
+under an `ActivityLayout` route (its sidebar, app bar and `handle.title` stay).
+`Doc` then draws no top bar, no reading bar and no full-height frame; the
+shell's header is the page's. The page tree and the outline stick under that
+header (the same offset as an `ActivityContent` `aside`, so a taller header or
+a `scroll="container"` shell is followed), scroll with the shell, and stop above
+a bottom bar or floating toolbar (`--nxgt-bottom-chrome`). Below `md` the tree
+is a sheet opened by a « Browse docs » button, named apart from the shell's
+« Menu », with the search and `actions` beside it; `brand` shows at the top of
+that sheet. The default `chrome` is unchanged, markup included. See the
+[app shell guide](../guides/app-shell.md#a-docs-page-inside-the-shell).
+
 On `DocPage`: `title`, `description`, `badge`, `crumbs`, `editHref`,
 `updatedAt`, and `copyPage` / `copyMarkdown` with `markdown` for the copy
 buttons.
 
-**Storybook:** `Navigation & layout/Doc`, `Navigation & layout/Doc/Api`, `Navigation & layout/Doc/Blocks` · **Vue:** `Doc`, `DocPage`, `DocTopbar`, `DocSidebar`, `DocNav`, `DocArticle`, `DocToc`, `DocPager`, `DocSearch`, `DocChildCards`, `DocSeeAlso`, `DocEmpty`, `DocProgress`, `DocLink`, `DefaultDocLink`, `DocCopyPage` (no `linkComponent`: `@navigate`)
+**Storybook:** `Navigation & layout/Doc`, `Navigation & layout/Doc/Api`, `Navigation & layout/Doc/Blocks`, `Navigation & layout/Doc embedded in ActivityLayout` · **Vue:** `Doc`, `DocPage`, `DocTopbar`, `DocSidebar`, `DocNav`, `DocArticle`, `DocToc`, `DocPager`, `DocSearch`, `DocChildCards`, `DocSeeAlso`, `DocEmpty`, `DocProgress`, `DocLink`, `DefaultDocLink`, `DocCopyPage` (no `linkComponent`: `@navigate`)
 
 ---
 
@@ -1021,17 +1598,357 @@ in dark. `ActivityLayout` and `ThreadLayout` sit on it. The superset with `grain
 
 ---
 
+## NavigationBar
+
+The bottom navigation bar of a phone: a `nav` fixed to the bottom edge with 3 to
+5 destinations (icon in an indicator pill, label always visible, `aria-current`,
+48px targets, optional badge) and a "More" sheet for the others. `ActivityLayout`
+draws it with `navigation="bar"` (alone it is phone-only: hidden from 768px,
+where the default rail shows) or `{ phone: 'bar' }`; see the
+[app shell guide](../guides/app-shell.md#the-bottom-bar-navigationbar).
+
+No preview yet: see the stories `Navigation & layout/NavigationBar`.
+
+```tsx
+import { NavigationBar } from '@nxgt/material/components';
+
+<NavigationBar
+  className="md:hidden"
+  items={[
+    { label: 'Home', url: '/', icon: 'house' },
+    { label: 'Inbox', url: '/inbox', icon: 'envelope', badge: 3 },
+    { label: 'Files', url: '/files', icon: 'folder' },
+    { label: 'Settings', url: '/settings', icon: 'gear', priority: -1 },
+  ]}
+/>
+```
+
+| Prop | Type | Default | |
+| --- | --- | --- | --- |
+| `items` | `MenuItem[]` | `[]` | Entries; `bar` and `priority` choose those kept on the bar |
+| `max` | `number` | `5` | Destinations on the bar, More included; clamped to 3-5 |
+| `label` | `string` | "Navigation" | The landmark's name |
+| `linkComponent` | `LinkComponent` | React Router `Link` | As for `AppSidebar` |
+| `children` | `NavigationBar.Item` | | Entries composed by hand |
+| `className` | `string` | | On the `nav`; a breakpoint class such as `md:hidden` hides the bar |
+
+It sets `--nxgt-nav-bar` on the document root while it shows, and needs a
+router context. `NavigationBar.Item` takes `href`, `icon`, `children` (the label), `active`
+(default: the location is `href` or below it), `badge`, `badgeLabel`,
+`linkComponent` and `className`.
+
+Also exported: `splitBarItems(items, max)`, which returns a `BarSplit`
+(`{ bar, more }`), `BAR_MAX` (5) and the type `NavigationBarItemProps`.
+
+**Storybook:** `Navigation & layout/NavigationBar` · **Vue:** not yet
+
+---
+
 ## NavigationRail
 
-Placeholder: renders an empty rail container and takes no props yet.
+The navigation rail (Material 3 Expressive): a `nav` of destinations down the
+start edge, each an icon in an indicator pill with its label under it, an
+optional badge read in the link's name, a `fab` slot at the top for the
+screen's primary action and a menu button that expands it into a wide rail
+with the labels inline. `ActivityLayout` draws it with
+`navigation="rail-expanded"`; see the
+[app shell guide](../guides/app-shell.md#the-wide-rail-navigationrail-expanded).
+Without `items` or `children` it is still the empty `div` it was, and needs no
+router.
+
+Not previewed yet: see the stories `Navigation & layout/NavigationRail`.
+
+```tsx
+import { Plus } from 'lucide-react';
+import { Fab, NavigationRail } from '@nxgt/material/components';
+
+<NavigationRail
+  persistKey="app-rail"
+  items={[
+    { label: 'Home', url: '/', icon: 'house' },
+    { label: 'Inbox', url: '/inbox', icon: 'envelope', badge: 3 },
+    { label: 'Settings', url: '/settings', icon: 'gear', footer: true },
+  ]}
+  fab={({ expanded }) => (
+    <Fab extended collapsed={!expanded} icon={<Plus />} label="Compose" />
+  )}
+/>
+```
+
+| Prop | Type | Default | |
+| --- | --- | --- | --- |
+| `items` | `MenuItem[]` | `[]` | Entries; `footer: true` ones sit at the bottom |
+| `fab` | `ReactNode` or `({ expanded }) => ReactNode` | | The primary action above the destinations (an action, not a link) |
+| `expanded` | `boolean` | | Controls the state |
+| `defaultExpanded` | `boolean` | `false` | The initial state when not controlled |
+| `onExpandedChange` | `(expanded: boolean) => void` | | Called by the menu button |
+| `persistKey` | `string` | | Remembers the state in the browser under this key, read after hydration |
+| `toggle` | `boolean` | `true` | Whether the menu button shows |
+| `label` | `string` | "Navigation" | The landmark's name |
+| `linkComponent` | `LinkComponent` | React Router `Link` | As for `AppSidebar` |
+| `children` | `NavigationRail.Item` | | Entries composed by hand |
+| `className` | `string` | | On the `nav`; give it a height (the rail fills it) and a breakpoint class to hide it |
+
+A phone never draws `'rail-expanded'` (or `'rail'`): it keeps its menu sheet.
+A standalone `NavigationRail` starts collapsed (`defaultExpanded` is `false`); inside `ActivityLayout` the `rail-expanded` preset starts expanded.
+
+The rail is 5rem wide collapsed and 15rem expanded (the width eases unless the
+user prefers reduced motion). Targets are 48px or taller, the menu button
+carries `aria-expanded` and `aria-controls`, and its name is
+`material.navigation.rail-toggle` ("Navigation menu"). `NavigationRail.Item`
+takes `href`, `icon`, `children` (the label), `active`, `badge`, `badgeLabel`,
+`linkComponent` and `className`. Also exported: the types `NavigationRailItemProps`
+and `RailExpandedOptions`.
+
+**Storybook:** `Navigation & layout/NavigationRail` · **Vue:** placeholder only
+
+## NavigationRailPanel
+
+The second level of a two-level navigation (Material 3 Expressive): a panel
+beside the [`NavigationRail`](#navigationrail) that lists the `children` of the
+top-level entry the location belongs to, under that entry's label, in 48px pill
+rows with the current child tinted and marked `aria-current="page"` (a badge
+ends the row and is read in the link's name). It is a `nav` named by the
+section's label, which is also its visible heading; a button folds it to a
+narrow strip and back (`aria-expanded`, `aria-controls`, focus stays on it).
+Nothing opens it on hover. `ActivityLayout` draws the rail and the panel
+together with `navigation="two-level"`; see the
+[app shell guide](../guides/app-shell.md#the-two-level-navigation). It reads the
+location, so it needs a React Router context.
+
+The panel is **open by default** (`defaultExpanded` is `true`), or controlled with
+`expanded`; with a `persistKey` the last choice is kept in the browser under
+`nxgt-panel:<persistKey>`, read after hydration (the server and the first client
+render are open). On a section without `children` the panel hides itself with
+CSS and keeps its markup, so the page does not change shape between routes. Only
+one level of `children` is listed (the children's own children are ignored).
 
-No preview: it renders an empty container, so there is nothing to show and
-no story. Use [`Sidebar`](#sidebar) collapsed for a rail of icons today.
+```tsx
+import {
+  type MenuItem,
+  NavigationRail,
+  NavigationRailPanel,
+} from '@nxgt/material/components';
+
+const items: MenuItem[] = [
+  { label: 'Home', url: '/', icon: 'house' },
+  {
+    label: 'Projects',
+    url: '/projects',
+    icon: 'folder',
+    children: [
+      { label: 'Overview', url: '/projects', icon: 'folder' },
+      { label: 'Active', url: '/projects/active', icon: 'folder' },
+    ],
+  },
+];
+
+<div className="flex h-dvh">
+  <NavigationRail items={items} toggle={false} />
+  <NavigationRailPanel items={items} persistKey="app-panel" />
+</div>
+```
+
+| Prop | Type | Default | |
+| --- | --- | --- | --- |
+| `items` | `MenuItem[]` | `[]` | The rail's menu; the panel lists the active top-level entry's `children` |
+| `expanded` | `boolean` | | Controls the panel: open while `true` |
+| `defaultExpanded` | `boolean` | `true` | The state to start from, before a saved choice is read |
+| `onExpandedChange` | `(expanded: boolean) => void` | | Asked for every change, controlled or not |
+| `persistKey` | `string` | | Keeps the state under `nxgt-panel:<persistKey>` (ignored when controlled) |
+| `label` | `string` | the section's label | The landmark's accessible name, already translated |
+| `linkComponent` | `LinkComponent` | React Router `Link` | As for `AppSidebar` |
+| `className` | `string` | | On the panel's root |
+
+The button's names are `material.navigation.panel-collapse` ("Collapse the panel")
+and `material.navigation.panel-expand` ("Expand the panel"). Also exported: the
+type `NavigationRailPanelProps`. The rail beside it lights the section when the
+current page is one of its children, even a child whose `url` is not under the
+parent's (`NavigationRail` matches the whole tree and marks the top-level
+entry).
+
+**Storybook:** `Navigation & layout/NavigationRailPanel` · **Vue:** —
+
+## NavigationToolbar
+
+The floating navigation toolbar (Material 3 Expressive): a pill of round icon
+links over the content, at the bottom centre. It is a `nav` landmark of links
+(`aria-current="page"` on the current one, each named by a visually hidden label
+and a tooltip, 48px targets, a badge read in the link's name), not a
+`role="toolbar"`: `Toolbar variant="floating"` stays for *actions*. The two share
+the pill (the `--tb-*` tokens, the shadow and the slide away of
+`.nxgt-toolbar`, so a theme that restyles the toolbar restyles both) and nothing
+else. `ActivityLayout` draws it with `navigation="floating"`; see the
+[app shell guide](../guides/app-shell.md#the-floating-navigation-toolbar).
+
+No preview yet: see the stories `Navigation & layout/NavigationToolbar`.
 
 ```tsx
-import { NavigationRail } from '@nxgt/material/components';
+import { NavigationToolbar } from '@nxgt/material/components';
 
-<NavigationRail />
+<NavigationToolbar
+  hideOnScroll
+  items={[
+    { label: 'Home', url: '/', icon: 'house' },
+    { label: 'Inbox', url: '/inbox', icon: 'envelope', badge: 3 },
+    { label: 'Files', url: '/files', icon: 'folder' },
+    { label: 'Settings', url: '/settings', icon: 'gear', priority: -1 },
+  ]}
+/>
 ```
 
-**Storybook:** — · **Vue:** `NavigationRail`
+| Prop | Type | Default | |
+| --- | --- | --- | --- |
+| `items` | `MenuItem[]` | `[]` | Entries; `bar` and `priority` choose those kept on the pill, as for `NavigationBar` |
+| `max` | `number` | `5` | Destinations on the pill, More included; clamped to 3-5 (3 to 5 recommended) |
+| `label` | `string` | "Navigation" | The landmark's name |
+| `hideOnScroll` | `boolean` | `false` | Slides away while the page scrolls down (past 64px) and back on the way up; reads the shell's scroll, so outside `ActivityLayout` (or a `ShellScrollProvider`) nothing scrolls it away. While away it is `inert` and its focus moves to the content region, then returns. Reduced motion: it snaps |
+| `hidden` | `boolean` | — | Forces it away or shown, whatever the scroll says |
+| `linkComponent` | `LinkComponent` | React Router `Link` | As for `AppSidebar` |
+| `children` | `NavigationToolbar.Item` | | Entries composed by hand |
+| `className` | `string` | | On the `nav`; a breakpoint class such as `md:hidden` hides it |
+
+With more entries than fit, the last slot is « More »: the same bottom sheet as
+`NavigationBar`'s, lighting up when the current page is under it. The pill is
+`position: fixed`, `1rem` above the safe area, and shows at every width. A docked media bar sits above
+it (the dock rests at `var(--nxgt-nav-bar)`). While it shows it sets `--nxgt-nav-bar` to `calc(5rem + env(safe-area-inset-bottom))` (its
+4rem height, the gap and the safe area), also while it is slid away, so `FabDock`, the toaster,
+the mini player and `StickyActionBar` stay clear and nothing jumps when it
+returns. It does not rise with the on-screen keyboard. It needs a router context. `NavigationToolbar.Item` takes `href`,
+`icon`, `children` (the name), `active`, `badge`, `badgeLabel`, `linkComponent`
+and `className`; the type `NavigationToolbarItemProps` is exported too.
+
+**Storybook:** `Navigation & layout/NavigationToolbar` · **Vue:** not yet
+
+## TopNav
+
+The top navigation (Material 3 Expressive): one `nav` of destinations as 48px
+pills in a row, the current one tinted with `aria-current="page"`. An entry
+with `children` is a trigger button that opens a dropdown (a rounded card) of
+its child links; when the current page is one of them, the trigger reads as
+active. A badge ends the pill and is read in the link's name. Built on
+Radix's navigation menu: arrow keys move along the bar, Escape closes the
+dropdown and returns focus to its trigger, and the motion is off for users who
+prefer reduced motion. `ActivityLayout` draws it in the app header with
+`navigation="top"`; see the
+[app shell guide](../guides/app-shell.md#the-top-navigation). It reads the
+location, so it needs a React Router context.
+
+Not previewed yet: see the stories `Navigation & layout/TopNav`.
+
+An entry with `children` is only a trigger: its `url` is never a link, so put an "all" link as the first child. Past about 5 entries the bar does not fit at 768px beside the brand and the title and pushes the header's actions out; it does not scroll (that would clip the dropdowns). Use `{ tablet: 'rail', desktop: 'top' }` for a longer menu.
+
+```tsx
+import { TopNav } from '@nxgt/material/components';
+
+<TopNav
+  items={[
+    { label: 'Home', url: '/', icon: 'house' },
+    { label: 'Inbox', url: '/inbox', icon: 'envelope', badge: 3 },
+    {
+      label: 'Projects',
+      url: '/projects',
+      icon: 'folder',
+      children: [
+        { label: 'All projects', url: '/projects/all', icon: 'folder' },
+        { label: 'Archived', url: '/projects/archived', icon: 'box-archive' },
+      ],
+    },
+  ]}
+/>
+```
+
+| Prop | Type | Default | |
+| --- | --- | --- | --- |
+| `items` | `MenuItem[]` | `[]` | Destinations in order; an entry with `children` opens a dropdown (its own `url` is never a link) |
+| `label` | `string` | "Navigation" | The landmark's name |
+| `linkComponent` | `LinkComponent` | React Router `Link` | As for `AppSidebar` |
+| `children` | `TopNav.Item`, `TopNav.Menu` | | Entries composed by hand, after those of `items` |
+| `className` | `string` | | On the `nav` |
+
+By hand, with the pieces:
+
+```tsx
+import { TopNav, TopNavItem, TopNavMenu } from '@nxgt/material/components';
+
+<TopNav>
+  <TopNavItem href="/" icon="house" active>Home</TopNavItem>
+  <TopNavItem href="/inbox" badge={3}>Inbox</TopNavItem>
+  <TopNavMenu
+    label="Projects"
+    icon="folder"
+    current="/projects/all"
+    items={[
+      { label: 'All projects', url: '/projects/all', icon: 'folder' },
+      { label: 'Archived', url: '/projects/archived', icon: 'box-archive' },
+    ]}
+  />
+</TopNav>
+```
+
+`TopNavItem` (also `TopNav.Item`) takes `href`, `icon` (optional), `children`
+(the label), `active` (`false`), `badge` (none), `badgeLabel`, `linkComponent` and
+`className`.
+`TopNavMenu` (also `TopNav.Menu`) takes `label`, `icon`, `items` (`MenuItem[]`, the links),
+`current` (the `url` of the current one; unset, none is current), `badge`, `badgeLabel`,
+`linkComponent` and `className`. Also exported: the types `TopNavProps`,
+`TopNavItemProps` and `TopNavMenuProps`.
+
+**Storybook:** `Navigation & layout/TopNav` · **Vue:** —
+
+## NavigationDrawer
+
+The navigation drawer (Material 3 Expressive): a `nav` of destinations in
+sections, each a 56px row with an icon, a label and an optional badge that
+ends the row and is read in the link's name. `aria-current="page"` marks the
+current one, and its row is tinted. Entries are listed in sections by their
+`group` (the ones without a group first, with no headline) and the entries
+marked `footer` sit at the bottom. `ActivityLayout` draws the standard drawer
+with `navigation="drawer"`; see the
+[app shell guide](../guides/app-shell.md#the-drawer-and-the-collapsible-sidebar).
+It reads the location, so it needs a React Router context.
+
+Not previewed yet: see the stories `Navigation & layout/NavigationDrawer`.
+
+```tsx
+import { IconButton, NavigationDrawer } from '@nxgt/material/components';
+
+// permanent, 20rem wide
+<NavigationDrawer
+  items={[
+    { label: 'Home', url: '/', icon: 'house' },
+    { label: 'Inbox', url: '/inbox', icon: 'envelope', badge: 3, group: 'Mail' },
+    { label: 'Settings', url: '/settings', icon: 'gear', footer: true },
+  ]}
+/>
+
+// modal: a sheet from the start edge, closed by a followed link or Escape
+<NavigationDrawer
+  variant="modal"
+  items={items}
+  trigger={<IconButton aria-label="Menu" variant="outlined">...</IconButton>}
+/>
+```
+
+| Prop | Type | Default | |
+| --- | --- | --- | --- |
+| `variant` | `'standard' \| 'modal'` | `'standard'` | A permanent column, or the same column in a sheet |
+| `items` | `MenuItem[]` | `[]` | Entries, in sections by `group`; `footer: true` ones sit at the bottom |
+| `header` | `ReactNode` | | A block above the destinations (the brand) |
+| `label` | `string` | "Navigation" | The landmark's name |
+| `linkComponent` | `LinkComponent` | React Router `Link` | As for `AppSidebar` |
+| `children` | `NavigationDrawer.Section` | | Sections composed by hand, after those of `items` |
+| `open` / `onOpenChange` | `boolean` / `(open: boolean) => void` | | `variant="modal"`: controls the sheet |
+| `trigger` | `ReactNode` | | `variant="modal"`: the element that opens it |
+| `className` | `string` | | On the `nav`; give a standard drawer a height (it fills it, and scrolls) and a breakpoint class to hide it |
+
+`NavigationDrawerSection` (also `NavigationDrawer.Section`) takes `headline`
+(names the group), `items`, `current` (the `url` of the current entry; unset,
+the one of its own `items` the location is in), `linkComponent` and children
+(`NavigationDrawer.Item`: `href`, `icon`, `children`, `active`, `badge`,
+`badgeLabel`, `linkComponent`, `className`). The modal variant shares the app
+shell's menu sheet logic: a followed link and a new location close it and focus
+goes to the page's title, else back to the trigger. Also exported: the types
+`NavigationDrawerItemProps` and `NavigationDrawerSectionProps`.
+
+**Storybook:** `Navigation & layout/NavigationDrawer` · **Vue:** —