@nxgt/material 3.79.1 → 3.80.0

package/docs/guides/app-shell.md

@@ -211,6 +211,8 @@ partitionMenu(items);                              // { content, footer }
 | `align` | `'start' \| 'center'` | `'start'` | Where the collapsed rail's entries sit: right under the brand, or centred in the height below it |
 | `menuOpen` | `boolean` | — | Controls the phone's menu sheet: open while `true`. Leave it out and the layout manages the sheet. Only a phone shows the sheet |
 | `onMenuOpenChange` | `(open: boolean) => void` | — | Called for every change of the sheet: the menu button, Escape, the close button, a followed link, a new location |
+| `navigation` | `ShellNavigation \| { phone?, tablet?, desktop?, hideOnScroll?, persistKey? }` | `modal-drawer` / `rail` / `rail` | The navigation per window size; see [`navigation` and `header`](#navigation-and-header) |
+| `header` | `'small' \| 'center' \| 'medium' \| 'large' \| 'none' \| { variant, collapse?, hideOnScroll?, tabs?, search? }` | `'small'` | The app bar's size, overridable per route with `handle.header`; see [The app bar variants](#the-app-bar-variants) |
 | `backdrop` | `ReactNode \| false` | — | An exception to the theme's background (the page ground, [`--ground`](#the-page-ground), is painted either way), which the layout draws by default (Lavande's: the built-in gradient and blobs). A node replaces it for this screen: usually a `Background` preset from `@nxgt/material/backgrounds` (see [Use a background preset behind the shell](#use-a-background-preset-behind-the-shell)); `false` draws no background, a plain page |
 | `keepClear` | `boolean \| 'gaps'` | `true` | how the backdrop's glyphs keep clear of the page: `true` drops every glyph within 8px of a surface, a text or a control; `'gaps'` also keeps a glyph that fits in a gap of 24px or more between two surfaces; `false` keeps nothing clear (the edge and the header band still are). See [Keep the backdrop clear of the content](#keep-the-backdrop-clear-of-the-content) |
 
@@ -311,9 +313,573 @@ confirmation inside the menu) is the top layer: it takes the first Escape alone,
 and the second closes the sheet. A leave confirmation raised by a followed link
 comes after the sheet has closed: the sheet stays closed, "Stay" included.
 
+### `navigation` and `header`
+
+`ActivityLayout` takes two props that choose how the shell's navigation and
+header are drawn. Both are optional, and unset they are what the shell draws
+today: the menu sheet on a phone, the rail from `md`, a small header.
+
+```tsx
+<ActivityLayout items={items} navigation="rail" header="small">
+  <Outlet />
+</ActivityLayout>
+
+// one preset per window size
+<ActivityLayout
+  items={items}
+  navigation={{ phone: 'modal-drawer', tablet: 'rail', desktop: 'rail' }}
+  header={{ variant: 'small' }}
+>
+  <Outlet />
+</ActivityLayout>
+```
+
+- `navigation`: a `ShellNavigation` name for every size, or an object
+  `{ phone, tablet, desktop, hideOnScroll, persistKey }`; `persistKey` is a
+  field of that object (it keeps the `'rail-expanded'` rail's, the
+  `'sidebar'`'s and the `'two-level'` panel's state); `hideOnScroll` is another
+  (`false` by default; it slides the `'floating'` toolbar away on scroll). The sizes are a phone below `md` (768px), a tablet from
+  768px to 1279px and a desktop from `xl` (1280px). A name alone applies to
+  every size, except `'sidebar'`, `'drawer'`, `'top'` and `'two-level'`, which it draws from the
+  tablet size only: the phone keeps its default navigation unless the object asks for
+  it (`{ phone: 'sidebar' }`). `'bar'` and `'floating'` are phone navigations: a
+  name alone draws them at every size, the phone included. Every name is drawn:
+  `'modal-drawer'`, `'rail'`, `'rail-expanded'`, `'drawer'`, `'sidebar'`, `'top'`,
+  `'two-level'`, `'floating'`, `'bar'` and `'none'`.
+- `header`: `'small'`, `'center'`, `'medium'`, `'large'` or `'none'`, or
+  `{ variant, collapse, hideOnScroll, tabs, search }`. The five variants and
+  `hideOnScroll` are drawn (see [The app bar variants](#the-app-bar-variants));
+  `search` and `tabs` are drawn (see [The app bar's search](#the-app-bars-search) and
+  [Tabs under the app bar](#tabs-under-the-app-bar)). A route's `handle.back` draws a
+  back arrow ([The back arrow](#the-back-arrow)).
+
+An object's `phone` that names a preset never drawn on a phone (`rail`, `rail-expanded`, `top`, `two-level`) resolves to the default, as a name alone does.
+
+`resolveNavigation()` and `resolveHeader()` return the full settings for a
+value (what the props resolve to), and `navigationClasses()` the classes that
+show each preset only at the sizes it is configured for. `DEFAULT_NAVIGATION` is
+the default value (`modal-drawer`, `rail`, `rail`).
+
+`MenuItem` also accepts `children`, `group`, `bar` and `priority`. Each is read
+by the presets that use it, and ignored by the others: `bar` and `priority`
+choose the entries of the bottom bar **and** of the floating toolbar (the rest go
+under « More »), `group` is read by the drawer, and `children` by the top
+navigation, the two-level panel, the sidebar and the phone's menu sheet.
+`footer` is read by the rail, the sidebar and the drawer (its footer), `display`
+by the rail, the sidebar and the phone's menu sheet, and `badge` and `badgeLabel`
+by every preset that draws entries, except on a `display: 'icon'` entry.
+
+### The bottom bar (`navigation="bar"`)
+
+`navigation="bar"` alone is phone-only: the bar is hidden from 768px, where the
+default rail shows (`{ tablet: 'bar' }` keeps it there).
+
+```tsx
+// a bar on the phone, the rail from 768px
+<ActivityLayout
+  items={[
+    { label: 'Home', url: '/', icon: 'house' },
+    { label: 'Inbox', url: '/inbox', icon: 'envelope', badge: 3 },
+    { label: 'Tasks', url: '/tasks', icon: 'check', badge: true },
+    { label: 'Files', url: '/files', icon: 'folder' },
+    { label: 'Settings', url: '/settings', icon: 'gear', priority: -1 },
+  ]}
+  navigation={{ phone: 'bar' }}
+>
+  <Outlet />
+</ActivityLayout>
+```
+
+The bar is a `nav` named "Navigation" (`material.app-shell.navigation`) pinned
+to the bottom edge, clear of the home indicator. It shows 3 to 5 destinations,
+each an icon in an indicator pill with its label always visible, `aria-current="page"`
+on the current one and a target of 48px or more. A `badge` shows as a dot or a
+count on the icon and is read in the link's name ("Inbox, 3 new").
+
+- **Which entries.** Up to five fit when they all do; with more, the bar keeps
+  four and "More" takes the fifth slot. `bar: true` on some entries limits the bar to
+  them, `bar: false` keeps one off it, and `priority` (higher stays, unset is 0)
+  chooses among the rest; ties keep the menu's order. `splitBarItems(items, max)`
+  returns `{ bar, more }`.
+- **More.** A button that opens a sheet from the bottom with the other entries
+  (`material.navigation.more`, closed by Escape, the "Close" button
+  (`material.navigation.close`) or a followed link). Focus returns to the button;
+  after a followed link it goes to the page's title as for the menu sheet. It
+  lights up when the current page is one of its entries.
+- **Breakpoints.** The bar and the rail are both in the markup and CSS classes
+  show one per size, so a server render matches the client. A hidden bar is
+  `display: none`: out of the tab order and the accessibility tree. With the
+  bar on the phone the app bar has no menu button.
+- **Room.** While it shows, the bar sets `--nxgt-nav-bar` (`calc(4rem + env(safe-area-inset-bottom))`,
+  the safe area included) on the document root as long as any bar shows (it stays while a second
+  bar remains), and the shell's frame clears
+  `--nxgt-bottom-chrome`; with no bar the shell's markup is unchanged.
+
+Use it by hand with `<NavigationBar items={items} />` (needs a router context)
+and hide it with a breakpoint class such as `md:hidden`; compose entries with
+`<NavigationBar.Item href icon badge>Label</NavigationBar.Item>`. The variable
+is set after mount: a server render and the first paint get the room from the
+layout root's breakpoint class, and portals (the toaster) read the variable on
+the document root once the effect has run. A layout without `items` draws no bar.
+
+### The wide rail (`navigation="rail-expanded"`)
+
+```tsx
+import { ActivityLayout, Fab, Icon } from '@nxgt/material/components';
+
+// the wide rail from 768px, a bar on the phone
+<ActivityLayout
+  items={items}
+  navigation={{ phone: 'bar', tablet: 'rail-expanded', persistKey: 'app-rail' }}
+  navigationFab={({ expanded }) => (
+    <Fab extended collapsed={!expanded} icon={<Icon name="plus" />} label="Compose" />
+  )}
+>
+  <Outlet />
+</ActivityLayout>
+```
+
+`'rail'` stays the collapsed sidebar rail the shell has always drawn (it is
+the default, so its markup does not change). `'rail-expanded'` draws
+[`NavigationRail`](../components/navigation-and-layout.md#navigationrail)
+instead: a `nav` named "Navigation" with the menu button, the optional FAB, a
+link per entry (icon in an indicator pill, label, badge read in the link's
+name) and the `footer` entries at the bottom. It starts expanded (15rem) and the
+menu button narrows it to 5rem, labels under the icons.
+
+- **FAB.** `navigationFab` is the screen's primary action, a node or a function
+  of `{ expanded }` to pass an extended `Fab` that folds to its icon. The other
+  presets do not draw it. `navigationFab` is drawn only by `'rail-expanded'`; the other presets ignore it.
+- **Remembering the choice.** With `navigation.persistKey` the state is kept in
+  the browser's local storage and read after hydration, so a server render and
+  the first client render agree; without it the rail starts expanded each time.
+- **On a phone.** A phone never draws `'rail-expanded'` (or `'rail'`): it keeps
+  its menu sheet, or `'bar'`.
+- **Breakpoints.** Both rails and the bar are in the markup and CSS classes show
+  one per size (`display: none` elsewhere, so a hidden rail is out of the tab order
+  and the accessibility tree). A layout without `items` draws no wide rail.
+- **Motion.** The width and the indicator ease unless the user prefers reduced
+  motion.
+
+### The drawer and the collapsible sidebar
+
+```tsx
+// the phone's menu sheet, the collapsible sidebar from 768px, remembered
+<ActivityLayout
+  items={items}
+  navigation={{ tablet: 'sidebar', desktop: 'sidebar', persistKey: 'app-nav' }}
+>
+  <Outlet />
+</ActivityLayout>
+
+// the permanent drawer on a wide desktop
+<ActivityLayout items={items} navigation={{ desktop: 'drawer' }}>
+  <Outlet />
+</ActivityLayout>
+```
+
+- **`'drawer'`** draws the standard (permanent) drawer,
+  [`NavigationDrawer`](../components/navigation-and-layout.md#navigationdrawer),
+  20rem wide, instead of the rail at that size: a `nav` named "Navigation"
+  with the entries in sections by their `group`, the `footer` entries at the
+  bottom, the brand above. The modal variant is the phone's menu sheet
+  (`'modal-drawer'`, unchanged).
+- **`'sidebar'`** draws the shell's sidebar, collapsed to the rail of icons at
+  first. A small chevron button on its end edge, level with the brand and with
+  no row of its own, expands it (logo and name, labels beside the icons) and
+  collapses it again; it is named "Toggle sidebar", carries `aria-expanded` and
+  `aria-controls`, has a 48px hit area, and the chevron turns (unless the user
+  prefers reduced motion). The state is `sidebarExpanded` (controlled) or
+  `defaultSidebarExpanded` (`false`), reported by `onSidebarExpandedChange`.
+  With `navigation.persistKey` the user's last choice is kept in the browser's
+  local storage and read after hydration, so a server render and the first
+  client render agree; a blocked storage is ignored.
+- Both are in the markup with the other presets and CSS classes show one per
+  size (`display: none` elsewhere, out of the tab order and the accessibility
+  tree). They need `items`; a layout without any draws no drawer. The unset
+  `navigation` still draws the collapsed rail, so existing apps are unchanged.
+  On a phone they are drawn only when asked by size (`{ phone: 'drawer' }`),
+  taking 16 to 20rem beside the content: keep the menu sheet or a bar there.
+
+### The top navigation
+
+```tsx
+// the brand and a bar of destinations in the app header from 768px;
+// the phone keeps its menu sheet, with the children nested
+<ActivityLayout
+  items={[
+    { label: 'Home', url: '/', icon: 'house' },
+    {
+      label: 'Projects',
+      url: '/projects',
+      icon: 'folder',
+      children: [
+        { label: 'All projects', url: '/projects/all', icon: 'folder' },
+        { label: 'Archived', url: '/projects/archived', icon: 'box-archive' },
+      ],
+    },
+  ]}
+  name="Acme"
+  navigation="top"
+>
+  <Outlet />
+</ActivityLayout>
+```
+
+- **`'top'`** draws [`TopNav`](../components/navigation-and-layout.md#topnav)
+  in the app header, after the brand (`brand`, else `logo` and `name`: no rail
+  carries it then): a `nav` named "Navigation" of 48px pills, the current one
+  tinted with `aria-current="page"`. An entry with `children` is a button that
+  opens a dropdown of its child links; when the current page is one of them,
+  the button reads as active and the child carries `aria-current`. Arrow keys,
+  Escape and focus return follow Radix's navigation menu, and the dropdown's
+  motion is off for users who prefer reduced motion. A badge is read in the
+  link's name.
+- On a phone the bar is not drawn, whatever the object says
+  (`{ phone: 'top' }` keeps the menu sheet): the sheet lists the entries and
+  nests each entry's `children` under it, indented. The expanded sidebar nests
+  them the same way.
+- An entry with `children` is only a trigger: its `url` is never a link, so put an "all" link as the first child. (The phone's menu sheet and the expanded sidebar do list the
+  parent's own `url` as a link, with its children nested under it.)
+- 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.
+- It shows per size with CSS classes like the other presets, so the server and
+  the browser agree. It needs `items`; the `footer`, `group` and `display`
+  options are not used. The unset `navigation` is unchanged.
+
+### The two-level navigation
+
+```tsx
+// a rail of the top-level entries and, beside it, a panel of the current
+// entry's children, from 768px; the phone keeps its menu sheet
+<ActivityLayout
+  items={[
+    { 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' },
+        { label: 'Archived', url: '/projects/archived', icon: 'box-archive' },
+      ],
+    },
+  ]}
+  navigation={{ tablet: 'two-level', desktop: 'two-level', persistKey: 'app-nav' }}
+>
+  <Outlet />
+</ActivityLayout>
+```
+
+- **`'two-level'`** draws [`NavigationRail`](../components/navigation-and-layout.md#navigationrail)
+  (the top-level entries, 5rem wide, no menu button of its own) and
+  [`NavigationRailPanel`](../components/navigation-and-layout.md#navigationrailpanel)
+  (14rem) side by side in one lane, bled to the frame's edges like the other
+  lanes. The app's brand tops the rail's column: `brand`, else `logo` alone (named by
+  `name`).
+- **A rail entry always links to its own `url`**, with or without `children`:
+  following it navigates there, and the panel shows that entry's children
+  (an entry is the section the location belongs to when its `url` or one of its
+  children's matches; the most specific match wins, so a child outside the
+  parent's `url` still lights its parent). Put the section's overview at the
+  parent's `url`, and as a first child with the same `url` if you want it listed:
+  that child is marked current there.
+- **The panel is open by default and collapsible.** Its button folds it to a
+  narrow strip and back; nothing opens it on hover, and a rail entry does not
+  reopen it. With `navigation.persistKey` the choice is remembered under
+  `nxgt-panel:<persistKey>` (the rail's `'rail-expanded'` state and the sidebar's
+  keep their own prefixes), read after hydration: the server render and the first
+  client render are open.
+- **An entry without `children`** just navigates; the panel is hidden by CSS for
+  it (its markup stays, so the tree does not change between routes). Only one
+  level of `children` is listed.
+- **On a phone** neither is drawn, whatever the object says
+  (`{ phone: 'two-level' }` keeps the menu sheet, as `'top'` does): the sheet lists
+  the entries and nests each one's `children`. A name alone leaves the phone its
+  default.
+- At 768px the rail and the open panel take 19rem beside the content; fold the
+  panel or use `{ tablet: 'rail', desktop: 'two-level' }` when that is too much.
+  It needs `items` (none draws nothing); `footer` entries sit at the rail's
+  bottom, `group` and `display` are not used. The unset `navigation` is unchanged.
+
+### The floating navigation toolbar
+
+```tsx
+import { ActivityLayout } from '@nxgt/material/components';
+import { Outlet } from 'react-router';
+
+// a floating pill on the phone, the rail from 768px, hiding while the page scrolls down
+<ActivityLayout
+  items={[
+    { label: 'Home', url: '/', icon: 'house' },
+    { label: 'Inbox', url: '/inbox', icon: 'envelope', badge: 3 },
+    { label: 'Tasks', url: '/tasks', icon: 'check' },
+    { label: 'Files', url: '/files', icon: 'folder' },
+    { label: 'Settings', url: '/settings', icon: 'gear', priority: -1 },
+  ]}
+  navigation={{ phone: 'floating', hideOnScroll: true }}
+>
+  <Outlet />
+</ActivityLayout>
+```
+
+[`NavigationToolbar`](../components/navigation-and-layout.md#navigationtoolbar) is
+a pill of round icon links at the bottom centre, over the content. It is a `nav`
+named "Navigation" (`material.app-shell.navigation`) of links, each named by a
+visually hidden label (and a tooltip), with `aria-current="page"` on the
+current one: it is not a `role="toolbar"`, which is for actions (use
+`Toolbar variant="floating"` for those). It wears the same pill as that toolbar
+(its tokens, shadow and slide away), so a themed toolbar gives a themed pill.
+
+- **Where it shows.** A name alone (`navigation="floating"`) draws it at every
+  size, the phone included, like `'bar'`: the pill is a bar-like phone
+  navigation, and on a phone it replaces the menu sheet, so the app bar has no
+  menu button. `{ phone: 'floating' }` limits it to the phone, `{ desktop: 'floating' }`
+  to the desktop. Pill and rail are both in the markup and breakpoint classes show
+  one per size, so a server render matches the client.
+- **Which entries.** The same rules as the bottom bar: 3 to 5 destinations,
+  `bar`, `priority` and `splitBarItems` choose them, and with more the last slot
+  is « More » (the bar's bottom sheet, lit when the current page is under it).
+  Keep to 3-5 destinations; without a fifth slot to spare, mark the secondary
+  ones `priority: -1` so they live under « More ». No entry is lost: nothing is
+  reachable only from a hidden place.
+- **Hide on scroll is off by default.** `navigation.hideOnScroll: true` slides the
+  pill away on the way down (past 64px, after 8px of movement) and back on the
+  way up, reading the shell's scroll ([Scroll direction](#scroll-direction)). While away it is
+  `inert` (out of the tab order and the accessibility tree), and a focus inside
+  it moves to the content region and returns to its link when the pill is back,
+  unless the user went elsewhere meanwhile. With reduced motion it snaps instead
+  of sliding. `hideOnScroll` reads no other preset; the header's own
+  `hideOnScroll` is separate. The server draws it shown.
+- **Room.** The pill is `1rem` above the safe area; 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))` (4rem of pill, the gap and the safe area), also
+  while slid away, so `FabDock`, the toaster, the mini player and a sticky
+  `StickyActionBar` stay above it and nothing jumps when it returns; the shell's
+  frame clears `--nxgt-bottom-chrome` as for the bar. The first paint gets the
+  value from a class on the layout root, as the bar does. The pill does not rise
+  with the on-screen keyboard: it stays at the bottom of the layout viewport.
+- It needs `items` (none draws nothing) and a router context. Use it by hand with
+  `<NavigationToolbar items={items} />` (hide it with a breakpoint class such as
+  `md:hidden`) or compose entries with `<NavigationToolbar.Item href icon>Label</NavigationToolbar.Item>`.
+
+### Scroll direction
+
+`useShellScroll()` returns `{ direction, offset, reducedMotion }` for a bar
+that hides while scrolling down: `direction` is `'down'`, `'up'` or `'none'`
+(at the top), and flips only after 8px of movement the other way. Wrap the part
+that reads it in `ShellScrollProvider` (it is `useScrollTracker()`, the hook
+behind it, in a context; use `ShellScrollContext` to provide your own state); give it `container` (a ref to the
+scrolling box) when the content region scrolls (`scroll="container"`), none for
+the window. Outside a provider the hook is idle. `reducedMotion` is true when
+the user asked for less motion: skip the slide and snap. The header
+(`header.hideOnScroll`) and the floating navigation toolbar
+(`navigation.hideOnScroll`) read it; the shell tracks the scroll only when one of
+them asks, and `NavigationToolbar` reads it by hand too.
+
+### The app bar variants
+
+`header` chooses the bar's size, the way Material 3 does. Unset is `'small'`:
+today's one row, byte for byte.
+
+```tsx
+import { ActivityLayout, type AppShellHandle } from '@nxgt/material/components';
+
+<ActivityLayout items={items} header="large">
+  <Outlet />
+</ActivityLayout>
+
+// a route opts in, whatever the layout says
+export const handle = { title: 'Projects', header: 'large' } satisfies AppShellHandle;
+
+// a bar that goes away on the way down
+<ActivityLayout items={items} header={{ variant: 'small', hideOnScroll: true }} />
+```
+
+Defaults: `variant` is `'small'`; `collapse` is `true` for `'medium'` and
+`'large'`; `hideOnScroll` is `false`. Nothing to import beyond `styles.css`: the
+bar's CSS ships with it.
+
+- `'small'`: one row, the title beside the actions.
+- `'center'`: the title centred in the room between the menu button and the
+  actions.
+- `'medium'` and `'large'`: the page's title on a second row, in display type
+  (`large` is taller and bigger, up to two lines), under the small row. As the
+  page scrolls the headline fades and the bar shrinks into the small row, which
+  then shows the title (a copy hidden from assistive technology). `collapse:
+  false` keeps the headline however far the page scrolls.
+- `'none'`: no bar. The screen's own `ActivityContent` title is then the page's
+  `h1`; the phone's menu button goes with the bar, so pair it with a navigation
+  that has one on its own (`navigation="bar"`).
+- `hideOnScroll`: the bar slides away while the page scrolls down (past 64px) and
+  comes back on the way up. While away it is `inert` and out of the tab order; if
+  the focus was inside it, the focus moves to the content region.
+
+A route gives its own through `handle.header` (a variant or the options, like
+the prop). The deepest route that declares one wins, and its options win over
+the layout's one by one: a route that only names a variant keeps the layout's
+`hideOnScroll`. It is read from the matched routes, so the server and the
+browser draw the same bar.
+
+The headline **is** the page's one `h1` (the small row's copy is `aria-hidden`).
+A medium or large header needs a title in the bar, a route's `handle.title`;
+without one the bar stays small, so nothing changes for a screen that titles
+itself with `ActivityContent`. The server always renders the bar expanded and
+shown; the browser then follows the scroll.
+
+The scroll is the shell's ([Scroll direction](#scroll-direction)): the window,
+or the content region with `scroll="container"` (a hidden bar then gives its
+room back). Once per animation frame the bar sets one CSS variable on itself,
+`--nxgt-header-progress` (0 expanded, 1 collapsed), through `setProperty`, so
+no inline style reaches the markup; the sizes are CSS in `app-header.css`.
+Under reduced motion the bar snaps between the two states halfway, with no slide.
+A plain shell, with no collapsing or hiding bar, tracks no scroll at all.
+
+`AppHeader` takes the same as props (`variant`, `collapse`, `hideOnScroll`, the
+`headline` node, `tabs` (a node, default none) and `back` (a `ShellBack`,
+default none); see [Using the parts](#using-the-parts)), and so does `TopAppBar` (`variant`, `headline`) for a bar
+of your own. Known limits: a hidden bar in a `scroll="container"` shell that is
+barely taller than its container can flicker at the very bottom (the region
+grows, so the scroll clamps); the scroll-driven CSS animation enhancement is not
+used, the JavaScript path drives every browser.
+
+### The app bar's search
+
+`header.search` puts an `AppSearchBar` after the title: `true` for a bare one,
+or its props. From 768px it is a pill with the results in a docked panel; on a
+phone a search button opens a full-screen dialog (`SearchView`). Unset (the
+default) there is no search, and the bar is the same markup as before.
+
+```tsx
+import { ActivityLayout } from '@nxgt/material/components';
+
+<ActivityLayout
+  items={items}
+  header={{
+    variant: 'small',
+    search: { placeholder: 'Search projects', shortcut: '/', onSubmit: (q) => navigate(`/search?q=${q}`) },
+  }}
+/>
+
+// a route turns it off, or changes it, like the other options
+export const handle = { title: 'Settings', header: { variant: 'small', search: false } };
+```
+
+The search never changes the shape of the page: the content stays mounted when
+a route adds or drops it. A route's `search` replaces the layout's whole object
+(its props are not merged). The props, the keyboard and the focus rules are in
+[`AppSearchBar`](../components/navigation-and-layout.md#appsearchbar).
+
+### Tabs under the app bar
+
+`header.tabs` is a node, normally a `TabsNav` (route links), drawn as a 48px row
+at the foot of the bar. It is part of the bar: under a `medium` or `large` header
+it stays under the small row as the headline collapses, and with `hideOnScroll`
+the bar slides away **but the tabs stay pinned at the top of the window**
+(Material 3's behaviour for a bar with tabs: the title row goes, the tabs stay
+within reach). Only the bar's rows are `inert` while they are away; the tabs keep
+the focus if they had it. The default is none: no row, and the bar is the same
+markup as before. A `'none'` header draws none.
+
+```tsx
+// layout.tsx: tabs on every route
+import { ActivityLayout, type MenuItem, TabsNav, TabsNavLink } from '@nxgt/material/components';
+
+const tabs = (
+  <TabsNav aria-label="Project sections" value="activity">
+    <TabsNavLink to="/projects/overview" value="overview">Overview</TabsNavLink>
+    <TabsNavLink to="/projects/activity" value="activity">Activity</TabsNavLink>
+  </TabsNav>
+);
+
+export function Layout({ items }: { items: MenuItem[] }) {
+  return <ActivityLayout items={items} header={{ variant: 'small', tabs }} />;
+}
+```
+
+```tsx
+// routes/project.tsx: tabs on this route only, or none
+import { type AppShellHandle, TabsNav, TabsNavLink } from '@nxgt/material/components';
+
+const projectTabs = (
+  <TabsNav aria-label="Atlas sections" value="board">
+    <TabsNavLink to="/projects/atlas/board" value="board">Board</TabsNavLink>
+    <TabsNavLink to="/projects/atlas/files" value="files">Files</TabsNavLink>
+  </TabsNav>
+);
+
+export const handle = {
+  title: 'Atlas',
+  header: { variant: 'small', tabs: projectTabs }, // tabs: null drops the layout's
+} satisfies AppShellHandle;
+```
+
+The option is `header.tabs` (there is no `handle.headerTabs`): a route's `tabs`
+replaces the layout's whole, `tabs: null` drops them for that route, and a route
+that only names a variant keeps the layout's. The row's height is one CSS
+variable, `--nxgt-header-tabs` (3rem, in `app-header.css`). The bar's whole
+height (the row, a headline row and the tabs) is `--nxgt-header-total` on the
+`ActivityLayout` root, measured with a `ResizeObserver` (worked out in CSS from
+the variant and tabs before script runs, from `data-header="medium|large"`, set only when the bar has a headline, and `data-header-tabs` on that root); the sticky aside and `Doc` stick below it. Give the `TabsNav` an
+`aria-label` and its `value`, as it asks; a long list scrolls sideways in its
+own row, never the page. The content stays mounted when a route adds or drops
+the tabs; the bar's own row is drawn again then (as it is when a route moves to or
+from a `medium` or `large` header), so an uncontrolled search loses its text.
+
+### The back arrow
+
+A route's `handle.back` draws an arrow at the start of the app bar, 48px, named
+`Back` or `Back to <label>` (`material.app-header.back`, default text "Back", and
+`back-to`, default "Back to {label}"). It is read from the matched routes like
+`handle.header`: the deepest route that declares one wins, and a route without it
+has none. The type is `ShellBack`, which `AppShellHandle['back']` uses:
+`import type { ShellBack } from '@nxgt/material/components'`.
+
+```tsx
+// routes/project.tsx
+import type { AppShellHandle } from '@nxgt/material/components';
+
+export const handle = {
+  title: 'Atlas redesign',
+  back: { to: '/projects', label: 'Projects' },
+} satisfies AppShellHandle;
+```
+
+```tsx
+// routes/file.tsx: history back; the page above when the visit started here
+import type { AppShellHandle } from '@nxgt/material/components';
+
+export const handle = { title: 'File', back: true } satisfies AppShellHandle;
+```
+
+- `{ to, label? }` is a link drawn with the shell's `linkComponent` (React
+  Router's `Link` by default), so it opens in a new tab and shows its address.
+- `true` is a button: it goes back in the history when the visit has a previous
+  entry, and otherwise (a deep link, a reload) goes up one level of the URL, so the
+  arrow never leaves the app. It works under a router `basename`.
+- The arrow comes first in the bar, before the top navigation and the title. On a
+  phone that has the menu sheet (the default) the menu button follows the arrow,
+  so the route is never a dead end; a phone with the bottom bar
+  (`navigation={{ phone: 'bar' }}`) has no menu button, so the arrow is first
+  and the bar navigates. From 768px the rail or sidebar stays.
+- The arrow mirrors in right-to-left. The content stays mounted when a route adds
+  or drops it, and so does the bar's row (the menu button and the search keep their
+  state).
+
+### Room at the bottom
+
+`--nxgt-nav-bar` is the room of a bottom navigation bar (4rem plus the bottom
+safe-area inset) or of the floating navigation toolbar with its gap (5rem plus
+the inset); 0 when there is none. It already holds the safe area: a consumer
+clears `max(env(safe-area-inset-bottom), var(--nxgt-nav-bar, 0px))` once and
+never adds the inset again. `--nxgt-media-dock` is that of a `MediaPlayerHost`'s
+docked bar, and `--nxgt-bottom-chrome` is the two added together (it falls back to that sum
+when unset). `FabDock`, `Toaster`, the mini player and a sticky
+`StickyActionBar` keep clear of them, so a bar added at the bottom never
+covers a button.
+
 ### The app bar: a title, the actions, the account
 
-The header reads, from the start: the phone's menu button, `headerTitle`
+The header reads, from the start: a route's back arrow (`handle.back`), the phone's menu button, `headerTitle`
 (the context the app is in, the active school or organisation), then
 `headerActions` (language, notifications) and `avatar` at the end. The title
 takes the room left and ends in an ellipsis when it does not fit, so the
@@ -1037,6 +1603,44 @@ import { ActivityContent, Alert } from '@nxgt/material/components';
 - **Width token.** `--nxgt-aside-width` changes `asideWidth="md"` (20rem) app-wide;
   any CSS length goes in `asideWidth` for one screen.
 
+## A docs page inside the shell
+
+A documentation section of an app (the help, the API reference) is a `Doc`
+under a route of the shell, not a second page with its own top bar. Pass
+`chrome="embedded"`:
+
+```tsx
+import { ActivityLayout, Doc, DocPage } from '@nxgt/material/components';
+
+<ActivityLayout items={items} navigation={{ phone: 'bar' }}>
+  <Doc chrome="embedded" items={docItems} pathname={pathname} toc={toc}>
+    <DocPage title="Install">…</DocPage>
+  </Doc>
+</ActivityLayout>
+```
+
+- The shell's header stays the page's only bar: `Doc` draws no top bar and no
+  reading bar, and does not take the viewport's height.
+- The page tree (from `md`) and the outline (from `xl`) stick under the header,
+  at the offset `ActivityContent`'s `aside` uses, and scroll with the shell:
+  its window, or the region of a `scroll="container"` shell.
+- On a phone the tree is a sheet, opened by « Browse docs » under the header
+  (not the shell's « Menu »), together with the search and `actions`. Its list
+  and the page clear a bottom bar or the floating toolbar (`--nxgt-bottom-chrome`).
+- Without `chrome` (or `chrome="standalone"`) `Doc` is what it was: it owns the
+  page.
+
+See [Doc](../components/navigation-and-layout.md#doc).
+
+## A public page outside the shell
+
+A landing or marketing page is not inside the app shell: it has no rail or
+sidebar and is read by people who are not signed in. `LandingLayout` is its
+frame (a top bar on `TopNav`, a drawer on a phone, `LandingSection` bands, a
+`SiteFooter`), and it takes the same `items` as the shell, so the links are
+declared once. See
+[LandingLayout](../components/navigation-and-layout.md#landinglayout).
+
 ## Dense pages on large screens
 
 On a 1440 or 1920 px screen a page should show more, not stretch the same four
@@ -1192,7 +1796,9 @@ export function InvoiceTrail() {
 `AppSidebar`, `AppHeader` and `AppBreadcrumb` are exported for a layout of your
 own. They take the same `items`; `AppHeader` takes `actions`, `avatar`,
 `showMenuIcon` (default `true`), and `menuOpen` / `onMenuOpenChange` to control
-its phone menu sheet. The lower-level `Sidebar`, `TopAppBar` and
+its phone menu sheet, `tabs` (a node, default none: a `TabsNav` drawn as a row
+at the foot of the bar) and `back` (a `ShellBack`, default none: the back arrow,
+before the menu button). The lower-level `Sidebar`, `TopAppBar` and
 `Breadcrumb` primitives are on the
 [navigation & layout](../components/navigation-and-layout.md) page.
 
@@ -1211,3 +1817,36 @@ render(
   </MemoryRouter>,
 );
 ```
+
+A bar of your own with a back arrow and tabs, complete:
+
+```tsx
+import { MemoryRouter } from 'react-router';
+import {
+  AppHeader,
+  TabsNav,
+  TabsNavLink,
+  type MenuItem,
+} from '@nxgt/material/components';
+
+const items: MenuItem[] = [{ label: 'Home', url: '/', icon: 'house' }];
+
+export function ProjectBar() {
+  return (
+    <MemoryRouter initialEntries={['/projects/activity']}>
+      <AppHeader
+        items={items}
+        back={{ to: '/projects', label: 'Projects' }}
+        tabs={
+          <TabsNav aria-label="Project sections" value="activity">
+            <TabsNavLink to="/projects/overview" value="overview">Overview</TabsNavLink>
+            <TabsNavLink to="/projects/activity" value="activity">Activity</TabsNavLink>
+          </TabsNav>
+        }
+      >
+        <h1>Atlas redesign</h1>
+      </AppHeader>
+    </MemoryRouter>
+  );
+}
+```