@nxgt/material 2.5.0 → 2.6.0

package/docs/components/date-and-time.md

@@ -105,7 +105,7 @@ calendar is labelled by the trigger, so named by the label.
 **Emits:** `Date | undefined`.
 **Form wrapper:** `DateFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Date & time/DateField` · **Vue:** `DateField`, `DateFormField`
+**Storybook:** `Date & time/DateField` · **Vue:** `DateField`, `DateFormField` (`disabled-days`, same rules)
 
 ---
 
@@ -113,7 +113,7 @@ calendar is labelled by the trigger, so named by the label.
 
 ![DateRangeField](../previews/date-time-daterangefield.webp)
 
-From / to range picked in a popover calendar.
+From / to range picked in a popover calendar, with presets and times.
 
 ```tsx
 import { type DateRange, DateRangeField } from '@nxgt/material/components';
@@ -128,10 +128,13 @@ export function Stay() {
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `value` | `DateRange` | — | `{ from: Date \| undefined; to?: Date }` |
-| `onValueChange` | `(value?: DateRange) => void` | — | called on each click: `to` is unset after the first |
+| `onValueChange` | `(value?: DateRange) => void` | — | called on each click: after the first, `to` is the same day as `from` |
 | `placeholder`, `label`, `helperText`, `error`, `required` | | — | `placeholder` is the trigger's text; `label` and `helperText` sit beside it; `error` and `required` its state |
 | `disabled` | `boolean` | — | disables the field: the trigger cannot be focused or opened |
 | `disabledDays` | react-day-picker's `Matcher \| Matcher[]` | — | days that cannot be picked (the calendar's `disabled`) |
+| `presets` | `readonly DateRangePresetOption[]` | — (no list) | one-click ranges beside the calendar: built-in ids (`DATE_RANGE_PRESET_IDS`) and `{ label, range }` of your own |
+| `withTime` | `boolean` | `false` | a time of day on each end, under the calendar, and on the trigger; the popover stays open until OK |
+| `minDate`, `maxDate` | `Date` | — | the first and last day that can be picked (the calendar's, as are `disablePast` / `disableFuture`) |
 
 Every other `Calendar` prop is passed to the calendar; it opens on the
 month of `value.from`. `id`, `aria-describedby` and `data-*` attributes go on
@@ -148,11 +151,103 @@ trigger in the field's root `div` (`data-slot="date-range-field"`, which takes
 rendered alone, shows only the value: use the field for the label and the
 helper text. The open calendar is labelled by the trigger.
 
-**Emits:** `DateRange | undefined` — `{ from, to }`, where `to` stays
-`undefined` until the second day is picked.
+### Presets
+
+`presets` lists one-click ranges beside the calendar (above it on a narrow
+screen), in the order you give them. A built-in id is translated
+(`material.date-range-field.preset.<id>`); a preset of your own is
+`{ label, range }`, where `range` is `{ from, to }` or `(now) => ({ from, to })`.
+
+```tsx
+import {
+	type DateRange,
+	DateRangeField,
+	type DateRangePreset,
+} from '@nxgt/material/components';
+import { useState } from 'react';
+
+const lastQuarter: DateRangePreset = {
+	label: 'Last quarter',
+	range: (now) => {
+		const start = new Date(now.getFullYear(), Math.floor(now.getMonth() / 3) * 3 - 3, 1);
+		return { from: start, to: new Date(start.getFullYear(), start.getMonth() + 3, 0) };
+	},
+};
+
+export function Report() {
+	const [period, setPeriod] = useState<DateRange | undefined>();
+	return (
+		<DateRangeField
+			label="Period"
+			value={period}
+			onValueChange={setPeriod}
+			maxDate={new Date()}
+			presets={['today', 'last-7-days', 'this-month', 'last-month', lastQuarter]}
+		/>
+	);
+}
+```
+
+| Built-in id | Range |
+| --- | --- |
+| `today`, `yesterday` | that day |
+| `last-7-days`, `last-30-days` | ends today and counts it |
+| `this-month`, `this-year` | from the first day to today |
+| `last-month` | the whole previous month |
+
+A built-in range starts at 00:00 (and with `withTime` ends at 23:59); your
+own ranges keep the times you gave them. Picking a preset sets the value and
+closes the popover (with `withTime` it stays open); open again, the calendar
+is on that range's month. The list is a group named "Presets"
+(`material.date-range-field.presets`) of buttons in the tab order, and the
+one whose days are the value's has `aria-pressed="true"`. A preset is
+disabled when its range starts before `minDate`, ends after `maxDate`, or
+either end is one of `disabledDays`; the days between are not checked, as the
+calendar lets a range span a disabled day.
+The built-in presets use the current date when the popover opens; there is
+no `now` prop, and none is planned. A preset of your own whose end comes
+before its start is disabled.
+
+### Times
+
+`withTime` adds two `TimePicker`s under the calendar, in groups named
+"Start time" and "End time" (`material.date-range-field.start-time`,
+`.end-time`), each disabled until its end has a day, and an OK button
+(`material.buttons.ok`) that closes the popover. The trigger shows each end
+with its time (date-fns `Pp`).
+
+```tsx
+import { type DateRange, DateRangeField } from '@nxgt/material/components';
+import { useState } from 'react';
+
+export function Booking() {
+	const [slot, setSlot] = useState<DateRange | undefined>();
+	return (
+		<DateRangeField
+			label="Booking"
+			value={slot}
+			onValueChange={setSlot}
+			withTime
+			presets={['today']}
+		/>
+	);
+}
+```
+
+A day picked on the calendar keeps the time that end had; a new start is
+00:00 and a new end 23:59, as a built-in preset ends, so a filter on
+`<= to` keeps the last day. On the same day, an end time set before the
+start time becomes the start time.
+
+Without `withTime`, a picked day is at 00:00. (`@nxgt/material-vue` gives
+it the current time of day.)
+
+**Emits:** `DateRange | undefined` — `{ from, to }`, where the first day
+picked is both `from` and `to` (react-day-picker's `addToRange`) until the
+second day is picked.
 **Form wrapper:** `DateRangeFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Date & time/DateRangeField` · **Vue:** `DateRangeField`, `DateRangeFormField`
+**Storybook:** `Date & time/DateRangeField` (stories `DisabledDays`, `MinMaxDates`, `Presets`, `DisabledPresets`, `WithTime`) · **Vue:** `DateRangeField`, `DateRangeFormField` (`disabled-days`, `presets`, `with-time`, `min-date` / `max-date`; without time, a picked day carries the current time of day there, 00:00 here)
 
 ---
 
@@ -235,6 +330,11 @@ export function Clock() {
 | `label` | `ReactNode` | — | header text |
 | `footer` | `ReactNode` | — | under the inputs (the OK button in `TimeField`) |
 
+The hours and minutes inputs are named "Hours" and "Minutes"
+(`material.time-picker.hours`, `.minutes`). AM / PM shows the half of the day
+`date` is in, so a date changed from outside shows its own; switching it moves
+the time 12 hours, and a click on the pressed half changes nothing.
+
 **Emits:** `Date | undefined`. No form wrapper — use `TimeFormField`.
 **Storybook:** `Date & time/TimePicker` · **Vue:** `TimePicker`
 

package/docs/components/feedback-and-status.md

@@ -227,7 +227,7 @@ built on `AlertDialog`, so it does not close on an outside click. Put
 `AlertDialogCancel` / `AlertDialogAction` in its `footer`.
 
 **Storybook:** `Feedback & status/ConfirmDialog`, `Feedback & status/ConfirmationDialog`,
-`Feedback & status/CustomAlertDialog` · **Vue:** `ConfirmDialog`, `ConfirmationDialog`, `CustomAlertDialog`
+`Feedback & status/CustomAlertDialog` · **Vue:** `ConfirmDialog`, `ConfirmationDialog` (`form-options` + `#form` slot for `renderForm`), `CustomAlertDialog`
 
 ---
 

package/docs/components/form-fields.md

@@ -218,6 +218,7 @@ export function Quantity() {
 | `hideSteppers` | `boolean` | `false` | hides the +/− buttons |
 | `suffix` | `ReactNode` | — | unit after the input |
 | `aria-label` | `string` | — | names the input when it has no `label` (a part of a larger field) |
+| `aria-labelledby` | `string` | — | names the input by another element's id (a part of a larger field) |
 
 **Emits:** `number | null`.
 **Form wrapper:** `NumberFormField` — `control` and `name`, see
@@ -506,6 +507,9 @@ import { InlineEdit } from '@nxgt/material/components';
 | `placeholder` | `string` | "Click to edit" | shown while empty |
 | `disabled` | `boolean` | `false` | read-only text |
 
+Enter, Escape, Save and Cancel return focus to the field, while a click
+elsewhere saves and leaves focus where it went.
+
 **Emits:** `string`, trimmed, on save only.
 **Form wrapper:** `InlineEditFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
@@ -639,7 +643,9 @@ names the thumbs); a range's thumbs add "Minimum" and "Maximum":
 `getByRole('slider', { name: 'Price Minimum' })`. A labelled range is also a
 `role="group"` named by the label, and its readout inputs are named
 "Minimum" and "Maximum" (`material.slider.minimum` / `maximum`), so two range
-sliders are told apart. `aria-invalid` (or `error`) goes on every thumb too,
+sliders are told apart. A single value's readout input is named as its thumb
+is, and "Value" (`material.slider.value`) when nothing names the slider.
+`aria-invalid` (or `error`) goes on every thumb too,
 not on the root `span`.
 
 `SliderField` is the same component under `@nxgt/material-vue`'s name (an
@@ -652,7 +658,7 @@ form's value is a number, and `number[]` when it is an array — the default
 value decides.
 **Form wrapper:** `SliderFormField` — `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/Slider` · **Vue:** `Slider`, `SliderField`, `SliderFormField`
+**Storybook:** `Form fields/Slider` · **Vue:** `Slider`, `SliderField` (`ticks`, `leading` / `trailing` or their slots), `SliderFormField`
 
 ---
 

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

@@ -11,6 +11,7 @@ them into a form.
 | <img src="../previews/media-files-s3uploadfield.webp" width="96" alt=""> | [S3UploadField, NetworkUploadField](#s3uploadfield-networkuploadfield) | Drag-and-drop uploader with progress, retry, previews and size / count limits |
 | <img src="../previews/media-files-uploadfield.webp" width="96" alt=""> | [UploadField](#uploadfield) | Labelled file input showing the chosen file's name |
 | <img src="../previews/media-files-filelist.webp" width="96" alt=""> | [FileList](#filelist) | File list with type icons, size, download and remove |
+| <img src="../previews/media-files-filepreview.webp" width="96" alt=""> | [FilePreview](#filepreview) | One file previewed by its type: image, PDF, video, audio, text, or a download card |
 | | [FilesFormField](#filesformfield) | Free-solo autocomplete of file URLs, with image thumbnails |
 | <img src="../previews/media-files-imagefield.webp" width="96" alt=""> | [ImageField](#imagefield) | Single image upload with preview and progress |
 | <img src="../previews/media-files-imagecropper.webp" width="96" alt=""> | [ImageCropper](#imagecropper) | Crop with zoom, rotation, aspect presets and a round shape |
@@ -221,6 +222,75 @@ dropzone as well read the error twice, and the group still says it once
 
 ---
 
+## FilePreview
+
+![FilePreview](../previews/media-files-filepreview.webp)
+
+Previews one file, picked by its MIME type (else its extension): an image, a PDF, a video or audio file, the text of a text, JSON, CSV or Markdown file, and a download card for anything else.
+
+```tsx
+import { useState } from 'react';
+import { FilePreview } from '@nxgt/material/components';
+
+export function Attachment() {
+  const [file, setFile] = useState<File | null>(null);
+  return (
+    <>
+      <input type="file" onChange={(event) => setFile(event.target.files?.[0] ?? null)} />
+      {/* A File or Blob: shown through an object URL, revoked on change and unmount. */}
+      <FilePreview file={file} onError={(error) => console.warn(error)} />
+      {/* A URL: the kind comes from `type`, else the extension; `name` is the alt text. */}
+      <FilePreview file="/api/files/42" type="application/pdf" name="contract.pdf" />
+    </>
+  );
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `file` | `File \| Blob \| string \| null` | — | the file, or its URL; nothing renders without one. A URL must be `http(s):`, relative, `blob:`, or a `data:` URL of an image, video, audio, plain text, CSV, Markdown, JSON or PDF; any other (`javascript:`, `data:text/html`, and also a `data:` URL of XML, TSV or YAML) shows the error state, with no link and nothing loaded |
+| `type` | `string` | the `Blob`'s, or a `data:` URL's | MIME type; picks the kind before the extension does |
+| `name` | `string` | the `File`'s, else the URL's last segment | shown on the card, the image's alt text and the download's file name; "Untitled file" when there is none |
+| `maxTextBytes` | `number` | `262144` (`TEXT_PREVIEW_MAX_BYTES`, 256 KB) | how much of a text kind is read; past it, the preview shows the beginning and says so |
+| `onError` | `(error: unknown) => void` | — | the file could not be read (an HTTP error: `FilePreviewHttpError`, with its `status`; a refused URL: `FilePreviewUnsafeUrlError`) or shown (a broken image, video or audio file) |
+| `className`, other `<figure>` props | | | on the root `<figure>` |
+
+| Kind | Picked by | Renders |
+| --- | --- | --- |
+| `image` | `image/*`; `.png` `.jpg` `.jpeg` `.gif` `.webp` `.avif` `.svg` `.bmp` `.ico` | `<img>`, its alt text the file name |
+| `pdf` | `application/pdf`; `.pdf` | [`PdfReader`](#pdfreader), imported the first time a PDF is previewed; the card when the viewer cannot be loaded. A PDF the reader fails to open leaves the preview `ready`: `PdfReader` shows its own error, and `onError` is not called |
+| `video` | `video/*`; `.mp4` `.m4v` `.webm` `.ogv` `.mov` | `<video controls>` |
+| `audio` | `audio/*`; `.mp3` `.wav` `.ogg` `.oga` `.m4a` `.aac` `.flac` `.opus` | `<audio controls>` |
+| `json` | `application/json`, `text/json`, `*+json`; `.json` | [`JsonViewer`](data-display.md#codeblock) |
+| `markdown` | `text/markdown`, `text/x-markdown`; `.md` `.markdown` | [`Markdown`](data-display.md#markdown), rendered; its links are sanitized like any `Markdown`, but a remote image in it still loads, so an untrusted `.md` can make the browser request a URL of its choosing |
+| `csv` | `text/csv`, `application/csv`, `text/tab-separated-values`; `.csv` `.tsv` | the text, in a `<pre>` |
+| `text` | any other `text/*`, `application/xml`, `application/yaml`, `application/javascript`…; `.txt` `.log` `.xml` `.yaml` `.yml` `.ini` `.toml` | the text, in a `<pre>` |
+| `other` | anything else, `application/octet-stream` without a known extension | a [`FileCard`](data-display.md#card-presets): icon, name, size and type, and a Download link |
+
+A text kind is fetched (a URL) or read (a `Blob`) up to `maxTextBytes` and
+decoded with the `charset` of the response's `Content-Type` (or of the
+`Blob`'s `type`) when the browser's `TextDecoder` supports it, else as UTF-8;
+a JSON or Markdown file cut by the cap is shown as plain text, with "Showing
+the first 256.0 KB of this file." below it. The `<pre>` and the Markdown box
+are regions named "Contents of {name}"; they scroll and take focus, so a
+keyboard can scroll them.
+
+The root is a `<figure>` named "Preview of {name}", with `data-kind` and
+`data-state`: `pending` on the server and in the first client render — an
+empty placeholder, with no object URL made and nothing fetched, so it hydrates
+without a mismatch — then `loading` ("Loading preview…", put into a `status` live region that
+stays mounted, so it is announced), `ready`
+or `error` ("This file could not be previewed.", an `alert`, with a Download
+link when there is something to download). The kind comes from
+`fileKind({ type, name, url })`, exported too, from
+[`@nxgt/material-core/file-preview`](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/README.md#a-files-preview-file-preview).
+Every string is translated (`material.file-preview.*`, see the
+[i18n guide](../guides/i18n.md)).
+
+**Storybook:** `Media & files/FilePreview` · **Vue:** `FilePreview`
+
+---
+
 ## FilesFormField
 
 No preview: it has no story of its own. It is an [`Autocomplete`](selection-and-choice.md)
@@ -257,7 +327,7 @@ function Gallery() {
 | `freeSolo` | `boolean` | `true` | accept values that are not in `options` |
 
 **Form wrapper:** it is one — `control` and `name`, see [forms](../guides/forms.md).
-**Storybook:** — · **Vue:** —
+**Storybook:** — · **Vue:** `FilesFormField`
 
 ---
 

package/docs/components/primitives.md

@@ -593,7 +593,7 @@ Parts: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`.
 | `onValueChange` (`Tabs`) | `(value: string) => void` | — | called when a trigger is selected |
 | `icon` (`TabsTrigger`) | `ReactNode` | — | shown before the label (above it on the phone in `bar`) |
 
-**Storybook:** `Primitives/Tabs` · **Vue:** `Tabs` (same parts)
+**Storybook:** `Primitives/Tabs` · **Vue:** `Tabs` (same parts, `variant="line"`)
 
 ---
 

package/docs/components/rich-widgets.md

@@ -372,7 +372,7 @@ function Config() {
 
 **Form wrapper:** `CodeEditorFormField` — `control` and `name`, see
 [forms](../guides/forms.md).
-**Storybook:** `Rich widgets/CodeEditor` · **Vue:** `CodeEditor`, `CodeEditorFormField`
+**Storybook:** `Rich widgets/CodeEditor` · **Vue:** `CodeEditor` (`options`), `CodeEditorFormField`
 
 ---
 

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
@@ -137,7 +138,7 @@ export function Framework() {
 **Emits:** `string`.
 **Form wrapper:** `SelectFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Selection & choice/SelectField` · **Vue:** `SelectField`, `SelectFormField`
+**Storybook:** `Selection & choice/SelectField` · **Vue:** `SelectField`, `SelectFormField` (`#option` slot for `renderOption`)
 
 ---
 
@@ -291,7 +292,7 @@ Parts: `Autocomplete`, `AutocompleteChips` (the chips row it uses in
 **Emits:** `string | null` in `single` mode, `string[]` in `multiple`.
 **Form wrapper:** `AutocompleteFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Selection & choice/Autocomplete` · **Vue:** `Autocomplete`, `AutocompleteFormField`
+**Storybook:** `Selection & choice/Autocomplete` · **Vue:** `Autocomplete`, `AutocompleteFormField` (generic; `#option`, `#selected-leading`, `#actions` slots)
 
 ---
 
@@ -627,6 +628,82 @@ export function Ranking() {
 
 ---
 
+## 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. Pass `value` and update it in `onValueChange`;
+without it, a pick changes nothing on screen.
+
+```tsx
+import { TreeSelectField, type TreeNode } from '@nxgt/material/components';
+import { useState } from 'react';
+
+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' }] },
+];
+
+export function Regions() {
+	const [value, setValue] = useState<string[]>(['france']);
+	return (
+		<TreeSelectField
+			label="Regions"
+			items={regions}
+			multiple
+			searchable
+			value={value}
+			onValueChange={setValue}
+		/>
+	);
+}
+```
+
+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, while open, `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? }` |
+| `multiple` | `boolean` | `false` | checkboxes and chips; decides the `value` type |
+| `value` | `string \| null` / `string[]` | — | the picked id, or ids with `multiple` |
+| `onValueChange` | `(value: string \| null) => void` / `(value: string[]) => void` | — | per `multiple` |
+| `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`) |
+| `searchPlaceholder` | `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:** `string | null` (single), `string[]` (multiple).
+**Form wrapper:** `TreeSelectFormField` — `control`, `name` and `multiple`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Selection & choice/TreeSelectField` · **Vue:** `TreeSelectField`, `TreeSelectFormField`
+
+---
+
 ## Switcher
 
 ![Switcher](../previews/selection-choice-switcher.webp)

package/docs/guides/forms.md

@@ -116,7 +116,7 @@ export function PlanForm() {
 | --- | --- |
 | one input (`TextFormField`, `EmailFormField`, `TextareaFormField`, `SwitchFormField`, `CheckboxFormField`, …) | its input loses focus, as a native `blur` |
 | several controls (`PasswordFormField` and its eye button, `NumberFormField` and its steppers, `PhoneFormField`, `OtpFormField`, `SliderFormField` with two thumbs, `DurationFormField`, `RatingFormField`, `RadioGroupFormField`, `CheckboxGroupFormField`, `SelectChipFormField`, `SelectCardFormField`, `SortableListFormField`, `TransferListFormField`, `InlineEditFormField`, `AttributeValuesFormFieldSet`, …) | focus leaves all of them; moving between them is not leaving |
-| a picker (`SelectFormField`, `ComboboxFormField`, `AutocompleteFormField`, `CountryFormField`, `TimezoneFormField`, `ColorFormField`, `DateFormField`, `DateRangeFormField`, `TimeFormField`, …) | 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`, `ComboboxFormField`, `AutocompleteFormField`, `TreeSelectFormField`, `CountryFormField`, `TimezoneFormField`, `ColorFormField`, `DateFormField`, `DateRangeFormField`, `TimeFormField`, …) | 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/map`) | focus leaves its buttons and the dialog they open. Closing the dialog hands focus back to the button that opened it |
 | an upload (`UploadFormField`, `NetworkUploadFormField`, `S3UploadFormField`, `ImageFormField`, `ImageS3FormField`, `FileListFormField`, `FileListS3FormField`) | focus leaves the drop zone and its buttons. Choosing a file in the browser's own dialog is not leaving |
 | `RichTextEditorFormField`, `CodeEditorFormField` | focus leaves the editor and its toolbar |
@@ -343,6 +343,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
 

package/docs/guides/i18n.md

@@ -204,7 +204,9 @@ presets and `Min`/`Max` fields, the `variant="4"` spinner's label,
 `You are here` and zoom buttons, and the icon-only close button of
 `DialogClose`, `DrawerClose`, `SheetClose` and `SheetContent`'s
 `withCloseButton`. A range `Slider`'s readout inputs read
-`material.slider.minimum` / `maximum` ("Minimum", "Maximum"). The other icon-only buttons are named from it too: the
+`material.slider.minimum` / `maximum` ("Minimum", "Maximum"), and a
+single value's input, when nothing names the slider, `material.slider.value`
+("Value", "Valeur"). 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`), its loading status, "Loading data…" /
 "Chargement des données…" (`material.table.loading`), a chip's remove button — `Chip`,
@@ -220,7 +222,10 @@ reads `material.print.table.total` ("Total", "Total") for its totals row and
 unless you pass `totalLabel` or `emptyText`; a PDF does not see your
 app's provider, so pass `PrintDocument` its `language` (see
 [printing](printing.md#translating-built-in-strings-in-a-pdf)). The keys and the French
-are the same in `@nxgt/material-vue`, so one set of overrides fits both. Text
+are the same in `@nxgt/material-vue`, so one set of overrides fits both. Some
+keys are read there only, such as `material.confirm-dialog.form-failed` ("The form could
+not be loaded."), which `@nxgt/material-vue`'s `ConfirmationDialog` shows when
+its on-demand form fails to load. Text
 you pass yourself always wins over the translation: a `label`,
 `Autocomplete`'s `freeSoloLabel` and `empty`, the editor's `options.labels`,
 `QRCode`'s `title`, `Barecode`'s `aria-label`, `CarouselPrevious`/`CarouselNext`
@@ -252,8 +257,46 @@ French); and the names of `DurationField`'s inputs, "Hours" and "Minutes"
 (`material['duration-field']['hours-label']` / `minutes-label`); the status a
 `Stepper` step announces after its title, "Completed" or "Error"
 (`material.stepper.completed` / `error`, "Terminée" / "Erreur" in French); and
-`PaginationFirst` / `PaginationLast`'s "First" / "Last"
-(`material.pagination.first` / `last`). `material.carousel.roledescription` /
+the pagination buttons' names and text: `PaginationPrevious` /
+`PaginationNext`'s "Previous" / "Next" (`material.pagination.previous` /
+`next`), `PaginationFirst` / `PaginationLast`'s "First" / "Last"
+(`material.pagination.first` / `last`), `PaginationBar`'s "Page {page}" on
+each page button (`material.pagination.page`) and `PaginationEllipsis`'s
+"More pages" (`material.pagination.more`). `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 `searchPlaceholder` props take precedence over them. 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.carousel.roledescription` /
 `slide` and `material.attributes.buttons.add-option` are there for
 `@nxgt/material-vue`'s carousel and attribute options, so the bundles hold
 the same keys. Your `placeholder`, `sheetTitle` and `aria-label` still

package/docs/roadmap.md

@@ -6,27 +6,16 @@ the version something shipped in.
 
 ## Now
 
-- **Spinner `light` colour renders** — a `Spinner` with `color="light"` shows
-  its light ring, for loading states on dark or coloured surfaces.
-- **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.
-- **Alert keeps long content inside** — a long title, description or unbroken
-  string wraps inside the `Alert` instead of running past its edge.
-- **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.
-- **Layouts that hold long content** — `ListTile`, `StatCard` and `Banner`
-  keep long titles, values and actions inside their box instead of overflowing.
-- **The same exports as `@nxgt/material-vue`** — `Camera`, `NativeSelect`, the
-  `InputOTP` parts, `PaginationFirst` and `PaginationLast`, `TableEmpty`,
-  `DialogScrollContent` and `ToastAction`, `Button`'s sizes, and the
-  `RadioGroupField`, `SliderField` and `SwitchField` names, so code moves
-  between the two libraries without renaming.
-- **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.
+- **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`).
+- **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 (`withTime`).
+- **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`, `onError`). Safe on a server.
 
 ## Next
 
@@ -35,12 +24,6 @@ the version something shipped in.
 - **Previews that cannot go stale** — a CI check that fails when a story changes
   but its preview image does not, so the picture in the docs is the component
   you install.
-- **DateRangeField presets and time** — one-click ranges such as Today, Last 7
-  days and This month, and a time of day on each end of the range.
-- **TreeSelectField** — pick one or several items from a tree inside a form
-  field.
-- **FilePreview** — preview an image, PDF, video or text file, chosen by its
-  type, in one component.
 
 ## Later
 
@@ -111,6 +94,28 @@ the version something shipped in.
 
 ## Shipped
 
+- **Spinner `light` colour renders** — a `Spinner` with `color="light"` shows
+  its light ring, for loading states on dark or coloured surfaces. 2.5.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. 2.5.0.
+- **Alert keeps long content inside** — a long title, description or unbroken
+  string wraps inside the `Alert` instead of running past its edge. 2.5.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. 2.5.0.
+- **Layouts that hold long content** — `ListTile`, `StatCard` and `Banner`
+  keep long titles, values and actions inside their box instead of overflowing.
+  2.5.0.
+- **The same exports as `@nxgt/material-vue`** — `Camera`, `NativeSelect`, the
+  `InputOTP` parts, `PaginationFirst` and `PaginationLast`, `TableEmpty`,
+  `DialogScrollContent` and `ToastAction`, `Button`'s sizes, and the
+  `RadioGroupField`, `SliderField` and `SwitchField` names, so code moves
+  between the two libraries without renaming. 2.5.0.
+- **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. 2.5.0.
 - **PDFs from a Next.js route handler in one line of config** —
   `withNxgtPrint(nextConfig)` from `@nxgt/material/next` adds what `/print`
   needs to `next.config.ts` — the library in `serverExternalPackages`, and