@nxgt/material 3.92.0 → 3.94.0

package/docs/components/form-fields.md

@@ -15,6 +15,7 @@ for the value type each one writes. Everything is imported from
 | <img src="../previews/form-fields-choicelistfield.webp" width="96" alt=""> | [ChoiceListField](#choicelistfield) | An editable list of answer choices with correct marks |
 | <img src="../previews/form-fields-textfield.webp" width="96" alt=""> | [TextField](#textfield) | Labelled input with adornments and helper text |
 | <img src="../previews/form-fields-textareafield.webp" width="96" alt=""> | [TextareaField](#textareafield) | Labelled textarea with row sizing and a counter |
+| <img src="../previews/form-fields-markdowntextareafield.webp" width="96" alt=""> | [MarkdownTextareaField](#markdowntextareafield) | Textarea for Markdown and math with a Write / Preview tab list |
 | <img src="../previews/form-fields-emailfield.webp" width="96" alt=""> | [EmailField](#emailfield) | Validates on blur, `mailto:` button |
 | <img src="../previews/form-fields-passwordfield.webp" width="96" alt=""> | [PasswordField](#passwordfield) | Show / hide toggle and a strength meter |
 | <img src="../previews/form-fields-numberfield.webp" width="96" alt=""> | [NumberField](#numberfield) | `number \| null` with clamping and +/− buttons |
@@ -333,8 +334,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 +404,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 +417,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 +458,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.
@@ -500,6 +525,44 @@ stores `string`.
 
 ---
 
+## MarkdownTextareaField
+
+![MarkdownTextareaField](../previews/form-fields-markdowntextareafield.webp)
+
+Textarea for Markdown and KaTeX math with a **Write / Preview** tab list, the
+usual label, helper text, error and `maxLength` counter, and a collapsed
+formatting help (bold, list, code, `$…$`, `$$…$$`, escaping `\$`). The preview
+is rendered by [`Markdown`](./data-display.md#markdown); raw HTML is never rendered.
+
+```tsx
+import { MarkdownTextareaField, MarkdownTextareaFormField } from '@nxgt/material/components';
+
+<MarkdownTextareaField label="Prompt" maxLength={4000} helperText="Markdown and $math$." />
+
+<MarkdownTextareaFormField control={control} name="prompt" label="Prompt" maxLength={4000} />
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `minRows` | `number` | `6` | minimum height of the textarea and the preview, in lines |
+| `maxLength` | `number` | — | shows an `n/max` counter, red when over |
+| `showCount` | `boolean` | `true` when `maxLength` is set | force the counter on or off |
+| `math` | `boolean` | `true` | render `$…$` and `$$…$$` in the preview |
+| `mermaid` | `boolean` | `false` | draw ```` ```mermaid ```` fences in the preview |
+| `showHelp` | `boolean` | `true` | the formatting help under the field |
+| `previewClassName` | `string` | — | class of the preview panel |
+| `error` | `boolean` | — | error outline and helper colour |
+
+The Write / Preview toggle is a `tablist` (arrow keys move between the tabs);
+the textarea stays mounted while Preview shows. Text labels use the
+`material.markdown-textarea-field.*` i18n keys.
+
+**Emits:** the native `ChangeEvent<HTMLTextAreaElement>`; `MarkdownTextareaFormField`
+stores `string`.
+**Form wrapper:** `MarkdownTextareaFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/MarkdownTextareaField` · **Vue:** none yet
+
 ## EmailField
 
 ![EmailField](../previews/form-fields-emailfield.webp)
@@ -1753,7 +1816,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 +1839,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/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)
 
 ---
 
@@ -2781,8 +2834,37 @@ French bundle — see [i18n](../guides/i18n.md).
 | `QuestionCard` `preview` | `boolean` | `false` | an author's preview, `<QuestionCard question={q} preview />`: forces `revealed` and `readOnly`, drops `onValueChange`, and shows the marks (the `question.correct` options marked, the expected text or number filled in) and the `explanation`, with no verdict banner. `verdict` and `showFeedback` are always ignored in a preview; `value` is ignored when the question has a `correct` — an `open` or `code` question has none, so pass its reference answer as `value`. Not for a learner's attempt |
 | `QuestionCard` `readOnly` / `busy` | `boolean` | `false` | `readOnly`: an answer already submitted, shown without the revealed marks; `busy`: read-only and `aria-busy` while it is saved; every kind honours both |
 | new strings | `material.education.kind-open`, `kind-code`, `code-placeholder` | — | English fallbacks and a French bundle |
+| `Question` `markdown` | `boolean` | `false` | draws the `prompt`, the string option labels, `explanation`, option explanations and hints as Markdown with math (`$x^2$`), through the safe `Markdown` (raw HTML is not rendered, mermaid off). The prompt, option labels and the verdict's "Correct answer" use an inline form (paragraph unwrapped, no lists or headings) so the HTML stays valid in a `<legend>` or a label; explanations and hints keep blocks |
+| `Question` `hints` | `string[]` | — | revealed one at a time behind a "Show hint 1 of N" button; the focus moves to the hint just shown and the hint's name is "Hint 1 of N" (one announcement). Hidden once revealed. The single `hint` is deprecated (kept: a Show / Hide toggle), ignored when `hints` is set |
+| `QuestionOption` `explanation` | `string` | — | why this option is right or wrong; a list "About each answer" under the card once revealed or in a `preview` |
+| `Question` `references` | `{ title: string; url?: string }[]` | — | a labelled "References" list once revealed or in a `preview`; a safe `url` is a link, an external one with `rel="noopener noreferrer"` |
+| `Question` `kind: 'code'` | `starterCode?`, `examples?: { input, expected }[]` | — | `starterCode` fills the field while there is no draft (`value` null or undefined; an empty string is a draft), it reaches `onValueChange` on the first edit only; `examples` is a table (Input, Expected) above the field |
+| new strings | `material.quiz.rich.*` | — | English fallbacks and a French bundle (React only for now) |
 | `QuestionCard` `variant` / `density` / `showShortcuts` / `number` / `showFeedback` | — | `'card'`, `'comfortable'`, `false`, —, `true` | framed or plain, spacing, key badges, "Question 2", the verdict banner (for a card with marks and no banner, use `preview`) |
 
+A quiz question with Markdown, math, progressive hints and references:
+
+```tsx
+<QuestionCard
+  question={{
+    id: 'q1',
+    kind: 'choice',
+    markdown: true,
+    prompt: 'Solve $2x + 6 = 14$',
+    options: [
+      { id: 'a', label: '$x = 4$', explanation: 'Subtract 6, then divide by 2.' },
+      { id: 'b', label: '$x = 10$', explanation: 'You added 6 instead.' },
+    ],
+    correct: 'a',
+    hints: ['Isolate $x$.', 'Subtract 6 from both sides.'],
+    references: [{ title: 'Linear equations', url: 'https://example.org/linear' }],
+  }}
+  value={value}
+  onValueChange={setValue}
+  revealed={checked}
+/>
+```
+
 An open answer and a code answer, with the code editor from its own subpath
 (it is client-only, so load it lazily in an SSR app):
 

package/docs/guides/csp.md

@@ -38,7 +38,7 @@ Components outside this table need nothing more. Measured per component:
 | --- | --- | --- |
 | `PdfReader` | `worker-src 'self'` (the worker is a file of the package), `connect-src` for the PDF's and the assets' origins, and `script-src 'wasm-unsafe-eval'` for the JPEG 2000 and ICC WebAssembly decoders (without it: a JavaScript fallback for JPEG 2000, device colours for ICC profiles) | worker checked in the same Playwright run (Vite production build under `worker-src 'self'`), the rest read from pdf.js's code: [PDF reader guide](pdf-reader.md#content-security-policy) |
 | `CodeEditor`, `CodeDiff` (Monaco) | `@monaco-editor/react` loads Monaco from `https://cdn.jsdelivr.net/npm/monaco-editor@…/min/vs` by default: that host in `style-src-elem` (Monaco's CSS) and `font-src` (its icon font), plus `worker-src blob:` | not yet verified in a browser. Safe default: allow `https://cdn.jsdelivr.net` in `script-src`, `style-src-elem` and `font-src`, and `worker-src blob:`; or stay on `'self'` by [serving Monaco yourself](#monaco-on-self) |
-| `Markdown` (maths, mermaid, code) | nothing beyond the policy above, in a client render | checked in Chromium under that policy with `style-src-attr 'none'`, no `img-src data:` and no `'unsafe-eval'`: [Markdown under a strict CSP](#markdown-katex-mermaid-and-code-under-a-strict-csp) |
+| `Markdown` (maths, mermaid, code) | nothing beyond the policy above, on the server or the client (math needs `NonceProvider`); mermaid's mindmap and architecture diagrams still add an un-nonced `<style>` | checked in Chromium under that policy with `style-src-attr 'none'`, no `img-src data:` and no `'unsafe-eval'`: [Markdown under a strict CSP](#markdown-katex-mermaid-and-code-under-a-strict-csp) |
 | `RichTextViewer` (`@nxgt/material/editor/viewer`) | none, but it emits `style` attributes: a text colour, a highlight, a text alignment or a table cell's background in the saved document becomes an inline `style` (only allow-listed properties with plain values survive), so a page that shows such a document needs `style-src-attr 'unsafe-inline'`. A document with none sends no style | measured by reading the renderers; a strict `style-src-attr 'none'` page shows the document without those colours |
 | `Camera` | none: `getUserMedia` is not governed by CSP; the captured photo is a `data:` image | `media-src` for the live preview is not yet verified. Safe default: `media-src 'self' blob:` (a `srcObject` stream usually needs nothing) |
 | `MediaPlayer` with `hlsStreaming()` | `connect-src` and `media-src blob:` for the stream; `worker-src blob:` only with `config: { enableWorker: true }` (the adapter defaults to no worker) | see the [streaming guide](media-streaming.md#content-security-policy) |
@@ -211,6 +211,7 @@ mermaid and pdf.js's font fallback are the [known gaps](#known-gaps).
 | `Spinner` (variant `4`), `PdfReader` (search highlights, night mode) | nothing | their rules are in the stylesheet (`spinner.css`, `pdf-viewer.css`) |
 | `Progress`, `CircularProgress` | nothing | the server draws SVG percentages, SMIL and path data, and the rules are in the stylesheet (`progress.css`); no `style` attribute |
 | `ScrollArea`, `Select` (Radix) | the nonce | Radix renders a `<style>` element with `NonceProvider`'s nonce: wrap the app in [`NonceProvider`](#nonceprovider) |
+| `Markdown` (math) | the nonce | one `<style>` of `mk-` rules replacing KaTeX's `style` attributes, with `NonceProvider`'s nonce |
 | `RichTextEditor` (tiptap) | the nonce | tiptap, on mount, with `NonceProvider`'s nonce as `injectNonce` |
 | `Dialog`, `AlertDialog`, `Sheet`, `ConfirmationDialog`, … (Radix scroll lock) | the nonce | react-style-singleton, when a modal opens: see below |
 
@@ -278,8 +279,17 @@ the page carry the nonce in its meta tag).
   (`data-scheme`), and `maxHeight` is a custom property written through the
   CSSOM in a layout effect (a server-rendered block is full height until
   hydration).
-- **KaTeX**: on a client render React writes its styles through the CSSOM.
-  Its fonts are files ([KaTeX fonts](#katex-fonts)).
+- **KaTeX**: its markup carries inline `style="…"` attributes (offsets,
+  heights, widths), which `style-src-attr 'none'` blocks on a server render
+  (hydration does not rewrite them). `Markdown` turns each into a class
+  (`mk-<hash>`, one per distinct declaration list, the same on the server and
+  the client) and appends one `<style>` with the rules, given the nonce of the
+  nearest `NonceProvider`: `style-src-elem 'nonce-…'` allows it, and the
+  formula is laid out as before, with server and client rendering the same
+  markup. So `NonceProvider` is required for math under a nonce policy
+  (without it the `<style>` has no nonce and is blocked); a declaration that
+  is not a plain `property:value` is dropped, never copied to the sheet. Its
+  fonts are files ([KaTeX fonts](#katex-fonts)).
 - **Mermaid**: the diagram stays an image, now from a `blob:` URL (revoked when
   the diagram goes), so the SVG's own `<style>` and `style` attributes live in
   the image and the page needs neither `data:` nor `style-src-attr` for them.
@@ -293,11 +303,13 @@ the page carry the nonce in its meta tag).
   each is a pass-through once the last render ends and is restored only if
   no other script patched it since). Unrelated calls, such as an editor
   parsing HTML, are left alone.
-- **Left**: a page whose HTML the server renders with math carries KaTeX's
-  `style="…"` attributes in the markup, which `style-src-attr 'none'` blocks
-  (the formula loses its spacing until `style-src-attr 'unsafe-inline'`, or a
-  client-only render of the `Markdown`). Mermaid's mindmap and architecture
-  diagrams add a `<style>` to `<head>` ([known gaps](#known-gaps)).
+- **Left**: mermaid's mindmap and architecture diagrams (cytoscape) add a
+  `<style>` to `<head>` with no nonce, which `style-src-elem 'nonce-…'` blocks:
+  the diagram still draws, without that sheet's rules. The classes mechanism
+  above does not reach it; allow that element (a hash of the sheet, or
+  `style-src-elem 'unsafe-inline'`) only if you show those two diagram types
+  ([known gaps](#known-gaps)). Flowcharts, sequence and the other types are
+  checked and need nothing.
 
 ### Known gaps
 

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

@@ -490,6 +490,7 @@ or fails validation.
 | --- | --- | --- |
 | `TextField` · `TextFormField` | `string`. With `type="number"`: `number \| null` | `''` |
 | `TextareaField` · `TextareaFormField` | `string` | `''` |
+| `MarkdownTextareaField` · `MarkdownTextareaFormField` | `string` (Markdown source) | `''` |
 | `EmailField` · `EmailFormField` | `string` (as typed; the field shows its own "Enter a valid email" hint on blur) | `''` |
 | `PasswordField` · `PasswordFormField` | `string` | `''` |
 | `NumberField` · `NumberFormField` | `number \| null`. `null` when cleared; clamped to `min` / `max` on blur | `null` |
@@ -644,7 +645,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
@@ -245,7 +247,7 @@ until the bar is drawn), the `ThreadLayout` stepper's `nav` name `material.navig
 single value's input, when nothing names the slider, `material.slider.value`
 ("Value", "Valeur"). `CopyButton` reads `material.copy.copy`, `copied` and `failed` ("Copy", "Copied",
 "Copy failed"). An overflowing `TabsList`'s scroll buttons read
-`material.tabs.scroll-left` / `scroll-right` ("Scroll tabs left" / "Scroll tabs right"). The other icon-only buttons are named from it too: the
+`material.tabs.scroll-left` / `scroll-right` ("Scroll tabs left" / "Scroll tabs right"). `QuestionCard`'s rich content reads `material.quiz.rich.*` (the hint button and names "Show hint 1 of 3" / "Hint 1 of 3", "About each answer", "References", "Examples" with its Input / Expected headers). The other icon-only buttons are named from it too: the
 `Sidebar` toggle (`material.sidebar.toggle`), the data table's row expander
 (`material.table.labels.toggle-row`) and its header, a hidden "Expand" / "Déplier"
 (`material.table.labels.expand`), its loading status, "Loading data…" /

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