@nxgt/material 3.68.0 → 3.70.0

package/dist/{use-heading-spy-DaqibCCm.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-BhARh_qC.js";
-import { a as l } from "./button-Du7fJ9i_.js";
-import { i as u } from "./translate-material-DkcuQBNr.js";
-import { t as d } from "./use-material-translation-Bxl8sv1n.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-Bxl8sv1n.js → use-material-translation-BAYyZOcH.js}

@@ -1,4 +1,4 @@
-import { i as e, t } from "./translate-material-DkcuQBNr.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-Y_Kx0QlW.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-DCgDw8eq.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

@@ -19,6 +19,7 @@ for the value type each one writes. Everything is imported from
 | <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 |
@@ -610,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)
@@ -665,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`
 
@@ -1870,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/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

@@ -246,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

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.68.0",
+	"version": "3.70.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"