@nxgt/material 3.80.0 → 3.82.0

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/icon-motifs.md

@@ -138,7 +138,7 @@ An `Illustration` draws a hero icon on a Material 3 Expressive plate, with two
 to four satellites. There are twelve base scenes (`empty`, `no-results`,
 `not-found`, `error`, `offline`, `success`, `welcome`, `forbidden`,
 `maintenance`, `invitation`, `sign-in`, `empty-inbox`) and two domain sets of
-ten, **health** and **education**, plus **game** (sixteen scenes for games and
+ten, **health** and **education**, plus **game** (twenty-five scenes for games and
 events), each its own subpath so an app that does not import one does not carry it:
 
 <img src="../previews/feedback-status-illustration.webp" width="480" alt="The twelve base illustration scenes">

package/docs/guides/illustrations.md

@@ -5,7 +5,7 @@ on a Material 3 Expressive plate, two to four satellite icons around it, a
 dashed ring and a few sparkles. There are twelve scenes: `empty`, `no-results`,
 `not-found`, `error`, `offline`, `success`, `welcome`, `forbidden`,
 `maintenance`, `invitation`, `sign-in` and `empty-inbox`, and two domain sets of
-ten more each, health and education, in their own entries ([health](#scene-sets-the-health-scenes) and [education](#scene-sets-the-education-scenes)), and sixteen for games ([game](#scene-sets-the-game-scenes)). The icons are
+ten more each, health and education, in their own entries ([health](#scene-sets-the-health-scenes) and [education](#scene-sets-the-education-scenes)), and twenty-five for games ([game](#scene-sets-the-game-scenes)). The icons are
 [Font Awesome](https://fontawesome.com) sprites **your app serves** (see
 [Icons](../getting-started.md#icons)): the package ships no icon artwork, so it
 works with the sprites your licence covers. The [icon motifs guide](icon-motifs.md) shows them next to the icon backgrounds, the sky and the themes, and lists the suggested names that are Pro only, with Free neighbours.
@@ -148,12 +148,12 @@ icons: serve a Pro sprite, or set `edition="free"` on `IconSpritesProvider`, whi
 
 ## Scene sets: the game scenes
 
-`@nxgt/material/illustrations/game` holds sixteen scenes for a game, a quiz, a
+`@nxgt/material/illustrations/game` holds twenty-five scenes for a game, a quiz, a
 community or an event app: `night-sky`, `dawn`, `village` (night),
-`day-village`, `graveyard`, seven character pictograms (`seer`, `healer`,
-`archer`, `cupid`, `wolf`, `villager`, `witch`), `victory`, `empty-table`,
+`day-village`, `graveyard`, sixteen character pictograms (`seer`, `healer`,
+`archer`, `cupid`, `wolf`, `villager`, `witch`, `protector`, `elder`, `village-idiot`, `scapegoat`, `raven`, `fox`, `siblings`, `big-bad-wolf`, `wolf-father`), `victory`, `empty-table`,
 `waiting-players` and `connection-lost`. It works exactly like the other sets,
-and they register side by side. Use them where a screen is empty, waiting,
+and they register side by side. The `fox` and `scapegoat` heroes are drawn as vector art, because the icon sprites have no fox or goat; they follow the tone and dark mode like the sprite icons. Use them where a screen is empty, waiting,
 failed, celebrating or opening: a lobby with no players, a round that waits, a
 dropped connection, a winner, a night-phase hero. Keep them away from behind
 data.

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.

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

@@ -144,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). */

package/lib/components/ui/collections/data-table/data-table-items-tiles.css

@@ -65,8 +65,34 @@
 		) {
 		outline-offset: -2px;
 	}
-	/* The checkbox is centred on the tile, not pinned to its corner. */
+	/* The checkbox sits on the tile's title row (#2391): its centre on the
+	 * title's first line (1rem at 1.4, so 0.7rem under the tile's padding), not
+	 * the tile's middle, which a multi-line tile moves down to the body text.
+	 * The 36px box (44px on a coarse pointer) then starts at the padding minus
+	 * the half-box plus the half-line. The tile's content starts at the top so
+	 * the title is where the box expects it. */
+	[data-slot="data-table-tiles"]
+	> [data-slot="data-table-item"]:not(:has([data-slot="data-table-record"])) {
+		align-content: start;
+	}
 	[data-slot="data-table-tiles"] [data-slot="data-table-item-select"] {
+		inset-block-start: 0.325rem;
+	}
+	[data-slot="data-table-tiles"][data-density="compact"]
+		[data-slot="data-table-item-select"] {
+		inset-block-start: 0.075rem;
+	}
+	@media (pointer: coarse) {
+		[data-slot="data-table-tiles"] [data-slot="data-table-item-select"],
+		[data-slot="data-table-tiles"][data-density="compact"]
+			[data-slot="data-table-item-select"] {
+			inset-block-start: 0.075rem;
+		}
+	}
+	/* A record row is one dense line: its box stays centred on it. */
+	[data-slot="data-table-tiles"]
+		> [data-slot="data-table-item"]:has([data-slot="data-table-record"])
+		[data-slot="data-table-item-select"] {
 		inset-block-start: 50%;
 		translate: 0 -50%;
 	}

package/lib/components/ui/collections/data-table/data-table-items.css

@@ -48,6 +48,21 @@
 		gap: var(--nxgt-cards-gap, 0.75rem);
 		grid-template-columns: minmax(0, 1fr);
 	}
+	/* The list's 4px of ring room sits inside the scroll box, which clips: the
+	 * box takes it back on each inline side, so the cards' edges (not the
+	 * room's) meet the page's edge and the heading above (#2472); the parent needs 4px of inline room. */
+	[data-slot="table-wrapper"]:has(> [data-slot="data-table-cards"]) {
+		margin-inline: -4px;
+		/* `w-full` (utilities layer) would win over this layer. */
+		width: calc(100% + 8px) !important;
+	}
+	/* Tiles keep their own 4px margin, except on a phone (#2292). */
+	@media (min-width: 768px) {
+		[data-slot="table-wrapper"]:has(> [data-slot="data-table-tiles"]) {
+			margin-inline: -4px;
+			width: calc(100% + 8px) !important;
+		}
+	}
 	@container (min-width: 36rem) {
 		[data-slot="data-table-cards"] {
 			grid-template-columns: repeat(2, minmax(0, 1fr));

package/lib/components/ui/display/tube-cap/tube-cap.css

@@ -0,0 +1,87 @@
+/* TubeCap: a specimen tube's chip. The cap colours are the international tube
+ * convention, so they are fixed values, not theme tokens: the same in light
+ * and dark and in every theme. The swatch carries no text; the name beside it
+ * keeps the theme's foreground (AA by the theme), and a hairline in the
+ * foreground colour keeps a black or pale cap visible on either scheme. */
+@layer components {
+	.nxgt-tube-cap {
+		--tube-cap: oklch(0.92 0 0);
+		--tube-cap-size: 1.75rem;
+		display: inline-flex;
+		align-items: center;
+		gap: 0.5rem;
+		max-inline-size: 100%;
+		min-inline-size: 0;
+		padding: 0.25rem 0.625rem 0.25rem 0.25rem;
+		border: 1px solid var(--border);
+		border-radius: 9999px;
+		background: var(--card, var(--background));
+		color: var(--foreground);
+		font-size: 0.875rem;
+		line-height: 1.25;
+	}
+	.nxgt-tube-cap[data-size="sm"] {
+		--tube-cap-size: 1.25rem;
+		font-size: 0.8125rem;
+	}
+	.nxgt-tube-cap[data-size="lg"] {
+		--tube-cap-size: 2.5rem;
+		font-size: 1rem;
+	}
+	.nxgt-tube-cap[data-kind="edta"] {
+		--tube-cap: oklch(0.62 0.13 300);
+	}
+	.nxgt-tube-cap[data-kind="heparin"] {
+		--tube-cap: oklch(0.62 0.17 145);
+	}
+	.nxgt-tube-cap[data-kind="citrate"] {
+		--tube-cap: oklch(0.8 0.1 230);
+	}
+	.nxgt-tube-cap[data-kind="esr"] {
+		--tube-cap: oklch(0.22 0 0);
+	}
+	.nxgt-tube-cap[data-kind="serum"] {
+		--tube-cap: oklch(0.55 0.21 27);
+	}
+	.nxgt-tube-cap[data-kind="gel"] {
+		--tube-cap: oklch(0.82 0.15 85);
+	}
+	.nxgt-tube-cap[data-kind="fluoride"] {
+		--tube-cap: oklch(0.68 0.01 260);
+	}
+	.nxgt-tube-cap[data-kind="trace"] {
+		--tube-cap: oklch(0.45 0.18 262);
+	}
+	.nxgt-tube-cap [data-slot="tube-cap-swatch"] {
+		flex: none;
+		box-sizing: border-box;
+		inline-size: var(--tube-cap-size);
+		block-size: var(--tube-cap-size);
+		border-radius: 9999px;
+		background: var(--tube-cap);
+		box-shadow: 0 0 0 1px
+			color-mix(in oklab, var(--foreground) 45%, transparent);
+		forced-color-adjust: none;
+	}
+	.nxgt-tube-cap [data-slot="tube-cap-text"] {
+		display: inline-flex;
+		flex-wrap: wrap;
+		align-items: baseline;
+		column-gap: 0.5rem;
+		min-inline-size: 0;
+		overflow-wrap: anywhere;
+	}
+	.nxgt-tube-cap [data-slot="tube-cap-label"] {
+		font-weight: 600;
+	}
+	.nxgt-tube-cap [data-slot="tube-cap-volume"],
+	.nxgt-tube-cap [data-slot="tube-cap-accession"] {
+		color: var(--muted-foreground);
+		font-variant-numeric: tabular-nums;
+	}
+	.nxgt-tube-cap [data-slot="tube-cap-action"] {
+		display: inline-flex;
+		flex: none;
+		margin-inline-start: 0.125rem;
+	}
+}

package/lib/themes/ambre.css

@@ -1,6 +1,6 @@
 /* Theme "ambre", generated.
  * Seeds: primary oklch(0.52 0.13 48), secondary oklch(0.5 0.09 95), tertiary oklch(0.5 0.14 350), neutral hue 65, tint 0.85.
- * Contrast: 66 pairs, 0 failing.
+ * Contrast: 67 pairs, 0 failing.
  * hue-near-status: The primary's hue 48 is 14° from warning (62): they may read alike. Keep an icon and a word with every status.
  */
 [data-nxgt-theme="ambre"] {

package/lib/themes/ardoise.css

@@ -1,6 +1,6 @@
 /* Theme "ardoise", generated.
  * Seeds: primary oklch(0.45 0.065 252), secondary oklch(0.48 0.05 215), tertiary oklch(0.48 0.1 290), neutral hue 250, tint 0.7.
- * Contrast: 66 pairs, 0 failing.
+ * Contrast: 67 pairs, 0 failing.
  */
 [data-nxgt-theme="ardoise"] {
 	--radius: 0.375rem;

package/lib/themes/bleumono.css

@@ -1,6 +1,6 @@
 /* Theme "bleumono", generated.
  * Seeds: primary oklch(0.46 0.13 255), secondary oklch(0.55 0.06 255), tertiary oklch(0.38 0.17 255), neutral hue 255, tint 1.1.
- * Contrast: 66 pairs, 0 failing.
+ * Contrast: 67 pairs, 0 failing.
  * lightness-moved: secondary: lightness 0.550 to 0.520 for AA.
  * chroma-lowered: tertiary: chroma 0.170 to 0.125 (lowered to fit sRGB or AA).
  * hue-near-status: The primary's hue 255 is 0° from info (254.624): they may read alike. Keep an icon and a word with every status.

package/lib/themes/bluemoon.css

@@ -1,6 +1,6 @@
 /* Theme "bluemoon", generated.
  * Seeds: primary oklch(0.45 0.12 265), secondary oklch(0.55 0.02 250), tertiary oklch(0.62 0.08 290), neutral hue 265, tint 1.
- * Contrast: 66 pairs, 0 failing.
+ * Contrast: 67 pairs, 0 failing.
  * lightness-moved: secondary: lightness 0.550 to 0.520 for AA.
  * lightness-moved: tertiary: lightness 0.620 to 0.563 for AA.
  * hue-near-status: The primary's hue 265 is 10° from info (254.624): they may read alike. Keep an icon and a word with every status.

package/lib/themes/corail.css

@@ -1,6 +1,6 @@
 /* Theme "corail", generated.
  * Seeds: primary oklch(0.58 0.17 35), secondary oklch(0.52 0.1 70), tertiary oklch(0.5 0.1 200), neutral hue 30, tint 0.8.
- * Contrast: 66 pairs, 0 failing.
+ * Contrast: 67 pairs, 0 failing.
  * lightness-moved: primary: lightness 0.580 to 0.575 for AA.
  * chroma-lowered: tertiary: chroma 0.100 to 0.085 (lowered to fit sRGB or AA).
  * hue-near-status: The primary's hue 35 is 8° from error (27.325): they may read alike. Keep an icon and a word with every status.
@@ -17,7 +17,7 @@
 	--popover-foreground: oklch(0.227 0.0136 30);
 	--primary: oklch(0.575 0.17 35);
 	--primary-foreground: oklch(0.984 0.003 30);
-	--primary-text: color-mix(in oklab, var(--primary) 89%, black);
+	--primary-text: color-mix(in oklab, var(--primary) 88%, black);
 	--primary-indicator: var(--primary);
 	--secondary: oklch(0.52 0.1 70);
 	--secondary-foreground: oklch(0.984 0.003 30);

package/lib/themes/foret.css

@@ -1,6 +1,6 @@
 /* Theme "foret", generated.
  * Seeds: primary oklch(0.48 0.1 152), secondary oklch(0.5 0.08 118), tertiary oklch(0.5 0.1 55), neutral hue 140, tint 0.8.
- * Contrast: 66 pairs, 0 failing.
+ * Contrast: 67 pairs, 0 failing.
  */
 [data-nxgt-theme="foret"] {
 	--radius: 0.5rem;

package/lib/themes/lavande.css

@@ -1,6 +1,6 @@
 /* Theme "lavande", generated.
  * Seeds: primary oklch(46% 0.1135 276.35), secondary oklch(48% 0.1135 245.65), tertiary oklch(45.91% 0.1864 310.75), neutral hue 292, tint 1.
- * Contrast: 66 pairs, 0 failing.
+ * Contrast: 67 pairs, 0 failing.
  */
 [data-nxgt-theme="lavande"] {
 	--radius: 0.625rem;