@12-apps/ui 6.39.20 → 6.41.0

package/src/components/form/NumberField/NumberField.md

@@ -0,0 +1,86 @@
+# NumberField
+
+## Purpose
+
+A **digits-only** numeric input whose value is a `number | null`. For the
+counts, durations and limits settings forms are full of — "prepare in 15 min",
+"keep for 30 days" — where a plain text input lets letters in and a
+`type="number"` field brings scroll-wheel surprises, `e`, `-` and a value that is
+a string.
+
+- `inputMode="numeric"` on the `<input>` itself, so a phone opens its number pad.
+- A non-digit keystroke never reaches the field; a paste keeps only its digits
+  (`"1.500 min"` → `1500`).
+- `suffix` — the unit — is drawn **inside** the field's border, at its end.
+- ArrowUp / ArrowDown move by `step`, never past `min` / `max`.
+- An empty field is `null`. Never `0`, never `NaN`: "cleared" and "zero" stay
+  two different answers.
+
+Built on [`Input`](../Input/Input.md), so it takes the field radius, height,
+border, variants and sizes like every other field.
+
+## Usage
+
+```tsx
+import { NumberField } from '@12-apps/ui/form/NumberField';
+
+const [minutes, setMinutes] = useState<number | null>(15);
+
+<NumberField
+  label="Preparation time"
+  value={minutes}
+  onChange={setMinutes}
+  min={1}
+  max={120}
+  step={5}
+  suffix="min"
+  helperText="Between 1 and 120"
+/>
+```
+
+## Props
+
+Everything [`Input`](../Input/Input.md) takes (`label`, `helperText`, `error`,
+`size`, `variant`, `disabled`, `placeholder`, `data-testid`, …), except the ones
+this field owns (`value`, `onChange`, `type`, `inputMode`, `pattern`, `min`,
+`max`, `step`, `endAdornment`, `maxLength`), plus:
+
+| prop | type | default | effect |
+|---|---|---|---|
+| `value` | `number \| null` | **required** | The value. `null` renders an empty field. |
+| `onChange` | `(value: number \| null) => void` | **required** | Every edit, as a number, or `null` once cleared. Not called when an edit leaves the number unchanged. |
+| `min` | `number` | — | Where ArrowDown stops, where an empty field's first arrow press lands, and what a blur raises a smaller value to. |
+| `max` | `number` | — | Where ArrowUp stops, and what a blur lowers a larger value to. |
+| `step` | `number` | `1` | How far one arrow press moves. |
+| `suffix` | `ReactNode` | — | The unit, inside the field's border. Also read as part of the field's description. |
+
+## Behaviour notes
+
+- **Bounds apply to arrows at once, to typing on blur.** Typing `5` on the way to
+  `50` must not snap to a minimum of `10` under the reader's fingers; the blur
+  brings an out-of-range value back inside.
+- **Digits only means non-negative integers.** There is no minus sign and no
+  decimal separator; a field that needs either is not this one.
+- **At most fifteen digits** — the longest run that is always a safe integer, so
+  a pasted serial number never becomes a rounded float.
+- From empty, either arrow lands on `min` (or `0`): the first press says "give me
+  a number", and the floor is the one both directions agree on.
+- A caller's `onKeyDown` runs first; calling `preventDefault()` in it cancels the
+  field's own handling of that key.
+
+## Accessibility
+
+- `role="spinbutton"` with `aria-valuenow`, `aria-valuemin` and `aria-valuemax`
+  — the arrow keys make it one, and a screen reader then says so, and says where
+  in the range the value sits.
+- The suffix has an id and is in the input's `aria-describedby` (after the
+  helper text), so "15" is announced with its unit.
+- `inputMode="numeric"` and `pattern="[0-9]*"` bring up the numeric keypad on
+  iOS and Android.
+
+## Best practices
+
+- Put the unit in `suffix`, not in the label: "Preparation time" + `min` reads
+  better than "Preparation time (min)", and the unit stays next to the number.
+- Store `null` as "not set" on the host side. Coercing it to `0` is how a
+  cleared field ends up submitting a value nobody chose.

package/src/components/form/NumberField/NumberField.tsx

@@ -0,0 +1,88 @@
+import React, { useCallback, useId } from 'react';
+
+import { Input } from '../Input';
+
+import { clamp, formatValue, isRefusedKey, parseDigits, stepValue } from './NumberField.helpers';
+import type { NumberFieldProps } from './NumberField.types';
+
+/**
+ * A digits-only number input whose value is a `number | null`.
+ *
+ * - `inputMode="numeric"` on the `<input>` itself, so a phone opens its number
+ *   pad (the attribute does nothing anywhere else — see `Input.types.ts`).
+ * - A non-digit keystroke never reaches the field, and a paste keeps only its
+ *   digits: `"1.500 min"` pastes as `1500`.
+ * - `suffix` is drawn inside the field's border, and read as its description.
+ * - ArrowUp / ArrowDown move by `step`, never past `min` / `max`. Typing may go
+ *   out of bounds for a moment (typing `5` on the way to `50` must not snap to a
+ *   minimum of 10); the blur brings it back inside.
+ * - Clearing the field reports `null`, not `0` and not `NaN`.
+ *
+ * `role="spinbutton"` with `aria-valuenow` / `-min` / `-max`, because that is
+ * what the arrow keys make it — a screen reader then says so, and says where
+ * in the range the value sits.
+ */
+export const NumberField = React.forwardRef<HTMLInputElement, NumberFieldProps>(function NumberField(
+  props,
+  ref,
+) {
+  const {
+    value, onChange, min, max, step = 1, suffix, onKeyDown, onBlur, inputProps, id: idProp,
+    'aria-describedby': callerDescribedBy, ...rest
+  } = props;
+  const generated = useId();
+  const id = idProp ?? `number-field-${generated}`;
+  const suffixId = `${id}-suffix`;
+
+  const commit = useCallback(
+    (next: number | null) => {
+      if (next !== value) onChange(next);
+    },
+    [value, onChange],
+  );
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+    onKeyDown?.(event);
+    if (event.defaultPrevented) return;
+    if (event.key === 'ArrowUp' || event.key === 'ArrowDown') {
+      event.preventDefault();
+      commit(stepValue(value, event.key === 'ArrowUp' ? 1 : -1, step, { min, max }));
+    } else if (isRefusedKey(event)) {
+      event.preventDefault();
+    }
+  };
+
+  const handleBlur = (event: React.FocusEvent<HTMLInputElement>) => {
+    if (value !== null) commit(clamp(value, { min, max }));
+    onBlur?.(event);
+  };
+
+  const describedBy = [callerDescribedBy, suffix != null ? suffixId : undefined].filter(Boolean).join(' ');
+
+  return (
+    <Input
+      ref={ref}
+      {...rest}
+      id={id}
+      type="text"
+      autoComplete="off"
+      value={formatValue(value)}
+      onChange={(event) => commit(parseDigits(event.target.value))}
+      onBlur={handleBlur}
+      aria-describedby={describedBy || undefined}
+      endAdornment={suffix != null ? <span id={suffixId}>{suffix}</span> : undefined}
+      inputProps={{
+        ...inputProps,
+        inputMode: 'numeric',
+        pattern: '[0-9]*',
+        role: 'spinbutton',
+        'aria-valuenow': value ?? undefined,
+        'aria-valuemin': min,
+        'aria-valuemax': max,
+        onKeyDown: handleKeyDown,
+      }}
+    />
+  );
+});
+
+NumberField.displayName = 'NumberField';

package/src/components/form/NumberField/NumberField.types.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react';
+
+import type { InputProps } from '../Input/Input.types';
+
+/**
+ * What `NumberField` takes over from `Input`: the value and its change are
+ * numbers here, not strings, and the element's type, keyboard and trailing
+ * slot are the field's own.
+ */
+type OwnedInputProps =
+  | 'value'
+  | 'defaultValue'
+  | 'onChange'
+  | 'type'
+  | 'inputMode'
+  | 'pattern'
+  | 'min'
+  | 'max'
+  | 'step'
+  | 'endAdornment'
+  | 'maxLength';
+
+export interface NumberFieldProps extends Omit<InputProps, OwnedInputProps> {
+  /** The value. `null` is an empty field — never `0`, never `NaN`. */
+  value: number | null;
+  /** Every edit, as the number it now reads, or `null` once cleared. */
+  onChange: (value: number | null) => void;
+  /**
+   * The lowest value ArrowDown reaches, and what a blur raises a smaller one
+   * to. Digits only, so the field never holds a negative number whatever this
+   * says.
+   */
+  min?: number;
+  /** The highest value ArrowUp reaches, and what a blur lowers a larger one to. */
+  max?: number;
+  /** How far one ArrowUp / ArrowDown moves the value. Defaults to 1. */
+  step?: number;
+  /**
+   * The unit, drawn INSIDE the field's border at its end — "min", "%", "kg".
+   * Also read to screen readers as part of the field's description.
+   */
+  suffix?: ReactNode;
+}

package/src/components/form/NumberField/index.ts

@@ -0,0 +1,2 @@
+export { NumberField } from './NumberField';
+export type { NumberFieldProps } from './NumberField.types';

package/src/components/form/NumberField/tests.md

@@ -0,0 +1,51 @@
+# NumberField Test Status Tracking
+
+## Test Files Status
+
+- [x] NumberField.test.stories.tsx created
+- [x] `__tests__/NumberField.test.tsx` (Vitest: helpers + component)
+- [x] Core categories implemented (interaction, keyboard, screen reader, visual/layout, edge cases)
+
+## Storybook Tests Status
+
+### Test Results
+
+| Test Name                        | Status | Pass/Fail | Notes                                                   |
+| -------------------------------- | ------ | --------- | ------------------------------------------------------- |
+| Typing keeps digits only         | PASS   | Pass      | `1a2-3.e` lands as `123`                                |
+| Paste keeps digits only          | PASS   | Pass      | `1.500 min` reports `1500`                              |
+| Arrows step within bounds        | PASS   | Pass      | step 5, clamped to 5–20; `aria-valuenow` follows        |
+| Clearing reports null            | PASS   | Pass      | reported value is `null`, input empty                   |
+| Blur clamps typed value          | PASS   | Pass      | typed `5` with min 10 becomes `10` on blur              |
+| Suffix inside the border         | PASS   | Pass      | suffix rect inside `.MuiInputBase-root`, right of input |
+| Numeric spinbutton               | PASS   | Pass      | `inputmode`, `aria-value*`, suffix in describedby       |
+
+Legend: Pending | Running | PASS | FAIL
+
+## Static Stories Status
+
+- [x] Default story
+- [x] WithSuffix, WithBounds
+- [x] Empty state story (`null`)
+- [x] Error state story
+- [x] Disabled state story
+- [x] Sizes
+- [x] Edge cases (fifteen digits, long suffix)
+
+## Lint Status
+
+- [x] No lint errors
+- [x] No warnings
+
+## TypeCheck Status
+
+- [x] No type errors
+- [x] All props properly typed
+
+## Overall Component Status
+
+- [x] All tests passing
+- [x] Lint clean
+- [x] TypeCheck clean
+- [x] Stories working
+- [ ] Ready for production (pending review)

package/src/components/form/NumberField/track.md

@@ -0,0 +1,42 @@
+# NumberField
+
+A digits-only numeric input over `Input` whose value is `number | null` (`null`
+is an empty field). `inputMode="numeric"` on the `<input>`, non-digit keystrokes
+refused and pastes reduced to their digits, a `suffix` drawn inside the field,
+and ArrowUp / ArrowDown stepping by `step` within `min` / `max`. Built for the
+`layout/SettingCard` family's forms (FUT-2823) but independent of it.
+
+## Props
+
+- **value** — the number, or `null` for an empty field.
+- **onChange** — every edit as a number, or `null` once cleared.
+- **min** — floor for arrows and for the blur clamp.
+- **max** — ceiling for arrows and for the blur clamp.
+- **step** — how far one arrow press moves (default 1).
+- **suffix** — the unit, inside the field border, read as its description.
+- Everything else `Input` takes, minus the props this field owns.
+
+## Lint
+
+- Clean (`pnpm lint:files src/components/form/NumberField`), including the
+  complexity and flakiness gates.
+
+## Type Errors
+
+- None (`pnpm typecheck`, `tsc -p tsconfig.stories.json`).
+
+## Testing Scenarios
+
+- Digits-only typing and paste; `null` on clear; arrow stepping and clamping;
+  blur clamp; suffix geometry; spinbutton ARIA; caller `onKeyDown` precedence.
+
+## Storybook Tests List
+
+- Form/NumberField/Tests → 7 interaction stories.
+
+## Current
+
+- 2026-09-26 16:40 BRT — v1 shipped with `Input` gaining a merged `inputProps`
+  pass-through (an attribute `Input` does not recognise otherwise lands on the
+  text field's root `<div>`). Remaining TODO: none for v1; a host adoption
+  follows in the origin host.

package/src/components/form/index.ts

@@ -13,6 +13,7 @@ export * from './Input';
 export * from './InputOTP';
 export * from './Label';
 export * from './Menubar';
+export * from './NumberField';
 export * from './PasswordStrength';
 export * from './PhoneInput';
 export * from './RadioGroup';

package/src/components/layout/SettingCard/SettingCard.hooks.ts

@@ -0,0 +1,191 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type RefObject } from 'react';
+
+import { focusFirstTabbable } from '../../feedback/Dialog/Dialog.focus';
+
+import type { SettingCardProps, SettingErrorFormatter, SettingSaveResult } from './SettingCard.types';
+
+/** The sentence a rejected save shows: the host's, else the copy's fallback. */
+export function saveErrorMessage(
+  error: unknown,
+  formatError: SettingErrorFormatter | undefined,
+  fallback: string,
+): string {
+  return formatError?.(error) ?? fallback;
+}
+
+/**
+ * Open state that is controlled when `open` is passed and uncontrolled
+ * otherwise — the shape MUI's own `useControlled` has, without its dev-only
+ * warnings reaching into this package's surface.
+ */
+export function useControllableOpen(
+  open: boolean | undefined,
+  defaultOpen: boolean,
+  onOpenChange: ((open: boolean) => void) | undefined,
+): [boolean, (next: boolean) => void] {
+  const [inner, setInner] = useState(defaultOpen);
+  const controlled = open !== undefined;
+  const value = controlled ? open : inner;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!controlled) setInner(next);
+      onOpenChange?.(next);
+    },
+    [controlled, onOpenChange],
+  );
+
+  return [value, setOpen];
+}
+
+/**
+ * Runs a save that may or may not be async and reports how it went.
+ *
+ * `Promise.resolve().then(save)` rather than `await save()`: it also catches a
+ * handler that throws SYNCHRONOUSLY, which an `await` inside `try` would too —
+ * but it keeps the pending state visible for one tick even when the handler
+ * returns nothing, so a save never "succeeds" in the middle of the click that
+ * started it. A sequence id drops the outcome of a run the card has since
+ * abandoned (closed, or started again).
+ */
+export function useSaveRunner(formatError: SettingErrorFormatter | undefined, fallback: string) {
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const seq = useRef(0);
+
+  useEffect(
+    () => () => {
+      // Unmounted: whatever is still in flight has nobody left to report to.
+      seq.current += 1;
+    },
+    [],
+  );
+
+  const run = useCallback(
+    async (save: () => SettingSaveResult): Promise<boolean> => {
+      const mine = (seq.current += 1);
+      setSaving(true);
+      setError(null);
+      try {
+        await Promise.resolve().then(save);
+        if (seq.current !== mine) return false;
+        setSaving(false);
+        return true;
+      } catch (cause) {
+        if (seq.current !== mine) return false;
+        setSaving(false);
+        setError(saveErrorMessage(cause, formatError, fallback));
+        return false;
+      }
+    },
+    [formatError, fallback],
+  );
+
+  const reset = useCallback(() => {
+    seq.current += 1;
+    setSaving(false);
+    setError(null);
+  }, []);
+
+  return { saving, error, run, reset };
+}
+
+/**
+ * A switch that saves the moment it flips.
+ *
+ * It shows the flip at once (`pending`) and holds it while the save runs; a
+ * success hands back to the host's `checked`, which by then says the same
+ * thing, and a failure drops `pending` so the switch returns to what is
+ * actually saved. A flip while one is in flight is ignored rather than queued:
+ * two racing writes of a boolean have no right answer.
+ */
+export function useAsyncSwitch(options: {
+  checked: boolean;
+  onChange: (checked: boolean) => SettingSaveResult;
+  formatError: SettingErrorFormatter | undefined;
+  fallback: string;
+}) {
+  const { checked, onChange, formatError, fallback } = options;
+  const [pending, setPending] = useState<boolean | null>(null);
+  const { saving, error, run } = useSaveRunner(formatError, fallback);
+
+  const flip = useCallback(
+    async (next: boolean) => {
+      if (saving) return;
+      setPending(next);
+      await run(() => onChange(next));
+      setPending(null);
+    },
+    [saving, run, onChange],
+  );
+
+  return { shown: pending ?? checked, saving, error, flip };
+}
+
+/**
+ * Focus follows the card: into it when it opens, back to the trigger when it
+ * closes.
+ *
+ * Inward, it is the Dialog's own rule (`focusFirstTabbable`, FUT-2696): the
+ * first tabbable descendant, and a caller's `autoFocus` keeps winning. The
+ * card is NOT a trap — it is inline, the rest of the page is still there, and
+ * locking Tab inside it would strand a keyboard user who wants to leave
+ * mid-edit. What it owes them is the round trip: the Edit trigger unmounts
+ * while the card is open, so without the return focus would fall to <body>
+ * and the reader would start again from the top of the page.
+ *
+ * Only a TRANSITION moves focus: a card mounted open (or closed) leaves focus
+ * where the page put it.
+ */
+export function useFocusHandoff(
+  open: boolean,
+  body: RefObject<HTMLElement | null>,
+  trigger: RefObject<HTMLElement | null>,
+): void {
+  const previous = useRef(open);
+
+  useLayoutEffect(() => {
+    if (previous.current === open) return;
+    previous.current = open;
+    if (open && body.current) focusFirstTabbable(body.current);
+    if (!open) trigger.current?.focus();
+  }, [open, body, trigger]);
+}
+
+/**
+ * Everything an editable card DOES, apart from how it looks: its open state,
+ * the save and its outcome, Cancel, and where focus goes.
+ */
+export function useSettingCard(props: SettingCardProps) {
+  const { copy, onSave, onCancel, open: openProp, defaultOpen = false, onOpenChange, formatError } = props;
+  const disabled = props.disabled ?? false;
+  const saveDisabled = props.saveDisabled ?? false;
+  const [open, setOpen] = useControllableOpen(openProp, defaultOpen, onOpenChange);
+  const { saving, error, run, reset } = useSaveRunner(formatError, copy.saveFailed);
+  const bodyRef = useRef<HTMLDivElement>(null);
+  const editRef = useRef<HTMLButtonElement>(null);
+  useFocusHandoff(open, bodyRef, editRef);
+
+  // However the card closed — Cancel, a save, or a controlling host — the
+  // next opening starts without the last one's error.
+  useEffect(() => {
+    if (!open) reset();
+  }, [open, reset]);
+
+  const openCard = useCallback(() => setOpen(true), [setOpen]);
+
+  const cancel = useCallback(() => {
+    if (saving) return;
+    setOpen(false);
+    onCancel?.();
+  }, [saving, setOpen, onCancel]);
+
+  const save = useCallback(() => {
+    if (saving || saveDisabled) return;
+    void run(onSave).then((saved) => {
+      if (saved) setOpen(false);
+    });
+  }, [saving, saveDisabled, run, onSave, setOpen]);
+
+  return { open, disabled, saveDisabled, saving, error, bodyRef, editRef, openCard, cancel, save };
+}

package/src/components/layout/SettingCard/SettingCard.md

@@ -0,0 +1,121 @@
+# SettingCard
+
+## Purpose
+
+One setting, summarised while closed and edited **in place**. A settings screen
+built from these reads as a list of answers ("Sign out after 30 minutes") with
+one Edit each, instead of a wall of open forms.
+
+- **Closed:** title, a status pill, a one-line summary, and Edit.
+- **Open:** Edit opens the card where it is — no dialog, no route change —
+  around the host's form (`children`), a collapsible "learn more" disclosure and
+  Cancel / Save.
+
+The card knows nothing about what it edits. The form, the draft and the save
+are the host's; the card owns the open/closed state, the save's pending and
+failed states, and focus.
+
+Part of the `layout/SettingCard` family, with
+[`SettingToggle`](./SettingToggle.md), [`SettingGroup`](./SettingGroup.md) and
+[`SettingGrid`](./SettingGrid.md).
+
+## Usage
+
+```tsx
+import { SettingCard } from '@12-apps/ui/layout/SettingCard';
+import { NumberField } from '@12-apps/ui/form/NumberField';
+import { useLocaleCopy } from '@12-apps/i18n/react';
+import { SETTING_CARD_COPY } from '@12-apps/ui/locales';
+
+const copy = useLocaleCopy(SETTING_CARD_COPY);
+const [draft, setDraft] = useState<number | null>(saved);
+
+<SettingCard
+  copy={copy}
+  title="Session timeout"
+  summary={`Sign out after ${saved} minutes`}
+  status={{ label: 'On', color: 'success' }}
+  learnMore="A shorter timeout protects shared devices."
+  onCancel={() => setDraft(saved)}
+  onSave={() => api.saveTimeout(draft)}   // may return a promise
+>
+  <NumberField label="Minutes" value={draft} onChange={setDraft} min={5} max={240} suffix="min" />
+</SettingCard>
+```
+
+## Props
+
+| prop | type | default | effect |
+|---|---|---|---|
+| `copy` | `SettingCardCopy` | **required** | Edit / Cancel / Save / Saving / Learn more / the fallback error. No shipped default — pass `EN_US_SETTING_CARD_COPY`, `PT_BR_SETTING_CARD_COPY`, or `SETTING_CARD_COPY` through `useLocaleCopy`. |
+| `title` | `string` | **required** | The setting's name. A heading, and the accessible name of the card's region. |
+| `onSave` | `() => void \| Promise<unknown>` | **required** | Persist the draft. See *Saving* below. |
+| `children` | `ReactNode` | **required** | The form. Rendered only while open. |
+| `summary` | `ReactNode` | — | The one line a closed card shows. Ends in an ellipsis rather than wrapping. |
+| `status` | `{ label: string; color?: ColorValue }` | — | The pill beside the title. `label` is always shown, so colour never carries the meaning alone. |
+| `learnMore` | `ReactNode` | — | Longer explanation behind a disclosure in the open card. Omit for no disclosure. |
+| `onCancel` | `() => void` | — | The card closed without saving. Reset the host's draft here. |
+| `open` / `defaultOpen` / `onOpenChange` | | uncontrolled, closed | Controlled or uncontrolled open state. `onOpenChange` hears Edit, Cancel, Escape and a successful save. |
+| `disabled` | `boolean` | `false` | Disables Edit. |
+| `saveDisabled` | `boolean` | `false` | Disables Save — for a draft the host knows is invalid. |
+| `formatError` | `(error: unknown) => string \| undefined` | — | The sentence to show for a rejected save. `undefined` falls back to `copy.saveFailed`. |
+| `headingLevel` | `'h2' … 'h6'` | `'h3'` | Where the title sits in the page outline. |
+| `icon` | `ReactNode` | — | A decorative glyph before the title. |
+| `dataTestId` | `string` | — | Root test id; parts derive `-edit`, `-save`, `-cancel`, `-summary`, `-status`, `-error`, `-saving`, `-body`, `-learn-more`, `-title`. |
+| `className`, `sx` | | | Styling hooks on the root `<section>`. |
+
+## Saving
+
+- **Pending.** While the promise `onSave` returned is pending, Save shows a
+  spinner and `copy.saving`, the card is `aria-busy`, Cancel is disabled and
+  further presses of Save are ignored — `onSave` runs once.
+- **Resolved.** The card closes and focus returns to Edit. Update `summary` from
+  the saved value in the same handler.
+- **Rejected** (or `onSave` throws). The card **stays open**, the draft is
+  untouched, and the error appears in a `role="alert"` line that Save is
+  described by. The card never prints `error.message` by itself — that string
+  is written for a developer; map it with `formatError`.
+
+Save is `aria-disabled`, not `disabled`, while pending: a disabled button drops
+the focus it holds, and a keyboard user whose save then failed would be sent
+back to the top of the page.
+
+## Cancelling
+
+Cancel (or Escape inside the open card) closes the card and calls `onCancel`.
+`children` unmount on close, so any **uncontrolled** state inside the form is
+discarded by construction; a controlled draft is the host's to reset in
+`onCancel`, as in the example above.
+
+## In a grid
+
+An open card sets `grid-column: 1 / -1` on itself and carries
+`data-setting-card-open`, so inside a [`SettingGrid`](./SettingGrid.md) — or any
+CSS grid — its form gets the whole row. `height: 100%` lets it match the other
+cards in its row while closed.
+
+## Accessibility
+
+- The root is a `<section>` labelled by the title; the title is a real heading
+  (`headingLevel`).
+- Edit's accessible name is `copy.edit` **plus the title** ("Edit Session
+  timeout"), so a grid of cards is not a list of identical buttons.
+- **Focus round trip.** Opening moves focus to the first tabbable element in the
+  form — the rule `Dialog` uses (`focusFirstTabbable`, FUT-2696), so a field's
+  own `autoFocus` still wins. Closing, by any path, returns focus to Edit. A
+  card mounted open does not take focus.
+- **No focus trap.** The card is inline and the page around it stays usable; a
+  trap would strand a keyboard user who wants to leave mid-edit. Escape
+  cancels.
+- The "learn more" trigger owns `aria-expanded` / `aria-controls`; the region is
+  kept mounted so `aria-controls` always resolves.
+- The save failure is `role="alert"`, announced without moving focus.
+
+## Best practices
+
+- Keep `summary` to the current **value** in words, not a description of the
+  setting — the title already says what it is.
+- Use `status` for a state that changes how the summary reads ("Off",
+  "Managed by your organisation"); skip it when the summary says it all.
+- A setting that is a single on/off is a [`SettingToggle`](./SettingToggle.md),
+  not a card with a switch inside.

package/src/components/layout/SettingCard/SettingCard.metrics.ts

@@ -0,0 +1,22 @@
+/**
+ * The setting-card family's lengths, in design px. The web reads every one
+ * through `rem(theme, n)`, so they scale with the host's type scale.
+ */
+export const SETTING_CARD = {
+  /** Between the icon and the title. */
+  iconGap: 12,
+  /** The spinner beside a switch while its flip is saving. */
+  spinnerSize: 16,
+  /** How far a group's dependent rows sit in from its main switch. */
+  groupIndent: 24,
+  /** The rule down the left of a group's dependent rows. */
+  groupRuleWidth: 2,
+  /** The narrowest a grid column gets by default. */
+  gridMinColumnWidth: 320,
+} as const;
+
+/** The grid's default gap, in theme SPACING units (not px): what `sx`'s `gap: 2` means. */
+export const SETTING_GRID_GAP_UNITS = 2;
+
+/** How faded a group's dependent rows are while the main switch is off. */
+export const SETTING_GROUP_INACTIVE_OPACITY = 0.5;