@nxgt/material 3.94.0 → 3.95.1

package/docs/guides/field-look-refined.md

@@ -0,0 +1,130 @@
+# The Refined field look
+
+Every text field and picker trigger shares one look, the **field box**. This
+page describes the Refined look it has now, what changed for an app that
+upgraded, and how to tune it or bring a detail of the earlier look back. The
+tokens are listed in [Theming, the field box](theming.md#the-field-box); the
+earlier steps are in [The field look (2.x)](field-look-2-x.md).
+
+It is a minor release with no API removed. The one new prop is
+`NumberField`'s `variant="score"`.
+
+## What a field looks like
+
+| State | The box |
+| --- | --- |
+| Rest | the card surface, a 1px border that keeps 3:1 or more against it, 8px corners |
+| Hover | the border firms and the surface takes a 2.5% foreground wash (not on a disabled or read-only field) |
+| Focus, or a picker open | a 1px primary border and a 4px ring (it replaces the 3px halo); one ring for the whole box whichever part has focus |
+| Error | an error-text border with a 1px line inside and, on focus, an error ring |
+| Read-only | a dashed border, no surface |
+| Disabled | a recessed surface and a quieter border |
+| Filled | the same as empty: no primary tint. `data-filled` is still set (an empty attribute, or `"true"` / `"false"` on a `Switch` row and an `UploadField`), so your own CSS can style on it |
+
+Forced colours and reduced motion are unchanged.
+
+Fields that draw their own box follow the same tokens: the OTP slots, the
+verification code slots and recovery input, the inline edit display, the
+`Switcher` search and the `ColorField` swatch. The date, time and duration
+boxes (`DateField`, `DateRangeField`, `TimeField`, `DurationField`) take the
+same focus ring instead of their former 2px inset boundary.
+
+```tsx
+import { TextField } from '@nxgt/material/components';
+
+<TextField label="Name" placeholder="Ada Lovelace" helperText="As on your ID." />
+```
+
+## What each field changed
+
+| Field | Change |
+| --- | --- |
+| `TextField` and the `*Field` text wrappers | `leading` / `trailing` icons and actions are muted with no well fill; a text unit (`"/ 20"`, a currency code) sits inline at the end in muted text. `CurrencyField` follows |
+| `NumberField`, `PercentField`, `CalculatorField` | one `role="group"` box; the value is end-aligned in tabular figures, the suffix hugs it, the Decrease and Increase buttons are a tinted round pair at the end (the `DurationField` look), no dividers |
+| `QuantityField`, `AgeField` | the value, the unit and the pair share one box; the unit is a chip that opens a menu |
+| `NumberField variant="score"` | a big value with its maximum, no box at rest; see [the form fields page](../components/form-fields.md#numberfield) |
+| Date, time and duration fields | the shared focus ring, a dashed hairline when read-only, the recessed surface when disabled |
+
+### Tab order and roles (for tests)
+
+- The `NumberField` order is the input, Decrease, Increase (it was Decrease,
+  input, Increase). With a `CalculatorField`: input, Open calculator,
+  Decrease, Increase. A `QuantityField` is value, unit, Decrease, Increase.
+- The number box is a `group`. A test that queries an unnamed
+  `getByRole('group')` now also matches it: name the one you mean.
+- A `QuantityField` unit is a button named "Unit: mg", not a `combobox`:
+  query `getByRole('button', { name: /unit/i })`.
+- Visual snapshots of fields change; role and name queries hold.
+
+```tsx
+import { QuantityField } from '@nxgt/material/components';
+import type { QuantityValue } from '@nxgt/material/components';
+import { useState } from 'react';
+
+export function Dose() {
+	const [dose, setDose] = useState<QuantityValue>({ value: 5, unit: 'mg' });
+	return (
+		<QuantityField
+			label="Dose"
+			units={[
+				{ value: 'mg', label: 'mg' },
+				{ value: 'ml', label: 'mL' },
+			]}
+			value={dose}
+			onChange={setDose}
+		/>
+	);
+}
+```
+
+## Tune it
+
+Set the tokens after the import, on `:root` and again under `.dark`
+(`--nxgt-field-border` and the like follow `--card` and `--foreground`, so a
+formula you write once usually serves both):
+
+```css
+@import "@nxgt/material/styles.css";
+
+:root,
+.dark,
+[data-theme="dark"] {
+	--nxgt-field-border: color-mix(in oklab, var(--foreground) 60%, var(--card));
+	--nxgt-field-halo: color-mix(in oklab, var(--primary-text) 32%, transparent);
+}
+```
+
+Lightening the border below 3:1 against the card fails WCAG 1.4.11; the story
+`Guides/Accessibility/Field contrast` measures the shipped values.
+
+## Getting a detail of the earlier look back
+
+**A tint on a filled field.** The `--nxgt-field-bg-filled` tokens are kept but
+alias the rest surface, and nothing paints from them any more. Style on
+`data-filled` instead; an unlayered rule beats the field box's layer. The selector excludes `"false"` because the field box sets an empty `data-filled`, while a `Switch` row and an `UploadField` write a boolean, so an off switch or an empty upload renders `data-filled="false"`:
+
+```css
+.nxgt-field-box[data-filled]:not([data-filled="false"]) {
+	background-color: color-mix(in oklab, var(--primary) 10%, transparent);
+}
+
+.dark .nxgt-field-box[data-filled]:not([data-filled="false"]),
+[data-theme="dark"] .nxgt-field-box[data-filled]:not([data-filled="false"]) {
+	background-color: color-mix(in oklab, var(--primary) 26%, transparent);
+}
+```
+
+**The 3px halo and the translucent surface.** Set `--nxgt-field-halo` and
+`--nxgt-field-bg` (for example to `color-mix(in oklab, var(--muted) 5%, transparent)`).
+A halo's width is fixed at 4px.
+
+**The 12px corners.** `--nxgt-field-radius: 0.75rem`.
+
+**NumberField steppers, order and box.** There is no prop for the old outlined
+buttons around the input or the old tab order.
+
+## Related
+
+- [Theming, the field box](theming.md#the-field-box) lists every token.
+- [Form fields](../components/form-fields.md) has each field's props.
+- [Troubleshooting](../troubleshooting.md#a-filled-field-has-no-primary-tint-after-upgrading) covers the lost filled tint.

package/docs/guides/layouts.md

@@ -207,7 +207,8 @@ dashboard, a list and detail, a form and dialog, a table and settings, a dense
 detail page, a status board, a landing page, a search dialog with its results
 page, a team feed, the sign-in, sign-up and forgotten-password screens, a
 gallery of pictures, settings with sections, a messages thread, an overview of
-rearrangeable widgets on `DashboardGrid` and a document editor. Start from the
+rearrangeable widgets on `DashboardGrid`, a document editor and an entry sheet (one row per person with a
+mark out of a total, a comment behind a toggle, locked rows and one sticky Save). Start from the
 closest one and replace the data.
 
 ## See also

package/docs/guides/theming.md

@@ -71,6 +71,7 @@ at the top are needed is in [getting started](../getting-started.md#styles).
 | `--primary-text` | `text-primary-text` | primary drawn as text or an icon on a page, card or popover surface: `Typography tone="primary"`, links, the `Alert` primary icon, selected labels. In light, `--primary` mixed toward black: 96 % at most, solved lower on a tinted page so a tonal Button label on a striped, selected or header row, or straight on the page ground, reaches 4.6:1 (79 % on teal, 76 % on corail; read the shipped theme file for each preset); in dark, `--primary` mixed 60 % with white (`color-mix(in oklab, var(--primary) 40%, white)`), well over 4.5:1 on `--background` and `--card` |
 | `--primary-indicator` | `bg-primary-indicator`, `border-primary-indicator`, `ring-primary-indicator`, `stroke-primary-indicator` | primary drawn as a non-text mark that carries a state (WCAG 1.4.11, 3:1): an active bar or dot, a selected or focused border, a ring, a spinner arc. Equal to `--primary` in light; in dark, `--primary` mixed 25 % with white (`color-mix(in oklab, var(--primary) 75%, white)`), 4.8:1 on `--background`, 4.5:1 on `--card`, 4.2:1 on `--muted` (`--primary` itself gives 2.7, 2.5 and 2.3:1) |
 | `--error-text` | `text-error-text` | error drawn as text: field messages, `HelperText` in its error state, form and dialog errors, `variant="error"` menu items |
+| `--success-text`, `--warning-text` | `text-success-text`, `text-warning-text` | success and warning drawn as text: a field's valid or caution message. Solved like `--error-text` for every theme and preset: 4.5:1 or more on `--background` and `--card`, in light and dark |
 | `--destructive` | `bg-destructive`, `text-destructive` | deprecated alias of `--error`: the light theme sets it to `var(--error)`, the dark theme keeps its own value; use `--error` |
 | `--ground` | `bg-ground` | the page's ground under `ActivityLayout`: the tinted colour the cards stand on (see [Page ground](#page-ground)) |
 | `--surface-container`, `--surface-container-high` | `bg-surface-container`, `bg-surface-container-high` | tinted chrome: `--surface-container` is the scrolled top app bar (draw it with a 1px `--border` hairline), the primary at 12 % over `--ground` in light (less for a very dark primary, solved per seed) and 26 % in dark; `--surface-container-high` is raised chrome such as a search field, the primary at 16 % over `--background` in light (+4 points over the solved share) and 34 % over `--ground` in dark. Foreground, muted foreground and primary text keep 4.5:1 or more on both, in every preset |
@@ -828,29 +829,36 @@ export function DangerZone() {
 ## The field box
 
 Text fields and picker triggers share one look, the field box
-(`nxgt-field-box` in `styles.css`), drawn from its own tokens. `fg`, `bg`,
-`primary`, `primary-text` and `error` below stand for `--foreground`,
-`--background`, `--primary`, `--primary-text` and `--error`; "a % b" is
-`color-mix(in oklab, a %, b)`, and "a %" is the same over `transparent`.
-
-| Token | Light | Dark | Used for |
-| --- | --- | --- | --- |
-| `--nxgt-field-bg` | fg 2% bg | fg 5% bg | the empty surface |
-| `--nxgt-field-bg-hover` | fg 6.5% bg | fg 9% bg | the empty surface under the pointer |
-| `--nxgt-field-bg-filled` | primary 10% | primary 26% | the tint once the field holds a value |
-| `--nxgt-field-bg-filled-hover` | primary 14% | primary 32% | the same under the pointer |
-| `--nxgt-field-bg-invalid` | error 5% bg | error 10% bg | the faint wash of a field in error |
-| `--nxgt-field-border` | fg 13% | fg 16% | the hairline |
-| `--nxgt-field-border-hover` | fg 24% | fg 32% | the hairline under the pointer |
-| `--nxgt-field-focus` | `var(--primary-text)` | `var(--primary-text)` | the focused or open border |
-| `--nxgt-field-halo` | primary-text 22% | primary-text 35% | the 3px halo around a focused field |
-| `--nxgt-field-halo-invalid` | error 22% | error 40% | the halo of a focused field in error |
-| `--nxgt-field-well` | fg 6% | fg 10% | the round well behind a trigger's chevron, flag or avatar |
-| `--nxgt-field-radius` | `0.5rem` | the same | the corners (8px, the buttons' radius; `0.75rem` gives the earlier 12px) |
-| `--nxgt-field-inner-radius` | `0.25rem` | the same | the facing corners when a picker's list opens against its trigger |
-| `--nxgt-field-list-shadow` | a fg 9% ring and a soft drop shadow | a fg 12% ring and a deeper shadow | the shadow of that list |
-| `--nxgt-option-ring` | primary-text 70% | primary-text 50% | the 1px keyboard ring of a list or menu row: the lightest that keeps 3:1 against the row and the popover |
-| `--nxgt-option-muted` | muted-foreground 78% toward foreground | the same mix | muted text on a row or a filled box: a row's description and suffix ("GMT+2", "+33"), a box's suffix and `TreeSelectField`'s path; keeps 4.5:1 on the 18 % chosen row |
+(`nxgt-field-box` in `styles.css`), drawn from its own tokens: the Refined
+look, on the card surface, with a border that keeps 3:1 against it, a 1px
+primary border with a 4px ring on focus, and no tint once the field holds a
+value ([the Refined field look](field-look-refined.md) has the states and the
+way back). `fg`, `card`, `primary-text` and `error` below stand for
+`--foreground`, `--card`, `--primary-text` and `--error`; "a % b" is
+`color-mix(in oklab, a %, b)`, and "a %" is the same over `transparent`. Light
+and dark take the same formulas: they follow `--card` and `--foreground`.
+
+| Token | Value | Used for |
+| --- | --- | --- |
+| `--nxgt-field-bg` | `var(--card)` | the surface |
+| `--nxgt-field-bg-hover` | fg 2.5% card | the surface under the pointer |
+| `--nxgt-field-bg-disabled` | fg 5% card | the recessed surface of a disabled field |
+| `--nxgt-field-bg-filled`, `--nxgt-field-bg-filled-hover` | the two above | kept so a read resolves; an override no longer paints (nothing uses them): style on `data-filled` |
+| `--nxgt-field-bg-invalid` | `var(--nxgt-field-bg)` | alias: an error no longer washes the surface |
+| `--nxgt-field-border` | fg 52% card | the rest border (3:1 or more against the card) |
+| `--nxgt-field-border-hover` | fg 74% card | the border under the pointer |
+| `--nxgt-field-border-readonly` | fg 50% card | the dashed border of a read-only field (3:1 or more against the card and the page ground) |
+| `--nxgt-field-border-disabled` | fg 24% card | the border of a disabled field |
+| `--nxgt-field-focus` | `var(--primary-text)` | the focused or open border (1px) |
+| `--nxgt-field-error` | `var(--error-text)` | the border of a field in error |
+| `--nxgt-field-halo` | primary-text 24% | the 4px ring around a focused field |
+| `--nxgt-field-halo-invalid` | error 26% | the ring of a focused field in error |
+| `--nxgt-field-well` | fg 6% (dark: fg 10%) | the round well behind a trigger's chevron, flag or avatar |
+| `--nxgt-field-radius` | `0.5rem` | the corners (8px, the buttons' radius; `0.75rem` gives the earlier 12px) |
+| `--nxgt-field-inner-radius` | `0.25rem` | the facing corners when a picker's list opens against its trigger |
+| `--nxgt-field-list-shadow` | a fg 9% ring and a soft drop shadow (dark: a fg 12% ring and a deeper shadow) | the shadow of that list |
+| `--nxgt-option-ring` | primary-text 70% (dark: 50%) | the 1px keyboard ring of a list or menu row: the lightest that keeps 3:1 against the row and the popover |
+| `--nxgt-option-muted` | muted-foreground 78% toward foreground | muted text on a row or a filled box: a row's description and suffix ("GMT+2", "+33"), a box's suffix and `TreeSelectField`'s path; keeps 4.5:1 on the 18 % chosen row |
 
 Set them after the import. The colour tokens are declared again under
 `.dark`, so a dark wrapper computes them from its own colours, and a colour
@@ -862,12 +870,12 @@ radii are declared once, on `:root`.
 
 :root {
   --nxgt-field-radius: 0.25rem;
-  --nxgt-field-bg-filled: color-mix(in oklab, var(--primary) 8%, transparent);
+  --nxgt-field-border: color-mix(in oklab, var(--foreground) 60%, var(--card));
 }
 
 .dark,
 [data-theme="dark"] {
-  --nxgt-field-bg-filled: color-mix(in oklab, var(--primary) 20%, transparent);
+  --nxgt-field-border: color-mix(in oklab, var(--foreground) 60%, var(--card));
 }
 ```
 
@@ -882,12 +890,12 @@ knows both, so a `className="rounded-lg"` you pass replaces the field's
 radius instead of sitting beside it. Round parts (the chevron's well, a
 colour swatch) stay `rounded-full`.
 
-The shipped values keep the placeholder and the text at 4.5:1 or more, the
-focus and error borders at 3:1, a filled field 1.15:1 apart from the page and
-1.10:1 apart from an empty one, in both themes; the story
-`Guides/Accessibility/Field contrast` measures them. A lighter dark filled
-tint can fall under 1.10:1; check it with that story. What changed from the
-earlier look, and how to get it back: [The field look (2.x)](field-look-2-x.md).
+The shipped values keep the placeholder and the text at 4.5:1 or more and the
+rest, focus and error borders at 3:1 or more against the card, in every shipped
+theme and both modes; the story `Guides/Accessibility/Field contrast` measures
+them. A border you lighten can fall under 3:1: check it with that story. What
+changed, and how to get the earlier look back: [The Refined field
+look](field-look-refined.md) and [The field look (2.x)](field-look-2-x.md).
 
 ## Links