@nxgt/material 3.67.0 → 3.70.0

package/dist/{use-heading-spy-K-HUp4o_.js → use-heading-spy-CVzW2NM3.js}

@@ -1,8 +1,8 @@
 import { t as e } from "./utils-BLfntITJ.js";
-import { a as t, c as n, d as r, i, n as a, r as o, t as s, u as c } from "./alert-dialog-BgQDxcYh.js";
-import { a as l } from "./button-2de_lrix.js";
-import { i as u } from "./translate-material-BlCQ6AW9.js";
-import { t as d } from "./use-material-translation-DkE9J5NE.js";
+import { a as t, c as n, d as r, i, n as a, r as o, t as s, u as c } from "./alert-dialog-CBkWG32g.js";
+import { a as l } from "./button-D3qzqDY_.js";
+import { i as u } from "./translate-material-Dh7MYkHT.js";
+import { t as d } from "./use-material-translation-BAYyZOcH.js";
 import { _ as f, g as p, h as m, n as h, v as g, y as _ } from "./number.utils-BG_eEt5g.js";
 import { useCallback as v, useEffect as y, useMemo as b, useRef as x, useState as S } from "react";
 import { jsx as C, jsxs as w } from "react/jsx-runtime";

package/dist/{use-material-translation-DkE9J5NE.js → use-material-translation-BAYyZOcH.js}

@@ -1,4 +1,4 @@
-import { i as e, t } from "./translate-material-BlCQ6AW9.js";
+import { i as e, t } from "./translate-material-Dh7MYkHT.js";
 import { useCallback as n } from "react";
 //#region lib/i18n/use-material-translation.ts
 function r() {

package/dist/{use-return-focus-KypnR7vv.js → use-return-focus-CQAuk9kh.js}

@@ -1,6 +1,6 @@
 import { o as e, r as t } from "./dist-DVRQkaTK.js";
 import { a as n, c as r, i, l as a, o, r as s, s as c } from "./dist-lmHmz_bu.js";
-import { C as l, S as u, w as d } from "./spinner-PdSk7zEs.js";
+import { C as l, S as u, w as d } from "./spinner-ByYdcukU.js";
 import { c as f, i as p, l as m, o as h, r as g, s as ee } from "./in-dialog-Vwkyp-M5.js";
 import { r as _ } from "./escape-owner-DpaP0lm1.js";
 import * as v from "react";

package/docs/components/form-fields.md

@@ -12,12 +12,14 @@ for the value type each one writes. Everything is imported from
 | <img src="../previews/form-fields-field.webp" width="96" alt=""> | [Field](#field) | Renders the field matching a config `type` |
 | <img src="../previews/form-fields-formsection.webp" width="96" alt=""> | [FormSection](#formsection) | Titled section of a form, one column on a phone |
 | <img src="../previews/form-fields-repeatablegroup.webp" width="96" alt=""> | [RepeatableGroup](#repeatablegroup) | Rows a user adds, removes and reorders |
+| <img src="../previews/form-fields-choicelistfield.webp" width="96" alt=""> | [ChoiceListField](#choicelistfield) | An editable list of answer choices with correct marks |
 | <img src="../previews/form-fields-textfield.webp" width="96" alt=""> | [TextField](#textfield) | Labelled input with adornments and helper text |
 | <img src="../previews/form-fields-textareafield.webp" width="96" alt=""> | [TextareaField](#textareafield) | Labelled textarea with row sizing and a counter |
 | <img src="../previews/form-fields-emailfield.webp" width="96" alt=""> | [EmailField](#emailfield) | Validates on blur, `mailto:` button |
 | <img src="../previews/form-fields-passwordfield.webp" width="96" alt=""> | [PasswordField](#passwordfield) | Show / hide toggle and a strength meter |
 | <img src="../previews/form-fields-numberfield.webp" width="96" alt=""> | [NumberField](#numberfield) | `number \| null` with clamping and +/− buttons |
 | <img src="../previews/form-fields-percentfield.webp" width="96" alt=""> | [PercentField](#percentfield) | `NumberField` with a `%` suffix |
+| <img src="../previews/form-fields-quantityfield.webp" width="96" alt=""> | [QuantityField](#quantityfield) | One labelled field holding an amount and its unit |
 | <img src="../previews/form-fields-currencyfield.webp" width="96" alt=""> | [CurrencyField](#currencyfield) | Locale-formatted amount with a currency suffix |
 | <img src="../previews/form-fields-phonefield.webp" width="96" alt=""> | [PhoneField](#phonefield) | International number, emits E.164 |
 | <img src="../previews/form-fields-urlfield.webp" width="96" alt=""> | [UrlField](#urlfield) | Validates on blur, open and copy buttons |
@@ -325,6 +327,104 @@ masculine one.
 
 ---
 
+## ChoiceListField
+
+![ChoiceListField](../previews/form-fields-choicelistfield.webp)
+
+An editable list of answer choices, for a quiz question: each row has a text
+and a "correct" mark. `ChoiceListFormField` wires it to react-hook-form; the
+value is an array of `{ id, text, correct }`.
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { Button, ChoiceListFormField } from '@nxgt/material/components';
+import type { ChoiceRow } from '@nxgt/material/components';
+
+type Values = { choices: ChoiceRow[] };
+
+declare function save(choices: ChoiceRow[]): void;
+
+function QuestionForm() {
+  const { control, handleSubmit } = useForm<Values>({
+    defaultValues: {
+      choices: [
+        { id: 'a', text: 'Paris', correct: true },
+        { id: 'b', text: 'Lyon', correct: false },
+      ],
+    },
+  });
+  return (
+    <form onSubmit={handleSubmit((values) => save(values.choices))}>
+      <ChoiceListFormField
+        control={control}
+        name="choices"
+        label="Answers"
+        selection="multiple"
+        min={2}
+        max={20}
+      />
+      <Button type="submit">Save</Button>
+    </form>
+  );
+}
+```
+
+It is a [`RepeatableGroup`](#repeatablegroup) of rows: Add, Remove and move
+up / down buttons, `min` and `max` rows (Remove is disabled at `min`, Add is
+`aria-disabled` at `max`), focus that follows each change and polite
+announcements. Without a form library, `ChoiceListField` takes `value` and
+`onChange`.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `control`, `name` | `Control<T>`, `Path<T>` | — | the form and its array (`ChoiceListFormField`) |
+| `value`, `onChange` | `ChoiceRow[]`, `(rows) => void` | — | the rows (`ChoiceListField`) |
+| `selection` | `'single' \| 'multiple'` | `'multiple'` | `single`: native radios sharing one name in a `radiogroup`; marking a row unmarks the others. `multiple`: checkboxes |
+| `requireCorrect` | `boolean` | `true` | the built-in rules ask for a marked row; `false` lets a list with none pass, for a poll (`ChoiceListFormField`) |
+| `min`, `max` | `number` | none | bounds on the row count |
+| `reorderable` | `boolean` | `true` | move up / down buttons on each row |
+| `label` | `ReactNode` | none | names the group (a `group`, or a `radiogroup` in `single`) |
+| `rowLabel`, `addLabel` | `string` | "answer", "Add answer" | lower-case noun for the buttons (translated by default) |
+| `error`, `rowErrors` | `ReactNode`, `{ [id]: ReactNode }` | none | the list's error and each row's, by id (`ChoiceListField`; the form field fills them from the form) |
+| `onBlur` | `() => void` | none | `ChoiceListField` alone: called when the focus leaves the whole list. In a form the list's root is registered with the form's `FieldBlur`, so touched works without it |
+| `onAssignIds` | `(rows) => void` | `onChange` | `ChoiceListField`: called once on mount with ids given to rows that had none or repeated one; the form field sets them without marking the form dirty |
+| other props | `div` props | | passed to the group's root (`className`, `id`, `data-*`, `ref`) |
+| `emptyTitle`, `emptyDescription`, `disabled` | | | as `RepeatableGroup` |
+
+- **Ids:** every row keeps its `id` across edits, removals and moves, so a
+  server can match a choice to its stored one. A new row gets a generated id;
+  a row that arrives without one, or repeating an earlier row's, is given a new
+  one on mount (the form field does it with `setValue` when the `FormProvider` above is its own form, and then leaves the form clean; otherwise it calls `onChange`). Give the rows ids in `defaultValues`, the clean path: with assigned ids `defaultValues` still lack them, so `dirtyFields.choices` marks rows after the first real edit.
+  In `single`, the new row is marked when no row is. A list that arrives with
+  several rows marked is not changed: it fails the `too-many` rule.
+- **Semantics:** each row's text is a labelled input ("Answer 2"); its mark
+  is a radio or a checkbox named "Correct: answer 2" (the visible word
+  "Correct" starts the name), so `getByRole('checkbox', { name: 'Correct: answer 2' })`
+  finds it. Buttons are named after the row ("Remove answer 2", "Move answer 2 up"):
+  the keyboard reorders with them.
+- **Tab order:** in `single` the radios are native and share one name, so
+  Tab visits each row's text field in order; the checked radio is reached in
+  its own row and the unchecked ones are skipped. The arrow keys move between
+  the radios and check the one they land on. The radios point their `form`
+  attribute at no form, so a surrounding `<form>`'s native `FormData` gets no
+  entry for them. (A
+  roving radio group over the whole list would send Tab to the checked radio
+  first.)
+- **Errors:** without a resolver the field validates by itself: fewer than
+  `min` rows, several rows marked in `single`, no row marked (unless
+  `requireCorrect` is `false`), or a blank row puts a message under the
+  list, and blank rows are marked invalid (only for that rule, never for a resolver's or another rule's message). With a resolver (zod), an issue on
+  `choices.2.text` shows under row 3 and an issue on `choices` under the list.
+  When both fail in one pass, react-hook-form keeps only the list's.
+- **Translations:** `material.choice-list.*` (English and French). The
+  messages name the row with `rowLabel` ("Fill in every answer"); `too-few`
+  is a plural that adds `s` to it, and the French templates carry the
+  feminine article, so a French app overrides the keys for a masculine noun.
+
+**Storybook:** `Form fields/ChoiceListField` · **Vue:** none yet
+
+---
+
 ## TextField
 
 ![TextField](../previews/form-fields-textfield.webp)
@@ -511,6 +611,79 @@ ratio (`0.15`).
 
 ---
 
+## QuantityField
+
+![QuantityField](../previews/form-fields-quantityfield.webp)
+
+One labelled field holding an amount and its unit ("2 capsule", "500 mg"): a
+[`NumberField`](#numberfield)'s number beside a unit picker, under one label
+and one error message. The value is `{ value: number | null, unit: string }`.
+`QuantityFormField` wires it to react-hook-form.
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { Button, QuantityFormField } from '@nxgt/material/components';
+import type { QuantityValue } from '@nxgt/material/components';
+
+type Values = { dose: QuantityValue };
+
+function DoseForm() {
+  const { control, handleSubmit } = useForm<Values>({
+    defaultValues: { dose: { value: null, unit: '' } },
+  });
+  return (
+    <form onSubmit={handleSubmit((values) => console.log(values.dose))}>
+      <QuantityFormField
+        control={control}
+        name="dose"
+        label="Dose"
+        min={0}
+        step={0.5}
+        units={[
+          { value: 'mg', label: 'mg' },
+          { value: 'ml', label: 'mL' },
+        ]}
+      />
+      <Button type="submit">Save</Button>
+    </form>
+  );
+}
+```
+
+Without a form library, `QuantityField` takes `value` and `onChange` (or
+`defaultValue`). The number is the one `NumberField` has: the language's
+decimal separator, `min`, `max` and `step` (clamped on blur), and steppers
+named after the field ("Increase Dose"). Both parts stay on one line on a
+phone: the number shrinks, the unit keeps a fixed 7rem.
+
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `control`, `name` | `Control<T>`, `Path<T>` | — | the form and its `{ value, unit }` (`QuantityFormField`) |
+| `value`, `defaultValue`, `onChange` | `QuantityValue`, `(value) => void` | empty | the amount and its unit; `onChange` gets both on each change |
+| `label` | `ReactNode` | none | the one label; it names the group |
+| `units` | `{ value, label }[]` | none | the units offered |
+| `allowCustomUnit` | `boolean` | `false` | the unit is typed in a text input and `units` are suggestions; otherwise it is picked from `units` |
+| `min`, `max`, `step`, `hideSteppers` | | `step` 1 | as `NumberField` |
+| `unitLabel`, `unitPlaceholder` | `string` | "<label> unit" | the unit part's accessible name and its placeholder |
+| `helperText`, `error` | `ReactNode`, `boolean` | none | the one message under the pair; in a form, an error on `name`, `name.value` or `name.unit` shows there |
+| `className`, `aria-label` | `string` | none | `className` goes on the group; `aria-label` names it when `label` is not plain text |
+| `name`, `onBlur` | | none | `QuantityField` only (the form field takes them from the form): `name` names the parts `<name>.value` and `<name>.unit`; `onBlur` fires when the number input loses focus |
+| `required`, `disabled`, `placeholder`, `id`, `ref` | | | `placeholder`, `id` and `ref` reach the number input (React Hook Form's `field.ref` focuses it on an error) |
+
+- **Semantics:** a `<fieldset>` (role `group`) named by the label; the number
+  is a textbox named after the label, the unit a combobox (or, with
+  `allowCustomUnit`, a text input) named "Dose unit". The message describes
+  the group, the number and the unit, and both are `aria-invalid` on an error.
+- **Translations:** `material.quantity-field.unit` and `.unit-named` (English
+  and French) name the unit part.
+
+**Emits:** `{ value: number | null, unit: string }`.
+**Form wrapper:** `QuantityFormField` — `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/QuantityField` · **Vue:** none yet (#2106)
+
+---
+
 ## CurrencyField
 
 ![CurrencyField](../previews/form-fields-currencyfield.webp)
@@ -566,9 +739,19 @@ export function Mobile() {
 | `value` / `defaultValue` | `string \| null` | `null` | an E.164 number (`+33612345678`) |
 | `onChange` | `(value: string \| null) => void` | — | `null` until the typed number is possible for the country |
 | `defaultCountry` | `string` (ISO 3166-1) | `'FR'` | the country used when the value has no `+` prefix |
-
-**Emits:** E.164 `string`, or `null` while the number is incomplete.
-**Form wrapper:** `PhoneFormField` — `control` and `name`, see
+| `onValidityChange` | `(incomplete: boolean) => void` | — | `true` while the draft is not empty but not yet a possible number (`onChange` gives `null` for it, as for an empty field); `false` once it is complete or empty. Fires before the matching `onChange`; not called while the field has never been incomplete |
+
+**Emits:** E.164 `string`, or `null` while the number is empty or incomplete.
+Outside a form, tell the two apart with `onValidityChange` (or
+`isIncompletePhone(draft, iso)`).
+**Form wrapper:** `PhoneFormField` — `control` and `name`; an empty field is
+`null`, and a half-typed number is a field error « Incomplete number »
+(`material.phone-field.incomplete`, « Numéro incomplet » in French) that blocks
+the submit, so a stored number is never cleared silently. `PhoneFormField` takes `rules`: your own `rules.validate` (a function or an
+object of them) runs beside the incomplete check, as its `custom` key for a
+function. A `rules.required` is checked first by React Hook Form, so a half-typed
+number reads as the required message there. A form `reset()` to `null` does not clear a half-typed draft (the
+value did not change), so an incomplete draft stays an error until it is edited. See
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
 **Storybook:** `Form fields/PhoneField` (and `/Field look`) · **Vue:** `PhoneField`, `PhoneFormField`
 
@@ -1771,6 +1954,16 @@ Parts: `PostalAddress` (the card), `PostalAddressDialog` (the edit form).
 | `onEdit` | `() => void` | — | shows the edit button |
 | `disabled` | `boolean` | — | hides it |
 
+**One line and country codes:** `formatPostalAddress(address, { language?, separator? })`
+returns the address as one line for a read view, `"12 rue du Lac, 74000 Annecy, France"`:
+street, city line, then the country named in `language` (default `'en'`, as
+`postalAddressCountryName`). The city line puts the postal code before the city
+(FR, BE, CH, DE and any other country) or after the city and region (GB, US, CA,
+IE, AU, NZ, IN: `"London SW1A 2AA"`). Empty parts are skipped; `separator`
+defaults to `', '`. `ISO_COUNTRY_CODES` (the 249 ISO 3166-1 alpha-2 codes) and
+`isCountryCode(code)` (a guard to `string`, upper case only) are exported from
+`@nxgt/material/components` too.
+
 `PostalAddressFormField` and `PostalAddressDialog` take `cancelVariant` (the
 dialog's Cancel button, a `Button` `variant`, default `'tonal'`; `'outlined'`
 restores the earlier look).

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

@@ -65,9 +65,10 @@ function Attachments() {
 <NetworkUploadField
   mode="single"
   label="Contract"
-  onUpload={async (file, onProgress) => {
+  onUpload={async (file, onProgress, signal) => {
+    const res = await fetch('/api/files', { method: 'POST', body: file, signal });
     onProgress?.(100);
-    return `https://files.example.com/${file.name}`;
+    return (await res.json()).url;
   }}
 />;
 ```
@@ -75,8 +76,8 @@ function Attachments() {
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `mode` | `'single' \| 'multiple'` | — (required) | `value` is a `string` or a `string[]` |
-| `onUpload` | `(file, onProgress?) => Promise<string>` | — | `NetworkUploadField` only; the resolved string becomes the value |
-| `getPresignedUrl` | `(file) => Promise<{ uploadUrl, publicUrl, headers? }>` | — | `S3UploadField` only; PUTs the file to `uploadUrl`, stores `publicUrl` |
+| `onUpload` | `(file, onProgress?, signal?) => Promise<string>` | — | `NetworkUploadField` only; the resolved string becomes the value. Removing an uploading row or unmounting the field aborts `signal`: pass it to your request, or the upload still completes (its value is dropped). An abort after the request completed cannot unsend it: the value is dropped and `onRemove` is not called. The S3 fields abort their request themselves and reject with an `UploadError` of kind `aborted` (named `AbortError`, no longer a `DOMException`) |
+| `getPresignedUrl` | `(file) => Promise<PresignedUploadTarget>` | — | `S3UploadField` only; `{ uploadUrl, publicUrl, headers? }` PUTs the file and stores `publicUrl`; `{ method: 'POST', url, fields, value }` posts a form and stores `value` (see [presigned POST](#presigned-post)) |
 | `accept` | `string` | — | file input `accept`, also shown under the drop zone |
 | `maxSize` | `number` (bytes) | — | larger files are rejected before upload |
 | `maxFiles` | `number` | — | `mode="multiple"` only; the drop zone is disabled once reached |
@@ -95,9 +96,51 @@ description instead, so the error is still said: with `error` and that
 group, so to set files in a test, reach the input through it:
 `getByRole('group', { name: 'Contract' }).locator('input[type=file]')`.
 
+### Presigned POST
+
+A backend that signs a POST policy (so the bucket enforces content type and
+size) returns `{ method: 'POST', url, fields, value }`. The field sends
+`multipart/form-data` with `fields` in their order and the file appended last
+under the name `file`, then stores `value` (the key). The same target works for `S3UploadFormField`,
+`ImageS3Field`, `ImageS3FormField`, `FileListS3Field` and `FileListS3FormField`;
+the PUT shape stays valid. Progress, retry, cancel and errors behave as for a PUT.
+
+```tsx
+<S3UploadFormField
+  control={control}
+  name="file"
+  label="Contract"
+  getPresignedUrl={async (file) => {
+    const { url, fields, key } = await api.presignPost({ name: file.name, contentType: file.type });
+    return { method: 'POST', url, fields, value: key }; // fields exactly as signed
+  }}
+/>
+```
+
+A refused policy (`403`, or `400 EntityTooLarge`) reaches `onError(file, error)`
+and the field's error state; when S3 answers with its XML error, the message
+carries the code. The S3 helpers reject with an `UploadError` (`kind`:
+`status` | `network` | `aborted`, plus `status` and `code`), and the field words
+it in the active language from `material.upload.error-status`,
+`error-status-code`, `error-network` and `error-aborted` (`Échec de l'envoi
+(statut 400, EntityTooLarge)` in French). `error.message` stays English, for
+logs. An error thrown by your own `onUpload` or `getPresignedUrl` is not an
+`UploadError`: its `message` is shown as is, so translate it yourself. A stored
+`value` that is a key needs `resolveUrl` to preview it.
+
+The bucket must allow the browser to POST from your origin:
+
+```json
+[{ "AllowedOrigins": ["https://app.example.com"], "AllowedMethods": ["POST"], "AllowedHeaders": ["*"] }]
+```
+
+If the app sends a `Content-Security-Policy`, add the bucket host to
+`connect-src` (uploads use `XMLHttpRequest`), for example
+`connect-src 'self' https://my-bucket.s3.eu-west-1.amazonaws.com`.
+
 **Form wrapper:** `S3UploadFormField`, `NetworkUploadFormField` — `control` and `name`, see
 [forms](../guides/forms.md).
-**Storybook:** `Media & files/S3UploadField`, `Media & files/NetworkUploadField` · **Vue:** `S3UploadField`, `NetworkUploadField`, `S3UploadFormField`, `NetworkUploadFormField`
+**Storybook:** `Media & files/S3UploadField`, `Media & files/NetworkUploadField` · **Vue:** `S3UploadField`, `NetworkUploadField`, `S3UploadFormField`, `NetworkUploadFormField` (PUT only, #2095)
 
 ---
 
@@ -199,7 +242,9 @@ function Attachments() {
 ```
 
 Parts: `FileList` (display only), `FileListField` (uploads through `onUpload`),
-`FileListS3Field` (uploads through `getPresignedUrl`, like `S3UploadField`).
+`FileListS3Field` (uploads through `getPresignedUrl`, like `S3UploadField`;
+with a POST target the value is `value`, a key, so pass `resolveUrl` to preview
+saved images).
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
@@ -224,7 +269,7 @@ dropzone as well read the error twice, and the group still says it once
 `maxFiles` hides the dropzone. The dropzone is outlined through `data-invalid`.
 
 **Form wrapper:** `FileListFormField`, `FileListS3FormField` — see [forms](../guides/forms.md).
-**Storybook:** `Media & files/FileList`, `Media & files/FileListField` · **Vue:** `FileList`, `FileListField`, `FileListS3Field`, `FileListFormField`, `FileListS3FormField`
+**Storybook:** `Media & files/FileList`, `Media & files/FileListField` · **Vue:** `FileList`, `FileListField`, `FileListS3Field`, `FileListFormField`, `FileListS3FormField` (S3 variants PUT only, #2095)
 
 ---
 
@@ -364,7 +409,8 @@ function Avatar() {
 ```
 
 Parts: `ImageField` (uploads through `onUpload`), `ImageS3Field` (through
-`getPresignedUrl`).
+`getPresignedUrl`; with a POST target the value is `value`, a key, so pass
+`resolveUrl` to preview saved images).
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
@@ -389,7 +435,7 @@ with no message of its own, by a visually hidden "This value is not valid."
 (`material.zod.default`, translated), and outlined through `data-invalid`.
 
 **Form wrapper:** `ImageFormField`, `ImageS3FormField` — see [forms](../guides/forms.md).
-**Storybook:** `Media & files/ImageField` · **Vue:** `ImageField`, `ImageS3Field`, `ImageFormField`, `ImageS3FormField`
+**Storybook:** `Media & files/ImageField` · **Vue:** `ImageField`, `ImageS3Field`, `ImageFormField`, `ImageS3FormField` (S3 variants PUT only, #2095)
 
 ---
 

package/docs/components/primitives.md

@@ -788,7 +788,7 @@ hides the indicator.
 
 For tabs that go to routes, use [TabsNav](#tabsnav): real links with `aria-current`, not tabs with panels.
 
-`TabsTrigger asChild` makes your link the tab (`<TabsTrigger value="a" asChild><Link to="/a">A</Link></TabsTrigger>`): the indicator and the icon and label spans go inside it. `ToggleGroupItem`, `AccordionTrigger`, `SelectTrigger` and `ExtendedLabel` take `asChild` the same way.
+`TabsTrigger asChild` makes your link the tab (`<TabsTrigger value="a" asChild><Link to="/a">A</Link></TabsTrigger>`): the indicator and the icon and label spans go inside it. `ToggleGroupItem`, `AccordionTrigger`, `SelectTrigger` and `ExtendedLabel` take `asChild` the same way. For links, use [SegmentedNav](#segmentednav), not `ToggleGroupItem asChild`: a radio group of links is announced wrongly.
 
 `dir="rtl"` on `Tabs` (or Radix's `DirectionProvider`) runs the tabs from the
 right: the indicator follows them, and the Left arrow key moves to the next
@@ -849,21 +849,19 @@ Use `Tabs` when the panels are on the page and `TabsNav` when each tab is a
 place to go: every tab is a real link, so it opens in a new window and its
 address can be copied. `aria-label` names the navigation and is required.
 
-- **Current link**: `TabsNav`'s `value` is matched against each link's
-  `value`; a link's `current` boolean overrides it (`current={false}` to
-  switch one off). The current link carries `aria-current="page"` and
-  `data-state="active"`, which is what the indicator follows.
+- **Current link**: a link's `current` boolean overrides the nav's `value`. The
+  current link carries `aria-current="page"` and `data-state="active"`, which
+  is what the indicator follows.
 - **Keyboard**: the links are plain links, so Tab moves from one to the next;
   the arrow keys do nothing (they are not tabs, there is no `tablist`).
 - **Looks**: `variant="underline"` (the default) or `"segmented"`, as `Tabs`.
   A nav wider than its container scrolls inside itself, with the same edge
   fades and scroll buttons as `Tabs`. On a coarse pointer each link is 44px
-  tall at least.
+  tall at least. In forced colours the current link keeps a `Highlight` mark.
 - **The link**: `TabsNavLink` takes `LinkButton`'s props (`to`, `replace`,
   `state`, `target`, `reloadDocument`, `download`, `linkComponent`) and an
   `icon`. It renders React Router's `Link`, or the `LinkComponentProvider`'s
-  component (given `href`). `preventScrollReset` is on by default, so changing
-  tab keeps the scroll position; pass `preventScrollReset={false}` to reset.
+  component (given `href`).
 - A tab bound to the URL's search params: [`useTabParam`](#route-tabs-in-the-url-usetabparam).
 
 **It needs a Router.** Without a `LinkComponentProvider`, `TabsNavLink` renders
@@ -993,9 +991,7 @@ each segment is a place to go: every item is a real link, so it opens in a
 new window and its address can be copied. A `ToggleGroup` of links would
 announce each as a radio. `aria-label` names the navigation and is required.
 
-- **Current item**: `SegmentedNav`'s `value` is matched against each item's
-  `value`; an item's `current` boolean overrides it (`current={false}` to
-  switch one off). The current item carries `aria-current="page"` and
+- **Current item**: an item's `current` boolean overrides the nav's `value`. The current item carries `aria-current="page"` and
   `data-state="active"`, and draws the selected pill (its label in
   `primary-text`); it does not glide, since the nav may scroll.
 - **Keyboard**: the items are plain links, so Tab moves from one to the next;
@@ -1007,8 +1003,7 @@ announce each as a radio. `aria-label` names the navigation and is required.
 - **The link**: `SegmentedNavItem` takes `LinkButton`'s props (`to`, `replace`,
   `state`, `target`, `reloadDocument`, `download`, `linkComponent`). It renders
   React Router's `Link`, or the `LinkComponentProvider`'s component (given
-  `href`). `preventScrollReset` is on by default, so changing segment keeps
-  the scroll position; pass `preventScrollReset={false}` to reset.
+  `href`).
 - A segment bound to the URL's search params: [`useTabParam`](#route-tabs-in-the-url-usetabparam) (`useTabParam({ param: 'p', values })`), as above.
 
 **It needs a Router.** Without a `LinkComponentProvider`, `SegmentedNavItem`
@@ -1079,7 +1074,7 @@ colour.
 Everything is CSS on data attributes (`data-variant`, `data-size`,
 `data-orientation`): nothing is measured, no inline style, the server
 writes the same markup. Motion is off under `prefers-reduced-motion`, and
-forced colours draw the selected item in `SelectedItem`.
+forced colours draw the selected item in `SelectedItem`. The segmented look also follows `aria-current="page"`, which is what [SegmentedNav](#segmentednav) uses for links.
 
 ```tsx
 import {

package/docs/components/rich-widgets.md

@@ -2457,9 +2457,10 @@ French bundle — see [i18n](../guides/i18n.md).
 | `QuestionCard` `renderCode` | `(field: QuestionCodeField) => ReactNode` | — | the code field of a `code` question; `field` is `{ value, onChange, label, labelledBy, describedBy, language, maxLength, readOnly, disabled }`. Keeps Monaco out of the card's bundle |
 | `Question` `description` | `string` | — | `open`, `code`: a persistent helper line under the answer field ("A person will mark this answer"), linked to it by `aria-describedby` and passed to `renderCode` as `field.describedBy`; always shown, unlike `hint` (a reveal button). Its id is `${promptId}-description` |
 | `QuestionCard` `promptId` | `string` | generated | the id of the prompt text: point a wrapping section's `aria-labelledby` at it (and `aria-describedby` at `${promptId}-description`) |
+| `QuestionCard` `preview` | `boolean` | `false` | an author's preview, `<QuestionCard question={q} preview />`: forces `revealed` and `readOnly`, drops `onValueChange`, and shows the marks (the `question.correct` options marked, the expected text or number filled in) and the `explanation`, with no verdict banner. `verdict` and `showFeedback` are always ignored in a preview; `value` is ignored when the question has a `correct` — an `open` or `code` question has none, so pass its reference answer as `value`. Not for a learner's attempt |
 | `QuestionCard` `readOnly` / `busy` | `boolean` | `false` | `readOnly`: an answer already submitted, shown without the revealed marks; `busy`: read-only and `aria-busy` while it is saved; every kind honours both |
 | new strings | `material.education.kind-open`, `kind-code`, `code-placeholder` | — | English fallbacks and a French bundle |
-| `QuestionCard` `variant` / `density` / `showShortcuts` / `number` / `showFeedback` | — | `'card'`, `'comfortable'`, `false`, —, `true` | framed or plain, spacing, key badges, "Question 2", the verdict banner |
+| `QuestionCard` `variant` / `density` / `showShortcuts` / `number` / `showFeedback` | — | `'card'`, `'comfortable'`, `false`, —, `true` | framed or plain, spacing, key badges, "Question 2", the verdict banner (for a card with marks and no banner, use `preview`) |
 
 An open answer and a code answer, with the code editor from its own subpath
 (it is client-only, so load it lazily in an SSR app):

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

@@ -417,7 +417,7 @@ disabled with the field; Backspace in the empty input removes the last one.
 | `getOptionValue`, `getOptionLabel` | `(option: T) => string` | `.value`, `.label` | for other option shapes |
 | `getOptionLeading` | `(option: T) => ReactNode` | — | an avatar (or a flag) before the label, in the list and in the chip; `renderOption` replaces the whole row |
 | `filter` | `'accent-insensitive' \| 'none' \| (option: T, query: string) => boolean` | `'accent-insensitive'`, `'none'` with `onSearch` | how the list is filtered as the user types: label or value, ignoring case and accents (`e` finds "École") in the provider's language; `'none'` shows `options` as given; a function gets the trimmed query, never an empty one |
-| `freeSolo` | `boolean` | — | accept a typed value that is not an option |
+| `freeSolo` | `boolean` | — | accept a typed value that is not an option; Enter adds it |
 | `onSearch` | `(query: string, { signal }: { signal: AbortSignal }) => Promise<T[]>` | — | server search: called once typing pauses; its results become the list. Each search aborts the previous one, and a response that lands after a newer one is dropped |
 | `onSearchError` | `(error: unknown) => void` | — | `onSearch` rejected (an abort is not a rejection) |
 | `minQueryLength` | `number` | `1` | `onSearch` waits for this many characters; below it the list says "Type at least N characters to search." |
@@ -433,6 +433,12 @@ disabled with the field; Backspace in the empty input removes the last one.
 | `disabled` | `boolean` | — | disables the input and each chip's remove button |
 | `error` | `boolean` | — | error border on the chips box, error helper text, `aria-invalid` on the input |
 
+Enter in a form: it acts on the list and does not submit the form while it has
+something to do (WAI-ARIA combobox practice). It picks the highlighted option;
+with `freeSolo` and no option highlighted it adds the typed text; with the list
+open it is only default-prevented. On a closed list with nothing typed it
+submits, as a plain input does.
+
 An avatar in the rows and the chips:
 `getOptionLeading={(person) => <Avatar src={person.photo} alt="" />}`; see
 [the field look](../guides/field-look-2-x.md#autocomplete-and-the-chips-box).
@@ -471,8 +477,9 @@ text, as a `Select` shows it, and keeps the search:
   gets the label back on leave: the value can only be replaced by another pick.
 - The option's `getOptionLeading` (or `renderSelectedLeading`) avatar shows
   before the text while it is picked.
-- `freeSolo` still adds through its "Add" button; text left in the input and
-  not added is dropped on leave, as any other typed text.
+- `freeSolo` adds through its "Add" button, or with Enter when no option is
+  highlighted; text left in the input and not added is dropped on leave, as
+  any other typed text.
 - Keep the selected option in `options` (as with `onSearch` and chips): a value
   with no matching option has no label, so the input stays empty.
 - The input is the combobox: `aria-expanded` follows the list,

package/docs/guides/forms.md

@@ -115,7 +115,7 @@ export function PlanForm() {
 | The field | Touched when |
 | --- | --- |
 | one input (`TextFormField`, `EmailFormField`, `TextareaFormField`, `SwitchFormField`, `CheckboxFormField`, …) | its input loses focus, as a native `blur` |
-| several controls (`OpeningHoursFormField`, inline by default: focus leaves the week editor and its phone sheet; `ContactsFormField`, inline by default: focus leaves the rows and the phone sheet; `AttributesFormField`, inline by default: focus leaves the rows, their open fields and the phone sheet; `PasswordFormField` and its eye button, `NumberFormField` and its steppers, `PhoneFormField`, `OtpFormField`, `SliderFormField` with two thumbs, `DurationFormField`, `RatingFormField`, `RadioGroupFormField`, `CheckboxGroupFormField`, `ChipGroupFormField`, `ChoiceCardGroupFormField`, `SortableListFormField`, `TransferListFormField`, `InlineEditFormField`, `LocalizedTextFormField`, `AttributeValuesFormFieldSet`, …) | focus leaves all of them; moving between them is not leaving |
+| several controls (`OpeningHoursFormField`, inline by default: focus leaves the week editor and its phone sheet; `ContactsFormField`, inline by default: focus leaves the rows and the phone sheet; `AttributesFormField`, inline by default: focus leaves the rows, their open fields and the phone sheet; `PasswordFormField` and its eye button, `NumberFormField` and its steppers, `QuantityFormField`, `PhoneFormField`, `OtpFormField`, `SliderFormField` with two thumbs, `DurationFormField`, `RatingFormField`, `RadioGroupFormField`, `CheckboxGroupFormField`, `ChipGroupFormField`, `ChoiceCardGroupFormField`, `SortableListFormField`, `TransferListFormField`, `InlineEditFormField`, `LocalizedTextFormField`, `AttributeValuesFormFieldSet`, …) | focus leaves all of them; moving between them is not leaving |
 | 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 typed `DateFormField`, `DateRangeFormField` or `TimeFormField` is one trigger: moving between its segments (both ends of a range) and its buttons is not leaving |
 | a dialog editor (`PostalAddressFormField`, `ContactsFormField` with `editing="dialog"`, `OpeningHoursFormField` with `editing="dialog"`, `AttributesFormField` with `editing="dialog"`, 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 |
@@ -485,8 +485,9 @@ or fails validation.
 | `PasswordField` · `PasswordFormField` | `string` | `''` |
 | `NumberField` · `NumberFormField` | `number \| null`. `null` when cleared; clamped to `min` / `max` on blur | `null` |
 | `PercentField` · `PercentFormField` | `number \| null`, `min` 0, `max` 100, `step` 1 by default | `null` |
+| `QuantityField` · `QuantityFormField` | `{ value: number \| null, unit: string }`. An error on the field, `.value` or `.unit` shows as one message under the pair | `{ value: null, unit: '' }` |
 | `CurrencyField` · `CurrencyFormField` | `number \| null`, the amount only, not rounded. `currency` (default `'EUR'`) and `fractionDigits` (the currency's own decimals by default) are display | `null` |
-| `PhoneField` · `PhoneFormField` | E.164 `string` (`'+33612345678'`), or `null` while the number is not yet a possible one. `defaultCountry` is `'FR'` | `null` |
+| `PhoneField` · `PhoneFormField` | E.164 `string` (`'+33612345678'`), or `null` when empty. `PhoneFormField` reports a non-empty number that is not yet possible as the field error `material.phone-field.incomplete`; `PhoneField` signals it with `onValidityChange`. `defaultCountry` is `'FR'` | `null` |
 | `UrlField` · `UrlFormField` | `string` (as typed) | `''` |
 | `SearchField` · `SearchFormField` | `string`, after `debounceMs` (default `0`) | `''` |
 | `ColorField` · `ColorFormField` | `string` (hex, `'#1e293b'`) | `''` |
@@ -535,7 +536,7 @@ or fails validation.
 | Field · wrapper | Form value | Empty default |
 | --- | --- | --- |
 | `NetworkUploadField` · `NetworkUploadFormField` | `mode="single"`: the `string` your `onUpload` resolved (a URL or a key), or `null` after removal. `mode="multiple"`: `string[]` | `undefined` / `[]` |
-| `S3UploadField` · `S3UploadFormField` | as above; the value is `publicUrl` from `getPresignedUrl` | `undefined` / `[]` |
+| `S3UploadField` · `S3UploadFormField` | as above; the value is `publicUrl` (PUT) or `value` (POST) from `getPresignedUrl` | `undefined` / `[]` |
 | `ImageField`, `ImageS3Field` · `ImageFormField`, `ImageS3FormField` | `string \| null` (the uploaded URL) | `undefined` |
 | `FileListField`, `FileListS3Field` · `FileListFormField`, `FileListS3FormField` | `string[]` | `[]` |
 | `FilesFormField` | `mode="single"`: `string \| null`. `mode="multiple"`: `string[]` (typed or picked URLs) | `null` / `[]` |

package/docs/roadmap.md

@@ -6,8 +6,6 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Now
 
-- **Link navigation** — `TabsNav` and `SegmentedNav` render route tabs and segmented navigation as a `nav` of links with `aria-current="page"`, looking like Tabs and the segmented ToggleGroup, plus `useTabParam` to keep the current tab in the URL. Tracked in [#2029](https://github.com/softistx/nxgt-material/issues/2029).
-
 - **Barcodes and label sheets** — `@nxgt/material/barcode` draws Code 128
   and Data Matrix as accessible SVG (themed, dark-aware, black on white in
   print) and lays labels out on a sheet to print: label size, columns, rows,
@@ -248,6 +246,9 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Later
 
+- **One `onUpload` options object (next major)** — the upload fields'
+  `onUpload(file, onProgress?, signal?)` becomes `onUpload(file, { onProgress,
+  signal })`, like the editor's upload context.
 - **A strict theme `motif` (4.0)** — a theme background's `motif` with an
   unknown key, a `layout` or `density` outside its list or a bad `icons` is
   dropped in 3.22 (`@nxgt/material/themes`'s `defineTheme` warns for each one in
@@ -363,6 +364,8 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **Link navigation (3.66.0)** — `TabsNav` and `SegmentedNav` render route tabs and segmented navigation as a `nav` of links with `aria-current="page"`, looking like Tabs and the segmented ToggleGroup, plus `useTabParam`, `skipTabChange` and `tabIds` to keep the current tab in the URL. Tracked in [#2029](https://github.com/softistx/nxgt-material/issues/2029).
+
 - **Smaller, easier-to-read components (3.58.0)** — the library's own source
   is kept to files under 200 lines and functions under 80, enforced by a
   check, so a component is quicker to read and to fix. No API or behaviour

package/docs/troubleshooting.md

@@ -4675,7 +4675,12 @@ expect(await within(button.parentElement!).findByRole('status')).toHaveTextConte
 error)`. The status may be any non-2xx.
 **Why:** the storage rejected the `PUT` to the presigned URL. For `403` the
 usual causes are an expired URL, or a `Content-Type` that differs from the
-one the URL was signed with.
+one the URL was signed with. With a presigned POST target, the policy refused
+the file (size, content type, expiry) and the message names the S3 code when
+it is readable, such as `Upload failed with status 400 (EntityTooLarge)`.
+The field shows it translated (`material.upload.error-status`, `error-status-code`);
+`error.message` in `onError` stays English, and `error` is an `UploadError`
+(`kind`, `status`, `code`).
 **Fix:**
 
 ```ts
@@ -4690,12 +4695,14 @@ const getPresignedUrl = async (file: File) => {
 
 **When:** an `S3UploadField` upload fails immediately. The browser console
 shows a CORS error for the storage host.
-**Why:** the browser blocked the cross-origin `PUT`. The bucket's CORS rules
-do not allow your origin, the `PUT` method, or the headers you send.
+**Why:** the browser blocked the cross-origin `PUT` (or `POST` with a presigned
+POST target). The bucket's CORS rules do not allow your origin, the method, or
+the headers you send; a `Content-Security-Policy` without the bucket host in
+`connect-src` fails the same way.
 **Fix:**
 
 ```json
-[{ "AllowedOrigins": ["https://app.example.com"], "AllowedMethods": ["PUT"], "AllowedHeaders": ["*"] }]
+[{ "AllowedOrigins": ["https://app.example.com"], "AllowedMethods": ["PUT", "POST"], "AllowedHeaders": ["*"] }]
 ```
 
 Apply it on the bucket, with your own origin.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "3.67.0",
+	"version": "3.70.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"