@nxgt/material 3.79.1 → 3.81.0

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

@@ -215,6 +215,32 @@ follow the language of an `I18nProvider` from `@nxgt/material/i18n` (see
 | `searchable` | `boolean` | `true` | search field filtering cards |
 | `reorderableColumns` | `boolean` | `true` | columns can be dragged |
 | `renderCard` | `(item, column) => ReactNode` | — | replaces the default card body |
+| `phoneLayout` | `'tabs' \| 'swipe' \| 'columns'` | unset (= `'columns'`) | below 768px of the board's own width: one column at a time under tabs, full-width snapping columns, or today's peeking columns |
+| `phoneColumn` / `onPhoneColumnChange` | `string` / `(columnId) => void` | first column | the column `tabs` shows (controlled) |
+
+### On a phone
+
+`phoneLayout="tabs"` puts a tab list (column name and card count) above the
+board and shows one column at a time under 768px; the selected column is kept
+in the board's state, or controlled with `phoneColumn`. The tabs follow the
+WAI-ARIA tabs keyboard model (arrows, Home, End). Every column stays in the
+markup and the switch is made by CSS container queries, so the server and the
+client render the same thing at every width; from 768px the tab list is gone
+and the board is the usual row of columns. `phoneLayout="swipe"` keeps all
+columns in a row, one per screen width, with scroll snapping.
+
+With either layout, a card's popover lists the other columns under "Move to"
+when the board is narrower than 768px (its own width, not the screen's), so a card can be moved without dragging; Ctrl/Cmd + arrows
+still move it, and with tabs the selected tab follows the card. A card drawn
+by `renderCard` has no popover: move it with the keys or drag.
+
+`useKanban()` returns `phoneColumnId` and `setPhoneColumn(id)`; the prop type is
+`KanbanPhoneLayout`. With `tabs` only the selected column is visible, so a card
+cannot be dragged to another tab; use Move to or Ctrl/Cmd + arrows.
+
+```tsx
+<Kanban phoneLayout="tabs" columns={columns} items={items} onColumnsChange={setColumns} />
+```
 
 **Storybook:** `Rich widgets/Kanban` · **Vue:** `Kanban`
 
@@ -226,6 +252,8 @@ follow the language of an `I18nProvider` from `@nxgt/material/i18n` (see
 
 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)
@@ -281,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
@@ -346,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
@@ -383,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`