@nxgt/material 3.85.1 → 3.86.1

package/docs/README.md

@@ -32,6 +32,7 @@ detail: every option, the second example, and the traps.
 | [SSR](guides/ssr.md) | Your app renders on a server and bundles this package |
 | [Content Security Policy](guides/csp.md) | Your app sends a strict CSP: the directives to use, the components that still inject a `<style>`, the zod and KaTeX settings, self-hosting a font, the per-request nonce |
 | [The Vite plugin](guides/vite-plugin.md) | You are adding `nxgtMaterial()` to `vite.config.ts`: the CSP by hash or nonce, fonts, the styles check, PDFs on a bundled server, and each option's opt-out |
+| [Moving to TopAppBar](guides/migrating-to-top-app-bar.md) | Your app uses `AppHeader`, `TopAppBar`'s `variant` / `headline`, the shell's `'center'` / `'medium'` / `'large'` header values or the `app-header*` slots: each old spelling and its replacement, the visual changes, the slot rename planned for the next major |
 | [Migrating to 3.0](guides/migrating-to-3.md) | You are upgrading from 2.x: the React 19.3 and React Router 8.5 peers, `ActivityLayout`'s default route transition, `use(browser())` in server HTML, and each API removed in 3.0 with what replaces it |
 | [Date and time fields: from 2.x](guides/date-time-fields-2-x.md) | Your app used `DateField`, `DateRangeField`, `TimeField` or `TimePicker` before their redesign: each change in look and behaviour, the 2.x ways back that 3.0 removed, and what to change in tests |
 | [The field look (2.x)](guides/field-look-2-x.md) | Your fields or pickers look different after an upgrade (8px corners, the focus halo, a dashed read-only, a 44px `NativeSelect`, a list connected to its trigger, a `CountryField` with no chip, new group headers, the date and time fields' boxes) and you want to know what changed or get the earlier look back |

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

@@ -7,11 +7,11 @@ 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; `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-appshell.webp" width="96" alt=""> | [ActivityLayout](#activitylayout) | App shell: sidebar, header, breadcrumbs, titled page; `header` sets the app bar, a `TopAppBar` (small, medium-flexible, large-flexible or search, 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 (small, center, medium, large) and bottom bars |
+| <img src="../previews/navigation-layout-topappbar.webp" width="96" alt=""> | [TopAppBar, BottomAppBar](#topappbar) | The top app bar (small, medium-flexible, large-flexible, search; collapse, icon actions as data, account menu, primary action) and a bottom bar |
 | | [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 |
@@ -68,7 +68,7 @@ const items: MenuItem[] = [
 ```
 
 Parts: `ActivityLayout` (the chrome), `ActivityContent` (one screen),
-`AppSidebar`, `AppHeader` and `AppBreadcrumb`, which the layout composes and
+`AppSidebar`, `AppHeader` (deprecated, use `TopAppBar`) and `AppBreadcrumb`, which the layout composes and
 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>"
@@ -90,10 +90,11 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 | `headerTitle` | `ReactNode` | — | the header's leading title (the context: an organisation's name), after the phone's menu button, truncated when long; when it is cut off, its full text is the `title` tooltip (#629) |
 | `handle.title` | `ReactNode \| (match: UIMatch) => ReactNode` | — | on a route: the page's title in the app bar, its one `h1`, in the first server HTML; `ActivityContent` leaves its own title out while it is set (see the [app shell guide](../guides/app-shell.md#the-pages-title-in-the-app-bar)) |
 | `titleAfter` / `handle.titleAfter` | `ReactNode \| (match: UIMatch) => ReactNode` | — | a node right after the page's title in the app bar, outside its `h1` (a record's `Switcher`); stays on screen on a phone, the title truncates first; the prop wins over the handle (see the [app shell guide](../guides/app-shell.md#a-slot-after-the-title)) |
-| `headerContext` | `ReactNode` | — | a small muted context line (the tenant) after the page's title and its slot, from `md` up, outside the `h1`, truncated with its full text as the tooltip; hidden on a phone, where `context` fills the menu sheet (see the [app shell guide](../guides/app-shell.md#a-context-line-after-the-title)) |
+| `headerContext` | `ReactNode` | — | the bar's `subtitle`: a small muted context line (the tenant) under the page's title and its slot, from `md` up, outside the `h1`, truncated with its full text as the tooltip; hidden on a phone, where `context` fills the menu sheet (see the [app shell guide](../guides/app-shell.md#a-context-line-after-the-title)) |
 | `breadcrumb` | `boolean` | `true` | `false` hides the breadcrumb trail (an error page); it is also hidden when every matched `handle.breadcrumb` renders `null`; see the [app shell guide](../guides/app-shell.md#breadcrumbs) |
 | `breadcrumbRoot` | `{ label: ReactNode; to: string }` or `{ label: string; to: string; icon: true }` | — | the breadcrumb's first crumb: a text link in place of the home icon, or with `icon: true` the home icon alone linked to `to`, named and tooltipped `label` (`AppBreadcrumb`'s `root`); see the [app shell guide](../guides/app-shell.md#breadcrumbs) |
-| `headerActions` | `ReactNode` | — | header, before the avatar |
+| `headerActions` | `ReactNode \| TopAppBarAction[]` | — | header, before the avatar; data (`TopAppBarAction`: `label`, `icon`, `onClick` / `href`, `placement` `'bar'` or `'account'`, `group`, `selected`, `disabled`; see [TopAppBar](#topappbar)) draws free icon buttons and an account menu |
+| `headerPrimaryAction` | `TopAppBarPrimaryAction` (`{ label, icon, onClick?, disabled? }`) | — | the bar's `primaryAction`, the screen's main action: a `Button` from 768 px, a `Fab` on a phone |
 | `title`, `subtitle`, `actions` | `ReactNode` | — | `ActivityContent`'s header card; `title` is left out while a route's `handle.title` puts the page's title in the app bar |
 | `header` / `hideHeader` | `ReactNode` / `boolean` | — | `ActivityContent`: replace or drop the header card |
 | `contentAs` / `scroll` | `'main' \| 'div'` / `'document' \| 'container'` | `'main'` / `'document'` | the content region is the page's `<main>`; the document scrolls (see the [app shell guide](../guides/app-shell.md#landmarks-headings-and-scrolling)) |
@@ -107,7 +108,7 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 | `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) |
+| `header` | `'small' \| 'medium-flexible' \| 'large-flexible' \| 'search' \| 'none' \| { size?, align?, collapse?, hideOnScroll?, tabs?, search? }` | `'small'` | `ActivityLayout`: the app bar, drawn with `TopAppBar`. `size` and `align` pick its look (the old `'center'`, `'medium'`, `'large'` and `variant` still work, deprecated); `collapse` (default on for medium and large) and `hideOnScroll` follow the scroll; `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 [Top app bar sizes](../guides/app-shell.md#top-app-bar-sizes), [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) |
@@ -128,7 +129,7 @@ pads its bottom and shortens its sidebar by the bar's height
 footer stay above it. Another layout adds `pb-(--nxgt-media-dock)` to what
 scrolls.
 
-**Storybook:** `Navigation & layout/AppShell` · **Vue:** `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb`
+**Storybook:** `Navigation & layout/AppShell` · **Vue:** `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader` (deprecated, use `TopAppBar`), `AppBreadcrumb`
 
 ---
 
@@ -360,19 +361,79 @@ recolour the rail. See [Theming](../guides/theming.md#the-active-entry-of-the-si
 
 ![TopAppBar](../previews/navigation-layout-topappbar.webp)
 
-Top bar surface, and a bottom bar of icon actions with an active state.
+The top app bar: the bar `ActivityLayout` draws, for a layout of your own. A
+`title` that is the page's one `<h1>`, a `subtitle` under it, four sizes, a
+collapse on scroll, free icon actions with an account menu, and a main action.
+Flat on the page ground; once the page scrolls it takes a soft tint and a hairline.
+
+```tsx
+import { Bell, Languages, Plus } from 'lucide-react';
+import { Avatar, TopAppBar } from '@nxgt/material/components';
+
+<TopAppBar
+  as="header"
+  size="large-flexible"
+  collapse
+  title="Orders"
+  subtitle="Acme workspace"
+  actions={[
+    { label: 'Notifications', icon: <Bell />, onClick: openInbox },
+    { label: 'English', icon: <Languages />, group: 'Language', selected: true, placement: 'account' },
+    { label: 'Français', group: 'Language', placement: 'account', onClick: () => setLocale('fr') },
+  ]}
+  trailing={<Avatar alt="Ada Lovelace" fallback="AL" />}
+  primaryAction={{ label: 'New order', icon: <Plus />, onClick: createOrder }}
+/>
+```
+
+`collapse` and `hideOnScroll` only mark the bar (`data-collapse`,
+`data-hide-on-scroll`): the scroll is followed by the shell, so in `ActivityLayout`
+use `header` instead (see [Top app bar sizes](../guides/app-shell.md#top-app-bar-sizes)).
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `size` | `'small' \| 'medium-flexible' \| 'large-flexible' \| 'search'` | `'small'` | `small`: one row. `medium-flexible` and `large-flexible`: the `title` on a second row (28 px, and 40 px or 36 px on a phone; up to two lines in large), collapsing into the small row. `search`: the `search` field is the bar's centre. Without a `title` a medium or large bar draws as small |
+| `align` | `'start' \| 'center'` | `'start'` | `center` centres a small bar's title |
+| `title` / `titleId` | `ReactNode` / `string` | — | the bar renders `title` as the page's one `<h1>`; `titleId` is its `id`, to name a region |
+| `subtitle` | `ReactNode` | — | a muted `<p>` right after the `<h1>`, one line, truncated |
+| `titleAfter` | `ReactNode` | — | beside the title: a badge, a status |
+| `leading` / `trailing` | `ReactNode` | — | start of the row (menu or back button) / its end (the avatar) |
+| `actions` | `ReactNode \| TopAppBarAction[]` | — | a node is drawn as given. An array of data (every item a plain object with a string `label`) draws free ghost icon buttons (one on a phone, two from 768 px) and gathers the rest, and every `'account'` action, in a menu opened by `trailing` (named "Account menu") or by a More button when there is no `trailing` |
+| `primaryAction` | `TopAppBarPrimaryAction` | — | `{ label, icon, onClick?, disabled? }`: a `Button` from 768 px; on a phone a `Fab` above `--nxgt-bottom-chrome`, portalled to `document.body` after mount |
+| `search` | `ReactNode` | — | the field of a `'search'` bar; the title stays in the page as an `sr-only` `<h1>` |
+| `tabs` | `ReactNode` | — | a row under the bar: a `Tabs` list |
+| `collapse` / `hideOnScroll` | `boolean` | `false` | mark the bar as collapsing its second row, or hiding on scroll down |
+| `linkComponent` | `LinkComponent` | nearest `LinkComponentProvider`'s, else `<a>` | draws an action with an `href` |
+| `as` | `'div' \| 'header'` | `'div'` | the element drawn; use `'header'` for the page's banner |
+| `variant` | `'small' \| 'center' \| 'medium' \| 'large'` | — | deprecated for `size` and `align`: warns once in development |
+| `headline` | `ReactNode` | — | deprecated for `title`: renders in a non-heading element; warns once in development |
+
+`TopAppBarAction` (the items of `actions`):
+
+| Field | Type | Effect |
+| --- | --- | --- |
+| `label` | `string` | required: the icon button's accessible name and the menu entry's text |
+| `icon` | `ReactNode` | decorative; the action is named by `label` |
+| `onClick` | `() => void` | the action was chosen |
+| `href` | `string` | makes the action a link, drawn with `linkComponent` |
+| `placement` | `'bar' \| 'account'` | `'bar'` (default): a bar icon while there is room. `'account'`: always in the account menu |
+| `group` | `string` | the menu section ("Language", "Theme"): entries sit under that label, inline (never a submenu, which overflows at 360 px); entries without one come first |
+| `selected` | `boolean` | the current choice of its group: a group of non-link entries where one sets `selected` is a radio group (`menuitemradio`, `aria-checked`); a link entry with `selected` is the current page (`aria-current="page"`) |
+| `disabled` | `boolean` | the action cannot be chosen |
+| `id` | `string` | the key; defaults to `label` |
+
+The `trailing` avatar becomes the menu's trigger (a `<button>`), so it must hold no
+link, button or input (a warning in development). New message keys:
+`material.top-app-bar.account` and `material.top-app-bar.more` (en, fr).
+
+`BottomAppBar` is a row of icon actions that spaces its children and styles the
+one with `data-state="active"`; it takes a `div`'s props.
 
 <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-md" emphasized className="flex-1">Inbox</Typography>
-  <IconButton variant="ghost" aria-label="Search"><Search /></IconButton>
-</TopAppBar>
+import { Book, Camera } from 'lucide-react';
+import { BottomAppBar, IconButton } from '@nxgt/material/components';
 
 <BottomAppBar>
   <IconButton data-state="active" aria-label="Camera"><Camera /></IconButton>
@@ -380,22 +441,14 @@ import { BottomAppBar, IconButton, TopAppBar, Typography } from '@nxgt/material/
 </BottomAppBar>
 ```
 
-`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)).
+The root is a column (`flex-col`) whose children sit in a
+`[data-slot="top-app-bar-row"]`: a `justify-between`, `gap-*` or `items-*` in the
+root's `className` does not reach them (aim it at the row), and `title` is the
+bar's `<h1>`, no longer the HTML `title` attribute. A `className` background,
+radius or shadow wins at rest; once scrolled the tint replaces the background.
+The shell's bar takes its height from `--nxgt-header-height`.
 
-```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>
-```
+Moving from `AppHeader` or the old props: [Moving to TopAppBar](../guides/migrating-to-top-app-bar.md).
 
 **Storybook:** `Navigation & layout/TopAppBar`, `Navigation & layout/BottomAppBar` · **Vue:** `TopAppBar`, `BottomAppBar`
 
@@ -422,7 +475,7 @@ function Shell() {
     <ActivityLayout
       items={items}
       header={{
-        variant: 'small',
+        size: 'small',
         search: {
           value: query,
           onValueChange: setQuery,

package/docs/guides/app-shell.md

@@ -201,10 +201,11 @@ partitionMenu(items);                              // { content, footer }
 | `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href` (see below). Defaults to the [`LinkComponentProvider`](../components/primitives.md#linkcomponentprovider)'s link when one is set. |
 | `headerTitle` | `ReactNode` | — | The header's leading title: the context the app is in (the active organisation's name), right after the phone's menu button, truncated when long; when it is cut off, its full text is the `title` tooltip (#629) |
 | `titleAfter` | `ReactNode` | — | A node right after the page's title in the app bar, outside its `h1` (a record's `Switcher`); wins over a route's `handle.titleAfter` (see [A slot after the title](#a-slot-after-the-title)) |
-| `headerContext` | `ReactNode` | — | A small muted context line (the tenant's name) after the page's title and its slot, from `md` up: outside the `h1`, truncated, its full text the tooltip once cut off. Not shown on a phone, where the menu sheet's `context` carries it (see [A context line](#a-context-line-after-the-title)) |
+| `headerContext` | `ReactNode` | — | The bar's `subtitle`: a small muted context line (the tenant's name) under the page's title, from `md` up: outside the `h1`, truncated, its full text the tooltip once cut off. Not shown on a phone, where the menu sheet's `context` carries it (see [A context line](#a-context-line-after-the-title)) |
 | `breadcrumb` | `boolean` | `true` | `false` hides the breadcrumb trail, for an error page whose matched routes would show a misleading one (see [Breadcrumbs](#breadcrumbs)) |
 | `breadcrumbRoot` | `AppBreadcrumbRoot` (`{ label: ReactNode; to: string }`, or `{ label: string; to: string; icon: true }`) | — | The breadcrumb's first crumb, in place of the default home icon: a text link to `to`, or with `icon: true` the home icon alone, linked to `to` and named `label` (see [Breadcrumbs](#breadcrumbs)) |
-| `headerActions` | `ReactNode` | — | In the header, before the avatar: notifications, help, `ThemeToggle` |
+| `headerActions` | `ReactNode \| TopAppBarAction[]` | — | In the header, before the avatar: notifications, help, `ThemeToggle`; an array of data draws free icon buttons, the rest in the account menu |
+| `headerPrimaryAction` | `TopAppBarPrimaryAction` (`{ label, icon, onClick?, disabled? }`) | — | The screen's main action in the header: a `Button` from 768 px, a `Fab` on a phone |
 | `children` | `ReactNode` | — | The routed content, usually `<Outlet />` |
 | `contentAs` | `'main' \| 'div'` | `'main'` | The content region's element: the page's `<main>` landmark, or a `div` when your app renders its own `<main>` |
 | `scroll` | `'document' \| 'container'` | `'document'` | Who scrolls: the page (header and sidebar sticky), or the content region inside a shell one screen high |
@@ -212,7 +213,7 @@ partitionMenu(items);                              // { content, footer }
 | `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) |
+| `header` | `'small' \| 'medium-flexible' \| 'large-flexible' \| 'search' \| 'none' \| { size?, align?, collapse?, hideOnScroll?, tabs?, search? }` | `'small'` | The app bar's size, overridable per route with `handle.header`; the old `'center'`, `'medium'`, `'large'` and `variant` are deprecated; see [Top app bar sizes](#top-app-bar-sizes) |
 | `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) |
 
@@ -250,11 +251,49 @@ const MyLink: AppShellLinkComponent = ({ href, ...props }) => <Link to={href} {.
 // <ActivityLayout items={items} linkComponent={MyLink}>…</ActivityLayout>
 ```
 
+Actions as data: `headerActions` also takes a `TopAppBarAction[]` (`label`,
+`icon`, `onClick` or `href`, `placement: 'bar' | 'account'`, `group`, `selected`,
+`disabled`). The first ones are free icon buttons in the bar (one on a phone, two
+from 768 px); the others, and every `'account'` action, go to the menu opened by
+the `avatar`, which then must hold no link or button. `headerPrimaryAction` is
+the screen's main action:
+
+```tsx
+<ActivityLayout
+  items={items}
+  avatar={<Avatar src={user.photo} />}
+  headerActions={[
+    { label: 'Notifications', icon: <Icon name="bell" />, onClick: openInbox },
+    { label: 'Help', icon: <Icon name="circle-question" />, href: '/help' },
+    { label: 'Sign out', placement: 'account', onClick: signOut },
+  ]}
+  headerPrimaryAction={{ label: 'New invoice', icon: <Icon name="plus" />, onClick: create }}
+>
+  <Outlet />
+</ActivityLayout>
+```
+
 `className` and the rest of the `div` props (`id`, `data-*`…) go to the outer
 element, `[data-slot=activity-layout]`. The sticky app bar (menu button,
 `headerTitle`, `headerActions` and avatar) is `[data-slot=app-header]`, so a
 test or an accessibility helper can name it without a structural selector;
-`AppHeader` carries the same slot when used on its own.
+`AppHeader` (deprecated, use `TopAppBar`) carries the same slot when used on
+its own. The bar is a `TopAppBar` drawn as the page's `<header>` banner; it keeps
+the `app-header*` slot names below, which `TopAppBar` styles too. They become
+`top-app-bar*` at the next major.
+
+| `data-slot` | Marks |
+| --- | --- |
+| `app-header` | the bar's root (`<header>`) |
+| `app-header-page-title` | the page's `h1` |
+| `app-header-context` | the muted line under the title (`headerContext`) |
+| `app-header-headline` | the second row of a medium or large bar |
+| `app-header-collapsed-title` | the title's copy in the small row of a collapsing bar |
+| `app-header-tabs` | the tab row under the bar |
+| `app-header-title` | the leading `headerTitle` |
+| `app-header-title-after` | the slot after the title (`titleAfter`) |
+| `app-header-back` | the back arrow |
+
 `avatar` and `headerActions` are props because the shell holds no session:
 read the user wherever your app keeps it and pass the node.
 
@@ -328,7 +367,7 @@ today: the menu sheet on a phone, the rail from `md`, a small header.
 <ActivityLayout
   items={items}
   navigation={{ phone: 'modal-drawer', tablet: 'rail', desktop: 'rail' }}
-  header={{ variant: 'small' }}
+  header={{ size: 'small' }}
 >
   <Outlet />
 </ActivityLayout>
@@ -346,9 +385,10 @@ today: the menu sheet on a phone, the rail from `md`, a small header.
   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));
+- `header`: `'small'`, `'medium-flexible'`, `'large-flexible'`, `'search'` or
+  `'none'`, or `{ size, align, collapse, hideOnScroll, tabs, search }` (the old
+  `'center'`, `'medium'`, `'large'` and `variant` are deprecated). The sizes and
+  `hideOnScroll` are drawn (see [Top app bar sizes](#top-app-bar-sizes));
   `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)).
@@ -676,71 +716,122 @@ the user asked for less motion: skip the slide and snap. The header
 (`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
+### Top app bar sizes
 
-`header` chooses the bar's size, the way Material 3 does. Unset is `'small'`:
-today's one row, byte for byte.
+`header` chooses the bar's size, the way Material 3 does, and the shell draws it
+with [`TopAppBar`](../components/navigation-and-layout.md#topappbar). Unset is
+`'small'`: one row, the title beside the actions.
 
 ```tsx
 import { ActivityLayout, type AppShellHandle } from '@nxgt/material/components';
 
-<ActivityLayout items={items} header="large">
+<ActivityLayout items={items} header="large-flexible">
   <Outlet />
 </ActivityLayout>
 
 // a route opts in, whatever the layout says
-export const handle = { title: 'Projects', header: 'large' } satisfies AppShellHandle;
+export const handle = { title: 'Projects', header: 'large-flexible' } satisfies AppShellHandle;
 
-// a bar that goes away on the way down
-<ActivityLayout items={items} header={{ variant: 'small', hideOnScroll: true }} />
+// a centred small bar that goes away on the way down
+<ActivityLayout items={items} header={{ size: 'small', align: 'center', 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`).
+Defaults: `size` is `'small'`, `align` is `'start'`, `collapse` is `true` for the
+two flexible sizes, `hideOnScroll` is `false`. Nothing to import beyond
+`styles.css`: the bar's CSS ships with it.
+
+| Size | Use it for | What it draws |
+| --- | --- | --- |
+| `'small'` | most screens, a dense tool | one row: the title beside the actions. `align: 'center'` centres the title between the menu button and the actions |
+| `'medium-flexible'` | a section's landing screen | the page's title on a second row (28 px), under the small row |
+| `'large-flexible'` | a screen that opens a flow or a long list | the title on a second row, bigger (40 px, 36 px on a phone) and up to two lines |
+| `'search'` | a search-first screen | the `header.search` field is the bar's centre; the title stays in the page as a visually hidden `h1`, so the screen keeps its heading |
+| `'none'` | a full-screen tool that draws its own chrome | 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"`) |
+
+- **Collapse.** A flexible bar folds its second row into the small row as the
+  page scrolls: the headline fades and the bar shrinks over the headline row's
+  measured height, the title shrinks to 90% from its start edge, and the small
+  row then shows the title (a copy hidden from assistive technology). A scrolled
+  bar takes a soft tint and a 1px hairline. `collapse: false` keeps the headline
+  however far the page scrolls.
+- **`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.
+- **Subtitle.** `headerContext` is the bar's subtitle, a muted line under the title
+  (see [A context line after the title](#a-context-line-after-the-title)).
+- **Actions and main action.** `headerActions` takes nodes or a `TopAppBarAction[]`,
+  and `headerPrimaryAction` the screen's main action (see
+  [The app bar](#the-app-bar-a-title-the-actions-the-account)).
+
+The bar's height is `--nxgt-header-height` (default `4rem`, see
+[the header height](./theming.md#the-header-height)): the row is that height
+less the bar's own vertical padding, so a custom value resizes the bar, the
+rail's header and the first-paint total together. A `className` on the bar (a
+background, a radius, a shadow) wins over its at-rest look; once the page
+scrolls, the scrolled tint replaces a `className` background. The bar is drawn
+as the page's `<header>`; `title` on a standalone `TopAppBar` is its `<h1>` (it
+was the HTML `title` attribute), and its root is a column whose children sit in
+a `[data-slot="top-app-bar-row"]`, so layout utilities on the root's `className`
+(`justify-between`, `gap-*`, `items-*`) no longer reach them (see
+[Moving to TopAppBar](./migrating-to-top-app-bar.md#what-looks-different)).
+
+A route gives its own through `handle.header`: a size (`'large-flexible'`) or the
+options (`{ size, align, collapse, hideOnScroll, tabs, search }`, 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 size keeps the layout's `hideOnScroll` and
+`align`. It is read from the matched routes, so the server and the browser draw
+the same bar.
+
+The title **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 search size.** `header: { size: 'search', search: { placeholder: 'Search projects' } }`
+puts the search field at the bar's centre. A route that sets a `handle.title`
+still gets its `h1`, visually hidden but in the accessibility tree and
+labelling `<main>`; without a title the screen's own `ActivityContent` title is
+the heading, as for any small bar. See [The app bar's search](#the-app-bars-search)
+for the field's props.
+
+**Phone and desktop.**
+
+- On a phone the menu button is a ghost icon button leading the bar, with no
+  brand or logo; the bar keeps one free icon action, the rest go to the account
+  menu as inline sections. `headerPrimaryAction` is a floating button above the
+  bottom navigation. `headerContext` is hidden (the sheet's `context` covers it).
+- From 768 px two icon actions fit, `headerPrimaryAction` is a `Button` in the
+  bar, and `headerContext` shows under the title.
+- Heights: the headline row of a medium bar is 3 rem and a large bar's 6.5 rem
+  before it is measured, then follows the title's real height.
+
+**Reduced motion.** Under `prefers-reduced-motion: reduce` the collapse snaps
+between the two states at the halfway point, with no morph, no slide for
+`hideOnScroll` and no transition on the bar's tint.
+
 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.
+`--nxgt-header-progress` (0 expanded, 1 collapsed), through `setProperty`, and
+`data-scrolled` once the page has moved, so no inline style reaches the markup
+and a frame of scrolling does not re-render. A plain shell, with no collapsing
+or hiding bar, tracks no scroll at all.
+
+**Deprecated spellings.** `'center'`, `'medium'`, `'large'` and `variant` in the
+options still work and log a one-time development warning (see
+[troubleshooting](../troubleshooting.md#activitylayout-header-center-medium-or-large-is-deprecated)):
+`'center'` is `{ size: 'small', align: 'center' }`, `'medium'` is
+`'medium-flexible'`, `'large'` is `'large-flexible'`. See
+[Moving to TopAppBar](./migrating-to-top-app-bar.md).
+
+`TopAppBar` takes the same as props (`size`, `align`, `collapse`, `hideOnScroll`,
+`title`, `subtitle`, `tabs`, `search`) for a bar of your own; `AppHeader` is its
+deprecated wrapper (see [Using the parts](#using-the-parts)). 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
 
@@ -755,13 +846,13 @@ import { ActivityLayout } from '@nxgt/material/components';
 <ActivityLayout
   items={items}
   header={{
-    variant: 'small',
+    size: '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 } };
+export const handle = { title: 'Settings', header: { size: 'small', search: false } };
 ```
 
 The search never changes the shape of the page: the content stays mounted when
@@ -792,7 +883,7 @@ const tabs = (
 );
 
 export function Layout({ items }: { items: MenuItem[] }) {
-  return <ActivityLayout items={items} header={{ variant: 'small', tabs }} />;
+  return <ActivityLayout items={items} header={{ size: 'small', tabs }} />;
 }
 ```
 
@@ -809,13 +900,13 @@ const projectTabs = (
 
 export const handle = {
   title: 'Atlas',
-  header: { variant: 'small', tabs: projectTabs }, // tabs: null drops the layout's
+  header: { size: '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
+that only names a size 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
@@ -1045,14 +1136,14 @@ A multi-tenant app keeps the current tenant visible on a desktop screen with
 ```
 
 - **It is outside the `h1`** (`[data-slot=app-header-context]`), so the
-  heading's name stays the page's title; it is truncated (at most 14rem), and
-  its full text is the `title` tooltip once it is cut off (#629).
+  heading's name stays the page's title; it sits under the title (the bar's
+  subtitle), is truncated to the title's width, and its full text is the `title` tooltip once it is cut off (#629).
 - **From `md` up only.** On a phone it is hidden: the menu sheet's `context`
   line covers it. The two props are independent, so setting `context` alone
   adds nothing to the bar, and setting both never shows the name twice on one
   screen.
 - **The title truncates first**: with a long title, the slot and the line
-  together, the title gives way (two lines on a phone, then an ellipsis); the slot stays whole and the line keeps its cap.
+  together, the title gives way (two lines on a phone, then an ellipsis); the slot stays whole and the line stays under the title.
 - **It needs a page title**: while the bar shows none (no `handle.title`),
   `headerTitle` is the context line and `headerContext` is ignored.
 
@@ -1793,8 +1884,8 @@ export function InvoiceTrail() {
 
 ## Using the parts
 
-`AppSidebar`, `AppHeader` and `AppBreadcrumb` are exported for a layout of your
-own. They take the same `items`; `AppHeader` takes `actions`, `avatar`,
+`AppSidebar`, `AppHeader` (deprecated, use `TopAppBar`) 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, `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,
@@ -1802,6 +1893,10 @@ before the menu button). The lower-level `Sidebar`, `TopAppBar` and
 `Breadcrumb` primitives are on the
 [navigation & layout](../components/navigation-and-layout.md) page.
 
+The shell draws its bar with `TopAppBar`, as the page's `<header>`. `AppHeader`
+is deprecated: it stays as a wrapper over `TopAppBar` with the same props, and
+warns once in development.
+
 `AppHeader` needs a React Router context even on its own: its menu sheet reads
 the location (`useLocation`) to close when it changes, and outside a router
 that hook throws. Render it under your `RouterProvider` — or, in a test, inside

package/docs/guides/drawing.md

@@ -187,6 +187,8 @@ A fill, a stroke or a gradient stop is a **role**, a **tone** or a free colour.
   `outline-variant`, `success`, `info`, `warning`, `neutral`. `ROLES` lists them
   and `ROLE_VARS` gives each one's CSS variable (`on-primary-container` is
   `--primary-text`, `outline` is `--muted-foreground`).
+  The drawing role `surface-container` resolves to `--card`; it is not the
+  `--surface-container` theme token (`bg-surface-container`).
   They follow light and dark, scoped themes and a retheme with no re-render.
 - **Tones**: `tone('success')`, `tone('success', 'container')` (variants `base`,
   `text`, `on`, `container`) name a theme tone or an app tone of your own, the

package/docs/guides/layouts.md

@@ -75,7 +75,7 @@ layout of your own. Every preset, its entries (`bar`, `priority`, `group`,
 <ActivityLayout
   items={items}
   header={{
-    variant: 'large',
+    size: 'large-flexible',
     hideOnScroll: true,
     search: { placeholder: 'Search projects', shortcut: '/' },
     tabs: (
@@ -95,13 +95,13 @@ A route changes its own bar with a handle, and draws a back arrow:
 ```tsx
 export const handle = {
   title: 'Atlas redesign',
-  header: { variant: 'medium' },
+  header: { size: 'medium-flexible' },
   back: { to: '/projects', label: 'Projects' },
 } satisfies AppShellHandle;
 ```
 
 The search is a pill with a docked results panel from 768px and a full-screen
-view on a phone. See [The app bar variants](app-shell.md#the-app-bar-variants),
+view on a phone. See [Top app bar sizes](app-shell.md#top-app-bar-sizes),
 [the search](app-shell.md#the-app-bars-search),
 [the tabs](app-shell.md#tabs-under-the-app-bar) and
 [the back arrow](app-shell.md#the-back-arrow).