@nxgt/material 2.1.0 → 2.2.0

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

@@ -0,0 +1,592 @@
+# Navigation & layout
+
+Where a page sits and how you move between pages: the application shell,
+sidebars and app bars, breadcrumbs, page layouts, steppers, and a complete
+documentation-site shell. Everything is imported from
+`@nxgt/material/components`.
+
+| | Component | What it does |
+| --- | --- | --- |
+| <img src="../previews/navigation-layout-appshell.webp" width="96" alt=""> | [ActivityLayout](#activitylayout) | App shell: sidebar, header, breadcrumbs, titled page |
+| <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-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 |
+| <img src="../previews/navigation-layout-resizable.webp" width="96" alt=""> | [ResizableGroup](#resizablegroup) | Resizable panels |
+| <img src="../previews/navigation-layout-skiplink.webp" width="96" alt=""> | [SkipLink](#skiplink) | Skip-to-content link |
+| <img src="../previews/navigation-layout-pager.webp" width="96" alt=""> | [Pager](#pager) | Previous / next cards |
+| <img src="../previews/navigation-layout-seealso.webp" width="96" alt=""> | [SeeAlso](#seealso) | Related links |
+| <img src="../previews/navigation-layout-toc.webp" width="96" alt=""> | [Toc](#toc) | On-this-page outline |
+| <img src="../previews/navigation-layout-stepper.webp" width="96" alt=""> | [Stepper](#stepper) | Clickable steps with progress |
+| <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 |
+| <img src="../previews/navigation-layout-doc.webp" width="96" alt=""> | [Doc](#doc) | Documentation site shell |
+| <img src="../previews/navigation-layout-background.webp" width="96" alt=""> | [Background](#background) | Gradient backdrop with colour blobs |
+| | [NavigationRail](#navigationrail) | Placeholder, no props yet |
+
+## ActivityLayout
+
+![ActivityLayout](../previews/navigation-layout-appshell.webp)
+
+App shell: sidebar built from `items`, a header with a mobile sheet, route breadcrumbs and a titled page. See the [app shell guide](../guides/app-shell.md).
+
+```tsx
+import { Outlet } from 'react-router';
+import { ActivityContent, ActivityLayout, Button, type MenuItem } from '@nxgt/material/components';
+
+const items: MenuItem[] = [
+  { label: 'Home', url: '/', icon: 'house' },
+  { label: 'Identities', url: '/identities', icon: 'users' },
+  { label: 'Settings', url: '/settings', icon: 'gear', footer: true },
+];
+
+// The layout route, mounted once:
+<ActivityLayout items={items} avatar="/me.png">
+  <Outlet />
+</ActivityLayout>
+
+// Each leaf route:
+<ActivityContent title="Identities" subtitle="Everyone who can sign in" actions={<Button>Add</Button>}>
+  …
+</ActivityContent>
+```
+
+Parts: `ActivityLayout` (the chrome), `ActivityContent` (one screen),
+`AppSidebar`, `AppHeader` and `AppBreadcrumb`, which the layout composes and
+which work alone.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `MenuItem[]` | — | `label` (already translated), `url`, `icon`, `footer` |
+| `brand` | `ReactNode` | — | sidebar header |
+| `avatar` | `ReactNode` | — | an image URL or a node, in the header |
+| `headerActions` | `ReactNode` | — | header, before the avatar |
+| `title`, `subtitle`, `actions` | `ReactNode` | — | `ActivityContent`'s header card |
+| `header` / `hideHeader` | `ReactNode` / `boolean` | — | `ActivityContent`: replace or drop the header card |
+
+The active entry is the longest match across the whole menu, segment-aware.
+`AppBreadcrumb` reads `handle.breadcrumb` from `useMatches()`, so the shell
+needs a **data router** (`createBrowserRouter` / `createMemoryRouter` with
+`RouterProvider`), not `<BrowserRouter>`. Its crumbs are links (the home icon
+is one, named "Home", to the router's root, so a `basename` is kept) and the
+current page is text with `aria-current="page"`.
+`AppBreadcrumbItem` and `AppBreadcrumbSeparator` build a trail of your own (see
+the [app shell guide](../guides/app-shell.md#breadcrumbs)).
+
+**Storybook:** `Navigation & layout/AppShell` · **Vue:** `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb`
+
+---
+
+## Sidebar
+
+![Sidebar](../previews/navigation-layout-sidebar.webp)
+
+Collapsible navigation sidebar with icons, tooltips and active items.
+
+```tsx
+import { Home, Inbox, Settings } from 'lucide-react';
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarMenuItem,
+  SidebarMenuLabel,
+  TooltipProvider,
+} from '@nxgt/material/components';
+
+<TooltipProvider>
+  <Sidebar expanded={expanded} onExpandedChange={setExpanded} withToggleIcon>
+    <SidebarContent>
+      <SidebarMenuLabel>Project</SidebarMenuLabel>
+      <SidebarMenuItem icon={<Home />} active>Home</SidebarMenuItem>
+      <SidebarMenuItem icon={<Inbox />}>Inbox</SidebarMenuItem>
+    </SidebarContent>
+    <SidebarFooter>
+      <SidebarMenuItem icon={<Settings />}>Settings</SidebarMenuItem>
+    </SidebarFooter>
+  </Sidebar>
+</TooltipProvider>
+```
+
+Parts: `Sidebar`, `SidebarHeader`, `SidebarContent`, `SidebarFooter`,
+`SidebarMenuLabel` (`actions` slot), `SidebarMenuItem` (a button: `icon`,
+`active`, `tooltip`).
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `expanded` | `boolean` | `false` | labels beside the icons; collapsed shows icons with tooltips |
+| `onExpandedChange` | `(expanded: boolean) => void` | — | called by the toggle |
+| `withToggleIcon` | `boolean` | `false` | built-in expand / collapse button, shown on hover or while focus is inside the sidebar, named "Toggle sidebar" (`material.sidebar.toggle`) with `aria-expanded` |
+
+**Storybook:** `Navigation & layout/Sidebar` · **Vue:** `Sidebar` (same parts)
+
+---
+
+## TopAppBar
+
+![TopAppBar](../previews/navigation-layout-topappbar.webp)
+
+Top bar surface, and a bottom bar of icon actions with an active state.
+
+<img src="../previews/navigation-layout-bottomappbar.webp" height="56" alt="BottomAppBar">
+
+```tsx
+import { Book, Camera, Menu, Search } from 'lucide-react';
+import { BottomAppBar, IconButton, TopAppBar, Typography } from '@nxgt/material/components';
+
+<TopAppBar>
+  <IconButton variant="ghost" aria-label="Open menu"><Menu /></IconButton>
+  <Typography variant="title-medium" className="flex-1">Inbox</Typography>
+  <IconButton variant="ghost" aria-label="Search"><Search /></IconButton>
+</TopAppBar>
+
+<BottomAppBar>
+  <IconButton data-state="active" aria-label="Camera"><Camera /></IconButton>
+  <IconButton aria-label="Library"><Book /></IconButton>
+</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"`.
+
+**Storybook:** `Navigation & layout/TopAppBar`, `Navigation & layout/BottomAppBar` · **Vue:** `TopAppBar`, `BottomAppBar`
+
+---
+
+## Breadcrumb
+
+![Breadcrumb](../previews/navigation-layout-breadcrumb.webp)
+
+Breadcrumb primitives.
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@nxgt/material/components';
+
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem><BreadcrumbLink href="/docs">Docs</BreadcrumbLink></BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem><BreadcrumbPage>Breadcrumb</BreadcrumbPage></BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+Parts: `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`
+(`asChild` for a router link), `BreadcrumbPage`, `BreadcrumbSeparator`,
+`BreadcrumbEllipsis` (put it in a `DropdownMenuTrigger` for collapsed
+crumbs). For crumbs built from routes, use `AppBreadcrumb` from the
+[app shell](#activitylayout).
+
+**Storybook:** `Navigation & layout/Breadcrumb` · **Vue:** `Breadcrumb` (same parts)
+
+---
+
+## ListDetailsLayout
+
+![ListDetailsLayout](../previews/navigation-layout-listdetailslayout.webp)
+
+List / details that collapses to one view on mobile, a side pane that becomes a sheet, and a centred column.
+
+<img src="../previews/navigation-layout-panelayout.webp" height="96" alt="PaneLayout">
+<img src="../previews/navigation-layout-threadlayout.webp" height="96" alt="ThreadLayout">
+
+```tsx
+import { ListDetailsLayout, ListDetailsTrigger, PaneLayout, ThreadLayout } from '@nxgt/material/components';
+
+<ListDetailsLayout activeView={view} onActiveViewChange={setView}>
+  <ListDetailsLayout.List>{conversations}</ListDetailsLayout.List>
+  <ListDetailsLayout.Details>
+    <ListDetailsTrigger view="list">Back</ListDetailsTrigger>
+    {thread}
+  </ListDetailsLayout.Details>
+</ListDetailsLayout>
+
+<PaneLayout defaultOpen paneSide="right">
+  <PaneLayout.Content>
+    <PaneLayout.Trigger>Folders</PaneLayout.Trigger>
+    {messages}
+  </PaneLayout.Content>
+  <PaneLayout.Pane sheetTitle="Folders">{folders}</PaneLayout.Pane>
+</PaneLayout>
+
+<ThreadLayout header={<BackButton />}>
+  <SignUpForm />
+</ThreadLayout>
+```
+
+Below 648 px `ListDetailsLayout` shows one view at a time and
+`PaneLayout` moves its pane into a sheet; the `…Trigger` parts switch view or
+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. A page
+rendered only in the browser starts on the real layout. `ThreadLayout` is a centred column over the app
+[background](#background) for focused flows (sign-in, onboarding), with no
+app bar.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `activeView` / `defaultActiveView` / `onActiveViewChange` | `'list' \| 'details'` | `'list'` | `ListDetailsLayout`: which view a phone shows |
+| `listPosition` | `'left' \| 'right'` | `'left'` | `ListDetailsLayout` |
+| `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 |
+
+`useListDetails()` and `usePaneLayout()` read the state from inside.
+
+**Storybook:** `Navigation & layout/ListDetailsLayout`, `Navigation & layout/PaneLayout`, `Navigation & layout/ThreadLayout` · **Vue:** `ListDetailsLayout`, `PaneLayout`, `ThreadLayout`
+
+---
+
+## ResponsiveGrid
+
+![ResponsiveGrid](../previews/navigation-layout-responsivegrid.webp)
+
+Container-query grid that grows from 1 to 5 columns.
+
+```tsx
+import { ResponsiveGrid, StatCard } from '@nxgt/material/components';
+
+<ResponsiveGrid>
+  <StatCard label="Revenue" value="€48,200" />
+  <StatCard label="Orders" value="1,284" />
+  <StatCard label="Customers" value="812" />
+</ResponsiveGrid>
+```
+
+No props of its own. Columns follow the grid's own width, not the window's:
+2 from `@lg`, 3 from `@2xl`, 4 from `@4xl`, 5 from `@6xl`.
+
+**Storybook:** `Navigation & layout/ResponsiveGrid` · **Vue:** `ResponsiveGrid`
+
+---
+
+## ResizableGroup
+
+![ResizableGroup](../previews/navigation-layout-resizable.webp)
+
+Resizable panels with an optional grip handle.
+
+```tsx
+import { ResizableGroup, ResizablePanel, ResizableSeparator } from '@nxgt/material/components';
+
+<ResizableGroup orientation="horizontal" className="rounded-lg border">
+  <ResizablePanel defaultSize={30}>{sidebar}</ResizablePanel>
+  <ResizableSeparator withHandle />
+  <ResizablePanel defaultSize={70}>{editor}</ResizablePanel>
+</ResizableGroup>
+```
+
+Parts: `ResizableGroup`, `ResizablePanel`, `ResizableSeparator`
+(`withHandle` draws the grip). The props are those of
+`react-resizable-panels`; nest a group with `orientation="vertical"` for a
+grid.
+
+**Storybook:** `Navigation & layout/Resizable` · **Vue:** `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle`
+
+---
+
+## SkipLink
+
+![SkipLink](../previews/navigation-layout-skiplink.webp)
+
+Skip-to-content control, visible on focus. `DocSkipLink` composes it with `#doc-content`.
+
+```tsx
+import { SkipLink } from '@nxgt/material/components';
+
+<SkipLink href="#main" />
+<main id="main">…</main>
+```
+
+`href` defaults to `#content`; the label defaults to a translated "Skip to
+content". The preview shows it focused — it is invisible until the first Tab.
+
+**Storybook:** `Navigation & layout/SkipLink` · **Vue:** `SkipLink`
+
+---
+
+## Pager
+
+![Pager](../previews/navigation-layout-pager.webp)
+
+Previous / next cards for a sequence of pages. `DocPager` composes it.
+
+```tsx
+import { Pager } from '@nxgt/material/components';
+
+<Pager
+  previous={{ title: 'Install', href: '/docs/install', description: 'Add the package.' }}
+  next={{ title: 'Theming', href: '/docs/theming', description: 'CSS tokens.' }}
+  shortcuts
+/>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `previous`, `next` | `{ title; href; description? }` | — | either may be omitted |
+| `shortcuts` | `boolean` | `false` | shows `[` / `]` key hints (the `Doc` shell handles the keys) |
+| `previousLabel`, `nextLabel` | `string` | translated | small labels |
+| `linkComponent` | `ComponentType<{ href; className?; children? }>` | `<a>` | your router's link |
+
+External `href`s open in a new tab.
+
+**Storybook:** `Navigation & layout/Pager` · **Vue:** `Pager`
+
+---
+
+## SeeAlso
+
+![SeeAlso](../previews/navigation-layout-seealso.webp)
+
+Related-link list with outbound icons. `DocSeeAlso` composes it.
+
+```tsx
+import { SeeAlso } from '@nxgt/material/components';
+
+<SeeAlso
+  items={[
+    { title: 'Install', href: '/docs/install' },
+    { title: 'Source', href: 'https://example.com/source' },
+  ]}
+/>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `{ id?; title; href }[]` | — | external links get the outbound icon |
+| `label` | `string` | translated "See also" | heading |
+| `linkComponent` | `ComponentType<{ href; className?; children? }>` | `<a>` | your router's link |
+
+**Storybook:** `Navigation & layout/SeeAlso` · **Vue:** `SeeAlso`
+
+---
+
+## Toc
+
+![Toc](../previews/navigation-layout-toc.webp)
+
+On-this-page outline with a per-item active bar. Rail from `xl`, collapsible panel below. `DocToc` composes it.
+
+```tsx
+import { Toc, type TocItem } from '@nxgt/material/components';
+
+const items: TocItem[] = [
+  { id: 'intro', title: 'Introduction', level: 2 },
+  { id: 'install', title: 'Install', level: 2 },
+  { id: 'tokens', title: 'Tokens', level: 3 },
+];
+
+<Toc items={items} activeId={activeId} onSelect={setActiveId} />
+<Toc items={items} placement="panel" />
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `{ id; title; level?: 2 \| 3 \| 4 }[]` | — | `id` is the heading's anchor |
+| `activeId` | `string` | — | item with the active bar |
+| `onSelect` | `(id: string) => void` | — | an item was clicked |
+| `placement` | `'rail' \| 'panel'` | `'rail'` | sticky rail (shown from `xl`) or a collapsible panel (hidden from `xl`) |
+| `label`, `linkComponent` | `string`, link component | translated, `<a>` | heading and link |
+
+**Storybook:** `Navigation & layout/Toc` · **Vue:** `Toc`
+
+---
+
+## Stepper
+
+![Stepper](../previews/navigation-layout-stepper.webp)
+
+Clickable horizontal or vertical steps with status and progress; compact on mobile.
+
+```tsx
+import { CreditCard, Truck, User } from 'lucide-react';
+import { Stepper, TooltipProvider } from '@nxgt/material/components';
+
+<TooltipProvider>
+  <Stepper
+    active={active}
+    onChange={setActive}
+    steps={[
+      { icon: <User />, title: 'Account', description: 'Your profile details.' },
+      { icon: <Truck />, title: 'Shipping', status: 'completed' },
+      { icon: <CreditCard />, title: 'Payment' },
+    ]}
+  />
+</TooltipProvider>
+```
+
+Parts: `Stepper`, `StepperIndicator` (the progress bar alone: `current`,
+`max`), `resolveStepState`.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `steps` | `{ icon?; title; description?; status? }[]` | — | `status`: `'completed' \| 'error' \| 'upcoming'`, else derived from `active` |
+| `active` | `number` | `0` | current step; its `description` shows under the bar |
+| `onChange` | `(index: number) => void` | — | makes steps clickable |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | vertical from `md` only; phones get the compact bar |
+| `renderStepLabel` | `(step, index) => ReactNode` | — | replaces the "Step n" caption |
+
+A server renders the desktop layout (every step), as does a hydrating client;
+a phone switches to the compact bar right after hydrating. A page rendered
+only in the browser starts on the real layout.
+
+**Storybook:** `Navigation & layout/Stepper` · **Vue:** `Stepper`
+
+---
+
+## Steps
+
+![Steps](../previews/navigation-layout-steps.webp)
+
+Numbered editorial steps that stay visible on every breakpoint.
+
+```tsx
+import { Steps, StepsItem } from '@nxgt/material/components';
+
+<Steps>
+  <StepsItem title="Create a project">Scaffold the app and install peers.</StepsItem>
+  <StepsItem title="Import styles">Pull in the source @theme tokens.</StepsItem>
+  <StepsItem title="Render a page">Compose the shell around your article.</StepsItem>
+</Steps>
+```
+
+`StepsItem` takes a `title` and content; `index` overrides the number, which
+otherwise counts up in order.
+
+**Storybook:** `Navigation & layout/Steps` · **Vue:** `Steps`, `StepsItem`
+
+---
+
+## Hero
+
+![Hero](../previews/navigation-layout-hero.webp)
+
+Landing band with eyebrow, title, supporting copy and actions.
+
+```tsx
+import { Button, Hero } from '@nxgt/material/components';
+
+<Hero
+  eyebrow="Documentation"
+  title="Build the page, not the chrome."
+  description="A landing band with an eyebrow, title, supporting copy and actions."
+  actions={<Button>Get started</Button>}
+/>
+```
+
+`eyebrow`, `title`, `description`, `actions` and `children` (below the
+actions) are all content slots.
+
+**Storybook:** `Navigation & layout/Hero` · **Vue:** `Hero`
+
+---
+
+## Doc
+
+![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`.
+
+<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">
+
+```tsx
+import { Doc, DocPage, type DocNavItem, type DocTocItem } from '@nxgt/material/components';
+
+const items: DocNavItem[] = [
+  {
+    id: 'start',
+    title: 'Start',
+    items: [
+      { id: 'intro', title: 'Introduction', href: '/docs' },
+      { id: 'install', title: 'Install', href: '/docs/install' },
+    ],
+  },
+];
+const toc: DocTocItem[] = [{ id: 'what', title: 'What it is', level: 2 }];
+
+<Doc items={items} pathname={pathname} toc={toc} onNavigate={navigate} brand="Material">
+  <DocPage
+    title="Introduction"
+    description="A documentation shell."
+    crumbs={[{ title: 'Docs', href: '/docs' }, { title: 'Introduction' }]}
+    editHref="https://github.com/acme/docs/edit/main/intro.md"
+  >
+    <h2 id="what">What it is</h2>
+  </DocPage>
+</Doc>
+```
+
+Parts: `Doc` (the shell), `DocPage` (header, content, see also and pager);
+the pieces it composes — `DocTopbar`, `DocSidebar`, `DocToc`, `DocPager`,
+`DocSearch`, `DocSeeAlso`, `DocChildCards`, `DocProgress`, `DocSkipLink`,
+`DocHeader`, `DocCopyPage`, `DocCopyMarkdown` — and `DocEmpty` for a 404.
+`useDoc` / `DocProvider` / `useDocContext` expose the state for a shell of
+your own.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `DocNavItem[]` | — | sidebar tree, also the search index and the pager order |
+| `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 |
+| `searchable` | `boolean` | `true` | search field and ⌘K |
+| `brand`, `actions` | `ReactNode` | — | top bar, left and right |
+| `previous`, `next` | `DocPagerLink \| null` | from `items` | override the pager; `null` hides one side |
+
+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`, `DocToc`, `DocPager`, `DocSearch`, `DocChildCards`, `DocSeeAlso`, `DocEmpty`, `DocProgress`
+
+---
+
+## Background
+
+![Background](../previews/navigation-layout-background.webp)
+
+Full-viewport gradient with blurred colour blobs; centres its children.
+
+```tsx
+import { Background, Card } from '@nxgt/material/components';
+
+<Background>
+  <Card className="w-80 p-6">Welcome back</Card>
+</Background>
+```
+
+No props of its own. It fills the viewport (`size-lv`); pass a `className`
+such as `h-96 w-full` to use it as a band. `ActivityLayout` and
+`ThreadLayout` sit on it.
+
+**Storybook:** `Navigation & layout/Background` · **Vue:** `Background`
+
+---
+
+## NavigationRail
+
+Placeholder: renders an empty rail container and takes no props yet.
+
+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 { NavigationRail } from '@nxgt/material/components';
+
+<NavigationRail />
+```
+
+**Storybook:** — · **Vue:** `NavigationRail`