@nxgt/material 3.94.0 → 3.95.1

package/dist/{use-chat-composer-DQ2rTD_q.js → use-chat-composer-DEd6GM2N.js}

@@ -4,28 +4,28 @@ import { t as n } from "./utils-BLfntITJ.js";
 import { n as r } from "./use-shape-morph-BKA_R5P5.js";
 import { n as i, o as a, t as o } from "./dist-DVRQkaTK.js";
 import { i as s, n as c, r as l, t as u } from "./dist-DWZXlCZR.js";
-import { _ as d, a as f, b as p, g as m, h, i as g, m as _, n as v, o as y, r as b, s as x, t as S, v as C, y as w } from "./spinner-D7ol2n_-.js";
+import { _ as d, a as f, b as p, g as m, h, i as g, m as _, n as v, o as y, r as b, s as x, t as S, v as C, y as w } from "./spinner-rk8J5y9O.js";
 import { a as T, i as E, n as D, r as O, t as k } from "./dist-DHdUUM1w.js";
 import { a as A, i as ee } from "./dist-DOK3zo5C.js";
 import { i as j, n as M } from "./in-dialog-D61Yeaol.js";
-import { c as N, l as P, n as te, r as F, t as ne } from "./alert-dialog-BaqK-rmd.js";
+import { c as N, l as P, n as te, r as F, t as ne } from "./alert-dialog-D4r0Kn9h.js";
 import { A as re, C as ie, D as ae, E as oe, O as se, S as I, T as ce, _ as le, a as ue, b as de, d as fe, f as pe, g as me, h as he, i as ge, k as _e, l as ve, m as ye, n as be, o as xe, p as Se, r as Ce, s as we, t as Te, u as Ee, v as De, w as Oe, x as ke, y as Ae } from "./floating-ui.dom-KkZSW8_E.js";
-import { D as je, E as Me, N as Ne, O as Pe, c as Fe, d as Ie, f as Le, i as Re, k as ze, m as Be, n as Ve, o as He, p as Ue, t as We, u as Ge } from "./dropdown-menu-CawkIlW8.js";
+import { D as je, E as Me, N as Ne, O as Pe, c as Fe, d as Ie, f as Le, i as Re, k as ze, m as Be, n as Ve, o as He, p as Ue, t as We, u as Ge } from "./dropdown-menu-BvtBDoSD.js";
 import { a as Ke, i as qe, n as Je } from "./field-blur-context-BLGgf_3z.js";
-import { i as Ye, n as Xe, r as Ze, t as Qe } from "./popover-QQYPWzw6.js";
+import { i as Ye, n as Xe, r as Ze, t as Qe } from "./popover-XBAX2Shp.js";
 import { a as $e, i as et, n as tt, o as nt, t as rt } from "./bubble-input-CQwVSoU3.js";
-import { d as it, n as at, r as ot, t as st } from "./tabs-DyiFTy5g.js";
-import { a as ct, n as lt, o as ut, s as dt, v as ft, y as pt } from "./toolbar-items-BpOEBsSt.js";
+import { d as it, n as at, r as ot, t as st } from "./tabs-nuYLggwC.js";
+import { a as ct, n as lt, o as ut, s as dt, v as ft, y as pt } from "./toolbar-items-Bo-nMzKJ.js";
 import { t as mt } from "./dist-DkQbkF9T.js";
 import { o as ht, s as gt, t as _t } from "./use-click-lock-Bwg_caHO.js";
 import { a as vt, r as yt } from "./icon-sprites-CaYXzOL4.js";
 import { t as bt } from "./warn-once-C_e47JM8.js";
-import { r as xt, t as St } from "./button-CozGHXAv.js";
-import { a as Ct } from "./translator-VtzVrnLm.js";
+import { r as xt, t as St } from "./button-Z_xcg10A.js";
+import { a as Ct } from "./translator-gdpQeToI.js";
 import { h as wt } from "./get-CTzJAwfc.js";
 import { t as Tt } from "./isEmpty-F_g3jLf8.js";
-import { t as L } from "./use-material-translation-Cx5u36V5.js";
-import { t as R } from "./icon-button-B9WjQ3RO.js";
+import { t as L } from "./use-material-translation-BW5HZMwt.js";
+import { t as R } from "./icon-button-BG438okX.js";
 import { t as Et } from "./use-ssr-media-query-C6M5m8sf.js";
 import { n as Dt, t as Ot } from "./typography-CYEquVeb.js";
 import { n as kt, t as At } from "./util-4heV2LPI.js";
@@ -36,15 +36,14 @@ import { a as Bt } from "./toggle-group-CVMxEpWi.js";
 import { n as Vt } from "./use-slice-reducer-BGkeGtML.js";
 import { t as Ht } from "./browser-only-DQ94lWF8.js";
 import { t as Ut } from "./compose-refs-G4J4kaUA.js";
-import { n as Wt, r as Gt, t as Kt } from "./chip-DMEUGYdC.js";
+import { n as Wt, r as Gt, t as Kt } from "./chip-Bb9SM3Ly.js";
 import { c as qt, o as Jt, r as Yt, s as Xt, t as Zt } from "./input-CC2joTjB.js";
-import { i as Qt, n as $t, t as en } from "./input-group-Df9vp2EZ.js";
-import { t as tn } from "./text-field-BAdY-kpO.js";
+import { a as Qt, n as $t, r as en, t as tn } from "./text-field-DOndWDT5.js";
 import { r as nn } from "./use-csp-nonce-ZKs9k-ov.js";
-import { t as rn } from "./empty-state-sRVjgCis.js";
+import { t as rn } from "./empty-state-n2zb23YG.js";
 import { t as an } from "./skeleton-DSdtr2qc.js";
-import { l as on, n as sn, o as cn, r as ln, s as un, t as dn, u as fn } from "./dialog-H40HjqXN.js";
-import { t as pn } from "./icon-badge-CXgvqMsM.js";
+import { l as on, n as sn, o as cn, r as ln, s as un, t as dn, u as fn } from "./dialog-CFuONiW5.js";
+import { t as pn } from "./icon-badge-B2ns44Cz.js";
 import { H as mn, V as hn, X as gn, bt as _n, it as vn, lt as yn, n as bn, t as xn, xt as Sn, yt as Cn } from "./dist-moutbfbd.js";
 import { t as wn } from "./markdown-Dw_uH7j7.js";
 import { r as Tn, t as En } from "./create-store-Dqp-PLLn.js";
@@ -7094,7 +7093,7 @@ function j_({ className: e, children: t, ...r }) {
 }
 function M_({ className: e, children: t, disabled: r = !1, showTrigger: i = !0, showClear: a = !1, size: o = "default", leading: s, suffix: c, labelId: l, anchorRef: u, ...d }) {
 	let f = z.useContext(f_), p = __();
-	return /* @__PURE__ */ K(en, {
+	return /* @__PURE__ */ K($t, {
 		ref: Ut(u, f ?? void 0),
 		...qt({
 			size: o,
@@ -7102,7 +7101,7 @@ function M_({ className: e, children: t, disabled: r = !1, showTrigger: i = !0,
 		}),
 		className: n("w-full", o === "sm" && "h-9 pointer-coarse:h-11", o === "lg" && "h-13 md:*:data-[slot=input-group-control]:text-base", e),
 		children: [
-			s ? /* @__PURE__ */ G($t, {
+			s ? /* @__PURE__ */ G(en, {
 				align: "inline-start",
 				className: "ps-2.5",
 				children: /* @__PURE__ */ G("span", {
@@ -7116,12 +7115,12 @@ function M_({ className: e, children: t, disabled: r = !1, showTrigger: i = !0,
 				className: n("h-full", !s && "ps-3"),
 				...d
 			}),
-			c ? /* @__PURE__ */ G($t, {
+			c ? /* @__PURE__ */ G(en, {
 				align: "inline-end",
 				className: "pe-1",
 				children: c
 			}) : null,
-			i || a ? /* @__PURE__ */ G($t, {
+			i || a ? /* @__PURE__ */ G(en, {
 				align: "inline-end",
 				className: "gap-0.5 pe-1.5 has-[>button]:pe-1.5",
 				children: /* @__PURE__ */ G(m_, {
@@ -11180,7 +11179,7 @@ var eS = (e = {}) => Tn({
 		let [{ default: t }, { lowlight: n }, { richCodeBlock: r }] = await Promise.all([
 			import("./dist-CRMFGjng.js"),
 			import("./lowlight-OtcjU2Sa.js"),
-			import("./rich-code-block-DKJ8eKzL.js")
+			import("./rich-code-block-DP2RT7pV.js")
 		]);
 		return [r(t, {
 			lowlight: n,
@@ -12417,7 +12416,7 @@ var gC = () => Tn({
 //#region lib/components/ui/fields/search-field/search-field-end.tsx
 function xC({ shortcut: e, loading: t, filled: n, disabled: r, onClear: i }) {
 	let { t: a } = L(), o = e && !n && !t && !r, s = n && !t && !r;
-	return !o && !s && !t ? null : /* @__PURE__ */ K($t, {
+	return !o && !s && !t ? null : /* @__PURE__ */ K(en, {
 		align: "inline-end",
 		className: "pe-2.5 has-[>button]:pe-2.5 has-[>kbd]:pe-[0.275rem]",
 		children: [
@@ -12453,10 +12452,10 @@ function xC({ shortcut: e, loading: t, filled: n, disabled: r, onClear: i }) {
 //#region lib/components/ui/fields/search-field/search-box.tsx
 function SC({ search: e, error: t, loading: n, shortcut: r, placeholder: i, disabled: a, ...o }) {
 	let { t: s } = L();
-	return /* @__PURE__ */ K(en, {
+	return /* @__PURE__ */ K($t, {
 		"data-disabled": a || void 0,
 		children: [
-			/* @__PURE__ */ G($t, {
+			/* @__PURE__ */ G(en, {
 				align: "inline-start",
 				className: "ps-2.5",
 				children: /* @__PURE__ */ G("span", {

package/dist/{use-heading-spy-17B5xa7B.js → use-heading-spy-n_wPa5jC.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-BaqK-rmd.js";
-import { a as l } from "./button-CozGHXAv.js";
-import { i as u } from "./translate-material-DlMetRSJ.js";
-import { t as d } from "./use-material-translation-Cx5u36V5.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-D4r0Kn9h.js";
+import { a as l } from "./button-Z_xcg10A.js";
+import { i as u } from "./translate-material-H5GMStyF.js";
+import { t as d } from "./use-material-translation-BW5HZMwt.js";
 import { _ as f, g as p, h as m, t as h, v as g, y as _ } from "./date.utils-JTEIo3mM.js";
 import { useCallback as v, useEffect as y, useMemo as b, useRef as x, useState as S } from "react";
 import { Fragment as C, jsx as w, jsxs as T } from "react/jsx-runtime";

package/dist/{use-material-translation-Cx5u36V5.js → use-material-translation-BW5HZMwt.js}

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

package/dist/{use-return-focus-S7g7q_Yn.js → use-return-focus-BC4sGh1b.js}

@@ -1,6 +1,6 @@
 import { o as e, r as t } from "./dist-DVRQkaTK.js";
 import { i as n, n as r, r as i, t as a } from "./dist-DWZXlCZR.js";
-import { C as o, S as s, x as c } from "./spinner-D7ol2n_-.js";
+import { C as o, S as s, x as c } from "./spinner-rk8J5y9O.js";
 import { a as l, i as u, r as d } from "./dist-DHdUUM1w.js";
 import { c as f, i as p, l as m, o as h, r as g, s as ee } from "./in-dialog-D61Yeaol.js";
 import { r as te } from "./escape-owner-DpaP0lm1.js";

package/docs/README.md

@@ -36,6 +36,7 @@ detail: every option, the second example, and the traps.
 | [Moving to TopAppBar](guides/migrating-to-top-app-bar.md) | Your app uses `AppHeader`, `TopAppBar`'s `variant` / `headline`, the shell's `'center'` / `'medium'` / `'large'` header values or the `app-header*` slots: each old spelling and its replacement, the visual changes, the slot rename planned for the next major |
 | [Migrating to 3.0](guides/migrating-to-3.md) | You are upgrading from 2.x: the React 19.3 and React Router 8.5 peers, `ActivityLayout`'s default route transition, `use(browser())` in server HTML, and each API removed in 3.0 with what replaces it |
 | [Date and time fields: from 2.x](guides/date-time-fields-2-x.md) | Your app used `DateField`, `DateRangeField`, `TimeField` or `TimePicker` before their redesign: each change in look and behaviour, the 2.x ways back that 3.0 removed, and what to change in tests |
+| [The Refined field look](guides/field-look-refined.md) | Your fields look different after the Refined release (card surface, 3:1 border, 4px focus ring, no filled tint, `NumberField` steppers inside the box, `QuantityField` in one box) and you want the states, the test changes, the tokens, or a detail of the earlier look back |
 | [The field look (2.x)](guides/field-look-2-x.md) | Your fields or pickers look different after an upgrade (8px corners, the focus halo, a dashed read-only, a 44px `NativeSelect`, a list connected to its trigger, a `CountryField` with no chip, new group headers, the date and time fields' boxes) and you want to know what changed or get the earlier look back |
 | [Migrating to the Vite plugin](guides/migrate-to-vite-plugin.md) | Your app has its own CSP header, nonce, `zod-config`, Inter import or PDF bundling, and you move it to `nxgtMaterial()`: search → replace pairs, each with how to verify |
 | [Server lists in the URL](guides/server-lists-url.md) | A list's filter lives in the URL: parse it in a React Router loader with the codec in `@nxgt/material-core/filter`, feed the `Filter` bar's `query`, write it back on `onQueryChange` |

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

@@ -359,21 +359,21 @@ Storybook: `Date & time/Pickers surfaces/Phone sheet`, `/Popover` and `/Cancel`.
 ### The tonal field
 
 `DateField`, `DateRangeField` and `TimeField` (and their `*FormField`
-wrappers) share one style: a box tinted with the primary colour, no
-border at rest, and a 2px primary boundary while a segment has focus or the
-picker is open. While the box has focus every segment is a tint chip, and the
-focused one a primary pill (bold, a little larger, on a spring; none of it
-with `prefers-reduced-motion`). The open button is a tint circle, primary
-while the picker is open. An invalid field gets an error boundary and tint, a
-disabled one the plain disabled box.  On a phone the chips are drawn text-wide inside the 44px segments.
-In forced colours the box keeps a 1px system border and the pill is
-`Highlight`.
-
-At rest the box has no boundary, which WCAG 1.4.11 allows because the field is
-identified by its label, its text (the placeholder reaches 4.5:1 against the
-fill) and its open button (the icon reaches 3:1). The focus boundary reaches 3:1
-against the page, and the pill 3:1 against the fill (`Date & time/Fields
-expressive` → Contrast).
+wrappers) share one style, the field box of the text fields: the card as
+surface, a 1px border at rest, and the primary border with a 4px ring while a
+segment has focus or the picker is open (an error takes the error border and
+ring, read-only is dashed, disabled recessed). While the box has focus every
+segment is a tint chip, and the focused one a primary pill (bold, a little
+larger, on a spring; none of it with `prefers-reduced-motion`). The open button
+is a tint circle, primary while the picker is open. An invalid field gets the
+error border and ring, a disabled one the plain disabled box. On a phone the
+chips are drawn text-wide inside the 44px segments. In forced colours the box
+keeps a system border and the pill is `Highlight`.
+
+At rest the box has a 1px border that reaches 3:1 against the card (WCAG
+1.4.11), and the placeholder reaches 4.5:1 against the fill and the open
+button's icon 3:1. The focus ring reaches 3:1 against the page, and the pill
+3:1 against the fill (`Date & time/Fields expressive` → Contrast).
 
 The field's calendar and picker share it.
 
@@ -686,8 +686,9 @@ value shows the segments' placeholders. The box is the shared field box
 `data-focused` (while a segment has focus), `data-invalid` and
 `data-disabled`, set only when true, and the field box draws the filled
 tint, the open and focus looks and the red border of an invalid field from
-them; the field draws its own tonal box over it (see [The tonal
-field](#the-tonal-field)). With no value, the first pick in a column
+them. The typed box only adds the ring while the picker is open and while a
+trigger button around it has keyboard focus; the error look is the shared
+field box's (see [The tonal field](#the-tonal-field)). With no value, the first pick in a column
 (`variant="columns"`) starts from midnight today. In the tiles, a tile with no value starts from its lowest
 value on an increase and its highest on a decrease.
 
@@ -841,13 +842,14 @@ export function DueAt() {
 (`material.age-field.unit-day`, `unit-week`, `unit-month`, `unit-year`: "1 month",
 "2 months", « 2 mois »), and a polite status says the whole age when it changes
 (`material.age-field.reading`). `ageReading(t, 2, 'month')` gives the same text
-for your own use. The unit picker is named "Age unit" (`material.age-field.unit`).
+for your own use. The unit chip reads "Age unit: months" and the menu it opens
+is named "Age unit" (`material.age-field.unit`).
 
 **In tests.** One `group` named by the label, a `spinbutton` for the number
-and a `combobox` named "Age unit":
+and a `button` named "Age unit: months" (the chip) that opens a menu of options:
 
 ```ts
-await user.click(screen.getByRole('combobox', { name: 'Age unit' }));
+await user.click(screen.getByRole('button', { name: /^Age unit/ }));
 await user.click(await screen.findByRole('option', { name: 'years' }));
 ```
 
@@ -919,9 +921,9 @@ its number pad). A button at its limit is `aria-disabled`, not `disabled`, so
 a focused one keeps the focus.
 
 **Look.** The tonal box of the date fields, a leading timer icon
-(decorative), then the amounts and the pair: no border at rest, a 2px primary
-boundary while anything inside has focus, an error boundary and tint when
-invalid, the disabled box as the other fields. Every focus ring is drawn
+(decorative), then the amounts and the pair: the field box's border at rest,
+the primary border and 4px ring while anything inside has focus, the error
+border and ring when invalid, the disabled box as the other fields. Every focus ring is drawn
 inside the field. The buttons are 32px (44px on a coarse pointer, where the
 field grows to 52px so they keep 4px around them); every segment has a 44px
 hit area on a phone. The segments read left to right in every direction, as

package/docs/components/form-fields.md

@@ -7,6 +7,12 @@ them into a form, and [what each field emits](../guides/forms.md#what-each-field
 for the value type each one writes. Everything is imported from
 `@nxgt/material/components`.
 
+The text-like fields share one box, drawn in the Refined look (the card
+surface, a 3:1 border, a 1px primary border with a 4px ring on focus, no tint
+once filled). [The Refined field look](../guides/field-look-refined.md) has
+its states, what moved for tests (the `NumberField` and `QuantityField` tab
+order and roles) and the tokens that tune it.
+
 | | Component | What it does |
 | --- | --- | --- |
 | <img src="../previews/form-fields-field.webp" width="96" alt=""> | [Field](#field) | Renders the field matching a config `type` |
@@ -485,7 +491,7 @@ import { User } from 'lucide-react';
 | `label` | `ReactNode` | — | shown above the input |
 | `helperText` | `ReactNode` | — | hint under the input; the error message when `error` |
 | `error` | `boolean` | — | error outline and helper colour |
-| `leading`, `trailing` | `ReactNode` | — | adornments inside the input: an element (icon, button) is its own 32px well; text (`"/ 20"`) goes in a well as tall as the field, centred on the value |
+| `leading`, `trailing` | `ReactNode` | — | adornments inside the input: an element (icon, button) is muted with no well fill, 32px (44px on touch); text (`"/ 20"`) is a muted unit in the same box that hugs the value (the input is sized to it) |
 
 Every other prop is the native `<input>`'s.
 
@@ -636,13 +642,47 @@ export function Quantity() {
 | `min`, `max` | `number` | — | clamps typed and stepped values |
 | `step` | `number` | `1` | the +/− increment |
 | `hideSteppers` | `boolean` | `false` | hides the +/− buttons |
-| `suffix` | `ReactNode` | — | unit shown inside the input box, at its end |
+| `suffix` | `ReactNode` | — | unit shown inside the input box, at its end (the max of a `score`) |
+| `variant` | `'default' \| 'score'` | `'default'` | `score` is a big tabular value with its max, no box at rest and no steppers (see below) |
+| `tone` | `Tone` | none (neutral band) | `score` only: one of the eight named tones or an [app tone](../guides/theming.md#app-tones-on-shape-fab-avatar-statcard-and-the-metric-cards), drawn as text colour plus a shape marker |
+| `locked` | `boolean` | `false` | `score` only: read-only, muted, dashed frame and a lock |
+| `lockedReason` | `ReactNode` | — | `score` only: why it is locked; shown under the value and wired by `aria-describedby` |
 | `aria-label` | `string` | — | names the input when it has no `label` (a part of a larger field) |
 | `aria-labelledby` | `string` | — | names the input by another element's id (a part of a larger field) |
 | `aria-describedby` | `string` | — | more ids describing the input, after its `helperText` (an error the larger field shows) |
 | `onBlur` | `FocusEventHandler` | — | after the typed text is read and `onChange` called |
 | `ref` | `Ref<HTMLInputElement>` | — | reaches the text input (React Hook Form's `field.ref`) |
 
+**Score variant.** `variant="score"` draws a result the user types, such as
+a mark out of 20, a rating or a points total: a big value in tabular figures
+with the maximum (`suffix`, "/ 20") hugging it on the baseline. There is no box
+at rest (a quiet band, about 6% of the tone), a 1px frame on hover and the field
+focus ring on focus; it has no steppers (`hideSteppers` is implied). The tone is
+yours (`tone="success"`, `"warning"`, an app tone...) and is never colour alone:
+the text takes the tone's text colour and a small shape marker precedes the value
+(success a circle, warning a triangle, error a diamond, every other tone a
+square; the marker is `aria-hidden`, so say what the tone means in the label or
+the helper text). An `error` draws the error tone with a border and its
+`helperText` describes the input. `locked` makes the input read-only with a muted
+value, a dashed frame and a lock icon; `lockedReason` shows under the value and
+is added to the input's `aria-describedby`. A locked score keeps a visible focus frame, and a locked score in `error` keeps the error colour on its dashed frame. The styles ship in `styles.css`
+(`number-field-score.css`); `NumberFormField` forwards all of them.
+
+```tsx
+<NumberField
+	variant="score"
+	label="Result"
+	suffix="/ 20"
+	min={0}
+	max={20}
+	step={0.5}
+	tone={mark >= 10 ? 'success' : 'warning'}
+	value={mark}
+	onChange={setMark}
+/>
+<NumberField variant="score" label="Result" suffix="/ 20" value={16} locked lockedReason="Closed on 3 June." />
+```
+
 **Stepper names.** Each +/− button is named after its field: "Increase
 Quantity" / "Decrease Quantity" (`material.number-field.increase-named` and
 `decrease-named`, with the `label` interpolated), so a form with several number
@@ -651,11 +691,21 @@ plain-text `label`, else from `aria-label`; with neither (a field named only
 through `aria-labelledby` included), the buttons keep the bare "Increase" /
 "Decrease".
 
+**Layout and focus.** The box is one `role="group"` with the input and, at its
+end, the Decrease and Increase buttons as a tinted round pair, no dividers
+(32px circles, a 44px target on a coarse pointer; the look is shared with
+`DurationField` through `field-stepper.css`). At `min` or `max` a button is
+`aria-disabled`, so it keeps focus. The value is end-aligned in tabular figures, and a
+`suffix` sits right after it. The input never gets narrower than about 7
+digits. Tab goes input, Decrease, Increase (with a `CalculatorField`: input,
+Open calculator, Decrease, Increase). A test that queries an unnamed
+`getByRole('group')` now also matches the number box: name the group you mean.
+
 **Stepper tooltips.** Each +/− button shows its name in a tooltip on hover and
 on keyboard focus (`:focus-visible`). Focus that a script moves onto it, such
 as a `Sheet` or `Dialog` putting its initial focus on the first tabbable
 control, does not open the tooltip once the user has used the pointer (the browser does not treat that focus as `:focus-visible`), so it does not cover the field's label. The
-buttons stay in the tab order and keep their accessible names. `QuantityField`
+buttons stay in the tab order (input, Decrease, Increase) and keep their accessible names. `QuantityField`
 shares this (React only; the Vue steppers are unchanged, #2264).
 
 **Decimal separator.** After blur (and after +/−) the value is shown with the
@@ -671,7 +721,7 @@ Form's `field.ref` the input itself: `setFocus('amount')` and
 **Emits:** `number | null`.
 **Form wrapper:** `NumberFormField` — `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/NumberField` · **Vue:** `NumberField`, `NumberFormField` (the language separator is React only for now, #763; the stepper names, #2060)
+**Storybook:** `Form fields/NumberField` (`Score`) · **Vue:** `NumberField`, `NumberFormField` (the language separator is React only for now, #763; the stepper names, #2060; the `score` variant is React only)
 
 ---
 
@@ -703,8 +753,9 @@ ratio (`0.15`).
 ![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 }`.
+[`NumberField`](#numberfield)'s number and a unit chip in ONE field box (value
+at the start, the unit as a soft chip with a ⇅ icon, then the round −/+ pair),
+under one label and one error message. The value is `{ value: number | null, unit: string }`.
 `QuantityFormField` wires it to react-hook-form.
 
 ```tsx
@@ -741,8 +792,7 @@ 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 unit is sized to its longest label and shrinks first, the
-number keeps 9rem (see Unit width below).
+phone: the chip truncates before the value does (see The unit chip below).
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -750,27 +800,31 @@ number keeps 9rem (see Unit width below).
 | `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` |
+| `allowCustomUnit` | `boolean` | `false` | the unit menu gets a "Search or type a unit" input and a "Use “x”" item, so a unit outside `units` can be typed; otherwise it is a plain listbox of `units` |
 | `min`, `max`, `step`, `hideSteppers` | | `step` 1 | as `NumberField` |
-| `unitLabel`, `unitPlaceholder` | `string` | "<label> unit" | the unit part's accessible name and its placeholder |
+| `unitLabel`, `unitPlaceholder` | `string` | "<label> unit" | `unitLabel` names the unit part (the menu's name; the chip reads "<unitLabel>: mg"); `unitPlaceholder` shows while no unit is chosen |
 | `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) |
+| `required`, `disabled`, `placeholder`, `id`, `ref` | | | `required` applies to the number only; to require a unit, validate `unit` in the form schema. `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.
-- **Unit width:** the unit part is sized to the longest label of `units`
-  (never under 7rem, never over 55% of the row). It shrinks before the number
-  does: the number's cell keeps 9rem (two 44px steppers and a 44px input), so
-  the input stays a tap target at 375px, also in a padded side sheet. Beyond
-  the cap the label is cut with an ellipsis and the full label
-  is the select's `title` (the `units` select only; a free unit typed past
-  the cap scrolls in its input). No inline style is used for it.
-- **Translations:** `material.quantity-field.unit` and `.unit-named` (English
-  and French) name the unit part.
+  is a textbox named after the label, the unit chip a button named "Unit: mg"
+  (`aria-expanded`; it opens a popover), the menu a listbox named
+  "Dose unit". The message describes the group, the number and the chip, and
+  the number is `aria-invalid` on an error.
+- **Keyboard:** Tab goes value, unit chip, Decrease, Increase. Enter, Space or
+  ArrowDown on the chip opens the menu (focus lands on the list, or on the
+  search with `allowCustomUnit`); the arrows move, Enter picks, Esc closes and
+  returns focus to the chip.
+- **The unit chip:** one focus ring for the whole box, whichever part has
+  focus. The chip is capped at 52% of the box and truncates a long label with
+  an ellipsis (the full label is its `title`); the value keeps room for about
+  4 digits at 360px. A coarse pointer gets 44px targets. Disabled, the chip
+  and the steppers lose their tint. A unit outside `units` shows as typed.
+  The unit still posts as `<name>.unit` (a hidden input) in a native form.
+- **Translations:** `material.quantity-field.unit`, `.unit-named`, `.unit-chip`
+  ("Unit: {label}"), `.search` and `.use-typed` (English and French).
 
 **Emits:** `{ value: number | null, unit: string }`.
 **Form wrapper:** `QuantityFormField` — `control` and `name`, see
@@ -1762,9 +1816,9 @@ describes the switch too, and an `aria-describedby` you pass is kept beside
 these. With `required`, the switch has `aria-required` and the label's asterisk
 is drawn by CSS, so the name and the label text stay "Terms", not "Terms*".
 Without an `id` one is generated, under `SwitchFormField` too (it used to be
-the field's `name`, which two forms on one page shared). The row is tinted
-while the switch is on, from `checked` or, uncontrolled, from `defaultChecked` and each toggle, and carries
-`data-checked="true"` / `"false"`, so select rows that are on with
+the field's `name`, which two forms on one page shared). The row carries
+`data-checked="true"` / `"false"` (the checked state is the track, the thumb
+and the primary label, with no row tint), so select rows that are on with
 `[data-checked="true"]` (a bare `[data-checked]` also matches rows that are
 off).
 

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

@@ -81,7 +81,7 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `items` | `MenuItem[]` | — | `label` (already translated), `url`, `icon`, `footer`, `display` (`'icon'`: a round icon-only button, the label as tooltip and name, in the rail and the expanded sidebar; the phone's menu sheet always shows icon and label; see the [app shell guide](../guides/app-shell.md)), `badge` (`true` a dot, a number a count up to "99+"), `badgeLabel` (see [Badges](../guides/app-shell.md#badges)), and `children` (read by `navigation="top"`, which opens them in a dropdown under a parent that is then only a trigger; by `navigation="two-level"`, which lists them in the panel beside the rail, one level deep; by the phone's menu sheet and the expanded sidebar, which nest them under the parent's own link, unless the entry sets `childrenIn: 'sidebar'`, which keeps them to the sidebar and the top dropdown), `childrenIn`, `group`, `bar`, `priority` for the navigation presets that read them (the drawer reads `group`, the bar `bar` and `priority`; the floating toolbar, not drawn yet, is the only preset still to read them) |
+| `items` | `MenuItem[]` | — | `label` (already translated), `url`, `icon`, `footer`, `display` (`'icon'`: a round icon-only button, the label as tooltip and name, in the rail and the expanded sidebar; the phone's menu sheet always shows icon and label; see the [app shell guide](../guides/app-shell.md)), `badge` (`true` a dot, a number a count up to "99+"), `badgeLabel` (see [Badges](../guides/app-shell.md#badges)), and `children` (read by `navigation="top"`, which opens them in a dropdown under a parent that is then only a trigger; by `navigation="two-level"`, which lists them in the panel beside the rail, one level deep; by the phone's menu sheet and the expanded sidebar, which nest them under the parent's own link, unless the entry sets `childrenIn: 'sidebar'`, which keeps them to the sidebar and the top dropdown), `childrenIn`, `defaultExpanded` (the expanded sidebar folds the entry's children from a chevron button, open at first when `true`, folded when `false`; unset, they are always listed), `group`, `bar`, `priority` for the navigation presets that read them (the drawer reads `group`, the bar `bar` and `priority`; the floating toolbar, not drawn yet, is the only preset still to read them) |
 | `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href`; see the [app shell guide](../guides/app-shell.md). Defaults to the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s link when one is set. |
 | `logo`, `name` | `AppLogo` (`ReactNode \| string \| AppLogoImage`, `AppLogoImage` = `{ src, alt? }`), `string` | — | the app's logo alone in the collapsed rail, named by `name` (also its tooltip); logo and name side by side in the phone's menu sheet |
 | `context` | `ReactNode` | — | a line at the top of the phone's menu sheet, above the brand: the current tenant's name; `name` stays the app's brand; `AppHeader` and `AppSidebar` take it too (see the [app shell guide](../guides/app-shell.md#the-brand-logo-and-name)) |

package/docs/guides/app-shell.md

@@ -414,6 +414,21 @@ its `url`, with its badge, for a parent page that already lists them. Unset
 }
 ```
 
+`defaultExpanded` makes an entry's `children` fold in the expanded sidebar: a
+chevron button after the entry (named "Collapse the group" / "Expand the group",
+`material.navigation.group-collapse` and `group-expand`) shows and hides them,
+`true` opening them at first and `false` folding them (a folded group still opens at first when the current page is one of its children). It is ignored with `display: 'icon'`. Unset, they are always
+listed, as before. The entry stays a link to its `url`; the state is local (not
+remembered), and the phone's menu sheet and the other presets ignore it.
+
+```tsx
+{
+  label: 'Services', url: '/services', icon: 'grid-2',
+  children: [{ label: 'Lab', url: '/lab', icon: 'flask' }],
+  defaultExpanded: true, // open at first, foldable
+}
+```
+
 `MenuItem` also accepts `children`, `group`, `bar` and `priority`. Each is read
 by the presets that use it, and ignored by the others: `bar` and `priority`
 choose the entries of the bottom bar **and** of the floating toolbar (the rest go

package/docs/guides/field-look-2-x.md

@@ -1,5 +1,7 @@
 # The field look (2.x)
 
+> The Refined release later replaced this look (no filled tint, the card surface, a 4px ring): see [The Refined field look](field-look-refined.md). This page keeps the 2.x steps and their ways back.
+
 Every text field and picker trigger shares one look, the **field box**: a
 soft neutral surface, the primary tint once it holds a value, a hairline that
 firms on hover, and the border in primary with a 3px halo on focus. It lives
@@ -411,10 +413,14 @@ the corners and colours are the `--nxgt-field-*` tokens (set them under
 
 ### `NumberField` and `OtpField`
 
-The steppers of a `NumberField` and the slots of an `OtpField` take the
-field radius (`--nxgt-field-radius`, 8px) instead of 6px, so they read as
-parts of the same family as the field beside them. There is no prop for
-it: override the token to round them less, as every field.
+The Refined release moved the `NumberField` steppers inside the box and changed its tab order: see [The Refined field look](field-look-refined.md#tab-order-and-roles-for-tests).
+
+The slots of an `OtpField` take the field radius (`--nxgt-field-radius`, 8px)
+instead of 6px, so they read as parts of the same family as the field beside
+them. A `NumberField` is one field box: its Decrease and Increase buttons are
+tinted round circles inside it (DurationField's look), so there is no
+separate radius for them. There is no prop for either: override the token to
+round them less, as every field.
 
 ```css
 :root {