@nxgt/material 3.85.0 → 3.86.0

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).

package/docs/guides/migrating-to-top-app-bar.md

@@ -0,0 +1,156 @@
+# Moving to TopAppBar
+
+`ActivityLayout` draws its app bar with `TopAppBar`, and `TopAppBar` has new
+sizes, a title that is the page's `h1`, free icon actions and a main action. This
+is a minor release: every old spelling keeps working, logs a one-time development
+warning, and is removed no earlier than the next major. This page lists each one
+with what replaces it, what looks different, and which slots the next major renames.
+
+## Contents
+
+- [`AppHeader` becomes `TopAppBar`](#appheader-becomes-topappbar)
+- [`header` values and `handle.header`](#header-values-and-handleheader)
+- [`TopAppBar` `variant` and `headline`](#topappbar-variant-and-headline)
+- [Actions, the account menu and a main action](#actions-the-account-menu-and-a-main-action)
+- [What looks different](#what-looks-different)
+- [The `data-slot` rename in the next major](#the-data-slot-rename-in-the-next-major)
+
+## `AppHeader` becomes `TopAppBar`
+
+**Search**: `AppHeader`.
+
+`AppHeader` is a thin wrapper over `TopAppBar` with the props it always had; it
+logs `AppHeader: is deprecated, use TopAppBar` once in development. Inside
+`ActivityLayout` there is nothing to do: the layout does not use the wrapper.
+In a layout of your own, draw the bar with `TopAppBar`; the menu button and back
+arrow go in `leading`, the avatar in `trailing`.
+
+**Replace**:
+
+```tsx
+// before
+<AppHeader items={items} variant="large" headline={<h1>Orders</h1>} avatar={<Avatar />} />
+
+// after
+<TopAppBar
+  as="header"
+  size="large-flexible"
+  title="Orders"
+  leading={<MenuButton />}
+  trailing={<Avatar />}
+/>
+```
+
+`TopAppBar` does not draw the phone's menu sheet or read the router: the shell
+does. A bar of your own passes its own `leading` and `actions`. `AppHeader` also
+renders a `div`, where `as="header"` makes the bar the page's banner.
+
+## `header` values and `handle.header`
+
+**Search**: `header="center"`, `header="medium"`, `header="large"`,
+`header: 'center'` (and `'medium'`, `'large'`), `variant:` inside a `header` object
+or a route's `handle.header`.
+
+| Before | After |
+| --- | --- |
+| `'small'` | `'small'` (unchanged) |
+| `'center'` | `{ size: 'small', align: 'center' }` |
+| `'medium'` | `'medium-flexible'` |
+| `'large'` | `'large-flexible'` |
+| `'none'` | `'none'` (unchanged) |
+| `{ variant: 'large', hideOnScroll: true }` | `{ size: 'large-flexible', hideOnScroll: true }` |
+| (none) | `'search'`: the search field is the bar's centre |
+
+A string in the new spelling sets the size only, so the layout's `align` stays.
+A route's header in one spelling overrides the layout's in the other. The warning
+is `ActivityLayout: header `medium` is deprecated; use 'medium-flexible'.`
+([troubleshooting](../troubleshooting.md#activitylayout-header-center-medium-or-large-is-deprecated)).
+
+`resolveHeader` and `ResolvedHeader` gain `size` and `align`; `variant` stays
+filled with the old equivalent. `ShellHeaderVariant` is widened with the new
+values: an exhaustive `switch` over it needs them.
+
+## `TopAppBar` `variant` and `headline`
+
+**Search**: `<TopAppBar variant=`, `headline=`.
+
+| Before | After |
+| --- | --- |
+| `variant="center"` | `size="small" align="center"` |
+| `variant="medium"` | `size="medium-flexible"` |
+| `variant="large"` | `size="large-flexible"` |
+| `headline={<h1>Projects</h1>}` | `title="Projects"` (the bar renders the `<h1>`) |
+
+`headline` rendered in a non-heading element with display type; it still does, now
+with the bar's title styling. `data-variant` is still set (`"search"` is new), and
+`data-size` and `data-align` are added.
+
+## Actions, the account menu and a main action
+
+All additive. `headerActions` (and `TopAppBar`'s `actions`) takes a
+`TopAppBarAction[]` as well as a node: free ghost icon buttons, with the rest in
+the account menu on the avatar. `headerPrimaryAction` (`primaryAction`) is a
+`Button` from 768 px and a floating button on a phone. `headerContext` is now the
+bar's subtitle, under the title. An `actions` that is a node, an array of elements
+included, and `trailing` draw as before. See
+[Top app bar sizes](./app-shell.md#top-app-bar-sizes) and
+[the `TopAppBar` props](../components/navigation-and-layout.md#topappbar).
+
+An avatar used as `trailing` next to an `actions` array of data becomes the menu's
+trigger (a `<button>`): it must hold no link or button.
+
+## What looks different
+
+No code change, but snapshots of an app that renders the bar change:
+
+- **Heights.** The headline row of a medium bar is 3 rem and a large bar's 6.5 rem
+  before it is measured (it was 5 rem and 8 rem), then follows the title's real
+  height. Medium titles are 28 px, large ones 40 px (36 px on a phone).
+- **A flat bar.** It sits on the page ground with no shadow, border or surface
+  background (it was a translucent card). Once scrolled it takes the
+  `--surface-container` tint and a 1 px `--border` hairline (the `data-scrolled`
+  attribute). A `className` background, radius or shadow wins at rest (the
+  bar's own look is in `@layer components`); once scrolled the tint replaces a
+  `className` background, as the scrolled state's look.
+- **A ghost menu button on a phone**, leading the bar, with no logo or brand.
+  Desktop is unchanged.
+- **Vertical padding** sits on the bar itself, so `className="py-1"` still works.
+- **`position`.** A `TopAppBar` is no longer `position: relative` except
+  `size="search"`, so a `sticky` class works.
+- **The root is a column.** A standalone `TopAppBar` used to be one flex row on
+  the root; the root is now `flex-col` and its children sit in a
+  `[data-slot="top-app-bar-row"]` (a headline row and the tabs follow it). A
+  layout utility in the root's `className` (`justify-between`, `gap-*`,
+  `items-*`, a horizontal `px-*`) no longer reaches the children; aim it at the
+  row, for example `className="[&_[data-slot=top-app-bar-row]]:justify-between"`.
+  A vertical `py-*` on the root still works.
+- **`title` is the page's heading.** On the old `TopAppBar`, `title` was the HTML
+  `title` attribute (a native tooltip). It is now the bar's own title and renders
+  an `<h1>`. To keep a tooltip, put `title` on an element you pass as a child.
+- **The shell's bar** is the page's `<header>` (a banner landmark) instead of a
+  `<div>`. It keeps its `data-slot` names; `app-header-page-title-row` is now the
+  title block, always present around the title and the context line. A small
+  bar with `hideOnScroll` or tabs still carries `data-variant="small"`. The
+  internal `--nxgt-header-h` custom property (never documented) is gone;
+  `--nxgt-header-height` still sets the bar's height, and the first-paint total
+  `--nxgt-header-total` follows it.
+
+## The `data-slot` rename in the next major
+
+The shell keeps its `app-header*` `data-slot` names in this minor, so selectors
+and tests written against them keep working; `TopAppBar`'s CSS styles both
+families. The next major renames the slots in the table below. Update selectors then, or now with the new
+names on a `TopAppBar` of your own:
+
+| Today (shell) | Next major |
+| --- | --- |
+| `app-header` | `top-app-bar` |
+| `app-header-page-title` | `top-app-bar-title` |
+| `app-header-headline` | `top-app-bar-headline` |
+| `app-header-collapsed-title` | `top-app-bar-collapsed-title` |
+| `app-header-context` | `top-app-bar-subtitle` |
+| `app-header-tabs` | `top-app-bar-tabs` |
+
+The other `app-header*` slots (`app-header-title`, `-title-after`, `-back`, `-menu`) are not in this table: their next-major names are not decided yet, so do not rely on a `top-app-bar-*` equivalent.
+
+**Search**: `app-header` in tests, CSS and `data-slot=` selectors.

package/docs/guides/theming.md

@@ -73,6 +73,7 @@ at the top are needed is in [getting started](../getting-started.md#styles).
 | `--error-text` | `text-error-text` | error drawn as text: field messages, `HelperText` in its error state, form and dialog errors, `variant="error"` menu items |
 | `--destructive` | `bg-destructive`, `text-destructive` | deprecated alias of `--error`: the light theme sets it to `var(--error)`, the dark theme keeps its own value; use `--error` |
 | `--ground` | `bg-ground` | the page's ground under `ActivityLayout`: the tinted colour the cards stand on (see [Page ground](#page-ground)) |
+| `--surface-container`, `--surface-container-high` | `bg-surface-container`, `bg-surface-container-high` | tinted chrome: `--surface-container` is the scrolled top app bar (draw it with a 1px `--border` hairline), the primary at 12 % over `--ground` in light (less for a very dark primary, solved per seed) and 26 % in dark; `--surface-container-high` is raised chrome such as a search field, the primary at 16 % over `--background` in light (+4 points over the solved share) and 34 % over `--ground` in dark. Foreground, muted foreground and primary text keep 4.5:1 or more on both, in every preset |
 | `--card`, `--popover`, `--tooltip` (+ `-foreground`) | `bg-card`, `bg-popover`, `bg-tooltip` | surfaces |
 | `--card-edge` | `border-card-edge` | the edge of a `Card`, a `Popover` and a `Dialog`: `var(--border)` in light, `color-mix(in oklab, white 8%, var(--card))` in dark, a hairline lighter than the surface so it lifts off `--ground` |
 | `--border`, `--input`, `--ring` | `border-border`, `border-input`, `ring-ring` | outlines |
@@ -83,6 +84,10 @@ at the top are needed is in [getting started](../getting-started.md#styles).
 | `--nxgt-cards-min`, `--nxgt-cards-gap` | set on the list or an ancestor | the narrowest a `DataTable`/`ServerTable` card is (default `15rem`) with `cardDensity="compact"`, and the gap between cards (`0.75rem`, `0.5rem` when compact): see [Cards and tiles](./cards-and-tiles.md#columns) |
 | `--nxgt-field-radius`, `--nxgt-field-inner-radius` | `rounded-field` (and its sides, `rounded-s-field`…), `rounded-field-inner` | every field's corners, and the corner a field meets its open list with: see [The field box](#the-field-box) |
 
+```tsx
+<header className="bg-surface-container border-b border-border" />
+```
+
 Some colours are derived rather than tokens of their own:
 `bg-background-paper` (5 % primary), `bg-paper` (0.5 % primary),
 `bg-primary-container`, `bg-secondary-container`, `bg-tertiary-container`,

package/docs/roadmap.md

@@ -6,12 +6,6 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Now
 
-- **App shell header refresh** — `AppHeader` and the look `TopAppBar`
-  shares sit flat on the page ground and tint when content scrolls under
-  them; the actions are grouped in a pill, the search is a pill field (an
-  icon on a phone), and the menu button is a ghost icon button. The new look
-  is the default in a minor, with no API change; an A/B preview comes first
-  ([#2503](https://github.com/softistx/nxgt-material/issues/2503)).
 - **Calculator** — `@nxgt/material/calculator` is an exact-decimal calculator
   (Standard, Scientific, point of sale, Financial, Conversion, Programmer;
   every variant but Standard loads on demand)
@@ -386,6 +380,23 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **App shell header refresh: the TopAppBar family (next minor)** — `TopAppBar`
+  takes four sizes (`small`, `medium-flexible`, `large-flexible`, `search`), an
+  `align`, a `title` that is the page's `h1` with a `subtitle`, and a collapse
+  from large to small on scroll with a morph (snapped under reduced motion).
+  It sits flat on the page ground and tints when content scrolls under it,
+  with new surface-container tokens. Actions are data (`TopAppBarAction`):
+  free icon buttons plus an account menu on the avatar, and a `primaryAction`
+  that is a floating button on a phone. `ActivityLayout` draws its bar with it
+  (`header` / `handle.header` take the new sizes, `headerActions` takes data,
+  `headerPrimaryAction` is new, `headerContext` is the subtitle) and the
+  phone's menu button is a ghost icon leading the bar. `AppHeader` and the old
+  `variant`, `headline` and `'center'` / `'medium'` / `'large'` values are
+  deprecated, and some `app-header*` slots are renamed in the next major (see the guide)
+  ([#2503](https://github.com/softistx/nxgt-material/issues/2503),
+  [guide](guides/app-shell.md#top-app-bar-sizes),
+  [moving to `TopAppBar`](guides/migrating-to-top-app-bar.md)).
+
 - **Seven more layout recipes (next minor)** — whole screens to start from under Guides/Recipes, each a tested Storybook story with its code in the plugin's `screen-recipes` skill: a team feed, a gallery of pictures by day, sign-in, sign-up and forgotten-password screens, a messages thread, settings with sections, an overview of rearrangeable widgets and a document editor, on the layouts the shell ships ([#2413](https://github.com/softistx/nxgt-material/issues/2413)).
 
 - **Search dialog and results page recipe (next patch)** — a command dialog (Ctrl/Cmd+K and a header button), debounced grouped suggestions, type chips, a conditional filter and highlighted result cards, with its code in the plugin's `screen-recipes` skill ([#2333](https://github.com/softistx/nxgt-material/issues/2333)).