@nxgt/material 3.85.0 → 3.86.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @nxgt/material
 
+## 3.86.0
+
+### Minor Changes
+
+- [#2537](https://github.com/softistx/nxgt-material/pull/2537) [`0251d58`](https://github.com/softistx/nxgt-material/commit/0251d586037b2d922dc1391dedca176f6cc6cde7) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `ActivityLayout` `header` and a route's `handle.header` accept the new header sizes: `size` (`'small' | 'medium-flexible' | 'large-flexible' | 'search'`) and `align` (`'start' | 'center'`), as a string size or in the options object. The old values keep working and are deprecated: `'center'` becomes `{ size: 'small', align: 'center' }`, `'medium'` becomes `'medium-flexible'`, `'large'` becomes `'large-flexible'`, and `variant` in the options is replaced by `size` and `align` (`'none'` stays). A development console warning names the new spelling once per value. A route's header in one spelling overrides the layout's in the other; a string in the new spelling sets the size only, so the layout's `align` stays. The bar is drawn with `TopAppBar` (see the `ActivityLayout` changeset of this release). `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.
+
+- [#2537](https://github.com/softistx/nxgt-material/pull/2537) [`0251d58`](https://github.com/softistx/nxgt-material/commit/0251d586037b2d922dc1391dedca176f6cc6cde7) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `ActivityLayout` draws its app bar with `TopAppBar`, as the page's one `<header>` banner. The bar is flat on the page ground and tints with a hairline once the page scrolls; `header` / `handle.header` sizes (`small`, `medium-flexible`, `large-flexible`, `search`) map to `TopAppBar`'s `size` and `align`, a medium or large bar collapses with the measured headline row, and `hideOnScroll` slides it away. `headerContext` is the title's subtitle (desktop only), the page title is the one `h1`, and the `search` size makes the search field the bar's centre with the title kept for assistive tech. New `headerPrimaryAction` (`TopAppBar`'s `primaryAction`: a `Button` from 768 px, a `Fab` on a phone), and `headerActions` also takes a `TopAppBarAction[]`. On a phone the menu button is a ghost icon button leading the bar, with no brand; desktop is unchanged.
+  
+  Visual change: the bar's heights follow `TopAppBar`'s design. 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), the bar sits flat on the ground instead of a translucent card, and a phone's small bar keeps a long title to two lines.
+  
+  No markup break: the bar keeps its `data-slot` names (`app-header`, `app-header-page-title`, `app-header-headline`, `app-header-collapsed-title`, `app-header-context`, `app-header-tabs`, `app-header-title-after`, `app-header-back`). Renaming them to `top-app-bar*` is planned for the next major. `TopAppBar` takes an internal `slotNames` for this, and its CSS styles both names. `AppHeader` stays exported with its props, as a deprecated wrapper over `TopAppBar` (a development warning once); use `TopAppBar` or `ActivityLayout`.
+  
+  Other visible changes: the bar is a `<header>` (the page's banner) instead of a `<div>`; the internal `--nxgt-header-h` custom property (never documented) is gone, while `--nxgt-header-height` still sets the bar's height (the row is that height less the bar's own 1 rem of vertical padding) and the first-paint `--nxgt-header-total` follows it; `data-variant="small"` is still set on a small bar that hides on scroll or has tabs; the slot `app-header-page-title-row` is now the title block, always drawn around the title and the context line (it was drawn only with a `titleAfter` or `headerContext`). A `className` background, radius or shadow on the bar applies at rest; once scrolled the tint replaces a `className` background. A standalone `TopAppBar`'s root is now a column whose children sit in a `[data-slot="top-app-bar-row"]`, so layout utilities on its `className` (`justify-between`, `gap-*`, `items-*`) no longer reach them, and its `title` prop (formerly the HTML `title` attribute) now renders the bar's `<h1>`: see the migration guide, "What looks different".
+  
+  Fixes [#2514](https://github.com/softistx/nxgt-material/issues/2514).
+
+- [#2537](https://github.com/softistx/nxgt-material/pull/2537) [`0251d58`](https://github.com/softistx/nxgt-material/commit/0251d586037b2d922dc1391dedca176f6cc6cde7) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Theme: two new tokens, `--surface-container` and `--surface-container-high`, with the Tailwind utilities `bg-surface-container` and `bg-surface-container-high` (React; Vue gets the CSS variables only) (additive, nothing to migrate). `--surface-container` is the scrolled top app bar (pair it with a 1px `--border` hairline): the primary at 12 % over `--ground` in light, 26 % in dark. `--surface-container-high` is raised chrome such as a search field: the primary at 16 % over `--background` in light, 34 % over `--ground` in dark. `defineTheme` and every preset generate them, `ThemeToken` lists them, and the contrast pairs check foreground, muted foreground and primary text on both in light and dark. Fixes [#2509](https://github.com/softistx/nxgt-material/issues/2509).
+
+- [#2537](https://github.com/softistx/nxgt-material/pull/2537) [`0251d58`](https://github.com/softistx/nxgt-material/commit/0251d586037b2d922dc1391dedca176f6cc6cde7) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `TopAppBar`: free icon actions, an account menu and a primary action (additive: an `actions` that is a node, an array of elements included, and `trailing` draw as before; only an array whose every item is a plain object with a string `label` is read as data). `actions` also takes a `TopAppBarAction[]` (`label`, `icon`, `onClick`, `href`, `placement: 'bar' | 'account'`, `group`, `selected`, `disabled`): the first ones are free ghost icon buttons (one on a phone, two from 768 px, no pill or group background), the others and every `'account'` action go to a menu opened by `trailing` (the avatar, named "Account menu") or by a More button when there is no `trailing`. Entries with a `group` ("Language", "Theme") sit under that label as inline sections, never submenus, which overflow at 360 px. `linkComponent` draws the actions with an `href` (the nearest `LinkComponentProvider`'s, else `<a>`). A group of non-link entries where one sets `selected` is a radio group. `primaryAction` (`label`, `icon`, `onClick`) is a `Button` from 768 px and a `Fab` above `--nxgt-bottom-chrome` on a phone. New message keys `material.top-app-bar.account` and `material.top-app-bar.more` (en, fr). Fixes [#2512](https://github.com/softistx/nxgt-material/issues/2512).
+
+- [#2537](https://github.com/softistx/nxgt-material/pull/2537) [`0251d58`](https://github.com/softistx/nxgt-material/commit/0251d586037b2d922dc1391dedca176f6cc6cde7) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `TopAppBar` and the shell's `AppHeader`: a flexible bar now collapses over its headline row's real height instead of a fixed 5rem / 8rem (those stay only as the height before it is measured, on the server and at first paint). The title shrinks to 90% from its start edge as the bar folds, a reduced-motion visitor gets the collapse snapped, and a scrolled bar takes the `--surface-container` tint with a 1px `--border` hairline through a `data-scrolled` attribute set on the element, so a frame of scrolling no longer re-renders the bar. A collapsing `TopAppBar` also shows a small, `aria-hidden` copy of its title in the top row once the headline has folded away (the one `<h1>` stays in the headline). `[data-collapse]` on a `TopAppBar` has the matching CSS (`--nxgt-header-progress`, `--nxgt-header-extra`). The `AppHeader` headline row now has its natural height (`flex-none`), and `TopAppBar` is no longer `position: relative` except for `size="search"`, so a `sticky` class works. A background, radius or shadow set through `className` applies at rest (the bar's own look is in `@layer components`); once the page scrolls, the scrolled tint replaces a `className` background. No API to migrate; the bar looks different (see "What looks different" in the migration guide, `docs/guides/migrating-to-top-app-bar.md`).
+
+- [#2537](https://github.com/softistx/nxgt-material/pull/2537) [`0251d58`](https://github.com/softistx/nxgt-material/commit/0251d586037b2d922dc1391dedca176f6cc6cde7) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `TopAppBar`: new `size` (`'small'`, `'medium-flexible'`, `'large-flexible'`, `'search'`) and `align` (`'start'`, `'center'`) props, a `title` that the bar renders as the page's one `<h1>`, a `subtitle` line under it, and slots `leading`, `titleAfter`, `actions`, `trailing`, `search` and `tabs`, plus `as="header"`, `titleId`, `collapse` and `hideOnScroll` flags. The bar is now flat on the page ground with no shadow; once the shell marks it `data-scrolled` it takes a soft tint and a hairline. Medium titles are 28 px and large ones 40 px (36 px on a phone). No API to migrate (the visual changes are listed below): `variant` (`'center'`, `'medium'`, `'large'`) and `headline` keep working and are deprecated for `size`/`align` and `title`: each logs a one-time development warning (`variant="center"`, `"medium"` and `"large"` warn, `"small"` does not; `headline` without `title` warns). `headline` now takes the bar's title styling (it was display type) and still renders in a non-heading element. `data-variant` is still set (`"search"` is new) and `data-size` / `data-align` are added. Vertical padding now sits on the bar itself, so `className="py-1"` still works. Visual change: the root is now a column (children in a `[data-slot="top-app-bar-row"]`, so root `className` layout utilities no longer reach them), `title` is the bar's `<h1>` (it was the HTML `title` attribute), and the bar no longer paints a surface background and bottom border by default, so snapshots of apps that render it will change. Fixes [#2510](https://github.com/softistx/nxgt-material/issues/2510).
+
+### Patch Changes
+
+- [#2537](https://github.com/softistx/nxgt-material/pull/2537) [`0251d58`](https://github.com/softistx/nxgt-material/commit/0251d586037b2d922dc1391dedca176f6cc6cde7) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Document the `TopAppBar` family: a README example, the `TopAppBar` section of the navigation and layout components page (every `TopAppBarAction` field), a "Top app bar sizes" section in the app shell guide, a new "Moving to TopAppBar" guide (`AppHeader`, the old `header` values, `variant` and `headline`, the visual changes and the `data-slot` rename planned for the next major) and troubleshooting entries for the deprecation warnings.
+- Updated dependencies [[`0251d58`](https://github.com/softistx/nxgt-material/commit/0251d586037b2d922dc1391dedca176f6cc6cde7)]:
+  - @nxgt/material-core@0.51.0
+
+## 3.85.1
+
+### Patch Changes
+
+- [#2536](https://github.com/softistx/nxgt-material/pull/2536) [`06c866d`](https://github.com/softistx/nxgt-material/commit/06c866d6669e722ad58fa78bf7df474f2dd332ce) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `EventCalendar`: a click on the event preview's Edit or Delete button no longer also creates a slot. With `onSlotClick` set, the press on the popover (portaled, but a React child of the time column) made the column capture the pointer, so the click went to the column and `onSlotClick` fired instead of the button. The column now ignores presses that start outside its own DOM. Nothing to migrate.
+
 ## 3.85.0
 
 ### Minor Changes

package/README.md

@@ -300,7 +300,7 @@ import { ActivityLayout, SettingsLayout } from '@nxgt/material/components';
 <ActivityLayout
   items={items}
   navigation={{ phone: 'bar', tablet: 'rail', desktop: 'sidebar', persistKey: 'nav' }}
-  header={{ variant: 'large', search: { placeholder: 'Search' } }}
+  header={{ size: 'large-flexible', search: { placeholder: 'Search' } }}
 >
   <Outlet />
 </ActivityLayout>
@@ -311,6 +311,39 @@ import { ActivityLayout, SettingsLayout } from '@nxgt/material/components';
 />
 ```
 
+### A top app bar
+
+`TopAppBar` is the bar `ActivityLayout` draws; use it alone for a layout of your
+own. `size` is `'small'` (one row), `'medium-flexible'`, `'large-flexible'` (the
+`title` on a second row, collapsing into the small row on scroll) or `'search'`;
+`align="center"` centres a small bar's title. `actions` takes plain nodes or an
+array of data: free icon buttons in the bar, the rest in the account menu on the
+`trailing` avatar. `primaryAction` is a `Button` from 768px and a `Fab` on a phone.
+
+```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' },
+  ]}
+  trailing={<Avatar alt="Ada Lovelace" fallback="AL" />}
+  primaryAction={{ label: 'New order', icon: <Plus />, onClick: createOrder }}
+/>
+```
+
+In the shell the same things are `header` / `handle.header`, `headerContext`
+(the subtitle), `headerActions` and `headerPrimaryAction`. `AppHeader` and the
+old `variant` / `headline` props still work and are deprecated: see
+[Moving to TopAppBar](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/migrating-to-top-app-bar.md).
+
 Also: `ListDetailsLayout`, `PaneLayout`, `ThreadLayout`, `ResponsiveGrid`,
 `DashboardGrid`, `EditorLayout` and `LandingLayout`. The [layouts guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/layouts.md)
 picks one by need.
@@ -517,10 +550,10 @@ Each area a consumer starts from has its own page under `docs/guides/`.
 | --- | --- |
 | [Forms](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/forms.md) | wiring fields to React Hook Form and Zod, composite values (contacts, opening hours), config-driven `Field`, server errors, what each field emits |
 | [i18n](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/i18n.md) | adding your strings next to the package's, switching language, translated Zod messages, SSR without a text mismatch |
-| [App shell](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/app-shell.md) | laying out an app with `ActivityLayout` (its `header`: small, center, medium and large collapsing on scroll, hide on scroll, a search in the bar, sticky tabs under it, a back arrow per route with `handle.back`, per route with `handle.header`; route changes cross-fade by default, `routeTransition={false}` opts out; it draws the theme's background, `backdrop` is the exception and `backdrop={false}` a plain page), its `items` (rendered as links; `linkComponent` to pass your own), the brand (`logo`, `name`, and `context` for the phone sheet's tenant line), the header's title, a route's `handle.title` as the page's `h1` in the app bar (`AppShellHandle`, `PageTitle`; `handle.titleAfter` / `titleAfter` a slot right after it, such as a record's `Switcher`, and `headerContext` a small tenant line from md up; it labels `<main>`, and `usePageTitleFocus()` focuses it after a navigation), and `AccountMenu`, the active entry and breadcrumbs (needs a data router; `breadcrumbRoot` replaces the home icon with a text link, or with `icon: true` keeps it with its own target and name, `breadcrumb={false}` hides the trail), the `<main>` landmark, the `h1` title, document scrolling, a background preset behind the shell (`backdrop`), and the tinted page ground the cards stand on (`--ground`, the opt-out) |
+| [App shell](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/app-shell.md) | laying out an app with `ActivityLayout` (its `header`: small, medium-flexible and large-flexible collapsing on scroll, search, hide on scroll, a search in the bar, sticky tabs under it, a back arrow per route with `handle.back`, per route with `handle.header`; route changes cross-fade by default, `routeTransition={false}` opts out; it draws the theme's background, `backdrop` is the exception and `backdrop={false}` a plain page), its `items` (rendered as links; `linkComponent` to pass your own), the brand (`logo`, `name`, and `context` for the phone sheet's tenant line), the header's title, a route's `handle.title` as the page's `h1` in the app bar (`AppShellHandle`, `PageTitle`; `handle.titleAfter` / `titleAfter` a slot right after it, such as a record's `Switcher`, and `headerContext` a small tenant line from md up; it labels `<main>`, and `usePageTitleFocus()` focuses it after a navigation), and `AccountMenu`, the active entry and breadcrumbs (needs a data router; `breadcrumbRoot` replaces the home icon with a text link, or with `icon: true` keeps it with its own target and name, `breadcrumb={false}` hides the trail), the `<main>` landmark, the `h1` title, document scrolling, a background preset behind the shell (`backdrop`), and the tinted page ground the cards stand on (`--ground`, the opt-out) |
 | [Layouts](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/layouts.md) | choosing a navigation preset (bar, rail, drawer, sidebar, top, two-level, floating), an app bar variant or a page layout (list and details, settings, dashboard, editor, landing), with an example of each |
 | [Themes for your app](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/themes.md) | defining app themes, generating their stylesheets and types with the Vite plugin's `themes` option or the `nxgt-theme` command, the CI check |
-| [Theming](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/theming.md) | changing colours, radius or fonts, motion and corner tokens, the page ground (`--ground`, `bg-ground`: its light and dark values and the opt-out), dark mode, tones (the `data-tone` channel, app tones and the calm zone `data-density="calm"`), touch targets, using the compiled CSS without Tailwind |
+| [Theming](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/theming.md) | changing colours, radius or fonts, motion and corner tokens, the page ground (`--ground`, `bg-ground`: its light and dark values and the opt-out), the chrome surfaces (`--surface-container`, `--surface-container-high`), dark mode, tones (the `data-tone` channel, app tones and the calm zone `data-density="calm"`), touch targets, using the compiled CSS without Tailwind |
 | [Printing](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/printing.md) | producing PDFs with `@nxgt/material/print` and getting the file in one call (download, new tab, preview, server `Response`) — its own entry since 2.0.0, with optional peers, a bundling trap on SSR servers, and the `next.config.ts` a Next.js route handler (and `output: 'standalone'`) needs |
 | [Maps](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/maps.md) | using `@nxgt/material/map` — browser-only, optional leaflet peers, `map.css` |
 | [Charts](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/charts.md) | drawing charts with `@nxgt/material/charts` (client-only): the twelve charts, shared props, legend, View data, `onPointClick`, reference bands, thresholds and point tones on the line chart, zoom and phone scroll, right-to-left pages, keyboard and accessibility, theming the `--chart-*` tokens, and migrating from the Nivo charts, removed in 3.0 |
@@ -536,6 +569,7 @@ Each area a consumer starts from has its own page under `docs/guides/`.
 | [Content Security Policy](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/csp.md) | serving a strict CSP: the directives, `NonceProvider` and the per-request nonce, the components that still inject a `<style>`, the zod and KaTeX settings, a self-hosted font |
 | [The Vite plugin](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/vite-plugin.md) | adding `nxgtMaterial()` to `vite.config.ts`: the CSP by hash or nonce, self-hosted fonts, a build that checks the stylesheet, and each option's opt-out |
 | [The field look (2.x)](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/field-look-2-x.md) | what changed in the fields' look during 2.x (corners, surface, hover, focus halo, error, read-only; the `Select`, `Combobox`, `Autocomplete` and `TreeSelectField` triggers and their connected lists, the 44px `NativeSelect`, the country, time-zone and phone fields, `SearchField`, the date and time fields' boxes and triggers, and the lists' headers, descriptions and empty state) and how to get the earlier look back |
+| [Moving to TopAppBar](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/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, its replacement, the visual changes (heights, flat bar) and the slot rename planned for the next major |
 | [Migrating to 3.0](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/migrating-to-3.md) | upgrading from 2.x: the React 19.3 and React Router 8.5 peers, `ActivityLayout`'s default route transition (`routeTransition`), and each API removed in 3.0 with what replaces it, as search → replace pairs |
 | [Migrating to the Vite plugin](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/migrate-to-vite-plugin.md) | moving an app's hand-written CSP header, nonce, zod setting, Inter import or PDF bundling to `nxgtMaterial()`, as search → replace pairs |
 | [Code editor](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/code-editor.md) | `CodeEditor` and `CodeDiff` from `@nxgt/material/code-editor`: the theme presets and `defineCodeTheme`, several themes on one page, a self-hosted Monaco with `configureMonaco`, and moving off the barrel import |
@@ -764,11 +798,11 @@ Not components: what the stylesheet gives any element.
 
 | Preview | Component | What it does | @nxgt/material-vue |
 | --- | --- | --- | --- |
-| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-appshell.webp" width="120" alt="ActivityLayout"> | [`ActivityLayout`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#activitylayout), `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb`, `AppBreadcrumbItem`, `AppBreadcrumbSeparator` | App shell: sidebar built from `items`, a header with a mobile sheet (`header` picks its size: small, center, medium or large collapsing on scroll, `hideOnScroll`, a route's `handle.header`), route breadcrumbs and a titled page; entries are real links, and `linkComponent` swaps the link; it draws the theme's background (Lavande's is the gradient), `backdrop` puts a `/backgrounds` preset behind it for one screen, and `backdrop={false}` draws a plain page, and `keepClear="gaps"` lets its glyphs sit in the gaps between surfaces of a dense page. It paints the tinted page ground (`--ground`, `bg-ground`) under the content, with the sidebar and the app bar flat on `--background` and the cards on `bg-card` (`--ground: var(--background)` opts out). `ActivityContent` takes an `aside` side panel (beside the content from 1280px in CSS only, sticky under the app bar, a named `complementary` landmark, stacked below) and `width="form" \| "reading"` to cap the main column with the panel right beside it; `notice` puts an `Alert` or `Banner` above both, at their width. See the [app shell guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/app-shell.md). | `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-appshell.webp" width="120" alt="ActivityLayout"> | [`ActivityLayout`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#activitylayout), `ActivityContent`, `AppSidebar`, `AppHeader` (deprecated, use `TopAppBar`), `AppBreadcrumb`, `AppBreadcrumbItem`, `AppBreadcrumbSeparator` | App shell: sidebar built from `items`, a header with a mobile sheet (`header` picks its size: small, medium-flexible, large-flexible or search, `align`, collapsing on scroll, `hideOnScroll`, a route's `handle.header`; `headerActions` as data and `headerPrimaryAction`), route breadcrumbs and a titled page; entries are real links, and `linkComponent` swaps the link; it draws the theme's background (Lavande's is the gradient), `backdrop` puts a `/backgrounds` preset behind it for one screen, and `backdrop={false}` draws a plain page, and `keepClear="gaps"` lets its glyphs sit in the gaps between surfaces of a dense page. It paints the tinted page ground (`--ground`, `bg-ground`) under the content, with the sidebar and the app bar flat on `--background` and the cards on `bg-card` (`--ground: var(--background)` opts out). `ActivityContent` takes an `aside` side panel (beside the content from 1280px in CSS only, sticky under the app bar, a named `complementary` landmark, stacked below) and `width="form" \| "reading"` to cap the main column with the panel right beside it; `notice` puts an `Alert` or `Banner` above both, at their width. See the [app shell guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/app-shell.md). | `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader` (deprecated, use `TopAppBar`), `AppBreadcrumb` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-accountmenu.webp" width="120" alt="AccountMenu"> | [`AccountMenu`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#accountmenu) | The app bar's avatar menu: named after the account, the name and e-mail, the app's links, then an optional Theme choice (`themeChoice`) and a destructive Sign out with a busy state. | `AccountMenu` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-authcard.webp" width="120" alt="AuthCard"> | [`AuthCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#authcard) | The frame of a signed-out page: one `main`, a centred card whose title is the `h1` (focusable on an end state), a status or alert notice, a brand and toolbar row, safe-area padding, an optional backdrop (the theme's by default) that keeps clear of the card. | `AuthCard` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-sidebar.webp" width="120" alt="Sidebar"> | [`Sidebar`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#sidebar), `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarMenuItem`, `SidebarMenuLabel` | Collapsible navigation sidebar with icons, tooltips and active items. | `Sidebar` (same parts) |
-| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-topappbar.webp" width="120" alt="TopAppBar"> | [`TopAppBar`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#topappbar), `BottomAppBar` | Top bar surface in four sizes (`variant`), and a bottom bar of icon actions with an active state. | `TopAppBar`, `BottomAppBar` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-topappbar.webp" width="120" alt="TopAppBar"> | [`TopAppBar`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#topappbar), `BottomAppBar` | The top app bar: four sizes (`size`: small, medium-flexible, large-flexible, search), `align`, a `title` that is the page's `h1` with a `subtitle`, collapse on scroll, free icon `actions` as data with an account menu, a `primaryAction` (a FAB on a phone); and a bottom bar of icon actions with an active state. `AppHeader` is its deprecated wrapper. | `TopAppBar`, `BottomAppBar` |
 | | [`AppSearchBar`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#appsearchbar), `SearchView` | The app bar's search (`header.search` on `ActivityLayout`): a pill with a docked results panel from 768px (a `shortcut`, `results` as a node or a function, a polite `resultCount`), a search button opening a full-screen, focus-trapped `SearchView` on a phone. | not yet |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-stickyactionbar.webp" width="120" alt="StickyActionBar"> | [`StickyActionBar`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#stickyactionbar) | The bar of a page's main decision: stuck to the bottom on a phone above the keyboard and clear of the safe areas, inline from `md`, one primary action. | not yet |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-breadcrumb.webp" width="120" alt="Breadcrumb"> | [`Breadcrumb`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#breadcrumb), `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` | Breadcrumb primitives. | `Breadcrumb` (same parts) |

package/dist/{alert-dialog-1t6ULy5i.js → alert-dialog-DZnt8PYE.js}

@@ -4,7 +4,7 @@ import { o as n } from "./dist-DVRQkaTK.js";
 import { r } from "./dist-DWZXlCZR.js";
 import { a as i } from "./dist-DHdUUM1w.js";
 import { t as a } from "./in-dialog-D61Yeaol.js";
-import { a as o, c as s, d as c, i as l, l as u, n as d, o as f, r as p, s as m, t as h, u as g } from "./use-return-focus-Hv8rn55-.js";
+import { a as o, c as s, d as c, i as l, l as u, n as d, o as f, r as p, s as m, t as h, u as g } from "./use-return-focus-BA8G1qVU.js";
 import { i as _ } from "./escape-owner-DpaP0lm1.js";
 import * as v from "react";
 import { Fragment as y, isValidElement as b } from "react";

package/dist/{async-slice-xyA9Uzct.js → async-slice-D3OdV2BS.js}

@@ -1,4 +1,4 @@
-import { l as e, r as t, s as n, u as r } from "./translator-BstxG_hN.js";
+import { l as e, r as t, s as n, u as r } from "./translator-BRZNhsy5.js";
 import { t as i } from "./_baseIsEqual-C6ksIHya.js";
 import { useMemo as a } from "react";
 import { asyncThunkCreator as o, buildCreateSlice as s } from "@reduxjs/toolkit";

package/dist/{button-DhiNGrdT.js → button-MAL5an7L.js}

@@ -1,6 +1,6 @@
 import { t as e } from "./utils-BLfntITJ.js";
 import { n as t, t as n } from "./dist-DVRQkaTK.js";
-import { n as r, t as i } from "./spinner-C6LP2Rw8.js";
+import { n as r, t as i } from "./spinner-CweqX5A9.js";
 import { t as a } from "./dist-DkQbkF9T.js";
 import { a as o, i as s, n as c, o as l, s as u, t as d } from "./use-click-lock-Bwg_caHO.js";
 import { t as f } from "./is-production-GLw59WU8.js";

package/dist/{calculator-BcgxxScL.js → calculator-CyBjPONf.js}

@@ -1,8 +1,8 @@
 import { t as e } from "./utils-BLfntITJ.js";
-import { n as t, r as n, t as r, u as i } from "./tabs-Bj1zOe7-.js";
-import { t as a } from "./button-DhiNGrdT.js";
-import { t as o } from "./use-material-translation-1kCHtB0p.js";
-import { t as s } from "./icon-button-CG4aO8Gh.js";
+import { n as t, r as n, t as r, u as i } from "./tabs-BOT9B4le.js";
+import { t as a } from "./button-MAL5an7L.js";
+import { t as o } from "./use-material-translation-CCy1Me0h.js";
+import { t as s } from "./icon-button-DrqNk1Ww.js";
 import { t as c } from "./copy-to-clipboard-Be5Ffvs_.js";
 import { t as l } from "./useEvent-2fKq-6w8.js";
 import { t as u } from "./useLatest-C2PnQEeD.js";
@@ -11,7 +11,7 @@ import { t as f } from "./skeleton-DSdtr2qc.js";
 import { t as p } from "./live-status-BGPaN8r8.js";
 import { n as m, t as h } from "./calculator-context-BugcKuVG.js";
 import { a as g, c as _, i as v, l as y, n as b, o as ee, r as te, s as ne } from "./calculator-announce-DRd2c6Dq.js";
-import { i as re, t as ie } from "./pos-types-Dv2UxKSN.js";
+import { i as re, t as ie } from "./pos-types-JOXMY4Y2.js";
 import { a as ae, r as oe } from "./key-layout-cR79xfGE.js";
 import { n as x, r as se, t as ce } from "./programmer-word-CNCF7DJF.js";
 import { t as le } from "./standard-layout-BuSRr3TY.js";
@@ -279,11 +279,11 @@ function Le({ helpId: e }) {
 //#endregion
 //#region lib/components/ui/widgets/calculator/variants/variant-loader.ts
 var Re = {
-	scientific: () => import("./scientific-variant-DijUrpP8.js"),
-	pos: () => import("./pos-variant-DJvtN9N8.js"),
-	programmer: () => import("./programmer-variant-Bmcq2KzC.js"),
-	financial: () => import("./financial-variant-BYjQ690K.js"),
-	conversion: () => import("./conversion-variant-DultZZQm.js")
+	scientific: () => import("./scientific-variant-CskM4MLV.js"),
+	pos: () => import("./pos-variant-B2mS8bMB.js"),
+	programmer: () => import("./programmer-variant-C_Tl0P4_.js"),
+	financial: () => import("./financial-variant-DqW4HJ_v.js"),
+	conversion: () => import("./conversion-variant-BT5n4-jm.js")
 }, B = "failed", V = /* @__PURE__ */ new Map(), H = /* @__PURE__ */ new Map(), U = /* @__PURE__ */ new Set(), W = () => {
 	for (let e of U) e();
 };

package/dist/calculator-field.js

@@ -1,11 +1,11 @@
 import { t as e } from "./utils-BLfntITJ.js";
-import { t } from "./button-DhiNGrdT.js";
-import { t as n } from "./use-material-translation-1kCHtB0p.js";
-import { t as r } from "./icon-button-CG4aO8Gh.js";
-import { a as i, i as a, n as o, r as s, t as c } from "./picker-surface-pyGv-Qh9.js";
-import { r as l, t as u } from "./currency-field-CPbaM7ay.js";
+import { t } from "./button-MAL5an7L.js";
+import { t as n } from "./use-material-translation-CCy1Me0h.js";
+import { t as r } from "./icon-button-DrqNk1Ww.js";
+import { a as i, i as a, n as o, r as s, t as c } from "./picker-surface-Cg4V4-E0.js";
+import { r as l, t as u } from "./currency-field-t41sFYg_.js";
 import { r as d, t as f } from "./field-blur-DkiZOVNV.js";
-import { t as p } from "./calculator-BcgxxScL.js";
+import { t as p } from "./calculator-CyBjPONf.js";
 import { useId as m, useState as h } from "react";
 import { Fragment as g, jsx as _, jsxs as v } from "react/jsx-runtime";
 import { Calculator as y } from "lucide-react";

package/dist/{calculator-segment-C4WQAHcN.js → calculator-segment-BigMpjhn.js}

@@ -1,4 +1,4 @@
-import { t as e } from "./use-material-translation-1kCHtB0p.js";
+import { t as e } from "./use-material-translation-CCy1Me0h.js";
 import { jsx as t } from "react/jsx-runtime";
 //#region lib/components/ui/widgets/calculator/partials/calculator-segment.tsx
 function n({ label: n, choices: r, value: i, nameKey: a, onChange: o }) {

package/dist/calculator.js

@@ -1,2 +1,2 @@
-import { n as e, t } from "./calculator-BcgxxScL.js";
+import { n as e, t } from "./calculator-CyBjPONf.js";
 export { e as CALCULATOR_VARIANTS, t as Calculator };

package/dist/charts.js

@@ -1,12 +1,12 @@
 import { t as e } from "./ui.utils-CAnKTCw5.js";
 import { t } from "./utils-BLfntITJ.js";
 import { t as n } from "./warn-once-C_e47JM8.js";
-import { t as r } from "./button-DhiNGrdT.js";
-import { t as i } from "./use-material-translation-1kCHtB0p.js";
+import { t as r } from "./button-MAL5an7L.js";
+import { t as i } from "./use-material-translation-CCy1Me0h.js";
 import { t as a } from "./use-ssr-media-query-C6M5m8sf.js";
 import { i as o, n as s, r as c, t as l } from "./util-4heV2LPI.js";
 import { t as u } from "./useIsomorphicLayoutEffect-DfgAhWcH.js";
-import { t as d } from "./chip-m0_usuzd.js";
+import { t as d } from "./chip-DKAKoNxq.js";
 import { c as f, d as p, f as m, i as h, o as g, p as _, s as v, t as y } from "./line-path-C5pZGC49.js";
 import { t as b } from "./live-status-BGPaN8r8.js";
 import { t as x } from "./linear-G97mfnKF.js";

package/dist/{chip-m0_usuzd.js → chip-DKAKoNxq.js}

@@ -1,7 +1,7 @@
 import { t as e } from "./utils-BLfntITJ.js";
-import { n as t } from "./spinner-C6LP2Rw8.js";
+import { n as t } from "./spinner-CweqX5A9.js";
 import { s as n } from "./use-click-lock-Bwg_caHO.js";
-import { t as r } from "./use-material-translation-1kCHtB0p.js";
+import { t as r } from "./use-material-translation-CCy1Me0h.js";
 import { t as i } from "./react-node-text-Crkpfpco.js";
 import { cloneElement as a, isValidElement as o } from "react";
 import { Fragment as s, jsx as c, jsxs as l } from "react/jsx-runtime";

package/dist/{code-editor-BgKFrcld.js → code-editor-B6dFQSUJ.js}

@@ -1,12 +1,12 @@
 import { r as e } from "./rolldown-runtime-BFFgcFxR.js";
 import { t } from "./utils-BLfntITJ.js";
 import { t as n } from "./dist-DWZXlCZR.js";
-import { c as r, d as i, f as a, n as o, t as s } from "./dropdown-menu-CDKev8dk.js";
+import { c as r, d as i, f as a, n as o, t as s } from "./dropdown-menu-IRFp4CH9.js";
 import { a as c, i as l, n as u } from "./field-blur-context-BLGgf_3z.js";
-import { a as d, o as f, r as p, s as m, t as h } from "./toolbar-items-CEIuSxU_.js";
+import { a as d, o as f, r as p, s as m, t as h } from "./toolbar-items-BsgzHSNf.js";
 import { t as g } from "./is-production-GLw59WU8.js";
-import { t as _ } from "./use-material-translation-1kCHtB0p.js";
-import { i as v, n as y, o as b, t as x } from "./code-language-items-BWw17W9s.js";
+import { t as _ } from "./use-material-translation-CCy1Me0h.js";
+import { i as v, n as y, o as b, t as x } from "./code-language-items-CXEMiWoF.js";
 import { t as S } from "./useIsomorphicLayoutEffect-DfgAhWcH.js";
 import { n as C, t as w } from "./escape-owner-DpaP0lm1.js";
 import { t as T } from "./skeleton-DSdtr2qc.js";

package/dist/code-editor.js

@@ -1,13 +1,13 @@
 import { t as e } from "./utils-BLfntITJ.js";
 import { t } from "./dist-DWZXlCZR.js";
-import { o as n, r, s as i, t as a } from "./toolbar-items-CEIuSxU_.js";
-import { t as o } from "./use-material-translation-1kCHtB0p.js";
-import { i as s, n as c, o as l } from "./code-language-items-BWw17W9s.js";
+import { o as n, r, s as i, t as a } from "./toolbar-items-BsgzHSNf.js";
+import { t as o } from "./use-material-translation-CCy1Me0h.js";
+import { i as s, n as c, o as l } from "./code-language-items-CXEMiWoF.js";
 import { t as u } from "./skeleton-DSdtr2qc.js";
 import { t as d } from "./live-status-BGPaN8r8.js";
 import { t as f } from "./use-mobile-BDro060N.js";
 import { t as p } from "./react-node-text-Crkpfpco.js";
-import { a as m, c as h, d as g, f as _, i as v, l as y, m as b, o as x, p as S, r as C, s as w, t as T, u as E } from "./code-editor-BgKFrcld.js";
+import { a as m, c as h, d as g, f as _, i as v, l as y, m as b, o as x, p as S, r as C, s as w, t as T, u as E } from "./code-editor-B6dFQSUJ.js";
 import { r as D, t as O } from "./field-blur-DkiZOVNV.js";
 import { useEffect as k, useRef as A, useState as j } from "react";
 import { Fragment as M, jsx as N, jsxs as P } from "react/jsx-runtime";

package/dist/{code-language-items-BWw17W9s.js → code-language-items-CXEMiWoF.js}

@@ -1,5 +1,5 @@
-import { d as e, f as t } from "./dropdown-menu-CDKev8dk.js";
-import { t as n } from "./use-material-translation-1kCHtB0p.js";
+import { d as e, f as t } from "./dropdown-menu-IRFp4CH9.js";
+import { t as n } from "./use-material-translation-CCy1Me0h.js";
 import { t as r } from "./copy-to-clipboard-Be5Ffvs_.js";
 import { t as i } from "./live-status-BGPaN8r8.js";
 import { useEffect as a, useRef as o, useState as s } from "react";

package/dist/components/components.css

@@ -106,6 +106,8 @@
 @import "./rich-chat-composer-expressive.css";
 @import "./ui/actions/toolbar/toolbar-pair.css";
 @import "./ui/layout/app-bar/bottom-app-bar.css";
+@import "./ui/layout/app-bar/top-app-bar/top-app-bar.css";
+@import "./ui/layout/app-bar/top-app-bar/top-app-bar-collapse.css";
 @import "./ui/primitives/label/label.css";
 /* The field box every text field and picker trigger draws: its
  * --nxgt-field-* tokens, its states, its open shape and parts, then forced

package/dist/components/theme-tokens.css

@@ -10,6 +10,16 @@
 	   `body`, so a zone that sets --primary or --background gets its own. A page
 	   keeps the flat look with `--ground: var(--background)`. */
 	--ground: color-mix(in oklab, var(--primary) 7%, var(--background));
+	/* The scrolled top app bar (draw a 1px --border hairline with it): the primary at
+	   12 % over the ground. --surface-container-high is raised chrome such as a search
+	   field: the primary at 16 % over the page. The default seed solves to 12 and 16;
+	   palette.test and ground.test guard it. */
+	--surface-container: color-mix(in oklab, var(--primary) 12%, var(--ground));
+	--surface-container-high: color-mix(
+		in oklab,
+		var(--primary) 16%,
+		var(--background)
+	);
 	--card: oklch(1 0 0);
 	/* The card's edge (Card, Popover, Dialog): the border in light; dark draws it a
 	   hairline lighter than the card. */
@@ -114,6 +124,14 @@
 		var(--primary) 6%,
 		color-mix(in oklab, var(--background) 55%, black)
 	);
+	/* Dark: the primary at 26 % over the ground (the scrolled top app bar) and 34 % over
+	   the ground (raised chrome such as a search field). */
+	--surface-container: color-mix(in oklab, var(--primary) 26%, var(--ground));
+	--surface-container-high: color-mix(
+		in oklab,
+		var(--primary) 34%,
+		var(--ground)
+	);
 	--card: oklch(0.22 0.019 289.4);
 	--card-edge: color-mix(in oklab, white 8%, var(--card));
 	--card-foreground: oklch(0.943 0.012 291.3);

package/dist/components/ui/layout/app-bar/top-app-bar/top-app-bar-collapse.css

@@ -0,0 +1,60 @@
+/* Collapse (data-collapse, medium and large): use-header-scroll.ts sets
+ * --nxgt-header-progress (0 expanded, 1 collapsed) on the bar as the shell
+ * scrolls, and --nxgt-header-extra, the headline row's measured height. The
+ * headline gives that height back through a negative margin (the bar clips
+ * it), fades, and its title shrinks to 90% from its start edge. The rem values
+ * are the height before it is measured (the server, first paint). A bar
+ * outside the shell has no progress: 0, the expanded bar. */
+:is(
+	[data-slot="top-app-bar"],
+	[data-slot="app-header"]
+)[data-collapse][data-size="medium-flexible"] {
+	--nxgt-header-extra: 3rem;
+}
+:is(
+	[data-slot="top-app-bar"],
+	[data-slot="app-header"]
+)[data-collapse][data-size="large-flexible"] {
+	--nxgt-header-extra: 6.5rem;
+}
+:is([data-slot="top-app-bar"], [data-slot="app-header"])[data-collapse]:is(
+	[data-size="medium-flexible"],
+	[data-size="large-flexible"]
+) {
+	overflow: hidden;
+}
+:is([data-slot="top-app-bar"], [data-slot="app-header"])[data-collapse]
+	:is([data-slot="top-app-bar-headline"], [data-slot="app-header-headline"]) {
+	margin-bottom: calc(
+		var(--nxgt-header-extra) *
+		var(--nxgt-header-progress, 0) *
+		-1
+	);
+	opacity: clamp(0, calc(1 - var(--nxgt-header-progress, 0) * 1.6), 1);
+	transform-origin: left bottom;
+	transform: translateY(calc(var(--nxgt-header-progress, 0) * -0.75rem))
+		scale(calc(1 - var(--nxgt-header-progress, 0) * 0.1));
+}
+[dir="rtl"]
+	:is([data-slot="top-app-bar"], [data-slot="app-header"])[data-collapse]
+	:is([data-slot="top-app-bar-headline"], [data-slot="app-header-headline"]) {
+	transform-origin: right bottom;
+}
+
+/* The title's copy in the small row (aria-hidden: the headline keeps the one
+ * h1, folded away but still in the accessibility tree). It fades in over the
+ * second half of the collapse; under reduced motion the progress snaps. */
+:is(
+	[data-slot="top-app-bar-collapsed-title"],
+	[data-slot="app-header-collapsed-title"]
+) {
+	flex: 1;
+	min-width: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+	font-size: 1.125rem;
+	line-height: 1.5rem;
+	font-weight: 600;
+	opacity: clamp(0, calc((var(--nxgt-header-progress, 0) - 0.5) * 2), 1);
+}