@nxgt/material-vue 0.24.0 → 0.25.1

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

@@ -10,7 +10,8 @@ printable documents — plus Leaflet maps, which live outside the barrel in
 | <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 holding the chosen `File` |
 | <img src="../previews/media-files-filelist.webp" width="96" alt=""> | [FileList](#filelist) | File list with type icons, size, download and remove |
-| | [FilesFormField](#filesformfield) | Not in `@nxgt/material-vue` |
+| <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 |
 | <img src="../previews/media-files-gallery.webp" width="96" alt=""> | [Gallery, LightboxGallery, MiniGallery](#gallery-lightboxgallery-minigallery) | Image / video gallery with a lightbox and selection |
@@ -231,13 +232,126 @@ 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.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FilePreview } from '@nxgt/material-vue/components';
+
+const file = ref<File | null>(null);
+
+function pick(event: Event) {
+  file.value = (event.target as HTMLInputElement).files?.[0] ?? null;
+}
+</script>
+
+<template>
+  <input type="file" @change="pick" />
+  <!-- A File or Blob: shown through an object URL, revoked on change and unmount. -->
+  <FilePreview :file="file" @error="(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" />
+</template>
+```
+
+| 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 |
+| `max-text-bytes` | `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 |
+| `class`, other attributes | | | 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 the `error` event is not emitted |
+| `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 `max-text-bytes` 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 before mount — 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)).
+
+**Emits:** `error` — `unknown`: 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).
+**Storybook:** `Media & files/FilePreview` · **React:** `FilePreview`
+
+---
+
 ## FilesFormField
 
-Not in `@nxgt/material-vue`. For a list of file URLs use
-[`FileListFormField`](#filelist); for typed URLs with suggestions, an
-`AutocompleteFormField` with `free-solo` (see [Selection & choice](selection-and-choice.md#autocomplete)).
+No preview: it has no story title of its own. It is an
+[`AutocompleteFormField`](selection-and-choice.md#autocomplete) bound to
+vee-validate, free-solo by default.
+
+Free-solo autocomplete of file URLs, with image thumbnails.
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { FilesFormField } from '@nxgt/material-vue/components';
+
+useForm({ initialValues: { photos: [] as string[] } });
+</script>
 
-**Storybook:** — · **React:** `FilesFormField`
+<template>
+  <FilesFormField
+    name="photos"
+    mode="multiple"
+    label="Photos"
+    placeholder="Paste an image URL"
+    image
+    :image-link-builder="(key) => `https://cdn.example.com/${key}`"
+  />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `name` | `string` | — | required; the vee-validate field |
+| `mode` | `'single' \| 'multiple'` | `'single'` | one URL or a list |
+| `image` | `boolean` | — | selected values show a thumbnail instead of a file icon |
+| `image-link-builder` | `(value) => string` | — | maps a stored key to the thumbnail `src` |
+| `options` | `T[]`, `T extends { value: string; label: string }` | `[]` | suggestions, typed by your own option type; any typed value is accepted too |
+| `get-option-value` / `get-option-label` | `(option: T) => string` | `option.value` / `option.label` | read another field of your option as its value or label, as on `Autocomplete` |
+| `free-solo` | `boolean` | `true` | accept values that are not in `options` |
+
+Like `Autocomplete`, it is generic over `T`, inferred from `options`; it has
+no slots of its own (the chip's leading thumbnail or file icon is its
+`#selected-leading`). Its ref is typed with
+`ComponentExposed`, not `InstanceType`
+([troubleshooting](../troubleshooting.md#does-not-satisfy-the-constraint-abstract-new-args-any--any)).
+
+For uploads rather than typed URLs, use [`FileListFormField`](#filelist).
+
+**Form wrapper:** it is one — `name` inside a vee-validate form, see [forms](../guides/forms.md#the-pair).
+**Storybook:** `Selection & choice/Autocomplete` (story `FilesFormField`) · **React:** `FilesFormField`
 
 ---
 

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

@@ -690,7 +690,8 @@ provideDoc(
 ```
 
 `DocLink` is an anchor that navigates through `onNavigate` for an internal
-`href` (an external one opens in a new tab); `DefaultDocLink` is the same
+`href` (an external one opens in a new tab); without `@navigate`, it and the
+sidebar are plain anchors that load the page. `DefaultDocLink` is the same
 anchor without the navigation. `DocCopyPage` (`title`) copies the title and
 the page URL; `DocArticle` is the `#doc-content` landmark the skip link and
 copy-as-markdown target. Search, the phone sheet and the active heading live in a Pinia

package/docs/components/primitives.md

@@ -570,7 +570,7 @@ use `DataTable` on the [Data table, filter & lists](data-table-filter-and-lists.
 
 ![Tabs](../previews/primitives-tabs.webp)
 
-Tabs whose triggers can take an icon.
+Tabs whose triggers can take an icon. `variant="line"` is the quieter pill style.
 
 ```vue
 <script setup lang="ts">
@@ -596,18 +596,35 @@ import {
 ```
 
 Parts: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`. An icon goes in the
-trigger's slot, before the label. There is no `variant` and no `icon` prop in
-Vue: the list is one muted pill with the active trigger raised.
+trigger's slot, before the label; there is no `icon` prop in Vue. By default
+(`variant="bar"`) the list is one muted pill with the active trigger raised.
+`variant="line"` is React's quieter style: a full-width, scrolling strip of
+light tabs, the active one on the background — `TabsList` and `TabsTrigger`
+read it from `Tabs`.
+
+```vue
+<template>
+  <Tabs default-value="ts" variant="line">
+    <TabsList>
+      <TabsTrigger value="ts">TypeScript</TabsTrigger>
+      <TabsTrigger value="bash">Bash</TabsTrigger>
+    </TabsList>
+    <TabsContent value="ts">const n = 1;</TabsContent>
+    <TabsContent value="bash">bun install</TabsContent>
+  </Tabs>
+</template>
+```
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
+| `variant` (`Tabs`) | `'bar' \| 'line'` | `'bar'` | the look of the list and its triggers |
 | `default-value` / `v-model` (`Tabs`) | `string \| number` | — | the selected tab, uncontrolled / controlled |
 | `orientation` (`Tabs`) | `'horizontal' \| 'vertical'` | `'horizontal'` | arrow-key direction |
 | `activation-mode` (`Tabs`) | `'automatic' \| 'manual'` | `'automatic'` | select on focus, or only on Enter / click |
 | `value` (`TabsTrigger`, `TabsContent`) | `string \| number` | — (required) | pairs a trigger with its panel |
 
 **Emits:** `update:modelValue` on `Tabs` — `string | number`.
-**Storybook:** `Primitives/Tabs` · **React:** `Tabs` (same parts)
+**Storybook:** `Primitives/Tabs` (story `Line`) · **React:** `Tabs` (same parts)
 
 ---
 

package/docs/components/rich-widgets.md

@@ -442,12 +442,29 @@ Monaco mounts on the client only.
 | `filename` | `string` | — | shown in the header |
 | `required` | `boolean` | — | the asterisk, and `aria-required` on Monaco's textarea (its `ariaRequired` option) |
 | `label` | `string` | — | shown above the editor, and the name of Monaco's textarea (its `ariaLabel` option) |
+| `options` | `CodeEditorOptions` | — | Monaco's own construction options (`IStandaloneEditorConstructionOptions`), passed as they are; they win over the editor's defaults, and a change reaches the mounted editor |
 
-There is no `options` pass-through in Vue yet.
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CodeEditor, type CodeEditorOptions } from '@nxgt/material-vue/components';
+
+const source = ref('const greeting = "hello";\n');
+const options: CodeEditorOptions = { lineNumbers: 'off', fontSize: 16, minimap: { enabled: false } };
+</script>
+
+<template>
+  <CodeEditor v-model="source" label="Snippet" :options="options" />
+</template>
+```
+
+`CodeEditorOptions` is a type-only import: Monaco still loads on the client
+only.
 
 **Emits:** `update:modelValue` — `string`; `languageChange` — `string`.
-**Form wrapper:** `CodeEditorFormField` (`name` plus the same props; the error
-message replaces `helper-text`), see [forms](../guides/forms.md#the-pair).
+**Form wrapper:** `CodeEditorFormField` (`name` plus the same props, `options`
+included; the error message replaces `helper-text`), see
+[forms](../guides/forms.md#the-pair).
 **Storybook:** `Rich widgets/CodeEditor` · **React:** `CodeEditor`, `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
@@ -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`
 
 ---
 
@@ -615,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,7 +107,7 @@ 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`, `CodeEditorFormField` | focus leaves the editor and its toolbar |
@@ -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,6 +390,7 @@ 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 | `''` |
@@ -400,9 +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`).
-
 ## Composite values
 
 A composite field edits a structured value through its own dialog. The form

package/docs/guides/i18n.md

@@ -288,7 +288,10 @@ the `LocationPreview` trigger (`material.map.preview` / `preview-named`),
 (`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
@@ -323,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/roadmap.md

@@ -6,31 +6,7 @@ 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.
-- **Slider thumb follows the theme in dark mode** — the `Slider` thumb takes
-  the dark theme's colours instead of staying light. Vue only.
-- **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`** — 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.
-  ([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.
+Nothing in progress right now; see Next.
 
 ## Next
 
@@ -40,18 +16,6 @@ the version something shipped in.
   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.
-- **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 in the QR
-  code, slots on `AccordionCard`, an option slot on `SelectField`, editor
-  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, 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
 
@@ -128,6 +92,50 @@ the version something shipped in.
 
 ## Shipped
 
+- **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`). 0.25.0.
+- **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`. 0.25.0.
+- **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`.
+  0.25.0.
+- **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. 0.25.0.
+- **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