@nxgt/material 3.91.0 → 3.93.0

package/docs/components/form-fields.md

@@ -333,8 +333,8 @@ masculine one.
 ![ChoiceListField](../previews/form-fields-choicelistfield.webp)
 
 An editable list of answer choices, for a quiz question: each row has a text
-and a "correct" mark. `ChoiceListFormField` wires it to react-hook-form; the
-value is an array of `{ id, text, correct }`.
+and a "correct" mark (and, with `rowDetail`, a short explanation). `ChoiceListFormField` wires it to react-hook-form; the
+value is an array of `{ id, text, correct }` (plus `explanation?` with `rowDetail`).
 
 ```tsx
 import { useForm } from 'react-hook-form';
@@ -403,6 +403,8 @@ form.setError('choices.1.text', { message }, { shouldFocus: true });
 | `label` | `ReactNode` | none | names the group (a `group`, or a `radiogroup` in `single`) |
 | `rowLabel`, `addLabel` | `string` | "answer", "Add answer" | lower-case noun for the buttons (translated by default) |
 | `error`, `rowErrors` | `ReactNode`, `{ [id]: ReactNode }` | none | the list's error and each row's, by id (`ChoiceListField`; the form field fills them from the form) |
+| `rowDetail` | `boolean \| { label?, placeholder?, maxLength? }` | off | adds a textarea under each row, stored as `ChoiceRow.explanation` (why a choice is right or wrong). `true` uses the defaults (`ChoiceRowDetail` types the object): label "Explanation" (translated, numbered "Explanation 2"), no placeholder, no limit. `maxLength` limits the text and shows a counter. Off: rows are `{ id, text, correct }` and nothing changes |
+| `rowDetailErrors` | `{ [id]: ReactNode }` | none | each row's detail error, by id (`ChoiceListField`; the form field fills them from the form) |
 | `onBlur` | `() => void` | none | `ChoiceListField` alone: called when the focus leaves the whole list. In a form the list's root is registered with the form's `FieldBlur`, so touched works without it |
 | `onAssignIds` | `(rows) => void` | `onChange` | `ChoiceListField`: called once on mount with ids given to rows that had none or repeated one; the form field sets them without marking the form dirty |
 | other props | `div` props | | passed to the group's root (`className`, `id`, `data-*`, `ref`) |
@@ -414,6 +416,28 @@ form.setError('choices.1.text', { message }, { shouldFocus: true });
   one on mount (the form field does it with `setValue` when the `FormProvider` above is its own form, and then leaves the form clean; otherwise it calls `onChange`). Give the rows ids in `defaultValues`, the clean path: with assigned ids `defaultValues` still lack them, so `dirtyFields.choices` marks rows after the first real edit.
   In `single`, the new row is marked when no row is. A list that arrives with
   several rows marked is not changed: it fails the `too-many` rule.
+- **Row detail:** with `rowDetail`, each row gets a textarea named "Explanation 2"
+  (or your `label`) that edits `ChoiceRow.explanation`. It follows its row through
+  reorder, add and remove, like `text`. A resolver's issue on
+  `choices.2.explanation` shows under that textarea, and `setFocus('choices.2.explanation')`
+  focuses it. The built-in rules never refuse a blank explanation; require one in
+  your schema. `explanation` stays absent on a row until its textarea is edited.
+
+  ```tsx
+  import type { ChoiceRowDetail } from '@nxgt/material/components';
+
+  const detail: ChoiceRowDetail = { label: 'Why', maxLength: 200 };
+  // <ChoiceListFormField … rowDetail={detail} />
+  ```
+
+  ```tsx
+  <ChoiceListFormField
+    control={control}
+    name="choices"
+    label="Answers"
+    rowDetail={{ label: 'Why', placeholder: 'Why is it right or wrong?', maxLength: 200 }}
+  />
+  ```
 - **Semantics:** each row's text is a labelled input ("Answer 2"); its mark
   is a radio or a checkbox named "Correct: answer 2" (the visible word
   "Correct" starts the name), so `getByRole('checkbox', { name: 'Correct: answer 2' })`
@@ -433,7 +457,7 @@ form.setError('choices.1.text', { message }, { shouldFocus: true });
   list, and blank rows are marked invalid (only for that rule, never for a resolver's or another rule's message). With a resolver (zod), an issue on
   `choices.2.text` shows under row 3 and an issue on `choices` under the list.
   When both fail in one pass, react-hook-form keeps only the list's.
-- **Translations:** `material.choice-list.*` (English and French). The
+- **Translations:** `material.choice-list.*` (English and French; `detail` is the default label of `rowDetail`). The
   messages name the row with `rowLabel` ("Fill in every answer"); `too-few`
   is a plural that adds `s` to it, and the French templates carry the
   feminine article, so a French app overrides the keys for a masculine noun.
@@ -1753,7 +1777,14 @@ import { AttributesFormField } from '@nxgt/material/components';
 ```tsx
 import { AttributeValuesFormFieldSet, FormSection } from '@nxgt/material/components';
 
-const form = useForm({ defaultValues: { attributes: { color: '#2563eb', size: 'M' } } });
+interface ItemValues {
+  label: string;
+  attributes: Record<string, string>;
+}
+
+const form = useForm<ItemValues>({
+  defaultValues: { label: 'Shirt', attributes: { color: '#2563eb', size: 'M' } },
+});
 
 <FormSection title="Attributes">
   <AttributeValuesFormFieldSet
@@ -1769,10 +1800,12 @@ const form = useForm({ defaultValues: { attributes: { color: '#2563eb', size: 'M
 </FormSection>
 ```
 
+`T` is inferred from `control`, so `name` is checked against the form's paths and no `as never` cast is needed.
+
 | Prop | |
 | --- | --- |
 | `attributes` | the attributes to fill, one input each |
-| `control`, `name` | the form and the path of the object it writes |
+| `control`, `name` | the form and the path of the object it writes; generic over the form values (`Control<T>`, `Path<T>`), so a typed form needs no cast |
 | `label` | the fieldset's accessible name (required) |
 | `hideLabel` | default `false`. `true` keeps `label` as the name but draws nothing, for a `FormSection` that already has the title |
 | `defaultValues` | optional fallback, used only while the form value at `name` is empty: `undefined`, `null` or an object with no keys (`{}`). Any other value in the form wins |

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

@@ -258,6 +258,22 @@ saved images).
 | `value` / `onValueChange` | `string[]` | `[]` | field variants: the stored URLs |
 | `onUpload` / `getPresignedUrl` | see [S3UploadField](#s3uploadfield-networkuploadfield) | — | field variants: how a file is sent |
 | `required` | `boolean` | — | field variants: the asterisk, and a "required" description on the field group (below) |
+| `describe` | `(value: string) => FileDescription \| null \| undefined` | — | field variants: names, sizes and types a kept value (an id, a key) instead of showing the value. `FileDescription` is `{ name?, size?, type?, href? }`; `href` is its download link (dropped when not safe: `javascript:` and the like get no Download button). `null` or `undefined` falls back to the plain display. Runs on every render: keep it pure and cheap |
+| `reorderable` | `boolean` | `false` | field variants: move up / move down buttons on the kept files, disabled at the ends and when the field is `disabled`; `onValueChange` receives the new order. The focus stays on the pressed button (the row's other one at an end) and a polite status says "Moved {name} to position {to}". Uploads in flight sit last until they finish |
+
+Kept files by name, size and type, reorderable (the value stays a `string[]`):
+
+```tsx
+<FileListS3Field
+  value={ids}
+  onValueChange={setIds}
+  getPresignedUrl={getPresignedUrl}
+  describe={(id) => files[id]} // { name, size, type, href? } | undefined
+  reorderable
+/>
+```
+
+A row's data is `NetworkUploadDisplayItem`, which gains an optional `type` and `href` (`null`: described with a link that is not safe). New `material.*` keys: `file-list.move-up` (`Move {name} up`), `file-list.move-down` (`Move {name} down`) and `file-list.moved` (`Moved {name} to position {to}`).
 
 The dropzone is a button, and a button may not carry `aria-required`, so the
 field's list and dropzone sit in a `group` named by the label. With `required`,

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

@@ -1249,6 +1249,7 @@ import { Badge, Button, Card, CardContent, Description, RecordDetails, RecordPag
 | `created`, `updated` | `{ label: string; at: Date \| string \| number }` | — | The two segments of the muted meta line; each « label date » stays on one line |
 | `timeZone` | IANA zone | `'UTC'` | The zone the dates are written in, the same on a server and in a browser. Dates have no seconds and no zone suffix |
 | `maxColumns` | `1`-`6` | `4` | The most columns of the facts: the panel's own width gives one, a stacked and wide panel up to this |
+| other `div` props | `ComponentProps<'div'>` minus `title` | — | `data-*`, `id`, `aria-*` and `className` go to the root card; `className` is merged with its own classes |
 
 The facts are a [`DescriptionList`](data-display.md#descriptionlist), so the columns follow the card's width, not the window's.
 

package/docs/components/rich-widgets.md

@@ -309,15 +309,18 @@ To edit and delete in your own dialog instead of the built-in inline fields:
 | `onEventClick` | `(event: CalendarEvent) => void` | — | an event was clicked; it runs even with `onSlotClick` set (an event click never reports a slot) |
 | `eventPreview` | `boolean` | `true` | `false` skips the preview popover, so `onEventClick` alone handles the click |
 | `previewFields` | `EventCalendarPreviewField[]` | all three | the fields the preview edits in place (`'title' \| 'color' \| 'description'`); `[]` keeps the time range and the actions |
-| `onEventEdit` | `(event: CalendarEvent) => void` | — | adds an Edit button to the preview; the app opens its own editor; hidden when the calendar or the event is `disabled` |
-| `onEventDelete` | `(event: CalendarEvent) => void` | — | the preview's delete button calls this instead of the built-in confirmation and removal; the app confirms and deletes; hidden when the calendar or the event is `disabled`, so it never runs for those |
+| `readOnlyEvents` | `boolean` | `false` | no event can be dragged, resized, moved with the keys, edited or deleted; events stay focusable, clickable and at full strength, `onSlotClick` still fires, see [Read-only events](#eventcalendar-read-only-events) |
+| `spans` | `EventCalendarSpan[]` | — | stretches of time shaded behind the events (a closure, a term, a half day off); they never block a slot, see the [guide](../guides/event-calendar.md#spans) |
+| `dayBadges` / `weekBadges` | `EventCalendarBadges` | — | a `{ label, tone? }` badge on a day, or on a week (keyed by its first day per `weekStartsOn`), see the [guide](../guides/event-calendar.md#day-and-week-badges) |
+| `onEventEdit` | `(event: CalendarEvent) => void` | — | adds an Edit button to the preview; the app opens its own editor; hidden when the calendar or the event is `disabled`, and with `readOnlyEvents` |
+| `onEventDelete` | `(event: CalendarEvent) => void` | — | the preview's delete button calls this instead of the built-in confirmation and removal; the app confirms and deletes; hidden when the calendar or the event is `disabled`, so it never runs for those, nor with `readOnlyEvents` |
 | `view` / `defaultView` | `'month' \| 'week' \| 'workweek' \| 'day' \| 'agenda'` | `'month'` | the visible view |
 | `date` / `defaultDate` | `string` | today | the date the view is centred on |
 | `startHour` / `endHour` | `number` | `0` / `24` | hours shown in the time grids |
 | `slotDurationMinutes` | `number` | `60` | grid step for creation and snapping |
 | `toolbar` | `ReactNode` | built-in | replace (or `null` to hide) the toolbar |
 | `views` | `EventCalendarView[]` | all five | the views the switcher offers, in order |
-| `weekStartsOn` | `0`–`6` | the locale's | the first day of the week |
+| `weekStartsOn` | `0`–`6` | the locale's | the first day of the week; the week view starts on it and `weekBadges` are keyed by it ([guide](../guides/event-calendar.md#weekstartson)) |
 | `density` | `'comfortable' \| 'compact'` | `'comfortable'` | compact: 40px hours, shorter month cells |
 | `eventVariant` | `'soft' \| 'solid' \| 'outline'` | `'soft'` | how events are drawn ([EventChip](data-display.md#eventchip)) |
 | `sidebar` | `boolean` | `false` | the side panel from 1024px: mini month and the day's events |
@@ -339,12 +342,40 @@ trade-off: each event stays reachable by keyboard (Tab and the arrow keys move
 through the events), and the agenda view lists every event in full, which is the
 accessible route.
 
+### EventCalendar read-only events
+
+A schedule to read and click, not to rearrange: set `readOnlyEvents`. No event
+can be dragged, resized or moved with Ctrl or Cmd and the arrow keys, and the
+preview offers no edit or delete. Each event keeps its look, its tab stop and
+`onEventClick`, empty slots still call `onSlotClick`, and no drag instruction
+is announced: the calendar is named "Event calendar" in both cases, and only a
+draggable one describes itself with "Drag event". Because `readOnlyEvents` leaves
+no edit path, it also hides the Edit button of `onEventEdit`.
+
+```tsx
+<EventCalendar
+	defaultView="day"
+	defaultDate="2026-03-12"
+	readOnlyEvents
+	onEventClick={(event) => open(event.id)}
+	onSlotClick={(slot) => book(slot.start)}
+	events={events}
+/>
+```
+
+It is not `disabled`, which locks the whole calendar (no slot click, no
+navigation), nor `CalendarEvent.disabled`, which dims one event and makes its
+button inert. Both keep their meaning; `readOnlyEvents` is React only for now
+(the Vue twin is tracked in #2526).
+
 ### EventCalendar event badge
 
 An event takes an optional `badge` (`CalendarEventBadge`: `{ label, tone? }`): a
 small tinted label that marks it, such as a category or a follow-up. `tone` is a
 tone of the library or one your app declared (neutral when omitted). The same
-prop is on [`EventChip`](data-display.md).
+prop is on [`EventChip`](data-display.md). An event also takes `tone` (its colour)
+and `status: 'cancelled'` (struck through, announced as cancelled); see
+[the EventCalendar guide](../guides/event-calendar.md#event-tone-badges-and-cancelled-events).
 
 ```tsx
 import { EventCalendar, type CalendarEvent } from '@nxgt/material/components';
@@ -372,6 +403,28 @@ const events: CalendarEvent[] = [
   in the event's accessible name. The agenda view wraps a long description
   instead of cutting it.
 
+For a status and a priority together, add `badges` (`CalendarEventBadge[]`):
+further badges drawn after `badge`, in the same places and order, all part of
+the event's accessible name (`Visit, Follow-up, Urgent, 2/3`). Each becomes its
+own tone dot where the box is narrow or short. `badges` works with or without
+`badge`.
+
+```tsx
+const events: CalendarEvent[] = [
+	{
+		id: '2',
+		title: 'Operation',
+		start: '2026-03-12T11:00:00Z',
+		end: '2026-03-12T13:00:00Z',
+		badge: { label: 'Scheduled', tone: 'info' },
+		badges: [
+			{ label: 'Urgent', tone: 'warning' },
+			{ label: '2/3', tone: 'success' },
+		],
+	},
+];
+```
+
 ### EventCalendar resources
 
 `resources` splits the **day view** into one column per room, person or team
@@ -547,7 +600,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`, `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)
+**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`, `Rich widgets/EventCalendar/Spans`, `Rich widgets/EventCalendar/Day and week badges`, `Rich widgets/EventCalendar/Event badge`, `Rich widgets/EventCalendar/Event tone and cancelled`, `Rich widgets/EventCalendar/Read-only events` · **Vue:** `EventCalendar` (the new props and layouts, `resources`, `timeZone` and `mode="template"`: React only for now, #892, #1780 and #2458)
 
 ---
 
@@ -1108,6 +1161,21 @@ const [html, setHtml] = useState('<p></p>');
   `compactKit` and `chatKit` show bold, italic, strikethrough and inline code
   (`editorFeatures.inlineCode`) in the toolbar; underline, subscript and
   superscript stay readable in the content but have no button.
+  Strikethrough can be left out. `strike` defaults to `true` and works on both
+  the compact and the full editor: `editorFeatures.marks({ compact: true, strike: false })`
+  (replacing the kit's `marks` feature) drops the mark and its button, `~~x~~`
+  in pasted Markdown reads as plain `x`, and the
+  mark buttons also hide any mark the editor's schema lacks (for example a
+  starter kit configured with `strike: false`):
+
+  ```tsx
+  <CompactEditor
+    features={(kit) => [
+      ...kit.filter((f) => f.name !== 'marks'),
+      editorFeatures.marks({ compact: true, strike: false }),
+    ]}
+  />
+  ```
 - The toolbar opens with undo and redo (one group, kept last when the row folds), and the block type is one menu (Paragraph, Heading 1 to 6) whose button names the block under the caret; its label shows from 64rem of width, an icon alone below.
 - The toolbar is one row on the library's `Toolbar` (one tab stop, arrow keys), each feature's group a `ToolbarGroup`: groups that do not fit fold into the `Toolbar`'s More menu as a unit, lowest `priority` first: a group of two or more rows is a section under its name (its `label`, else `material.editor.group.<id>`, translated; else its id), a group of one row lists that row alone, and a single-choice group (the alignments) stays a radio group under its name. In that menu a toggle is a checkbox row with its state (bold, a list), the alignments one radio group (`menuitemradio` rows, the current one checked), a button a row that runs it (a dialog it opens, the link, the table, the image or the video, keeps the focus, and gives it back to the document when it closes; in the bar a dialog gives it back to its own button, and the image address, which has no button of its own, to the document), a menu control a submenu (the block type and the font as radio rows, the current one checked and shown on the row; the callout types, translated; the image's upload and address), and a popover control (the text colour, the highlight, the emoji) a row that opens its popover at the More button; Escape there gives the focus back to More, a choice to the document. An editor panel opened from More (the outline, the comments) stays open while you use More, and its row turns it off, the focus then going to the document. `EditorRoot` takes `look` (`'classic'` by default for a root you compose; the presets pass `'expressive'`), which `EditorToolbar` reads (`useEditorContext().look`); `EditorToolbar` takes `density` (`'compact'`: 36 px tools in the expressive look), `variant` (`docked`, the default, or `floating`) and `layout="wrap"` to keep every group on screen. `orientation` is `'horizontal'` (the default) or `'vertical'`, a column with Up and Down for the arrow keys, which folds what does not fit its height into the same More menu, at its bottom; `layout="page"` uses it for its rail, and you can use it in your own layout:
 

package/docs/guides/event-calendar.md

@@ -0,0 +1,163 @@
+# EventCalendar: spans, badges, tones and cancelled events
+
+`EventCalendar` (`@nxgt/material/components`) shows more than events. It can
+shade what the days themselves are (a closure, a term, a half day off), put a
+short label on a day or a week, draw an event in a tone, mark one as cancelled,
+and lock the whole schedule to reading and clicking.
+
+- [Spans](#spans)
+- [Day and week badges](#day-and-week-badges)
+- [Event tone, badges and cancelled events](#event-tone-badges-and-cancelled-events)
+- [Read-only events](#read-only-events)
+- [In each view](#in-each-view)
+- [weekStartsOn](#weekstartson)
+- [Translations](#translations)
+- [Exports](#exports)
+
+## Spans
+
+`spans` shades stretches of time behind the events. A span never blocks a slot:
+events can still be made and dropped over it.
+
+```tsx
+import { EventCalendar, type EventCalendarSpan } from '@nxgt/material/components';
+
+const spans: EventCalendarSpan[] = [
+	// Whole days: date-only values, `end` is exclusive (this is 24 December only).
+	{ id: 'closed', start: '2026-12-24', end: '2026-12-25', label: 'Closed', tone: 'warning' },
+	// A range of days.
+	{ id: 'term', start: '2026-12-28', end: '2027-01-04', label: 'Break', tone: 'info' },
+	// A half day: a value with a time is an instant.
+	{ id: 'half', start: '2026-12-23T12:00:00', end: '2026-12-24', label: 'Half day' },
+];
+
+<EventCalendar defaultEvents={events} spans={spans} timeZone="Europe/Paris" />;
+```
+
+- A date-only `start` / `end` means whole days, read in the calendar's
+  `timeZone`. `end` is always exclusive.
+- `tone` is a tone of the library (default `'neutral'`).
+- With `resources`, a span with a `resourceId` shades only its column; one with
+  none shades every column; one with an unknown id shades none.
+- The shading is a thin hatch drawn with CSS classes (no inline gradient). It is
+  `aria-hidden`, takes no pointer event and no tab stop; its label is read in
+  the name of the day or column it falls on.
+- `spans` is not a prop of `mode="template"`, which has no dates.
+
+## Day and week badges
+
+`dayBadges` and `weekBadges` are records of `{ label, tone? }` keyed by a
+`YYYY-MM-DD` date.
+
+```tsx
+<EventCalendar
+	defaultEvents={events}
+	weekStartsOn={1}
+	dayBadges={{
+		'2026-12-24': { label: 'Eve', tone: 'info' },
+		'2026-12-25': { label: 'Holiday', tone: 'warning' },
+	}}
+	weekBadges={{
+		// The key is the first day of the week, per `weekStartsOn` (a Monday here).
+		'2026-12-21': { label: 'Week 52', tone: 'neutral' },
+	}}
+/>
+```
+
+A day badge is read in the name of its day (the day header, or the month cell); a
+week badge in the name of the week's first day. Where the
+room is short (a phone's week column or month cell), a badge becomes a small
+tone bar, distinct from the event dots. Neither prop exists in `mode="template"`.
+
+## Event tone, badges and cancelled events
+
+A `CalendarEvent` takes a `tone`, several `badges` and a `status`.
+
+```tsx
+const events: CalendarEvent[] = [
+	{
+		id: 'a',
+		title: 'Planning',
+		start: '2026-12-22T09:00:00',
+		end: '2026-12-22T10:00:00',
+		tone: 'success', // a `color` still wins, then the tone, then the resource's
+		badge: { label: 'Team', tone: 'info' },
+		badges: [{ label: '2/5', tone: 'neutral' }],
+	},
+	{
+		id: 'b',
+		title: 'Review',
+		start: '2026-12-22T11:00:00',
+		end: '2026-12-22T12:00:00',
+		status: 'cancelled', // struck through, muted, dashed outline; still draggable
+	},
+];
+```
+
+A cancelled event strikes its title (`<del>`) and adds "Cancelled" to its
+accessible name, so the state is never carried by style alone. The preview
+shows such an event's title struck and named the same way (and read-only, since
+its title is not an input then). `tone` and
+`badges` work in every view and in `mode="template"`. `EventChip` takes the same
+`tone`, `badges` and `cancelled`.
+
+## Read-only events
+
+`readOnlyEvents` forbids dragging, resizing, key moves, and edits or deletes
+from the preview, for every event. Events stay focusable, clickable
+(`onEventClick`) and at full strength, and `onSlotClick` still fires.
+
+```tsx
+<EventCalendar events={events} readOnlyEvents onEventClick={(event) => open(event.id)} />
+```
+
+No drag instruction is announced. The calendar is always named "Event calendar"
+(`material.event-calendar.label`); a calendar whose events can be dragged adds
+"Drag event" (`material.event-calendar.drag`) as its description, which a
+read-only one leaves out. The preview shows no Edit or Delete button, so
+`onEventEdit` and `onEventDelete` are not offered either.
+
+## In each view
+
+| View | Spans | Day badge | Week badge | Event tone and cancelled |
+| --- | --- | --- | --- | --- |
+| Month | shades the cell, or its half for a half day; the label shows from 7rem of cell width, with a dot under it | next to the day number | on the first cell of the row, with room below its events | chip tone; struck title, dashed outline |
+| Week / workweek | hatched band under the hours with its label, and a bar in the all-day strip (a half day only the band) | in the day's header | in the gutter corner | block tone; struck title, dashed outline |
+| Day | the same as the week; with `resources`, a span shades its own column | in the day's header | in the gutter corner | the same |
+| Agenda, phone day list | a plain, non-clickable row | in the day's heading | in the week's heading | tone dot; struck title, "Cancelled" in words |
+
+## weekStartsOn
+
+`weekStartsOn` (`0` Sunday to `6`) sets the first day of the week. Besides the
+month grid, the week view starts its days on it, and a week badge's key is that
+first day: with `weekStartsOn={1}`, the Monday.
+
+This is a change: the week view used to start on the locale's first day whatever
+`weekStartsOn` said. An app that set a `weekStartsOn` unlike its locale sees its
+week view shift.
+
+## Translations
+
+| Key | English | Used for |
+| --- | --- | --- |
+| `material.event-calendar.cancelled` | Cancelled | a cancelled event's accessible name |
+| `material.event-chip.cancelled` | Cancelled | the hidden word after a cancelled `EventChip`'s title, and in the preview and the agenda row |
+| `material.event-calendar.drag` | Drag event | the description of a calendar whose events can be dragged |
+| `material.event-calendar.week-badge` | Week: {label} | a week badge, read in the name of the week's first day |
+| `material.event-calendar.title` | Title | the placeholder of the preview's title field |
+| `material.event-calendar.label` | Event calendar | the calendar's accessible name |
+
+English and French ship. Override them through the `I18nProvider`
+([i18n guide](i18n.md)).
+
+## Exports
+
+From `@nxgt/material/components`:
+
+- `EventCalendarSpan`: the shape of one entry of `spans`.
+- `EventCalendarBadges`: `Record<string, { label: string; tone?: Tone }>`, the
+  type of `dayBadges` and `weekBadges`.
+- `EventCalendarDayMarksProps`: the props `spans`, `dayBadges` and `weekBadges`,
+  for a wrapper that forwards them.
+- `CalendarEventStatus`: `'scheduled' | 'cancelled'`, the type of an event's
+  `status`.

package/docs/guides/forms.md

@@ -644,7 +644,8 @@ export function SupplierForm({ onSave }: { onSave: (values: Values) => void }) {
   a `reset()` or `setValue()`), so `defaultValues` is only the fallback while
   the form value is empty (`undefined`, `null` or `{}`). Its fields fill the row, and `hideLabel` keeps
   `label` as the group's accessible name without drawing it, under a
-  `FormSection` that already has the title.
+  `FormSection` that already has the title. `control` and `name` are typed from your
+  form (see [Attributes](../components/form-fields.md#attributes)).
 
 ### Rows a user adds and removes
 

package/docs/guides/i18n.md

@@ -227,6 +227,8 @@ The package's own strings live under one top-level namespace per language,
 either side are kept, and where both define the same leaf, **your value
 wins**.
 
+`EventCalendar`'s strings (`material.event-calendar.*`) and `EventChip`'s hidden "Cancelled" (`material.event-chip.cancelled`) are listed in the [EventCalendar guide](event-calendar.md#translations).
+
 The copy components render on their own comes from this namespace: empty
 states, dialogs, pickers, the rich-text editor's toolbar, menus, node dialogs,
 slash menu, font names and table-caption alignment

package/docs/roadmap.md

@@ -389,6 +389,18 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **EventCalendar background spans, badges, tones and cancelled events** —
+  `EventCalendar` shows what the days themselves are: `spans` draw closures,
+  half days and other labelled, toned stretches behind the events in every
+  view (a hatched band in the time views, a shaded cell or half cell in the
+  month, a non-clickable row in the agenda and phone list), `dayBadges` and
+  `weekBadges` put a short toned label on a day or a week, each event takes a
+  `tone` and several `badges` (a status, a priority, a progress count), and a
+  `status: 'cancelled'` event is struck through, muted and
+  announced as cancelled in words, and `readOnlyEvents` makes every event
+  undraggable and unresizable while it stays clickable and in full colour
+  ([guide](guides/event-calendar.md), [#2372](https://github.com/softistx/nxgt-material/issues/2372)).
+
 - **Cells driven by their value** — in `DataTable`, `ServerTable` and
   `DataGrid`, `meta.cellClassName(value, row)` computes a class per cell from
   its value; `meta.tone(value, row)` colours a cell as coloured text after a

package/lib/components/components.css

@@ -216,5 +216,6 @@
 @import "./background-shared.css";
 @import "./ui/layout/app-search/app-search.css"; /* AppSearchBar, SearchView */
 @import "./ui/widgets/drawing/drawing.css"; /* @nxgt/material/draw: role colours, focus ring */
+@import "./ui/widgets/event-calendar/event-calendar-backdrop.css"; /* EventCalendar spans: the hatch and its label */
 @import "./ui/widgets/drawing/drawing-animate.css";
 @import "./ui/widgets/barcode/barcode.css"; /* @nxgt/material/barcode: symbol colours, label sheet */

package/lib/components/ui/widgets/event-calendar/event-calendar-backdrop.css

@@ -0,0 +1,43 @@
+/* EventCalendar spans (holidays, terms, closures): the thin hatch of direction
+ * A Refined, as CSS classes (no inline gradient, so the CSP holds). The
+ * shading is decoration under the events; the label sits on an opaque pill in
+ * the tone's text colour, which keeps it AA on the hatch. The tone comes from
+ * the nearest `data-tone`. */
+@layer components {
+	.nxgt-ec-backdrop {
+		background-image: repeating-linear-gradient(
+			135deg,
+			color-mix(in oklab, var(--nxgt-tone) 42%, transparent) 0 1px,
+			transparent 1px 7px
+		);
+	}
+	.nxgt-ec-backdrop-bar {
+		box-shadow: inset 0 0 0 1px
+			color-mix(in oklab, var(--nxgt-tone) 28%, transparent);
+	}
+	.nxgt-ec-backdrop-label {
+		display: block;
+		width: fit-content;
+		max-width: 100%;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+		padding: 2px 6px;
+		border-radius: 4px;
+		border: 1px solid var(--border);
+		background: var(--card);
+		color: var(--nxgt-tone-text);
+		font-size: 11px;
+		font-weight: 500;
+		line-height: 1.2;
+	}
+	.nxgt-ec-backdrop-label-css::before {
+		content: attr(data-label);
+	}
+	.nxgt-ec-backdrop-dot {
+		width: 0.375rem;
+		height: 0.375rem;
+		border-radius: 9999px;
+		background: var(--nxgt-tone);
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "3.91.0",
+	"version": "3.93.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -390,7 +390,7 @@
 		"docs:previews": "rm -rf node_modules/.cache/nxgt-preview-free/missing && NXGT_PREVIEW_FREE=1 vitest run --project previews && bun .storybook/preview-free-report.ts"
 	},
 	"dependencies": {
-		"@nxgt/material-core": "^0.53.0",
+		"@nxgt/material-core": "^0.54.0",
 		"@base-ui/react": "^1.6.0",
 		"@dnd-kit/core": "^6.3.1",
 		"@dnd-kit/sortable": "^10.0.0",
@@ -477,7 +477,7 @@
 		"@fontsource-variable/inter": "^5",
 		"@fortawesome/fontawesome-free": "7.3.1",
 		"@nxgt/material-testing": "0.0.0",
-		"@nxgt/playwright": "^0.12.0",
+		"@nxgt/playwright": "^0.17.0",
 		"@react-leaflet/core": "^3.0.0",
 		"@react-pdf/renderer": "^4.9.0",
 		"@storybook/addon-a11y": "10.6.0",