@nxgt/material 3.79.1 → 3.81.0

package/docs/guides/forms.md

@@ -262,6 +262,13 @@ in `[data-slot="form-actions"]`) and put each group of fields in a
 </form>
 ```
 
+- The form grid insets its fields and its actions by 16px. In a container that
+  already pads its content (a settings page, a card, a sheet), set
+  `data-padding="none"` on the `.form-grid-layout`: the fields lose their
+  padding on all sides and the actions lose it left and right, so both sit
+  flush with that container's content edge:
+  `<form className="form-grid-layout" data-padding="none">`. The default is
+  unchanged.
 - Each section's title is an `h2` (pass `titleAs="h3"` when the form sits
   under an `h2` of your own), so a screen reader moves from section to
   section, and each section is a group named by its title.

package/docs/guides/helpers.md

@@ -126,6 +126,7 @@ Vue: the Redux helpers are Pinia store factories: `defineLocalStore`
 | `useIsClient()` | `false` on the server and first render, `true` after mount: a hydration guard. |
 | `useCspNonce()` | The nonce of the nearest `NonceProvider`, for a `<style>` of your own (`<style nonce={useCspNonce()}>`); `undefined` outside one, on the server and on the client alike. See [CSP](csp.md#nonceprovider). |
 | `useIsMobile()` | `true` below 768 px (`ResponsiveButton` no longer uses it: it collapses with CSS). `false` on the server and while hydrating, so SSR HTML is the desktop layout; a phone switches right after. |
+| `useSsrMediaQuery(query, serverValue)` | Whether a media query matches, for a breakpoint `useIsMobile` (768 px) does not cover. The server and the hydrating client both render `serverValue` (`serverValue` is the answer the query gives on a desktop screen: `true` for `(min-width: …)`, `false` for `(max-width: …)`), and the client switches right after hydrating, so there is no hydration mismatch; a client-only render (SPA, client-side navigation) reads the real answer at once. Without `matchMedia` (jsdom) it answers `serverValue`. See [below](#usessrmediaquery). |
 | `useHeadingSpy(ids, onActive, options?)` | IntersectionObserver over heading ids; reports the topmost visible one. |
 | `useLocalizedDate()` | `{ language, locale, format }`: `DATE_UTILS.format` bound to the `I18nProvider` language (`en` without a provider). |
 | `useNumberFormatter()` | `{ formatNumber, formatCurrency }`: `Intl.NumberFormat` with the options you pass, bound to the `I18nProvider` language (`en-US` without a provider). For what `formatAmount` does not cover: percentages, units, compact notation. |
@@ -207,6 +208,28 @@ export function Sent({ email }: { email: string }) {
 `useFocusOnMount(open)` focuses again whenever `open` turns true, for content
 that stays mounted and is only shown. Storybook: `Guides/Hooks/useFocusOnMount`.
 
+### `useSsrMediaQuery`
+
+```tsx
+import { useSsrMediaQuery } from '@nxgt/material/hooks';
+
+// A panel that is open from 1280 px (xl, 80rem) and folded below.
+function Inspector({ children }: { children: React.ReactNode }) {
+	const isXl = useSsrMediaQuery('(min-width: 80rem)', true);
+	return isXl ? <aside>{children}</aside> : null;
+}
+```
+
+The second argument is what the server renders, and what a hydrating client
+renders on its first pass: it is the answer the query gives on a desktop
+screen (`true` for `(min-width: …)`, `false` for `(max-width: …)`). On an SSR
+page a narrower screen therefore paints the desktop markup first and switches right
+after hydrating (one flash, and no hydration mismatch). A client-only render
+(an SPA, a client-side navigation) reads the real answer from its first
+render, with no flash. Where `matchMedia` does not exist (jsdom) the hook
+answers `serverValue` and never subscribes. When CSS alone can do it
+(`hidden xl:block`), prefer CSS: it has no flash at all.
+
 ### `useCountdown`
 
 The clock behind [`CountdownTimer`](../components/feedback-and-status.md#countdowntimer),

package/docs/guides/i18n.md

@@ -236,7 +236,8 @@ the camera's button, toggle and image (`material.camera.capture`, `captured`,
 barcode accessible names, the calendar's navigation tooltips
 (`material.calendar.*`), the data table's selection checkboxes, the filter's
 presets and `Min`/`Max` fields, the `variant="4"` spinner's label,
-`ScrollToTop`, the network upload field's `Retry` and `Remove {name}`, the map's
+`ScrollToTop`, the bottom bar's `material.navigation.more` and `.close` (not shown
+until the bar is drawn), the `ThreadLayout` stepper's `nav` name `material.navigation.steps` ("Progress"), the network upload field's `Retry` and `Remove {name}`, the map's
 `You are here` and zoom buttons, and the icon-only close button of
 `DialogClose`, `DrawerClose`, `SheetClose` and `SheetContent`'s
 `withCloseButton`. A range `Slider`'s readout inputs read
@@ -331,6 +332,17 @@ and its emoji buttons (`material['rich-text-editor'].placeholder` /
 (`material['circular-progress'].label`); `MediaPlayer`'s "Media player" for a
 track without a title (`material['media-player'].label`); `PaneLayoutPane`'s
 sheet title on a phone (`material['pane-layout']['sheet-title']`);
+`EditorLayout`'s region names, "Toolbar", "Canvas", "Outline" and "Properties"
+(`material['editor-layout'].toolbar` / `canvas` / `start` / `properties`; French
+"Barre d'outils", "Zone de travail", "Plan", "Propriétés");
+`ListDetailsLayout`'s way back, inspector close and back buttons and the list
+separator's name (`material['list-details'].back` / `inspector-back` /
+`inspector-close` / `resize`);
+`SettingsLayout`'s default title, search name and empty message
+(`material['settings-layout'].title` / `search` / `empty`);
+`LandingLayout`'s phone menu button, "Menu", and `SiteFooter`'s links landmark,
+"Footer" and new-tab hint, "opens in a new tab" (`material.landing.menu` / `footer` /
+`new-tab`; French "Menu", "Pied de page" and "s'ouvre dans un nouvel onglet");
 `JsonViewer`'s "Empty JSON" (`material['json-viewer'].empty`);
 `TimePicker`'s AM / PM (`material['time-picker'].am` / `pm`, "a.m." / "p.m." in
 French); and the names of `DurationField`'s inputs, "Hours" and "Minutes"

package/docs/guides/layouts.md

@@ -0,0 +1,215 @@
+# Layouts
+
+A map of the layouts `@nxgt/material` draws, to pick from by need: how the app
+navigates, what its header looks like, and which layout a page takes. Every
+choice is a prop or a component; nothing here is on unless you ask, and the
+shell's default is unchanged. Each section gives a working example and links
+the page that has the full props. Every component in the snippets is imported
+from `@nxgt/material/components`.
+
+Three sizes decide what is drawn, by CSS only (so the server and the client
+agree): a **phone** below 768px, a **tablet** from 768px to 1279px and a
+**desktop** from 1280px.
+
+## Pick a navigation
+
+`ActivityLayout` takes `navigation`: one name for every size, or one per size.
+
+| The app needs | Use | Notes |
+| --- | --- | --- |
+| three to five main destinations, one thumb away | `'bar'` | a bottom bar on a phone only (below 768px); from 768px the default rail shows, and `{ tablet: 'bar' }` keeps the bar there; the rest go under "More"; badges on the icons |
+| a compact column of icons | `'rail'` | a rail with an optional FAB (`navigationFab`); a phone never draws it: it keeps its menu sheet |
+| the same, with labels and a primary action | `'rail-expanded'` | a wider rail, extended FAB; a phone never draws it: it keeps its menu sheet |
+| many destinations in groups | `'drawer'` | a standard drawer; modal on a phone |
+| a dense tool with the sidebar the user collapses | `'sidebar'` | remembered with `persistKey` |
+| a website-like app with menus | `'top'` | a top navigation with dropdowns; nested in the phone menu |
+| two levels: sections, then pages | `'two-level'` | a rail beside a panel of the section's pages |
+| a content app that wants the whole screen | `'floating'` | a pill of links at the bottom, `hideOnScroll` |
+| the default: a menu sheet on a phone, a rail from 768px | `'modal-drawer'` (the phone preset) | what an unset `navigation` draws |
+| no navigation of its own | `'none'` | |
+
+```tsx
+import { ActivityLayout, type MenuItem } from '@nxgt/material/components';
+import { Outlet } from 'react-router';
+
+const items: MenuItem[] = [
+  { label: 'Home', url: '/', icon: 'house' },
+  { label: 'Inbox', url: '/inbox', icon: 'envelope', badge: 3 },
+  { label: 'Tasks', url: '/tasks', icon: 'check' },
+  { label: 'Settings', url: '/settings', icon: 'gear', priority: -1 },
+];
+
+// a bottom bar on a phone, a rail with a button on a tablet, a sidebar on a desktop
+export function Shell() {
+  return (
+    <ActivityLayout
+      items={items}
+      logo="/logo.svg"
+      name="Acme"
+      navigation={{ phone: 'bar', tablet: 'rail', desktop: 'sidebar', persistKey: 'acme-nav' }}
+    >
+      <Outlet />
+    </ActivityLayout>
+  );
+}
+```
+
+Each preset is also exported as a part (`NavigationBar`, `NavigationRail`,
+`NavigationDrawer`, `TopNav`, `NavigationRailPanel`, `NavigationToolbar`) for a
+layout of your own. Every preset, its entries (`bar`, `priority`, `group`,
+`children`, `badge`) and its accessibility are in the
+[app shell guide](app-shell.md#navigation-and-header).
+
+## Pick a header
+
+`header` takes a name or `{ variant, collapse, hideOnScroll, tabs, search }`.
+
+| Variant | What it is |
+| --- | --- |
+| `'small'` | the default bar: title at the start, actions at the end |
+| `'center'` | the title centred |
+| `'medium'`, `'large'` | a taller bar whose headline collapses to the small one on scroll |
+| `'none'` | no bar (a full-bleed page) |
+
+```tsx
+<ActivityLayout
+  items={items}
+  header={{
+    variant: 'large',
+    hideOnScroll: true,
+    search: { placeholder: 'Search projects', shortcut: '/' },
+    tabs: (
+      <TabsNav aria-label="Project sections" value="activity">
+        <TabsNavLink to="/projects/overview" value="overview">Overview</TabsNavLink>
+        <TabsNavLink to="/projects/activity" value="activity">Activity</TabsNavLink>
+      </TabsNav>
+    ),
+  }}
+>
+  <Outlet />
+</ActivityLayout>
+```
+
+A route changes its own bar with a handle, and draws a back arrow:
+
+```tsx
+export const handle = {
+  title: 'Atlas redesign',
+  header: { variant: 'medium' },
+  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),
+[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).
+
+## Pick a page layout
+
+Inside the shell, a page is one of these. All of them follow the width of their
+own container where noted, so they also work in a dialog or a split pane.
+
+| The page is | Use | Phone |
+| --- | --- | --- |
+| a list beside the selected record | `ListDetailsLayout` (`inspector` adds a third pane) | one view at a time, with a back bar |
+| content with a side panel (filters, folders) | `PaneLayout` | the pane is a sheet (`phone="sheet"`, `"bottom"` or `"stack"`) |
+| a form, a wizard or a conversation in a centred column | `ThreadLayout` | the same column, full width |
+| grouped settings | `SettingsLayout` | the list, then the section's page |
+| cards or tiles | `ResponsiveGrid` (spans, masonry) | one column |
+| tiles the user rearranges | `DashboardGrid` | one or two columns |
+| a board of columns | `Kanban` with `phoneLayout="tabs"` | one column per tab, swipe |
+| a tool with a canvas | `EditorLayout` | properties in a bottom sheet |
+| a public page outside the shell | `LandingLayout` | the links in a drawer |
+| sign-in and sign-up | `AuthCard` with `layout="split"` | the card alone |
+| documentation | `Doc` with `chrome="embedded"` inside the shell | the tree in a sheet |
+
+A settings screen, from sections:
+
+```tsx
+import { SettingsLayout } from '@nxgt/material/components';
+
+<SettingsLayout
+  search
+  sections={[
+    { id: 'profile', group: 'Account', title: 'Profile', description: 'Name and language', content: <ProfileForm /> },
+    { id: 'alerts', group: 'Preferences', title: 'Notifications', description: 'Email and push', content: <AlertsForm /> },
+  ]}
+/>
+```
+
+A list with its detail, selected in the URL. `history="push"` keeps the view in
+`?view=`, so the browser's Back goes from the details to the list on a phone, and
+`useListDetailsParam()` reads and sets the selected id:
+
+```tsx
+const [id, select] = useListDetailsParam();
+
+<ListDetailsLayout history="push">
+  <ListDetailsLayout.List>
+    {patients.map((p) => <Row key={p.id} onClick={() => select(p.id, { open: 'details' })} />)}
+  </ListDetailsLayout.List>
+  <ListDetailsLayout.Details back="Patients"><Sheet id={id} /></ListDetailsLayout.Details>
+</ListDetailsLayout>
+```
+
+An editor, with its properties in a sheet on a phone:
+
+```tsx
+<EditorLayout
+  className="h-dvh"
+  toolbar={<><UndoRedoButtons /><span className="flex-1" /><EditorLayout.PropertiesTrigger /></>}
+  properties={<SelectionForm />}
+>
+  <Artboard />
+</EditorLayout>
+```
+
+A dashboard the user rearranges (the order is yours to store):
+
+```tsx
+<DashboardGrid aria-label="Dashboard" order={order} onOrderChange={setOrder}>
+  <DashboardTile id="revenue" title="Revenue" span={{ base: 1, md: 2 }}><RevenueChart /></DashboardTile>
+  <DashboardTile id="orders" title="Orders"><OrdersCount /></DashboardTile>
+</DashboardGrid>
+```
+
+A landing page, outside the shell (it needs a router, like the shell):
+
+```tsx
+<LandingLayout
+  name="Acme"
+  items={[{ label: 'Pricing', url: '/pricing', icon: 'tag' }]}
+  actions={<LinkButton to="/start" variant="filled">Get started</LinkButton>}
+  hero={<LandingSection variant="hero" tone="ground" title="Plan the work" />}
+  footer={<SiteFooter brand="Acme" groups={[]} legal="© 2026 Acme" />}
+>
+  <LandingSection title="Everything in one place">…</LandingSection>
+</LandingLayout>
+```
+
+The props of each are in
+[Navigation & layout](../components/navigation-and-layout.md):
+[`ListDetailsLayout`](../components/navigation-and-layout.md#listdetailslayout)
+(with `PaneLayout` and `ThreadLayout`),
+[`SettingsLayout`](../components/navigation-and-layout.md#settingslayout),
+[`ResponsiveGrid`](../components/navigation-and-layout.md#responsivegrid),
+[`DashboardGrid`](../components/navigation-and-layout.md#dashboardgrid),
+[`EditorLayout`](../components/navigation-and-layout.md#editorlayout) and
+[`LandingLayout`](../components/navigation-and-layout.md#landinglayout).
+
+## Whole screens to start from
+
+The `Guides/Recipes` stories in Storybook are tested whole screens (the code
+ships with the `screen-recipes` skill of the `nxgt-material` plugin): a home
+dashboard, a list and detail, a form and dialog, a table and settings, a dense
+detail page, a status board, a landing page and a search dialog with its
+results page. Start from the closest one and replace the data.
+
+## See also
+
+- [App shell](app-shell.md): `items`, breadcrumbs, the page's title, the
+  background and the route transitions.
+- [Cards and tiles](cards-and-tiles.md): what goes inside a grid.
+- [Themes](themes.md): the surfaces the layouts sit on.

package/docs/guides/ssr.md

@@ -167,7 +167,7 @@ State the server cannot know must be resolved the same way on both sides:
 | Language | no `localStorage`: `defaultLanguage` | Resolve it from the request and pass `initialLanguage` to `I18nProvider`. See [i18n](i18n.md#server-rendering) |
 | Theme | no preference: light | An inline boot script in `<head>`, and `suppressHydrationWarning` on `<html>`. See [theming](theming.md#no-flash-on-load-a-boot-script) |
 | `formatAmount`, `formatDate` | the server's locale and time zone, unless you pass them | Use `useFormatters({ timeZone })`, which follows the `I18nProvider` language, or pass `locale` and `timeZone` (`createFormatters` binds them). A date-only `YYYY-MM-DD` is the same everywhere. See [printing](printing.md#formatamount-and-formatdate) |
-| Screen width, `prefers-color-scheme` (`useIsMobile`, `useTheme`, `AppHeader`, `DataTable`, `TimeField`, `PaneLayout`, `ListDetailsLayout`, the code blocks, …) | no screen: a desktop, light | Nothing: a hydrating client renders the same, then switches on a phone or a dark screen |
+| Screen width, `prefers-color-scheme` (`useIsMobile`, `useTheme`, `AppHeader`, `DataTable`, `TimeField`, `PaneLayout`, `ListDetailsLayout`, the code blocks, …) | no screen: a desktop, light | Nothing: a hydrating client renders the same, then switches on a phone or a dark screen (`ListDetailsLayout`'s `listWidth` is the default width until then; its inspector is switched by CSS) |
 | An attribute's `DATETIME` / `TIME` instant (`AttributesSummary`, `AttributesEditor`), the opening hours' first day of the week | the server's time zone and Intl data differ from the browser's | Nothing: the instant is written in UTC and the week starts on the language's first day until mount, then the viewer's zone and the locale's week info take over, so hydration matches |
 | `Stepper` layout, `Timeline` sides | CSS breakpoints and a container query, no screen width in JavaScript | Nothing: server and client markup are the same |
 | `Timeline` `grouped` | the server's time zone and clock differ from the browser's | Pass `timeZone` and `now` to group on the server too; without them the day headings appear after mount (the items do not remount) |

package/docs/guides/theming.md

@@ -68,7 +68,7 @@ at the top are needed is in [getting started](../getting-started.md#styles).
 | `--accent`, `--accent-foreground` | `bg-accent`, … | hover surfaces |
 | `--nxgt-accent` | `[--nxgt-accent:…]` | the mark colour of the selection controls: the fill, handle, state layer and stop dots of `Slider`, the on state of `Switch`, the box and dot of `Checkbox` and `Radio`. It defaults to `--primary` (`--primary-text` in dark) and is set per control, so override it on the control itself, not on `:root` |
 | `--error`, `--success`, `--info`, `--warning` (+ `-foreground`) | `bg-error`, `text-success`, … | the status colours of `Button`, `Alert`, `Badge`, toasts |
-| `--primary-text` | `text-primary-text` | primary drawn as text or an icon on a page, card or popover surface: `Typography tone="primary"`, links, the `Alert` primary icon, selected labels. In light, `--primary` mixed toward black: 96 % at most, solved lower on a tinted page so a tonal Button label on a striped row reaches 4.6:1 (94 % on teal, 89 % on corail, 94 % on pink); in dark, `--primary` mixed 60 % with white (`color-mix(in oklab, var(--primary) 40%, white)`), well over 4.5:1 on `--background` and `--card` |
+| `--primary-text` | `text-primary-text` | primary drawn as text or an icon on a page, card or popover surface: `Typography tone="primary"`, links, the `Alert` primary icon, selected labels. In light, `--primary` mixed toward black: 96 % at most, solved lower on a tinted page so a tonal Button label on a striped row, or straight on the page ground, reaches 4.6:1 (92 % on teal, 88 % on corail, 92 % on pink, 95 % on menthe); in dark, `--primary` mixed 60 % with white (`color-mix(in oklab, var(--primary) 40%, white)`), well over 4.5:1 on `--background` and `--card` |
 | `--primary-indicator` | `bg-primary-indicator`, `border-primary-indicator`, `ring-primary-indicator`, `stroke-primary-indicator` | primary drawn as a non-text mark that carries a state (WCAG 1.4.11, 3:1): an active bar or dot, a selected or focused border, a ring, a spinner arc. Equal to `--primary` in light; in dark, `--primary` mixed 25 % with white (`color-mix(in oklab, var(--primary) 75%, white)`), 4.8:1 on `--background`, 4.5:1 on `--card`, 4.2:1 on `--muted` (`--primary` itself gives 2.7, 2.5 and 2.3:1) |
 | `--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` |
@@ -936,14 +936,14 @@ ones also take 10 % on focus, as on hover, so their label keeps 4.5:1 over it
 
 The `tonal`, `outlined` and `link` variants of `Button` and `IconButton` draw
 their text and icon in one tone per colour, read on `--background`, on
-`--card` and on the variant's own tint (15 % at most, at rest or focused). In
-the light theme `primary`, `secondary`, `info` and `success` use the token
-itself (5.8, 5.2, 5.2 and 5.0:1 at their lowest) and `warning` and `error` the
-token mixed with 15 % black (6.4 and 5.4:1). In the dark theme `primary` is
+`--card`, on the page ground (`--ground`, a tinted page) and on the variant's own tint over each (15 % at most, at rest or focused). In
+the light theme `primary` uses `--primary-text` (solved per theme), `secondary`, `info` and `success`
+are mixed with 10 % black, `warning` with 15 % black and `error` with 20 % black (4.6:1 or more
+on the page ground in every preset). In the dark theme `primary` is
 mixed with 60 % white, the `--primary-text` token (8.5:1 at its lowest: the token itself is a dark indigo,
 2.3:1), `success` and `warning` with 15 % white (5.3 and 6.5:1), `error` with
 30 % white (6.0:1), and `secondary` and `info` use the token (5.1 and 5.6:1).
-The tones are mixed from the tokens (`color-mix(in oklab, var(--color-error)
+The tones are mixed from the tokens (`color-mix(in oklab, var(--color-warning)
 85%, black)`), so an override of a token moves its tone with it; a text colour
 of your own on one of those buttons (`className="text-primary-text"`) replaces the tone
 and is yours to check.
@@ -1012,7 +1012,7 @@ override on the root, or use a [theme zone](#themes), which re-declares them.
 for the same reason: the brand colour is a dark fill (it keeps near-white text
 readable on a button) and reads at only about 2:1 as text on the dark surfaces.
 The light value is `color-mix(in oklab, var(--primary) 96%, black)` at most (primary
-4 % toward black, 7.9:1 on the white page; the share is solved per theme and drops when a tinted page would leave a tonal Button label under 4.6:1 on a striped row, to 94 % on teal); the dark one is
+4 % toward black, 7.9:1 on the white page; the share is solved per theme and drops when a tinted page would leave a tonal Button label under 4.6:1 on a striped row or on the page ground, to 92 % on teal); the dark one is
 `color-mix(in oklab, var(--primary) 40%, white)` (primary mixed 60 % with
 white, the recipe of the tonal `Button` labels). `Typography tone="primary"`,
 the `Alert` primary icon, links, selected labels and the other primary text of

package/docs/roadmap.md

@@ -169,8 +169,10 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Next
 
-- **Layouts: adaptive navigation, headers and page layouts** — `ActivityLayout` takes `navigation` (a bottom bar, a rail with a FAB, standard and modal drawers, a collapsible sidebar, a top navigation with dropdowns, two-level navigation or a floating toolbar, chosen for phone, tablet and desktop) and `header` (small, center-aligned, medium and large collapsing on scroll, a search bar with full-screen search on a phone, sticky tabs, hide on scroll); each piece is also exported. Page layouts grow with it: an inspector pane and URL state for `ListDetailsLayout`, phone modes for `PaneLayout`, spans and masonry for `ResponsiveGrid`, tabs for `Kanban` on a phone, and new settings, dashboard (rearranging tiles), editor and landing layouts, each with a screen recipe. Everything is opt-in; the shell's default is unchanged. Tracked in [#2103](https://github.com/softistx/nxgt-material/issues/2103).
-
+- **Seven more layout recipes** — Feed, Gallery, Auth, Thread, settings,
+  dashboard and editor screens, each a tested Storybook recipe under
+  Guides/Recipes with its code beside it, on the layouts the shell now ships
+  ([#2413](https://github.com/softistx/nxgt-material/issues/2413)).
 - **FilterBar "Add a filter" stays on its row** — the button no longer wraps
   alone onto a second row on a desktop screen ([#1752](https://github.com/softistx/nxgt-material/issues/1752)).
 
@@ -259,6 +261,10 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Later
 
+- **A lighter first load for the app shell** — `ActivityLayout` pulls about
+  831 KB gzipped through the library's single shared chunk; splitting it so the
+  shell costs tens of KB at first load, the rest loaded where a page uses it
+  (#2417; measured by `scripts/shell-size.spec.ts`).
 - **One `onUpload` options object (next major)** — the upload fields'
   `onUpload(file, onProgress?, signal?)` becomes `onUpload(file, { onProgress,
   signal })`, like the editor's upload context.
@@ -377,6 +383,10 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **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)).
+
+- **Layouts: adaptive navigation, headers and page layouts (3.80.0)** — `ActivityLayout` takes `navigation` (a bottom bar with More and badges, a rail with a FAB or expanded, a standard or modal drawer, a collapsible sidebar, a top navigation with dropdowns, two-level navigation, a floating toolbar or none, chosen for phone, tablet and desktop) and `header` (small, center-aligned, medium and large collapsing on scroll, hide on scroll, a search bar that opens full screen on a phone, sticky tabs), and a route adds a back arrow with `handle.back`; each piece is also exported. Page layouts grow with it: an inspector pane and the selection in the URL for `ListDetailsLayout`, phone modes and a container breakpoint for `PaneLayout`, a centred form and wizard for `ThreadLayout`, a split `AuthCard`, spans and masonry for `ResponsiveGrid`, tabs for `Kanban` on a phone, `Doc` drawn inside the shell, and new `SettingsLayout`, `DashboardGrid` (tiles the user rearranges), `EditorLayout` and `LandingLayout` (with `LandingSection` and `SiteFooter`). Everything is opt-in; the shell's default is unchanged. [Layouts guide](guides/layouts.md) ([#2103](https://github.com/softistx/nxgt-material/issues/2103)). Follow-ups: a resize handle for `EditorLayout`'s properties panel and a separate open state for its phone sheet.
+
 - **Moment (3.74.0)** — a transient full-screen announcement for a one-off event (a player is eliminated, a role is revealed): a modal dialog named by its title, with an illustration, description, action and tone, dismissed by Escape, a tap, its action or a timer, and no motion under reduced motion ([#2220](https://github.com/softistx/nxgt-material/issues/2220), [#2247](https://github.com/softistx/nxgt-material/pull/2247)). A `modal={false}` variant for live events (focus stays, taps pass through, polite status) follows in the next minor ([#2313](https://github.com/softistx/nxgt-material/issues/2313)).
 - **RecordActionsMenu (next minor)** — one menu for a record's lifecycle: archive with an Undo toast (or confirm first with `archivePolicy="confirm"`), restore, and delete that always confirms and shows the backend's refusal, with `ConfirmDialog` gaining `details` and `refusal` slots.
 - **Assistant approval card (next minor)** — `ChatActionProposal` shows an action an assistant proposes, with its status, deadline and Confirm / Reject, and `ChatToolActivity` is a compact row for a tool step in a chat thread ([#2134](https://github.com/softistx/nxgt-material/issues/2134)).

package/docs/troubleshooting.md

@@ -78,6 +78,8 @@ words in your error.
 - [`ActivityLayout`'s `backdrop` shows nothing, or the blobs are still there](#activitylayouts-backdrop-shows-nothing-or-the-blobs-are-still-there)
 - [Shapes of an `ActivityLayout` `backdrop` run behind the text of the chrome or a list](#shapes-of-an-activitylayout-backdrop-run-behind-the-text-of-the-chrome-or-a-list)
 - [Shaped Gallery tiles are plain rounded squares](#shaped-gallery-tiles-are-plain-rounded-squares)
+- [ChoiceCardGroup shows 2+2 instead of 3+1](#choicecardgroup-shows-22-instead-of-31)
+- [A `ChoiceCardGroup` collapses to nothing in an inline-flex or centred parent](#a-choicecardgroup-collapses-to-nothing-in-an-inline-flex-or-centred-parent)
 - [A component with my own tone (Shape, Fab, Avatar, StatCard, a metric card) shows no colour, or `tone` is a type error](#a-component-with-my-own-tone-shape-fab-avatar-statcard-a-metric-card-shows-no-colour-or-tone-is-a-type-error)
 - [A test expects the old `bg-muted` Avatar fallback, or a filled fallback shows a grey ring](#a-test-expects-the-old-bg-muted-avatar-fallback-or-a-filled-fallback-shows-a-grey-ring)
 
@@ -341,6 +343,8 @@ words in your error.
 - [An `Autocomplete` list covers its helper text, or a chip test no longer finds its markup](#an-autocomplete-list-covers-its-helper-text-or-a-chip-test-no-longer-finds-its-markup)
 - [A `CountryField` lost its chip, or its `renderOption` or `filter` does nothing](#a-countryfield-lost-its-chip-or-its-renderoption-or-filter-does-nothing)
 - [A `CountryField` or `TimezoneField` test no longer finds its field or its options](#a-countryfield-or-timezonefield-test-no-longer-finds-its-field-or-its-options)
+- [A test that queries a `SortableList` by `listbox` or `option` finds nothing](#a-test-that-queries-a-sortablelist-by-listbox-or-option-finds-nothing)
+- [axe reports `nested-interactive` on a list whose rows hold buttons](#axe-reports-nested-interactive-on-a-list-whose-rows-hold-buttons)
 - [A `SearchField` lost the height, radius or fill set through `[&_input]`](#a-searchfield-lost-the-height-radius-or-fill-set-through-_input)
 - [`ComboboxEmpty`'s text shows under the options of a `Combobox`](#comboboxemptys-text-shows-under-the-options-of-a-combobox)
 - [`ConfirmDialog` buttons stay in English](#confirmdialog-buttons-stay-in-english)
@@ -1744,6 +1748,23 @@ page.locator('[data-slot=chip]').getByRole('button', { name: 'Remove Design' });
 **Why:** the shapes live in an opt-in stylesheet, `@nxgt/material/galleries.css`, which `styles.css` does not import. Without it a shaped tile keeps the `xl` corner (`--nxgt-shape-corner-xl`, 28px). The same fallback shows in a browser without CSS [`shape()`](https://developer.mozilla.org/en-US/docs/Web/CSS/basic-shape/shape) (Chromium-based and Safari today), which drops the `clip-path`. Under `prefers-reduced-motion` the shapes show but do not morph, by design. Also check that nothing overrides `clip-path` on `[data-slot=gallery-tile-media]`.
 **Fix:** import it once, next to `styles.css`: `@import "@nxgt/material/galleries.css";` (or `import '@nxgt/material/galleries.css'`). For a browser without `shape()`, accept the rounded fallback, or use a non-shaped preset and pass `shape` only where you want it.
 
+
+### ChoiceCardGroup shows 2+2 instead of 3+1
+
+**When:** a `ChoiceCardGroup` with `columns={3}` (or 4) and 4 cards (or any count that leaves one card alone on the last row) draws two rows of two, where it used to draw three and one.
+**Why:** rows are balanced by default (`balance`, `true`): when the last row would hold one orphan card and fewer columns avoid it, the group draws fewer columns. It is decided by CSS container queries on the group's own width, so the server and the client print the same markup.
+**Fix:** keep it, or restore the old fill with `balance={false}`:
+
+```tsx
+<ChoiceCardGroup label="Size" columns={3} balance={false} options={options} />
+```
+
+### A `ChoiceCardGroup` collapses to nothing in an inline-flex or centred parent
+
+**When:** the group sits in an `inline-flex` box, a float or a `w-fit` column and its cards are squeezed to zero width or the label shows alone.
+**Why:** a balanced group (the default, horizontal) is an inline-size container (`@container`), so that it can balance its rows; a container's width does not come from its content, so a shrink-to-fit parent gives it none. With `balance={false}`, or `orientation="vertical"`, there is no container.
+**Fix:** give the parent a width (`w-full`, a `max-w-*` or a fixed width), centring it with margins rather than shrink-to-fit, or pass `balance={false}` to restore the previous layout.
+
 ### A component with my own tone (Shape, Fab, Avatar, StatCard, a metric card) shows no colour, or `tone` is a type error
 
 **When:** `<Shape tone="maths" />`, `<Fab tone="maths" />`, an `Avatar`, a `StatCard` or a metric card with `tone="maths"` draws no colour, or TypeScript reports:
@@ -3272,6 +3293,9 @@ only in the browser reads the real answer from its first render, as before.
 `Stepper` logged this line until 2.2.0, and a desktop hydrating its server
 HTML showed the mismatch (it asks whether the screen is wide); upgrade and
 drop any `clientOnly(Stepper)` you added for it.
+For a breakpoint of your own, use
+[`useSsrMediaQuery(query, serverValue)`](guides/helpers.md#usessrmediaquery)
+instead of `useMedia` or a hand-written `useSyncExternalStore`.
 
 ### `useMatches must be used within a data router`
 
@@ -5105,7 +5129,7 @@ append({ name: '' }, { shouldFocus: false });
 `aria-disabled`, still focusable, and does nothing by design; the reason, if
 `removeDisabledReason` gave one, is its tooltip, shown on hover, focus, tap and
 click, and its description), or `min` is
-reached (the button is `disabled`).
+reached (the button is `disabled`, or absent with `removeAtMin="hide"`).
 **Fix:** return `true` from `removable` for a row that may go, and say why for
 the others, so a user is told instead of left guessing:
 
@@ -5202,7 +5226,8 @@ The `*` is now drawn by a CSS pseudo-element with an empty `content`
 field's own `required` / `aria-required` says it is required, and every field
 of this library sets it on the element a screen reader lands on (the input, the
 picker's combobox, the select's trigger, the slider thumbs, the rating's
-radiogroup, the editor's textbox, the list's listbox, or, for a file picker,
+radiogroup, the editor's textbox, the `TransferList`'s listbox (a `SortableList` is a `list`
+and only draws the asterisk, with no `aria-required`), or, for a file picker,
 a group described as "This field is required."). A `SelectField`'s trigger is
 now named by its label (`aria-labelledby`), so `getByRole('combobox', { name:
 'Framework' })` finds it.
@@ -6353,6 +6378,29 @@ expect(screen.getByRole('combobox', { name: 'Time zone' })).toHaveValue('Paris')
 screen.getByRole('option', { name: 'Paris GMT+2' });
 ```
 
+### A test that queries a `SortableList` by `listbox` or `option` finds nothing
+
+**When:** a test queries a `SortableList` by `listbox`, `option` or `aria-selected`, after upgrading.
+**Why:** a row holds buttons of its own (grip, move, remove), which an `option`
+may not, so axe reported `nested-interactive`. The list is now a `role="list"`
+of `listitem` rows; `aria-selected`, `aria-activedescendant` and `aria-required`
+are gone (`aria-disabled` stays on a disabled row).
+**Fix:**
+
+```ts
+const list = screen.getByRole('list', { name: 'Ranking' });
+const rows = within(list).getAllByRole('listitem');
+```
+
+### axe reports `nested-interactive` on a list whose rows hold buttons
+
+**When:** axe flags a list whose rows hold buttons or other controls.
+**Why:** a row with `role="option"` (or `button`, `tab`...) may not contain
+focusable controls: assistive technology reads its children as text.
+**Fix:** make the row a `listitem` of a `list` (a roving tab stop on the row,
+the buttons keep their own names), as `SortableList` does. Do not exclude the
+list from the axe run.
+
 ### An input inside an `InputGroup` lost a class or a style of `Input`
 
 **When:** a test or a style relies on a class of `Input` or `Textarea`

package/lib/components/base-content.css

@@ -162,6 +162,17 @@
 		[data-slot="form-actions"] {
 			@apply sticky bottom-0 z-10 flex w-full justify-end gap-2 bg-background/80 border-t-8 border-transparent px-4 pb-[max(1rem,env(safe-area-inset-bottom))] backdrop-blur-sm max-sm:*:flex-1;
 		}
+		/* `data-padding="none"`: the form sits flush in a container that
+		   already pads it (a page, a card, a sheet): no inset on the fields or
+		   the actions, so both align with the container's content edge. */
+		&[data-padding="none"] {
+			[data-slot="form-fields"] {
+				@apply p-0;
+			}
+			[data-slot="form-actions"] {
+				@apply px-0;
+			}
+		}
 	}
 
 	/* No height cap and no scroll of its own: the page (or the overlay) is

package/lib/components/components.css

@@ -54,6 +54,7 @@
 @import "./ui/actions/button-group/button-group-standard.css";
 /* ActivityLayout: the route transition (cross-fade, none under reduced motion). */
 @import "./ui/layout/app-shell/route-transition.css";
+@import "./ui/layout/app-shell/app-header.css";
 @import "./ui/layout/app-shell/activity-backdrop.css";
 @import "./ui/layout/app-shell/activity-backdrop-shapes.css";
 @import "./ui/layout/auth-card/auth-card-backdrop.css";
@@ -97,6 +98,7 @@
 @import "./ui/actions/toolbar/toolbar-morph-slots.css";
 @import "./ui/actions/toolbar/toolbar-morph-widen.css";
 @import "./ui/actions/toolbar/toolbar-expressive-look.css";
+@import "./ui/layout/navigation-toolbar/navigation-toolbar.css";
 @import "./ui/actions/toolbar/toolbar-density.css";
 @import "./editor-toolbar-expressive.css";
 @import "./editor-floating-bar.css";
@@ -142,6 +144,8 @@
 @import "./ui/display/seat-ring/seat-ring-ring.css";
 /* VoteTally: ranked bars with counts, shares and voters. */
 @import "./ui/display/vote-tally/vote-tally.css";
+/* TubeCap: a specimen tube chip, cap colours fixed by the tube convention. */
+@import "./ui/display/tube-cap/tube-cap.css";
 /* SecretCard: a face that is not rendered until it is revealed. */
 @import "./ui/display/secret-card/secret-card.css";
 /* Alert and Banner span the row in the form grids (#1497). */
@@ -206,6 +210,7 @@
 @import "./ui/fields/attributes/attributes.css";
 /* Background: the gradient preset's CSS, shared (lib/backgrounds/css); the other presets are opt-in: backgrounds.css. */
 @import "./background-shared.css";
+@import "./ui/layout/app-search/app-search.css"; /* AppSearchBar, SearchView */
 @import "./ui/widgets/drawing/drawing.css"; /* @nxgt/material/draw: role colours, focus ring */
 @import "./ui/widgets/drawing/drawing-animate.css";
 @import "./ui/widgets/barcode/barcode.css"; /* @nxgt/material/barcode: symbol colours, label sheet */

package/lib/components/ui/actions/fab/fab-dock.css

@@ -1,6 +1,9 @@
 /* FabDock: the bottom-end corner, 16px in (24px from 840px wide, M3's
- * medium window), above the home indicator and above a docked bar that
- * sets --nxgt-media-dock. `contained` places it in its positioned parent.
+ * medium window), above the home indicator, above a docked bar that sets
+ * --nxgt-media-dock and above a bottom navigation bar (--nxgt-nav-bar);
+ * --nxgt-bottom-chrome is the two together. The bar's room holds the
+ * safe area, so the dock clears the taller of the two, not their sum. `contained` places it in its
+ * positioned parent.
  * While a FabMenu in it is open, a light scrim covers the page (contained:
  * the pane) behind the pills. The menu is modal, so the whole page is inert
  * either way. */
@@ -11,8 +14,13 @@
 		inset-inline-end: var(--fab-dock-gap);
 		inset-block-end: calc(
 			var(--fab-dock-gap) +
-			env(safe-area-inset-bottom, 0px) +
-			var(--nxgt-media-dock, 0px)
+			max(
+				env(safe-area-inset-bottom, 0px),
+				var(
+					--nxgt-bottom-chrome,
+					calc(var(--nxgt-nav-bar, 0px) + var(--nxgt-media-dock, 0px))
+				)
+			)
 		);
 		z-index: 40;
 		display: flex;
@@ -33,8 +41,13 @@
 		padding: var(--fab-dock-gap);
 		padding-block-end: calc(
 			var(--fab-dock-gap) +
-			env(safe-area-inset-bottom, 0px) +
-			var(--nxgt-media-dock, 0px)
+			max(
+				env(safe-area-inset-bottom, 0px),
+				var(
+					--nxgt-bottom-chrome,
+					calc(var(--nxgt-nav-bar, 0px) + var(--nxgt-media-dock, 0px))
+				)
+			)
 		);
 	}
 	@media (min-width: 840px) {