@nxgt/material 3.80.0 → 3.81.0

package/dist/{use-material-translation-BJucC_xe.js → use-material-translation-DYrfV_JJ.js}

@@ -1,4 +1,4 @@
-import { i as e, t } from "./translate-material-CZTGqgen.js";
+import { i as e, t } from "./translate-material-D4rn5UaQ.js";
 import { useCallback as n } from "react";
 //#region lib/i18n/use-material-translation.ts
 function r() {

package/dist/{use-return-focus-BS1JLcnq.js → use-return-focus-C_Qz_yTk.js}

@@ -1,6 +1,6 @@
 import { o as e, r as t } from "./dist-DVRQkaTK.js";
 import { i as n, n as r, r as i, t as a } from "./dist-DWZXlCZR.js";
-import { C as o, S as s, x as c } from "./spinner-RITOxvpH.js";
+import { C as o, S as s, x as c } from "./spinner-DH1mm8hH.js";
 import { a as l, i as u, r as d } from "./dist-DHdUUM1w.js";
 import { c as f, i as p, l as m, o as h, r as g, s as ee } from "./in-dialog-D61Yeaol.js";
 import { r as te } from "./escape-owner-DpaP0lm1.js";

package/docs/components/data-display.md

@@ -21,6 +21,7 @@ from `@nxgt/material/components`.
 | <img src="../previews/data-display-metric-cards.webp" width="96" alt=""> | [Metric cards](#metric-cards) | Sixteen dashboard tiles |
 | <img src="../previews/data-display-card-presets.webp" width="96" alt=""> | [Card presets](#card-presets) | Twenty-seven ready-made cards |
 | <img src="../previews/data-display-statusindicator.webp" width="96" alt=""> | [StatusIndicator](#statusindicator) | Coloured status dot with a label |
+| <img src="../previews/data-display-tubecap.webp" width="96" alt=""> | [TubeCap](#tubecap) | A specimen tube's chip: a cap in its fixed convention colour, the container's name beside it, optional volume, accession and action |
 | <img src="../previews/data-display-summarydata.webp" width="96" alt=""> | [SummaryData](#summarydata) | Label / value pairs as a grid or inline |
 | <img src="../previews/data-display-description.webp" width="96" alt=""> | [Description](#description) | One read-only label / value pair |
 | <img src="../previews/data-display-descriptionlist.webp" width="96" alt=""> | [DescriptionList](#descriptionlist) | A dense auto-fill grid of label / value pairs in a `dl`, with a panels variant |
@@ -193,7 +194,7 @@ no `style` attribute and a strict CSP is fine.
 - Seat changes are not animated beyond a colour fade, which stops under
   `prefers-reduced-motion`.
 
-**Storybook:** `Data display/SeatRing` · **Vue:** not yet (#1931)
+**Storybook:** `Data display/SeatRing` · **Vue:** not yet (#2470) (#1931)
 
 ---
 
@@ -268,7 +269,7 @@ const [open, setOpen] = useState(false);
   the layout follows `dir` (RTL) and dark mode.
 - Keep `front` and `description` free of the secret: they are always in the page.
 
-**Storybook:** `Data display/SecretCard` · **Vue:** not yet (#1938)
+**Storybook:** `Data display/SecretCard` · **Vue:** not yet (#2470) (#1938)
 
 ---
 
@@ -425,7 +426,7 @@ import { CountBadge, IconButton } from '@nxgt/material/components';
 
 ![HighlightedText](../previews/data-display-highlightedtext.webp)
 
-A string with the words of a search query in a themed `<mark>`. Case, accents and ligatures are folded (`œ` is `oe`, `æ` is `ae`, `ß` is `ss`), and a query word matches at the start of a word, as a search engine's normaliser does.
+A string with the words of a search query in a themed `<mark>`. Case, accents and ligatures are folded (`œ` is `oe`, `æ` is `ae`, `ß` is `ss`), and a query word matches at the start of a word, as a search engine's normaliser does. The `Guides/Recipes/Search dialog and results page` story marks the matches in command rows and result cards with it.
 
 ```tsx
 import { HighlightedText, highlightRanges } from '@nxgt/material/components';
@@ -790,6 +791,33 @@ import { StatusIndicator } from '@nxgt/material/components';
 
 ---
 
+## TubeCap
+
+![TubeCap](../previews/data-display-tubecap.webp)
+
+A chip for a specimen tube. The cap colour comes from the international tube convention, so it is a fixed value: it does not follow the theme and is the same in light and dark. The container's name is written beside the cap (`label` is required), so colour never carries the meaning alone; the text uses the theme's foreground, which keeps the theme's 4.5:1 contrast.
+
+```tsx
+import { TubeCap } from '@nxgt/material/components';
+
+<TubeCap kind="edta" label="EDTA" volume="4 mL" accession="L00000042-1" />
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `kind` | `'edta' \| 'heparin' \| 'citrate' \| 'esr' \| 'serum' \| 'gel' \| 'fluoride' \| 'trace' \| 'other'` | required | the cap colour: lavender, green, light blue, black, red, gold, grey, royal blue, plain |
+| `label` | `ReactNode` | required | the container's name beside the cap; it also names the chip (`role="group"`) |
+| `volume` | `ReactNode` | none | the volume, as text |
+| `accession` | `ReactNode` | none | the tube's accession label |
+| `action` | `ReactNode` | none | trailing slot, such as an `IconButton` |
+| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | cap of 20, 28 or 40px |
+
+`TUBE_CAP_KINDS` lists the kinds. The look is CSS on `data-kind`, with no inline style (strict CSP). The cap is `aria-hidden`.
+
+**Storybook:** `Data display/TubeCap` · **Vue:** not yet (#2470)
+
+---
+
 ## SummaryData
 
 ![SummaryData](../previews/data-display-summarydata.webp)
@@ -1339,7 +1367,7 @@ and the user's zone) and both sides agree:
 <ChangeHistory entries={entries} now={loaderData.now} timeZone={loaderData.timeZone} />
 ```
 
-**Storybook:** `Data display/ChangeHistory` · **Vue:** not yet (tracked as a `vue` issue)
+**Storybook:** `Data display/ChangeHistory` · **Vue:** not yet (#2470) (tracked as a `vue` issue)
 
 ---
 
@@ -1376,7 +1404,7 @@ The offset follows the instant (`Europe/Paris` is `UTC+1` in winter and
 `UTC+2` in summer). `ChangeHistory` takes a `timeZone` and `RelativeTime` a `now`
 the same way; pass the app's zone from the server so every screen agrees.
 
-**Storybook:** `Data display/ZonedTime` · **Vue:** not yet (tracked as a `vue` issue)
+**Storybook:** `Data display/ZonedTime` · **Vue:** not yet (#2470) (tracked as a `vue` issue)
 
 ---
 
@@ -1445,7 +1473,7 @@ own, so they add up to less.
 - Bar widths are SVG attributes, so server markup has no `style` attribute and
   a strict CSP is fine.
 
-**Storybook:** `Data display/VoteTally` · **Vue:** not yet (#1940)
+**Storybook:** `Data display/VoteTally` · **Vue:** not yet (#2470) (#1940)
 
 ---
 
@@ -1778,7 +1806,7 @@ lock set by another code form disables its field and leaves Cancel usable.
 button by `getByRole('button', { name: 'Activate' })` and the lock by
 `getByRole('alert')`.
 
-**Storybook:** `Data display/EnrolmentCard`, `…/Shared lock`, `Guides/Accessibility/Touch targets/Verification code` · **Vue:** not yet
+**Storybook:** `Data display/EnrolmentCard`, `…/Shared lock`, `Guides/Accessibility/Touch targets/Verification code` · **Vue:** not yet (#2470)
 
 ---
 
@@ -1921,4 +1949,4 @@ import { RecoveryCodesStatus, VerificationLockProvider } from '@nxgt/material/co
 
 It reads the page-wide lock like [EnrolmentCard](#enrolmentcard) does. With `requireCode={false}` there is no code form, so `error` and `attemptsLeft` are not shown: the plain button follows `pending`, and is disabled by `locked` and by the page-wide lock; then the lock's text (the message of the answer that locked, or "Too many wrong codes. Try again later.") shows above it as a muted line that describes the button.
 
-**Storybook:** `Data display/RecoveryCodesStatus`, `Data display/EnrolmentCard/Shared lock` · **Vue:** not yet
+**Storybook:** `Data display/RecoveryCodesStatus`, `Data display/EnrolmentCard/Shared lock` · **Vue:** not yet (#2470)

package/docs/components/data-table-filter-and-lists.md

@@ -864,8 +864,9 @@ export default function Students() {
   search. When rows come back while the focus was on the empty page, it
   goes to the search; rows that come back on their own leave the focus
   alone. The empty page stays while the next answer loads (`data-busy`).
-- **A failed fetch.** Pass `error` (`{ title?, description?, cause?, kind? }`,
-  `null` when there is none; `kind` takes `ErrorState`'s kinds, `generic`
+- **A failed fetch.** Pass `error` (`{ title?, description?, cause?, kind?, illustration? }`,
+  `null` when there is none; `illustration` is a scene id, a node, `true` or
+  `false`, as on `ListEmptyPage`, and replaces the scene `kind` picks; `kind` takes `ErrorState`'s kinds, `generic`
   (default), `offline` or `maintenance`; `title` and `description` default to
   the two strings below, `cause` to none) and `onRetry`: the failure replaces the rows,
   the header, the footer and the empty page, with a Retry (a returned promise,
@@ -1667,6 +1668,7 @@ import { DayGroupedList } from '@nxgt/material/components';
 | `labels` | `Partial<Record<DayGroupKey, ReactNode>>` | — | replaces a heading |
 | `sticky` | `boolean` | `true` | headings stick while their items scroll |
 | `showCount` | `boolean` | `false` | the count beside each heading |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | the level of each heading (`<h2>`…`<h6>`), to follow the heading above the list |
 | `headerClassName` / `listClassName` | `string` | — | a heading's background on a tinted parent, the `<ul>`'s dividers |
 
 **Storybook:** `Data table, filter & lists/DayGroupedList` · **Vue:** — (later)
@@ -2992,7 +2994,9 @@ import { Avatar, ListPane, ListPaneItem } from '@nxgt/material/components';
 `trailing`, `selected`, `focused` (a ring while its `group/listbox` parent has
 visible focus), `disabled`, `density` (`comfortable` or `compact`, one line),
 `appearance` (`plain` or `card`) and `lifted` (raised, as under a drag). It is
-purely visual: give it the role and the events of the list it sits in. The
+purely visual: give it the role and the events of the list it sits in. A
+`title` or `description` cut by the ellipsis keeps its full text in a `title`
+attribute (when it is a string). The
 badge steps aside when the pane is narrower than 20rem.
 
 The height reaches the body as a CSS custom property set from script, never

package/docs/components/form-fields.md

@@ -245,6 +245,7 @@ export function PlanForm({ onSave }: { onSave: (values: Values) => void }) {
 | `reorderable` | `boolean` | `false` | move up / move down buttons on each row |
 | `max` | `number` | — | at this many rows, Add is disabled and says why |
 | `min` | `number` | — | at this many rows, Remove is disabled |
+| `removeAtMin` | `'disable' \| 'hide'` | `'disable'` | at `min` rows, `'hide'` does not render Remove instead of disabling it |
 | `removable` | `(row, index) => boolean` | every row | a row it refuses keeps its Remove button `aria-disabled` (focusable; activating it does nothing). `row` is the `useFieldArray` field (`RepeatableGroupFormField`) or your item |
 | `removeDisabledReason` | `(row, index) => string \| undefined` | — | why a row cannot be removed: its Remove button's tooltip (on hover, focus, tap and click) and `aria-describedby` description |
 | `emptyTitle`, `emptyDescription` | `ReactNode` | — | an `EmptyState` when there is no row |

package/docs/components/media-and-files.md

@@ -624,6 +624,7 @@ with a `+N` tile).
 | `selectable` | `boolean` | — | checkboxes on tiles; `onSelectionChange(ids)` |
 | `open` / `defaultOpen` / `onOpenChange` | `boolean` | — | control the lightbox |
 | `onDelete` | `(item) => void` | — | adds a delete button on each tile |
+| `aria-label` / `aria-labelledby` | `string` | `'Gallery'` label | names the gallery (the root has `role="application"`); a given `aria-labelledby` replaces the default label. `MiniGallery` and `LightboxGallery` take both. Other `div` props (`id`, `data-*`, `onKeyDown`) reach the root element |
 
 **States.** Tiles use the `md` corner and round to `lg-plus` on hover (an
 effects easing, so the radius never overshoots) with a spring press scale. A

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

@@ -536,8 +536,9 @@ the page. It takes a `div`'s props.
   `Button`; a second filled `Button` among the children warns once in
   development, make the others `outlined` or `tonal`.
 - **Surface.** Below `md` the bar paints `--background` (it is stuck over the content); from `md`, and with `sticky={false}`, it paints nothing and takes its parent's surface, such as a `Card`.
+- **Edges.** The bar adds no horizontal padding: its leading and trailing edges are those of the column it sits in, sticky or inline, so its buttons line up with the cards and fields above. Pad the column, not the bar.
 - **Safe areas.** Under `viewport-fit=cover` the bar pads clear of
-  `env(safe-area-inset-left | right | bottom)`, as classes.
+  `env(safe-area-inset-left | right | bottom)` (the sides only below `md`), as classes.
 - **Keyboard.** From the visual viewport (`visualViewport`), the bar rises by
   the height the on-screen keyboard covers (`--nxgt-keyboard-inset` on the bar,
   `data-keyboard="open"` while it is open) and drops the bottom safe-area

package/docs/components/overlays-and-menus.md

@@ -157,8 +157,12 @@ The look lives in the stylesheet (`nxgt-dialog`, `nxgt-scrim`), under the
 utilities: a class you pass wins. The flat look of 2.x before it is
 `className="rounded-lg border bg-background shadow-lg"` on `DialogContent`
 (and `className="bg-black/50"` on a `DialogOverlay` of your own).
-`DialogFooter` stacks its actions full width on a phone, the main one at the
-bottom. `stackOnPhone={false}` keeps one row instead, the first
+`DialogFooter` stacks its actions full width on a phone. **One order for
+`DialogFooter`, `SheetFooter` and `AlertDialogFooter`:** write the actions in
+reading order, the secondary first and the main one last (`Cancel`, `Save`).
+On a wide screen the dialog puts them in a row with the main one on the right;
+on a phone the stack puts the main one on top and the secondary below it, in a
+dialog and in a sheet alike. `stackOnPhone={false}` keeps one row instead, the first
 action on the left and the last on the right, for two short actions such as
 Cancel and Confirm. With `prefers-reduced-motion`, nothing moves: it appears and goes.
 
@@ -271,7 +275,9 @@ Parts: `Sheet`, `SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetTitle`,
 
 `SheetContent` scrolls inside itself, and a top or bottom sheet is capped at
 `100dvh - 3.5rem`. Override the cap with `max-h-*` through `className`.
-`SheetFooter` makes its buttons full width. The former look is
+`SheetFooter` makes its buttons full width, stacked in the same order as
+`DialogFooter` on a phone: write the secondary first and the main action last,
+the main one is on top. The former look is
 `className="rounded-none border-l bg-background shadow-lg"` (the border on the
 side facing the page), and `className="w-3/4"` for the former width.
 
@@ -339,7 +345,7 @@ A bottom drawer spans a phone's width and is centred, at most 672 px wide,
 from 640 px up; `className="mx-auto max-w-md"` on `DrawerContent` centres a
 narrower one, `sm:max-w-none` spans the viewport again, and
 `className="rounded-t-lg bg-background"` is the former look. `DrawerFooter`
-makes its buttons full width. Prefer it to `Sheet` on touch screens.
+makes its buttons full width and keeps source order (first written on top). Prefer it to `Sheet` on touch screens.
 `DrawerContent` moves focus in on open and hands it back on close as
 `DialogContent` does (`Drawer` turns Vaul's `autoFocus` on; `autoFocus={false}`
 keeps focus where it was): back to the
@@ -641,7 +647,7 @@ in a desktop application.
 
 ![Command](../previews/overlays-menus-command.webp)
 
-Command palette with filtering, groups and shortcuts. `CommandDialog` shows it in a modal, with a visible close button (`showCloseButton`, on by default; `false` removes it) at the end of the input row: named "Close" (`material.buttons.close`) and 44px on a coarse pointer, since a phone has no Escape key.
+Command palette with filtering, groups and shortcuts. `CommandDialog` shows it in a modal, with a visible close button (`showCloseButton`, on by default; `false` removes it) at the end of the input row: named "Close" (`material.buttons.close`) and 44px on a coarse pointer, since a phone has no Escape key. For results the server already filtered (`commandProps={{ shouldFilter: false }}`), with debounced suggestions grouped by type, see the `Guides/Recipes/Search dialog and results page` story.
 
 ```tsx
 import {

package/docs/components/rich-widgets.md

@@ -252,6 +252,8 @@ cannot be dragged to another tab; use Move to or Ctrl/Cmd + arrows.
 
 Month / week / day / agenda calendar with drag, resize and slot creation, a
 now line, an optional mini-month side panel and a phone layout of its own.
+With `mode="template"` it edits a recurring week instead (weekday columns, no
+dates), see [Template week](#eventcalendar-template-week).
 
 It reads its **own width**, not the window's, so it adapts inside a narrow
 column too. From 1024px `sidebar` shows a [MiniMonth](date-and-time.md#minimonth)
@@ -307,6 +309,7 @@ function Schedule() {
 | `scrollToHour` | `number` | `7` | the hour the week and day views open on when today is not shown |
 | `resources` | `EventCalendarResource[]` | — | the day view draws one column per resource, see [Resources](#eventcalendar-resources) |
 | `timeZone` | `string` | the machine's | an IANA zone the grid, today and the times follow, see [Time zone](#eventcalendar-time-zone) |
+| `mode` | `'dated' \| 'template'` | `'dated'` | `'template'` is a recurring week with weekday columns and no dates, see [Template week](#eventcalendar-template-week) |
 
 **Short events.** Events that do not overlap in time share a column and keep the
 full width. An event is drawn at least 24px tall only where there is free space
@@ -372,6 +375,87 @@ const events: CalendarEvent[] = [
   date (`Room A, Thursday, March 12th, 2026`), and an event's name includes
   its resource (`Visit 1, Room A`).
 
+### EventCalendar template week
+
+`mode="template"` edits a **recurring week** instead of a dated one: a weekly
+timetable, an opening-hours grid. The columns are named by weekday only (a
+letter on a phone, the full name from 1024px), and there is no date
+navigation, no Today button, no today marker and no now line. Events,
+slots and changes are keyed by **ISO weekday** (1 Monday to 7 Sunday) and
+`HH:mm` times, never by a date. Create (click or drag across free hours),
+move, resize, the keyboard moves and the preview popover keep working.
+The month, day and agenda views do not apply: `view` is `'week'` (the
+default) or `'workweek'` (Monday to Friday), and the week always starts on
+Monday.
+
+```tsx
+import { useState } from 'react';
+import { EventCalendar, type EventCalendarTemplateEvent } from '@nxgt/material/components';
+
+function Timetable() {
+	const [events, setEvents] = useState<EventCalendarTemplateEvent[]>([
+		{ id: 'm', title: 'Maths', weekday: 1, start: '08:00', end: '09:00' },
+		{ id: 'p', title: 'Physics', weekday: 1, start: '09:00', end: '10:30', lane: 'A' },
+		{ id: 'c', title: 'Chemistry', weekday: 1, start: '09:00', end: '10:30', lane: 'B' },
+	]);
+	return (
+		<EventCalendar
+			mode="template"
+			events={events}
+			onEventsChange={setEvents}
+			lanes={[
+				{ id: 'A', label: 'Week A' },
+				{ id: 'B', label: 'Week B' },
+			]}
+			onSlotClick={({ weekday, start, end, lane }) =>
+				setEvents((current) => [
+					...current,
+					{ id: crypto.randomUUID(), title: 'New lesson', weekday, start, end, lane },
+				])
+			}
+		/>
+	);
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `mode` | `'template'` | `'dated'` | the recurring week; `'dated'` (the default) is the calendar above |
+| `events` / `defaultEvents` | `EventCalendarTemplateEvent[]` | — | `{ id, title, weekday, start, end, lane?, color?, description?, disabled? }`; `end` may be `'24:00'` |
+| `onEventsChange` | `(events: EventCalendarTemplateEvent[]) => void` | — | the whole list after a move, a resize, an edit or a delete |
+| `onChange` | `(change: EventCalendarTemplateChange) => void` | — | `{ events, event, previous }` after a move, a resize or an edit |
+| `onEventClick` | `(event: EventCalendarTemplateEvent) => void` | — | an event was clicked |
+| `onSlotClick` | `(slot: EventCalendarTemplateSlot) => void` | — | `{ weekday, start, end, lane? }` of the free slot clicked or dragged over; `lane` is the one picked in the switch |
+| `view` / `defaultView` / `onViewChange` | `'week' \| 'workweek'` | `'week'` | the visible view |
+| `renderEvent` | `(event: EventCalendarTemplateEvent) => ReactNode` | — | replaces how an event is drawn |
+| `className` | `string` | — | on the calendar's root |
+| `lanes` | `EventCalendarLane[]` | — | `{ id, label }` of the alternating weeks (`A`, `B`); adds a switch to the toolbar |
+| `lane` / `defaultLane` / `onLaneChange` | `string \| null` | `null` (all) | the lane shown; `null` shows them all |
+
+**Lanes.** An event with a `lane` belongs to that alternating week only; one
+with none belongs to every week. Picking a lane in the switch hides the other
+lanes' events, so one week is edited at a time; with **All weeks** every event shows,
+and the ones with a lane carry its label (`A · Physics`), side by side where they
+overlap. A slot made while a lane is picked reports it in `slot.lane`.
+Moving and resizing keep an event's lane.
+
+The shared options (`startHour`, `endHour`, `hourHeight`,
+`slotDurationMinutes`, `density`, `eventVariant`, `scrollToHour`, `toolbar`,
+`searchable`, `disabled`) work as in the dated calendar; `renderEvent` and
+`className` are in the table above. `date`, `resources`, `timeZone`,
+`sidebar`, `phoneView`, `views` and `weekStartsOn` do not apply. All-day
+events do not exist in a template week.
+
+Ctrl+Arrow moves the focused event within the visible days (Friday wraps to
+Monday in a `workweek`) and stops at 00:00 and 24:00. `ComponentProps<typeof
+EventCalendar>` is the union of the dated and template props: type a wrapper
+with `EventCalendarProps` or `EventCalendarTemplateProps`.
+
+The types are exported from `@nxgt/material/components`: `EventCalendarTemplateProps`
+(the props of this mode), `EventCalendarTemplateEvent`, `EventCalendarTemplateSlot`,
+`EventCalendarTemplateChange`, `EventCalendarLane` and `EventCalendarWeekday`
+(`1 | 2 | … | 7`, the ISO weekday).
+
 ### EventCalendar time zone
 
 `timeZone` (an IANA name such as `Africa/Lagos`) makes the calendar read that
@@ -409,7 +493,7 @@ zone's wall clock. Without it, nothing changes: the machine's clock.
 <EventCalendar view="day" date="2026-03-12" timeZone="Asia/Tokyo" events={events} />
 ```
 
-**Storybook:** `Rich widgets/EventCalendar`, `Rich widgets/EventCalendar/Layouts`, `Rich widgets/EventCalendar/Resources`, `Rich widgets/EventCalendar/Resources on a phone`, `Rich widgets/EventCalendar/Resources a11y`, `Rich widgets/EventCalendar/Time zone`, `Rich widgets/EventCalendar/Back to back`, `Rich widgets/EventCalendar/Resource tone`, `Rich widgets/EventCalendar/Hydration` · **Vue:** `EventCalendar` (the new props and layouts, `resources` and `timeZone`: React only for now, #892 and #1780)
+**Storybook:** `Rich widgets/EventCalendar`, `Rich widgets/EventCalendar/Layouts`, `Rich widgets/EventCalendar/Resources`, `Rich widgets/EventCalendar/Resources on a phone`, `Rich widgets/EventCalendar/Resources a11y`, `Rich widgets/EventCalendar/Time zone`, `Rich widgets/EventCalendar/Back to back`, `Rich widgets/EventCalendar/Resource tone`, `Rich widgets/EventCalendar/Hydration`, `Rich widgets/EventCalendar/Template week` · **Vue:** `EventCalendar` (the new props and layouts, `resources`, `timeZone` and `mode="template"`: React only for now, #892, #1780 and #2458)
 
 ---
 

package/docs/components/selection-and-choice.md

@@ -839,6 +839,18 @@ export function Topics() {
 }
 ```
 
+Balanced by default, and the unbalanced fill:
+
+```tsx
+const four = ['a', 'b', 'c', 'd'].map((value) => ({ value, title: value.toUpperCase() }));
+
+// Room for 3 columns, 4 cards: drawn 2+2, no orphan.
+<ChoiceCardGroup label="Size" columns={3} options={four} value={value} onValueChange={setValue} />
+
+// Every column that fits: 3+1.
+<ChoiceCardGroup label="Size" columns={3} balance={false} options={four} value={value} onValueChange={setValue} />
+```
+
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `type` | `'single' \| 'multiple'` | `'single'` | the value is `string \| null` or `string[]` |
@@ -945,8 +957,18 @@ check box at the end. `type="single"` (the default) is a radio group of
 card has a soft tint and a bar on its start edge; the mark says it too, so
 colour is never the only cue. The cards fill as many columns as fit (each at
 least 13.5rem wide), up to `columns`, so the layout follows the space the field
-has, not the window; there is no container query, so the group also keeps its
-cards inside a shrink-to-fit parent (an inline-flex box, a centred layout).
+has, not the window. The rows are balanced: when the last row would hold one
+orphan card (4 cards in room for 3), the group draws fewer columns and sits 2+2;
+`balance={false}` fills every column that fits (3+1).
+
+When it balances (the default, horizontal), the group is an inline-size
+container (`@container`), which is how it measures its own width. A container's
+width never comes from its content, so give the group a parent with a width: in
+a shrink-to-fit parent (an `inline-flex` box, a float, a centred `w-fit` column)
+it collapses to nothing. Add `w-full`, a `max-w-*` or a fixed width to that
+parent, or pass `balance={false}`: with it (and with `orientation="vertical"`)
+there is no container, and the group behaves as before in a shrink-to-fit
+parent.
 
 ```tsx
 import { ChoiceCardGroup } from '@nxgt/material/components';
@@ -971,7 +993,8 @@ export function Plan() {
 | `deselectable` | `boolean` | `false` | `single` only: pressing the chosen card clears it |
 | `max` / `min` | `number` | — | `multiple` only: `max` blocks the other cards once reached and speaks "{count} of {max} chosen"; `min` is a hint only |
 | `options` | `{ value; title; description?; meta?; icon?; disabled?; disabledReason? }[]` | — | the cards |
-| `columns` | `1 \| 2 \| 3 \| 4` | `2` | the most columns; fewer when a card would be under 13.5rem (one on a phone) |
+| `columns` | `1 \| 2 \| 3 \| 4` | `2` | the most columns; fewer when a card would be under 13.5rem (one on a phone). With `balance`, fewer also when it avoids an orphan: `columns={3}` and 4 cards draw 2+2 |
+| `balance` | `boolean` | `true` | when the last row would hold one orphan card (4 cards in room for 3), draw fewer columns (2+2); by container width, CSS only. `false` fills every column that fits |
 | `density` | `'comfortable' \| 'compact'` | `'comfortable'` | the cards' padding |
 | `label`, `helperText`, `error`, `required`, `disabled`, `id` | as on `ChipGroupField` | — | the shared choice-group props: the group's name and help, its invalid and required states |
 | `name` | `string` | — | put on every card (`ChoiceCardGroupFormField` passes its field `name`), so `document.getElementsByName(name)` finds the group's cards in order |
@@ -1113,11 +1136,19 @@ English without one.
 
 Searchable list you reorder by dragging or with the keyboard. The row under
 the pointer lifts into a card with a deep shadow, and its place in the list
-stays as a dashed slot. From the keyboard, Space (or Enter) picks the focused
-row up, the arrows move it, Space drops it and Escape puts it back; Ctrl/⌘ +
-arrow moves it at once, Home / End jump. Each step is read out by a live
-region ("Ada Lovelace moved to position 3 of 5."). With reduced motion the
-drop does not animate.
+stays as a dashed slot. With reduced motion the drop does not animate.
+
+The list is a `role="list"` of `listitem` rows, not a listbox: a row holds
+buttons of its own (grip, move, remove), which an `option` may not. Tab reaches
+the list once, on one row (a roving tab stop), and the arrows move the focus
+from row to row. A row of a disabled list is never a tab stop and carries
+`aria-disabled`. A long label keeps its full text in a `title`, and the grip is
+named after its item ("Drag: Ada Lovelace").
+
+From the keyboard, Space (or Enter) on a row picks it up, the arrows move it,
+Space drops it and Escape puts it back; Ctrl/⌘ + arrow moves it at once,
+Home / End jump. Each step is read out by a live region ("Ada Lovelace moved to
+position 3 of 5."). A key pressed on a row's own button is that button's.
 
 ```tsx
 import { SortableList, type SortableListItem } from '@nxgt/material/components';
@@ -1144,7 +1175,7 @@ export function Ranking() {
 | `reorderable` | `boolean` | `false` | move up / down buttons |
 | `searchable` | `boolean` | `true` | filter box |
 | `height` | `number \| string` | `320` | list height |
-| `required` | `boolean` | — | the asterisk, and `aria-required` on the `listbox`, which the label names |
+| `required` | `boolean` | — | the asterisk on the label (a `list` takes no `aria-required`) |
 | `hideLabel` | `boolean` | `false` | `true` keeps `label` as the list's accessible name (`aria-labelledby`) but draws nothing, for a heading that already titles it |
 | `numbered` | `boolean` | `false` | each row shows its rank in the whole order |
 | `removable` | `boolean` | `false` | a remove button on each row, and Delete: the row leaves the value |
@@ -1156,8 +1187,16 @@ export function Ranking() {
 where it is: no grip, not draggable, not movable from the keyboard, not
 removable).
 
+In a test, query it by role and name:
+
+```ts
+const list = screen.getByRole('list', { name: 'Ranking' });
+const rows = within(list).getAllByRole('listitem');
+await user.click(within(rows[0]).getByRole('button', { name: /^Move down/ }));
+```
+
 **Emits:** `string[]`, in the new order.
-**Form wrapper:** `SortableListFormField` — `control` and `name` plus the same props, `hideLabel` included (the label's `required` asterisk is hidden with it; the `listbox` keeps `aria-required`), see
+**Form wrapper:** `SortableListFormField` — `control` and `name` plus the same props, `hideLabel` included (the label's `required` asterisk is hidden with it; the asterisk only: a `list` takes no `aria-required`, so a required list is described by a visually hidden "This field is required."), see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
 **Storybook:** `Selection & choice/SortableList` · **Vue:** `SortableList`, `SortableListFormField`
 

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/layouts.md

@@ -204,8 +204,8 @@ The props of each are in
 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 and a landing page. Start from the closest one and
-replace the data.
+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
 

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

@@ -383,7 +383,9 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
-- **Layouts: adaptive navigation, headers and page layouts (next minor)** — `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.
+- **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.