@12-apps/ui 6.30.2 → 6.30.3

package/dist/types/pt-BR.layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pt-BR.layout.d.ts","sourceRoot":"","sources":["../../src/pt-BR.layout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EACV,eAAe,EAChB,MAAM,QAAQ,CAAC;AAEhB,eAAO,MAAM,uBAAuB,EAAE,eAMrC,CAAC"}
+{"version":3,"file":"pt-BR.layout.d.ts","sourceRoot":"","sources":["../../src/pt-BR.layout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,eAAe,EAChB,MAAM,QAAQ,CAAC;AAEhB,eAAO,MAAM,uBAAuB,EAAE,eAMrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAOrC,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,iBAGvC,CAAC"}

package/dist/typography/Heading.js

@@ -1,14 +1,14 @@
 import "../chunk-6GP2DOOO.js";
 import {
   Heading
-} from "../chunk-SLMA4UQS.js";
-import "../chunk-XYDW5RQB.js";
-import "../chunk-EUKYQXYU.js";
+} from "../chunk-A3TISECJ.js";
+import "../chunk-JTJR63WI.js";
+import "../chunk-PLDVEJPR.js";
 import "../chunk-TYJR4GOF.js";
 import "../chunk-PT6TCWIW.js";
-import "../chunk-SONWG2RT.js";
-import "../chunk-AG66JBNH.js";
+import "../chunk-OW4UEIXA.js";
 import "../chunk-2BYKTBDL.js";
+import "../chunk-AG66JBNH.js";
 import "../chunk-6JAIFIPW.js";
 import "../chunk-FZXKH2ZT.js";
 import "../chunk-PZ5AY32C.js";

package/dist/typography/Paragraph.js

@@ -1,11 +1,11 @@
 import {
   Paragraph
-} from "../chunk-NWQWUYOV.js";
+} from "../chunk-XGB3YF32.js";
 import "../chunk-QKLGH3RZ.js";
 import "../chunk-TYJR4GOF.js";
-import "../chunk-SONWG2RT.js";
-import "../chunk-AG66JBNH.js";
+import "../chunk-OW4UEIXA.js";
 import "../chunk-2BYKTBDL.js";
+import "../chunk-AG66JBNH.js";
 import "../chunk-6JAIFIPW.js";
 import "../chunk-FZXKH2ZT.js";
 import "../chunk-PZ5AY32C.js";

package/dist/typography/Text.js

@@ -1,12 +1,12 @@
 import "../chunk-VUHLNYAE.js";
 import {
   Text
-} from "../chunk-YTYROOLY.js";
-import "../chunk-EPRA5QLB.js";
+} from "../chunk-D22EGB3T.js";
+import "../chunk-6XUZDJZY.js";
 import "../chunk-TYJR4GOF.js";
-import "../chunk-SONWG2RT.js";
-import "../chunk-AG66JBNH.js";
+import "../chunk-OW4UEIXA.js";
 import "../chunk-2BYKTBDL.js";
+import "../chunk-AG66JBNH.js";
 import "../chunk-6JAIFIPW.js";
 import "../chunk-FZXKH2ZT.js";
 import "../chunk-PZ5AY32C.js";

package/dist/user-avatar.js

@@ -1,13 +1,13 @@
 import {
   UserAvatar,
   UserMenu
-} from "./chunk-554SVTCN.js";
+} from "./chunk-MKZNP32D.js";
 import "./chunk-UDQSIRAP.js";
-import "./chunk-HGJHZ5PE.js";
-import "./chunk-35UG2QDB.js";
+import "./chunk-2DHVWNTO.js";
+import "./chunk-3ZVUNSFF.js";
+import "./chunk-EUEUZI4L.js";
 import "./chunk-XRMZMBE3.js";
 import "./chunk-FAITHWIO.js";
-import "./chunk-3ZVUNSFF.js";
 import "./chunk-VUHLNYAE.js";
 import "./chunk-2GSIEDGN.js";
 import "./chunk-AVI3XHRQ.js";
@@ -16,16 +16,16 @@ import "./chunk-BEBLRL5D.js";
 import "./chunk-6Q6T3FW5.js";
 import "./chunk-BA4RHQ3B.js";
 import "./chunk-73BEVJCS.js";
-import "./chunk-BKAB4KZK.js";
-import "./chunk-TAMIZE4Q.js";
-import "./chunk-TSEWUY4V.js";
+import "./chunk-LKAKYP42.js";
+import "./chunk-23LZNANO.js";
 import "./chunk-5LQ7PKMW.js";
-import "./chunk-YTYROOLY.js";
-import "./chunk-EPRA5QLB.js";
+import "./chunk-TAMIZE4Q.js";
+import "./chunk-D22EGB3T.js";
+import "./chunk-6XUZDJZY.js";
 import "./chunk-TYJR4GOF.js";
-import "./chunk-SONWG2RT.js";
-import "./chunk-AG66JBNH.js";
+import "./chunk-OW4UEIXA.js";
 import "./chunk-2BYKTBDL.js";
+import "./chunk-AG66JBNH.js";
 import "./chunk-6JAIFIPW.js";
 import "./chunk-FZXKH2ZT.js";
 import "./chunk-PZ5AY32C.js";

package/dist/utility/InstallPrompt.js

@@ -1,10 +1,12 @@
 import "../chunk-3QQVEYOR.js";
 import {
   InstallPrompt
-} from "../chunk-IABE56TG.js";
+} from "../chunk-5ZOJLYD2.js";
+import "../chunk-GY62N32G.js";
 import {
   usePwaInstall
-} from "../chunk-S2GDYA6R.js";
+} from "../chunk-5GMHJ7Y5.js";
+import "../chunk-WXYLH3QZ.js";
 import {
   PWA_INSTALL_AVAILABLE_EVENT,
   PWA_INSTALL_STASH_KEY,
@@ -12,8 +14,6 @@ import {
   readPwaInstallStash,
   resetPwaInstallStash
 } from "../chunk-UUL44SUX.js";
-import "../chunk-GY62N32G.js";
-import "../chunk-WXYLH3QZ.js";
 import "../chunk-PZ5AY32C.js";
 export {
   InstallPrompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.30.2",
+  "version": "6.30.3",
   "license": "MIT",
   "packageManager": "pnpm@10.34.5",
   "type": "module",
@@ -420,6 +420,10 @@
       "types": "./dist/types/components/form/Menubar/index.d.ts",
       "default": "./dist/form/Menubar.js"
     },
+    "./form/NumberField": {
+      "types": "./dist/types/components/form/NumberField/index.d.ts",
+      "default": "./dist/form/NumberField.js"
+    },
     "./form/PasswordStrength": {
       "types": "./dist/types/components/form/PasswordStrength/index.d.ts",
       "default": "./dist/form/PasswordStrength.js"
@@ -536,6 +540,10 @@
       "types": "./dist/types/components/layout/Separator/index.d.ts",
       "default": "./dist/layout/Separator.js"
     },
+    "./layout/SettingCard": {
+      "types": "./dist/types/components/layout/SettingCard/index.d.ts",
+      "default": "./dist/layout/SettingCard.js"
+    },
     "./layout/SettingsLayout": {
       "types": "./dist/types/components/layout/SettingsLayout/index.d.ts",
       "default": "./dist/layout/SettingsLayout.js"

package/src/components/form/Input/Input.tsx

@@ -80,6 +80,28 @@ const interactionProps = (
   onClick: loading ? undefined : onClick,
 });
 
+/**
+ * `aria-label` has to ride `inputProps` to reach the `<input>` (FUT-755), and
+ * `aria-describedby` the same way — spread with the rest, either lands on the
+ * FormControl DIV that the text field renders as its root, which carries no
+ * role, so the field kept no accessible name or description and a source
+ * grep saying "this input is labelled" disagreed with the DOM. NumberField's
+ * suffix rides this to reach a caller's field (FUT-2823); this does not also
+ * join MUI's own helper-text id the way the shared package's later Input
+ * does — this maintenance line predates that fix.
+ */
+const mergedInputProps = (
+  dataTestId: string | undefined,
+  inputProps: InputProps['inputProps'],
+  ariaLabel: string | undefined,
+  ariaDescribedBy: string | undefined,
+) => ({
+  'data-testid': dataTestId,
+  ...inputProps,
+  ...(ariaLabel === undefined ? {} : { 'aria-label': ariaLabel }),
+  ...(ariaDescribedBy === undefined ? {} : { 'aria-describedby': ariaDescribedBy }),
+});
+
 export const Input = React.forwardRef<HTMLInputElement, InputProps>(
   (
     {
@@ -99,6 +121,8 @@ export const Input = React.forwardRef<HTMLInputElement, InputProps>(
       onFocus,
       onBlur,
       'aria-label': ariaLabel,
+      'aria-describedby': ariaDescribedBy,
+      inputProps,
       ...rest
     },
     ref,
@@ -120,18 +144,7 @@ export const Input = React.forwardRef<HTMLInputElement, InputProps>(
         {...interactionProps(loading, onClick, props.disabled)}
         onFocus={onFocus}
         onBlur={onBlur}
-        /*
-         * `aria-label` has to ride `inputProps` to reach the `<input>` (FUT-755).
-         * Spread with the rest it lands on the FormControl DIV that the text
-         * field renders as its root, which carries no role — so the field kept
-         * no accessible name, and a source grep saying "this input is labelled"
-         * disagreed with the DOM. The reports search box and the block-title
-         * inputs were both named in source and anonymous to a screen reader.
-         */
-        inputProps={{
-          'data-testid': dataTestId,
-          ...(ariaLabel === undefined ? {} : { 'aria-label': ariaLabel }),
-        }}
+        inputProps={mergedInputProps(dataTestId, inputProps, ariaLabel, ariaDescribedBy)}
         InputProps={{
           startAdornment: startAdornment && (
             <InputAdornment position="start">{startAdornment}</InputAdornment>

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

@@ -1,3 +1,4 @@
+import type { InputBaseComponentProps } from '@mui/material/InputBase/index.js';
 import type { InputLabelProps as MuiInputLabelProps } from '@mui/material/InputLabel/index.js';
 import type { InputHTMLAttributes } from 'react';
 import type React from 'react';
@@ -31,4 +32,13 @@ export interface InputProps
    * the TYPE was missing, so it failed to compile. FUT-729.
    */
   InputLabelProps?: Partial<MuiInputLabelProps>;
+  /**
+   * Attributes for the `<input>` element itself. Anything else this component
+   * does not recognise lands on the text field's ROOT `<div>`, where
+   * `inputMode`, `pattern`, `role` and `aria-value*` do nothing. Merged, not
+   * spread over: the field's own `data-testid` stays the default a caller can
+   * override, and the `aria-label` / `aria-describedby` it builds still land
+   * last.
+   */
+  inputProps?: InputBaseComponentProps;
 }

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

@@ -0,0 +1,77 @@
+/**
+ * The pure half of `NumberField`: what a keystroke may add, what a string of
+ * digits is worth, and where an arrow key lands. Kept apart from the component
+ * so every rule is a plain function a unit test can hold.
+ */
+
+/**
+ * The most digits the field keeps. Fifteen is the longest run that is always
+ * a safe integer (`Number.MAX_SAFE_INTEGER` has sixteen, but not every
+ * sixteen-digit number is below it), so a pasted serial number can never turn
+ * into a rounded float.
+ */
+export const MAX_DIGITS = 15;
+
+export interface NumberBounds {
+  min?: number;
+  max?: number;
+}
+
+/** Everything that is not a digit, removed; then cut to {@link MAX_DIGITS}. */
+export function digitsOf(raw: string): string {
+  return raw.replace(/\D+/g, '').slice(0, MAX_DIGITS);
+}
+
+/**
+ * What the field's text is worth. An empty field is `null` — never `0`, and
+ * never `NaN` — so "cleared" and "zero" stay two different answers.
+ */
+export function parseDigits(raw: string): number | null {
+  const digits = digitsOf(raw);
+  return digits === '' ? null : Number(digits);
+}
+
+/** The text a value shows as. */
+export function formatValue(value: number | null): string {
+  return value === null || !Number.isFinite(value) ? '' : String(value);
+}
+
+/** `value`, held inside whichever bounds are set. */
+export function clamp(value: number, { min, max }: NumberBounds): number {
+  if (max !== undefined && value > max) return max;
+  if (min !== undefined && value < min) return min;
+  return value;
+}
+
+/**
+ * Where ArrowUp (`+1`) or ArrowDown (`-1`) takes the value.
+ *
+ * From empty, either arrow lands on the floor (`min`, else 0) rather than
+ * stepping past it: the first press says "give me a number", and the floor is
+ * the only one both directions agree on.
+ */
+export function stepValue(
+  value: number | null,
+  direction: 1 | -1,
+  step: number,
+  bounds: NumberBounds,
+): number {
+  if (value === null) return clamp(bounds.min ?? 0, bounds);
+  return clamp(value + direction * step, bounds);
+}
+
+/**
+ * A key that would type a character the field refuses. Shortcuts (Ctrl/Cmd +
+ * a letter — copy, paste, select all) and the named keys (`Backspace`,
+ * `ArrowLeft`, `Tab`) are left alone: only a single printable character that
+ * is not a digit is blocked.
+ */
+export function isRefusedKey(event: {
+  key: string;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  altKey: boolean;
+}): boolean {
+  if (event.ctrlKey || event.metaKey || event.altKey) return false;
+  return event.key.length === 1 && !/\d/.test(event.key);
+}

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,48 @@
+# 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.
+- 2026-09-26 21:33 BRT — backported onto the `ui-6.30.x` maintenance line
+  (FUT-2823). `Input` there also gained a top-level `aria-describedby` route
+  to the `<input>`, the same way `aria-label` already rode `inputProps` — the
+  suffix's id reaches the field either way, but this line's `Input` does not
+  also join MUI's own helper-text id into it, a separate fix `main` shipped
+  after this line's fork point.

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';