@nxgt/material-vue 0.23.4 → 0.25.0

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

@@ -23,6 +23,7 @@ value type each one writes. Everything is imported from
 | <img src="../previews/selection-choice-selectchipfield.webp" width="96" alt=""> | [SelectChipField](#selectchipfield) | Choice shown as chips |
 | <img src="../previews/selection-choice-transferlist.webp" width="96" alt=""> | [TransferList](#transferlist) | Two-pane picker |
 | <img src="../previews/selection-choice-sortablelist.webp" width="96" alt=""> | [SortableList](#sortablelist) | Reorderable list of strings |
+| <img src="../previews/selection-choice-treeselectfield.webp" width="96" alt=""> | [TreeSelectField](#treeselectfield) | Pick from a tree, single or multiple |
 | <img src="../previews/selection-choice-switcher.webp" width="96" alt=""> | [Switcher](#switcher) | Workspace or account switcher |
 
 ## Select
@@ -105,7 +106,7 @@ const food = ref('banana');
 
 **Emits:** `update:modelValue` with the item value (`string` here). For a
 form, use `SelectField` / `SelectFormField`.
-**Storybook:** `Selection & choice/Select` · **React:** `Select` (same parts)
+**Storybook:** `Selection & choice/Select` · **React:** `Select` (same parts), `NativeSelect` (same parts)
 
 ---
 
@@ -113,7 +114,7 @@ form, use `SelectField` / `SelectFormField`.
 
 ![SelectField](../previews/selection-choice-selectfield.webp)
 
-Labelled select built from `options`.
+Labelled select built from `options`, with an `#option` slot.
 
 ```vue
 <script setup lang="ts">
@@ -142,7 +143,23 @@ const framework = ref('nuxt');
 | `required` | `boolean` | — | an asterisk after the label, and the select's `required` |
 | `label`, `helper-text`, `error`, `disabled` | | — | the field's text and state |
 
-React's `renderOption` is not in Vue: an option shows its `label`.
+`#option` renders each option's content in the list (React's
+`renderOption`); it receives `{ option, index, selected }`. The trigger shows
+the picked option's text.
+
+```vue
+<template>
+  <SelectField v-model="framework" label="Framework" :options="frameworks">
+    <template #option="{ option, selected }">
+      {{ option.label }} <small v-if="selected">current</small>
+    </template>
+  </SelectField>
+</template>
+```
+
+(with the script of the example above).
+
+`SelectFormField` passes the slot through.
 
 **Emits:** `update:modelValue` with `string`.
 **Form wrapper:** `SelectFormField` — `name` inside a vee-validate form, see
@@ -208,7 +225,7 @@ options by label. Picking the selected option again clears it.
 
 ![Autocomplete](../previews/selection-choice-autocomplete.webp)
 
-Single or multiple (chips) autocomplete with free-solo values and a query event.
+Single or multiple (chips) autocomplete typed by its options, with free-solo values, a query event and option slots.
 
 ```vue
 <script setup lang="ts">
@@ -239,23 +256,64 @@ const picked = ref<string[]>(['nuxt']);
 | --- | --- | --- | --- |
 | `mode` | `'single' \| 'multiple'` | `'single'` | decides the `v-model` type |
 | `v-model` | `string \| string[] \| null` | `null` | per `mode` |
-| `options` | `{ value: string; label: string }[]` | — | required; the items |
+| `options` | `T[]`, `T extends { value: string; label: string }` | — | required; the items, typed by your own option type |
+| `get-option-value` | `(option: T) => string` | `option.value` | the value an option stands for |
+| `get-option-label` | `(option: T) => string` | `option.label` | the text it shows and is searched by |
 | `free-solo` | `boolean` | `false` | accept a typed value that is not an option ("Add …") |
+| `free-solo-label` | `(query: string) => string` | `Add "{query}"`, translated | the free-solo button's text |
 | `@query-change` | `(query: string) => void` | — | the typed text, debounced 300 ms — fetch options here |
 | `empty` | `string` | "No option found." | text when nothing matches |
 | `required` | `boolean` | — | the asterisk, and `aria-required` on the input, which the label names |
 | `error` | `boolean` | — | red border on the box, error helper text, `aria-invalid` on the input |
 
-React's `getOptionValue` / `getOptionLabel` and `actions` are not in Vue:
-options are `{ value, label }`. In `multiple` mode each chip is a dismissible
-`Chip`: its remove button is named "Remove {label}", and is disabled with the
-field.
+It is a generic component: `T` is inferred from `options`, and the slots —
+React's render props — receive it whole:
+
+| Slot | Props | Replaces React's |
+| --- | --- | --- |
+| `#option` | `{ option: T, index, selected }` | `renderOption` |
+| `#selected-leading` | `{ option: T }` | `renderSelectedLeading` (before a chip's label) |
+| `#actions` | `{ query }` | `actions` (above the list) |
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Autocomplete } from '@nxgt/material-vue/components';
+
+type Country = { value: string; label: string; flag: string; capital: string };
+const countries: Country[] = [
+  { value: 'fr', label: 'France', flag: '🇫🇷', capital: 'Paris' },
+  { value: 'ch', label: 'Switzerland', flag: '🇨🇭', capital: 'Bern' },
+];
+const picked = ref<string[]>([]);
+</script>
+
+<template>
+  <Autocomplete
+    v-model="picked"
+    mode="multiple"
+    label="Countries"
+    :options="countries"
+    :get-option-label="(country) => `${country.label} (${country.capital})`"
+  >
+    <template #option="{ option }">{{ option.flag }} {{ option.label }}</template>
+    <template #selected-leading="{ option }">{{ option.flag }}</template>
+  </Autocomplete>
+</template>
+```
+
+The value stays the options' values (`string` or `string[]`), as in React. In
+`multiple` mode each chip is a dismissible `Chip`: its remove button is named
+"Remove {label}", and is disabled with the field. `AutocompleteFormField` is
+generic too, and passes the slots through. A generic component's ref is typed
+with `ComponentExposed`, not `InstanceType`
+([troubleshooting](../troubleshooting.md#does-not-satisfy-the-constraint-abstract-new-args-any--any)).
 
 **Emits:** `update:modelValue` with `string | null` in `single` mode,
 `string[]` in `multiple`.
 **Form wrapper:** `AutocompleteFormField` — `name` inside a vee-validate form, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Selection & choice/Autocomplete` · **React:** `Autocomplete`, `AutocompleteFormField`
+**Storybook:** `Selection & choice/Autocomplete` (stories `TypedOptions`, `FilesFormField`) · **React:** `Autocomplete`, `AutocompleteFormField`
 
 ---
 
@@ -263,35 +321,38 @@ field.
 
 ![Checkbox](../previews/selection-choice-checkbox.webp)
 
-Reka UI checkbox with an indeterminate state; pair it with a `Label`.
+Checkbox with label, helper text and an indeterminate state.
 
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue';
-import { Checkbox, Label } from '@nxgt/material-vue/components';
+import { Checkbox } from '@nxgt/material-vue/components';
 
 const receipts = ref(true);
 </script>
 
 <template>
-  <div class="flex items-center gap-2">
-    <Checkbox id="receipts" v-model="receipts" />
-    <Label for="receipts">Email me receipts</Label>
-  </div>
+  <Checkbox v-model="receipts" label="Email me receipts" helper-text="Sent after every payment." />
 </template>
 ```
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `v-model` / `default-value` | `boolean \| 'indeterminate'` | — | Reka UI checkbox state |
-| `disabled`, `required`, `name`, `value` | | — | as on a native checkbox |
+| `label` / `#label` slot | `string` | — | renders the box in a row with this label, which names and toggles it |
+| `helper-text` / `#helper-text` slot | `string` | — | a line under the label |
+| `class` | | — | the row when labelled, else the box |
+| `disabled`, `required`, `name`, `value`, `id` | | — | as on a native checkbox; a labelled box gets an id when it has none |
 
-Unlike React, `Checkbox` has no `label` / `helper-text` of its own, and there
-is no `CheckboxFormField`: bind `v-model` to a `useField` value, or use
-`CheckboxGroup` / `SwitchFormField`.
+Without `label` or `helper-text` it is the bare Reka UI box, as before: pair
+it with your own `Label`. The default slot replaces the check mark (its
+props give `state`, to draw a dash for `'indeterminate'`). Attributes such as
+`aria-*` always reach the box, not the row.
 
 **Emits:** `update:modelValue` with `boolean | 'indeterminate'`.
-**Form wrapper:** none — `useField` + `v-model`, see [forms](../guides/forms.md#the-pair).
+**Form wrapper:** `CheckboxFormField` (`name` plus the same props): an unset
+value shows as indeterminate, and an indeterminate value is written as `null`;
+the error message replaces `helper-text`. See [forms](../guides/forms.md#the-pair).
 **Storybook:** `Selection & choice/Checkbox` · **React:** `Checkbox`, `CheckboxFormField`
 
 ---
@@ -399,7 +460,7 @@ the layout wrapper): your own `aria-label` / `aria-labelledby` wins, and your
 **Emits:** `update:modelValue` with `string`.
 **Form wrapper:** `RadioGroupFormField` — `name` inside a vee-validate form, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Selection & choice/RadioGroup` · **React:** `RadioGroup`, `RadioGroupItem`, `RadioGroupFormField`
+**Storybook:** `Selection & choice/RadioGroup` · **React:** `RadioGroupField` (an alias of `RadioGroup`), `RadioGroup`, `RadioGroupItem`, `RadioGroupFormField`
 
 ---
 
@@ -612,6 +673,74 @@ The `#item` slot replaces a row's content.
 
 ---
 
+## TreeSelectField
+
+![TreeSelectField](../previews/selection-choice-treeselectfield.webp)
+
+A field that opens a `Tree` in a popover: pick one node, or several as chips,
+with an optional filter.
+
+The field is controlled only: it holds no value of its own. Bind it with `v-model`;
+without it, a pick changes nothing on screen.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { TreeSelectField, type TreeNode } from '@nxgt/material-vue/components';
+
+const regions: TreeNode[] = [
+  {
+    id: 'europe',
+    label: 'Europe',
+    children: [
+      { id: 'france', label: 'France' },
+      { id: 'spain', label: 'Spain' },
+    ],
+  },
+  { id: 'africa', label: 'Africa', children: [{ id: 'cameroon', label: 'Cameroon' }] },
+];
+
+const picked = ref<string[]>(['france']);
+</script>
+
+<template>
+  <TreeSelectField v-model="picked" label="Regions" :items="regions" multiple searchable />
+</template>
+```
+
+Single mode (no `multiple`): a pick closes the popover and the trigger shows
+the node's label. Multiple: the tree has checkboxes, and each pick is a
+dismissible `Chip` beside the trigger, its remove button named "Remove
+{label}" (`material.chip.dismiss-label`). The trigger is a `combobox`, named by
+the label, with `aria-expanded` and `aria-controls`. Opening moves focus into
+the filter, else into the tree on the pick (its branches unfolded); the tree
+keeps its own keys (arrows, Home / End, Enter / Space), ↓ from the filter
+enters it, and Escape closes the popover and hands focus back to the trigger.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `TreeNode[]` | — | required; `Tree`'s nodes: `{ id, label, icon?, trailing?, disabled?, children? }` |
+| `v-model` | `string \| null` / `string[]` | — | the picked id, or ids with `multiple` |
+| `multiple` | `boolean` | `false` | checkboxes and chips; decides the value type |
+| `searchable` | `boolean` | `false` | a filter above the tree; each match stays under its ancestors, which open |
+| `placeholder` | `string` | "Select…" | shown while nothing is picked (`material.tree-select-field.placeholder`) |
+| `search-placeholder` | `string` | "Search" | the filter's placeholder and name (`material.tree-select-field.search`) |
+| `required` | `boolean` | — | the asterisk, and `aria-required` on the `combobox` |
+| `disabled` | `boolean` | — | disables the trigger and each chip's remove button |
+| `error` | `boolean` | — | error border, error helper text, `aria-invalid` on the `combobox` |
+| `id`, `aria-describedby`, `data-*` | | — | on the trigger: the label is `for` the `id`, the description follows the helper text's |
+
+Its copy is `material.tree-select-field.*`: `placeholder`, `search`, `empty` ("No
+match found.") and `selected` ("{count} selected", the trigger's text in
+multiple mode).
+
+**Emits:** `update:modelValue` with `string | null` (single) or `string[]` (multiple).
+**Form wrapper:** `TreeSelectFormField` — `name` (and `multiple`) inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Selection & choice/TreeSelectField` · **React:** `TreeSelectField`, `TreeSelectFormField`
+
+---
+
 ## Switcher
 
 ![Switcher](../previews/selection-choice-switcher.webp)

package/docs/guides/forms.md

@@ -107,10 +107,10 @@ useForm({
 | --- | --- |
 | one input (`TextFormField`, `NumberFormField`, `SwitchFormField`, …) | its input loses focus, as a native `blur` |
 | several controls (`DateRangeFormField`, `SliderFormField` with two thumbs, `OtpFormField`, `PhoneFormField`, `TransferListFormField`, …) | focus leaves all of them; moving between them is not leaving |
-| a picker (`SelectFormField`, `DateFormField`, `TimeFormField`, `ComboboxFormField`, `CountryFormField`, …) | focus leaves the trigger **and** the popover it opened. Opening the popover, or picking in it, is not leaving; closing it hands focus back to the trigger, and the next Tab or click elsewhere is |
+| a picker (`SelectFormField`, `DateFormField`, `TimeFormField`, `ComboboxFormField`, `TreeSelectFormField`, `CountryFormField`, …) | focus leaves the trigger **and** the popover it opened. Opening the popover, or picking in it, is not leaving; closing it hands focus back to the trigger, and the next Tab or click elsewhere is |
 | a dialog editor (`PostalAddressFormField`, `ContactsFormField`, `OpeningHoursFormField`, `AttributesFormField`, and `LocationFormField` from `@nxgt/material-vue/map`) | focus leaves its buttons and the dialog they open |
 | an upload (`UploadFormField`, `NetworkUploadFormField`, `ImageFormField`, `FileListFormField` and their S3 variants) | focus leaves the drop zone and its buttons. Choosing a file in the browser's own dialog is not leaving |
-| `RichTextEditorFormField` | focus leaves the editor and its toolbar |
+| `RichTextEditorFormField`, `CodeEditorFormField` | focus leaves the editor and its toolbar |
 | `FilterFormField` | the filter is applied (or on every change, with `live-update`) — not on blur |
 
 "Opened" means named by one of the field's controls as the popup it controls
@@ -344,7 +344,7 @@ or fails validation.
 | `ColorField` · `ColorFormField` | `string` (hex, `'#1e293b'`), written when a valid colour is committed | `''` |
 | `OtpField` · `OtpFormField` | `string` of up to `length` (default 6) characters | `''` |
 | `InputGroupField` · `InputGroupFormField` | `string` | `''` |
-| `InlineEdit` | `string`, written on save only. No form wrapper: bind it with `useField` | `''` |
+| `InlineEdit` · `InlineEditFormField` | `string`, written on save only | `''` |
 | `CountryField` · `CountryFormField` | `mode="single"` (default): ISO code `string \| null` (`'FR'`). `mode="multiple"`: `string[]` | `null` / `[]` |
 | `TimezoneField` · `TimezoneFormField` | IANA `string \| null` (`'Europe/Paris'`) | `null` |
 | `RatingField` · `RatingFormField` | `number`, `0` for no rating | `0` |
@@ -372,7 +372,7 @@ or fails validation.
 | `SelectField` · `SelectFormField` | `string` (an option `value`) | `''` |
 | `ComboboxField` · `ComboboxFormField` | `string \| null`; picking the selected option again clears it | `null` |
 | `Autocomplete` · `AutocompleteFormField` | `mode="single"` (default): `string \| null`. `mode="multiple"`: `string[]` | `null` / `[]` |
-| `Checkbox` | `boolean` (`'indeterminate'` / `null` for the third state). No form wrapper: use `SwitchFormField`, or bind it with `useField` | `false` |
+| `Checkbox` · `CheckboxFormField` | `boolean`; an indeterminate value is written as `null` | `false` (see [Traps](#traps)) |
 | `CheckboxGroup` · `CheckboxGroupFormField` | `string[]` | `[]` |
 | `RadioGroupField` · `RadioGroupFormField` | `string` | `''` |
 | `CheckCardField` · `CheckCardFormField` | `boolean`: `true` for the first card, `false` for the second | `false` |
@@ -380,6 +380,7 @@ or fails validation.
 | `SelectChipField` · `SelectChipFormField` | same as `SelectCardField` | `[]` |
 | `TransferList` · `TransferListFormField` | `string[]`: the selected `value`s, in order | `[]` |
 | `SortableList` · `SortableListFormField` | `string[]`: the `value`s, in the user's order | `[]` |
+| `TreeSelectField` · `TreeSelectFormField` | `string \| null` (a node `id`). With `multiple`: `string[]`, in the order picked | `null` / `[]` |
 
 ### Media & files
 
@@ -389,8 +390,10 @@ or fails validation.
 | `S3UploadField` · `S3UploadFormField` | as above; the value is `publicUrl` from `get-presigned-url` | `undefined` / `[]` |
 | `ImageField`, `ImageS3Field` · `ImageFormField`, `ImageS3FormField` | `string \| undefined` (the uploaded URL) | `undefined` |
 | `FileListField`, `FileListS3Field` · `FileListFormField`, `FileListS3FormField` | `string[]` | `[]` |
+| `FilesFormField` | `mode="single"`: `string \| null`. `mode="multiple"`: `string[]` (typed or picked URLs) | `null` / `[]` |
 | `UploadField` · `UploadFormField` | a `File`, or `File[]` with `multiple`. Nothing is uploaded | `undefined` / `[]` |
 | `RichTextEditor` · `RichTextEditorFormField` | `string`: the editor's HTML | `''` |
+| `CodeEditor` · `CodeEditorFormField` | `string`: the source | `''` |
 | `LocationField` · `LocationFormField` (from `@nxgt/material-vue/map`) | `[lat, lng]`, rounded to 7 decimals | `null` |
 
 An upload field emits a **string** because it uploads as soon as a file is
@@ -399,10 +402,6 @@ dropped: the form holds where the file went, never the file.
 handler sends it (with `convertToFormData` from `@nxgt/material-vue/lib`,
 for example).
 
-Not in `@nxgt/material-vue`: `FilesFormField` (use `NetworkUploadFormField`
-or `FileListFormField`) and `CheckboxFormField` / `InlineEditFormField` (see
-the rows above).
-
 ## Composite values
 
 A composite field edits a structured value through its own dialog. The form
@@ -947,6 +946,15 @@ Type the schema as an array:
 z.object({ plan: z.array(z.string()).length(1, { error: 'Pick a plan' }) });
 ```
 
+**A checkbox with no initial value is indeterminate.** `CheckboxFormField`
+renders `undefined` as the indeterminate state (and writes `null` for it), as
+in `@nxgt/material`. A `validationSchema` alone gives it no initial value.
+Give it a boolean:
+
+```ts
+useForm({ initialValues: { terms: false } });
+```
+
 **A field re-mounted on every render loses its state.** A `:key` that changes
 on each render (`:key="Math.random()"`) mounts a new field every time: focus,
 the `PhoneField` draft and the `NumberField` text are lost as you type, and

package/docs/guides/i18n.md

@@ -280,14 +280,18 @@ checkboxes, the filter's presets and `Min`/`Max` fields, the `variant="4"` spinn
 `You are here` and zoom buttons, and the close button of dialogs, sheets and
 `DialogFooter`. 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`), a `Chip`'s remove button, which the
+(`material.table.labels.toggle-row`), its loading status, "Loading data…" /
+"Chargement des données…" (`material.table.loading`), a `Chip`'s remove button, which the
 `Autocomplete` chips use ("Remove {label}", `material.chip.dismiss-label`),
 the `LocationPreview` trigger (`material.map.preview` / `preview-named`),
 `DurationField`'s inputs, "Hours" and "Minutes"
 (`material['duration-field']['hours-label']` / `minutes-label`), and
 the delete button of the deprecated `ContactItem` / `OpeningHoursItem`
 (`material.contacts.buttons.remove`,
-`material['opening-hours'].buttons.remove`). The keys and the French are the
+`material['opening-hours'].buttons.remove`). When the form of a
+`ConfirmationDialog` with `form-options` cannot be loaded, it says so in the
+form's place: "The form could not be loaded." / "Le formulaire n’a pas pu être
+chargé." (`material.confirm-dialog.form-failed`). The keys and the French are the
 same in `@nxgt/material`, so one set of overrides fits both. Text you pass yourself always wins over the
 translation: a `label`, an `aria-label` on `Spinner`, `ScrollToTop`,
 `CalendarPrevButton` or `CalendarNextButton`, and `LocationMarker`'s
@@ -298,7 +302,10 @@ names and text, which reka-ui left in English (`material.pagination.first`,
 `previous`, `next`, `last`, `page`, and `more` for the ellipsis), and the
 `aria-label` of `Pagination` and `Breadcrumb` and the breadcrumb ellipsis's
 "More" (`material.pagination.label`, `material.breadcrumb.*`), and
-`DocHeader`'s breadcrumb (`material.doc.breadcrumb`); `CommandDialog`'s
+`DocHeader`'s breadcrumb (`material.doc.breadcrumb`); the status a `Stepper`
+step announces after its title, "Completed" or "Error"
+(`material.stepper.completed` / `error`, "Terminée" / "Erreur" in French);
+`CommandDialog`'s
 default title and description (`material.command.*`); the carousel's
 `aria-roledescription` (`material.carousel.roledescription` / `slide`); the
 filter's empty state and `+N more` chip (`material.filter.empty` / `more`) and
@@ -319,10 +326,47 @@ buttons (`material['rich-text-editor'].placeholder` / `insert-emoji`);
 (`material['circular-progress'].label`); `StxPlayer`'s "Media player" for a
 track without a title (`material['stx-player'].label`); `PaneLayoutPane`'s
 sheet title on a phone (`material['pane-layout']['sheet-title']`);
-`JsonViewer`'s "Empty JSON" (`material['json-viewer'].empty`); and
+`JsonViewer`'s "Empty JSON" (`material['json-viewer'].empty`);
 `TimePicker`'s AM/PM (`material['time-picker'].am` / `pm`, "a.m." / "p.m." in
-French). Your `placeholder`, `sheetTitle`, `title`, `description` and
-`aria-label` still win.
+French). `TreeSelectField`'s placeholder, search box, empty message and
+"{count} selected" follow the language too (`material['tree-select-field'].placeholder` /
+`search` / `empty` / `selected`; in French `selected` is an ICU plural,
+`{count, plural, …}`); the `placeholder` and `search-placeholder` props take
+precedence over them. Your `placeholder`, `sheetTitle`, `title`, `description`
+and `aria-label` still win. The names of
+`TimePicker`'s inputs read `material.time-picker.hours` and
+`material.time-picker.minutes` ("Hours" / "Minutes", "Heures" / "Minutes").
+`DateRangeField`'s preset list is a group named by
+`material.date-range-field.presets` ("Presets", "Plages prédéfinies"); its
+built-in presets read `material.date-range-field.preset.today`,
+`material.date-range-field.preset.yesterday`,
+`material.date-range-field.preset.last-7-days`,
+`material.date-range-field.preset.last-30-days`,
+`material.date-range-field.preset.this-month`,
+`material.date-range-field.preset.last-month` and
+`material.date-range-field.preset.this-year` ("Today", "Yesterday", "Last 7
+days", "Last 30 days", "This month", "Last month", "This year"; "Aujourd’hui",
+"Hier", "7 derniers jours", "30 derniers jours", "Ce mois-ci", "Le mois
+dernier", "Cette année"), and with times its two groups
+`material.date-range-field.start-time` and `material.date-range-field.end-time`
+("Start time" / "End time", "Heure de début" / "Heure de fin"); its OK button
+reads `material.buttons.ok`. The label of a preset of your own is yours.
+`FilePreview`'s figure is named by `material.file-preview.label` ("Preview
+of {name}", "Aperçu de {name}"), with `material.file-preview.untitled`
+("Untitled file", "Fichier sans nom") as the name of a file that has none; it
+reads `material.file-preview.loading` ("Loading preview…", "Chargement de
+l’aperçu…") while it reads the file, `material.file-preview.error` ("This
+file could not be previewed.", "Impossible d’afficher l’aperçu de ce
+fichier.") when it cannot show it, `material.file-preview.download`
+("Download", "Télécharger") on its download link, and
+`material.file-preview.truncated` ("Showing the first {size} of this file.",
+"Seuls les premiers {size} de ce fichier sont affichés.") under a text cut
+by the size cap; the text or Markdown it shows scrolls in a region named by
+`material.file-preview.content` ("Contents of {name}", "Contenu de {name}").
+`material.slider.value` / `minimum` / `maximum`
+("Value", "Minimum", "Maximum") are there for `@nxgt/material`'s editable
+`Slider` readout inputs (this package's readout is text), so the bundles hold
+the same keys.
 
 To format filter values yourself in the provider's language, pass
 `formatFilterValue` the same words `FilterChips` uses (`FilterValueWords`; the

package/docs/guides/ssr.md

@@ -42,12 +42,14 @@ at import time would crash the server before it answers anything.
   | --- | --- |
   | `PdfReader`, `PdfSidebar`, `PdfPageList`, `PdfThumbnailSidebar` | `pdfjs-dist` runs `new DOMMatrix()` when it is imported |
   | `CodeEditor`, `CodeDiff` | Monaco |
+  | `CodeEditorFormField` | it renders `CodeEditor`, whose Monaco is client-only |
   | `Camera` | `getUserMedia` |
   | `StxPlayer` | media element APIs |
   | the charts (`BarChart`, `AreaChart`, `HeatmapChart`, …) | ECharts draws on a canvas it sizes from the DOM |
   | `ImageCropper` (its canvas) | canvas cropping |
   | `RichTextEditor` (its editor) | Tiptap / ProseMirror |
   | mermaid diagrams inside `Markdown` | mermaid renders in the browser; the rest of the Markdown renders on the server |
+  | `MermaidDiagram` | the same mermaid chart on its own, rendered in the browser |
 
 - **The map entry is importable, but draws in the browser only.**
   `@nxgt/material-vue/map` is its own entry because `leaflet` and

package/docs/roadmap.md

@@ -6,7 +6,22 @@ the version something shipped in.
 
 ## Now
 
-Nothing in progress right now; see Next.
+- **TreeSelectField** — pick one or several items from a tree inside a form
+  field, as chips when several, with an optional filter that keeps each match
+  under its ancestors (`TreeSelectField`, `TreeSelectFormField`).
+- **The same options as `@nxgt/material`** — a generic `Autocomplete` and
+  `FilesFormField` typed by your items, a `ConfirmationDialog` that holds a
+  form, date fields that disable chosen days, `SliderField` ticks and
+  leading/trailing content, a presence status on `Avatar`, a logo slot on the
+  QR code, slots on `AccordionCard`, an option slot on `SelectField`, Monaco's
+  own options on `CodeEditor` and a line variant for `Tabs`.
+- **DateRangeField presets and time** — one-click ranges such as Today, Last 7
+  days and This month, or your own, beside the calendar (`presets`), and a time
+  of day on each end of the range (`with-time`), and `min-date` / `max-date`.
+- **FilePreview** — preview a file picked by its type, in one component: an
+  image, a PDF in `PdfReader`, a video or audio file, the text of a text, JSON,
+  CSV or Markdown file, or a card with a download link for anything else
+  (`FilePreview`, `@error`). Safe on a server.
 
 ## Next
 
@@ -14,6 +29,8 @@ Nothing in progress right now; see Next.
   their table header on every printed page, keep rows and totals whole, print
   their colours, and a `PrintPage` sets size and margins for `window.print()`.
   Vue only: `@nxgt/material`'s print blocks already produce a PDF.
+- **`StepperIndicator`, as in `@nxgt/material`** — the step markers on their
+  own, for a stepper laid out your way.
 
 ## Later
 
@@ -53,6 +70,8 @@ Nothing in progress right now; see Next.
 
 ## Not planned
 
+- **The `Combobox` primitive family** — `ComboboxFormField` covers forms; the
+  low-level `Combobox` parts stay in `@nxgt/material` only.
 - **The React library's state and form stacks** — widgets keep their state in
   per-instance Pinia stores (`defineLocalStore`), forms use vee-validate, the
   primitives Reka UI, the charts ECharts through `vue-echarts`, and routing
@@ -88,6 +107,33 @@ Nothing in progress right now; see Next.
 
 ## Shipped
 
+- **Spinner `light` colour renders** — a `Spinner` with `color="light"` shows
+  its light ring, for loading states on dark or coloured surfaces. 0.24.0.
+- **Range filters announce their field name** — the slider thumbs and the
+  `Min`/`Max` inputs of a `slider-range` or `number-range` filter are named
+  after the field, so a screen reader says which range is changing. 0.24.0.
+- **Alert keeps long content inside** — a long title, description or unbroken
+  string wraps inside the `Alert` instead of running past its edge. 0.24.0.
+- **Slider thumb follows the theme in dark mode** — the `Slider` thumb takes
+  the dark theme's colours instead of staying light. Vue only. 0.24.0.
+- **Stepper: unique ids, announced steps and truncated titles** — two steppers
+  on one page no longer share ids, a screen reader hears which step is current
+  and whether each is done or in error, and a long step title truncates. 0.24.0.
+- **Layouts that hold long content** — `ListTile`, `StatCard` and `Banner`
+  keep long titles, values and actions inside their box instead of overflowing.
+  0.24.0.
+- **The same exports as `@nxgt/material`** — a `Checkbox` with its own
+  `label` and `helper-text` (the bare box is unchanged) and
+  `CheckboxFormField`, `InlineEditFormField`, `CodeEditorFormField`,
+  `PaginationBar` with `paginationItems` and `PaginationLink`, `CopyValue`,
+  `MermaidDiagram`, and the `Doc` parts `DocArticle`, `DocNav`, `DocLink`,
+  `DefaultDocLink` and `DocCopyPage`, under the names they have in React.
+  0.24.0.
+  ([forms](guides/forms.md#what-each-field-emits))
+- **DataTable loading and empty states** — skeleton rows while the data loads
+  (the rows already shown stay in place, dimmed, during a refresh), the table
+  announced as busy, and your own content when there are no rows, told
+  whether a filter emptied it. 0.24.0.
 - **One copy of the framework-free code, shared with `@nxgt/material`** —
   the PDF document model and renderer, the print formatters, the PDF file
   helpers, `PdfReader`'s page geometry, scroll spy and search, the