@12-apps/ui 6.40.0 → 6.41.1

package/src/components/form/Autocomplete/useAutocomplete.ts

@@ -35,6 +35,15 @@ interface AutocompleteState<T> {
   setJustCompletedGhost: Setter<boolean>;
   userClosedDropdown: boolean;
   setUserClosedDropdown: Setter<boolean>;
+  /**
+   * Mirrors `userClosedDropdown`, set synchronously wherever the state is
+   * (see {@link setDeliberateClose}). An effect scheduled by one render and
+   * flushed after a LATER render has already changed this flag reads a
+   * stale, closed-over `userClosedDropdown` — but `.current` on a ref is
+   * dereferenced live, so it always reflects the latest write regardless of
+   * which render's closure is doing the reading (FUT-2780).
+   */
+  userClosedDropdownRef: React.RefObject<boolean>;
   inputRef: React.RefObject<HTMLInputElement | null>;
   listRef: React.RefObject<HTMLUListElement | null>;
   debounceRef: React.RefObject<number | undefined>;
@@ -50,6 +59,7 @@ function useAutocompleteState<T>(value: string, suggestions: T[]): AutocompleteS
   const [isInputFocused, setIsInputFocused] = useState(false);
   const [justCompletedGhost, setJustCompletedGhost] = useState(false);
   const [userClosedDropdown, setUserClosedDropdown] = useState(false);
+  const userClosedDropdownRef = useRef(false);
   const inputRef = useRef<HTMLInputElement>(null);
   const listRef = useRef<HTMLUListElement | null>(null);
   const debounceRef = useRef<number | undefined>(undefined);
@@ -57,10 +67,21 @@ function useAutocompleteState<T>(value: string, suggestions: T[]): AutocompleteS
     open, setOpen, activeIndex, setActiveIndex, ghost, setGhost, inputValue, setInputValue,
     composition, setComposition, filteredSuggestions, setFilteredSuggestions, isInputFocused,
     setIsInputFocused, justCompletedGhost, setJustCompletedGhost, userClosedDropdown,
-    setUserClosedDropdown, inputRef, listRef, debounceRef,
+    setUserClosedDropdown, userClosedDropdownRef, inputRef, listRef, debounceRef,
   };
 }
 
+/**
+ * Set the "this close was deliberate" flag in both the ref effects read
+ * synchronously (live, even from a stale closure) and the state the rest of
+ * the component reads for render — every call site that touches
+ * `userClosedDropdown` goes through this so the two never drift (FUT-2780).
+ */
+function setDeliberateClose<T>(s: AutocompleteState<T>, closed: boolean): void {
+  s.userClosedDropdownRef.current = closed;
+  s.setUserClosedDropdown(closed);
+}
+
 // ---- effects (one tiny hook each; explicit params keep deps complete) --------
 
 function useValueSync(value: string, setInputValue: Setter<string>): void {
@@ -101,17 +122,17 @@ function useLoadingOpen(
   isLoading: boolean,
   inputValue: string,
   disabled: boolean,
-  userClosedDropdown: boolean,
+  userClosedDropdownRef: React.RefObject<boolean>,
   setOpen: Setter<boolean>,
   setActiveIndex: Setter<number>,
 ): void {
   useEffect(() => {
-    if (isLoading && inputValue.trim().length > 0 && !disabled && !userClosedDropdown) setOpen(true);
+    if (isLoading && inputValue.trim().length > 0 && !disabled && !userClosedDropdownRef.current) setOpen(true);
     if (disabled) {
       setOpen(false);
       setActiveIndex(-1);
     }
-  }, [isLoading, inputValue, disabled, userClosedDropdown, setOpen, setActiveIndex]);
+  }, [isLoading, inputValue, disabled, userClosedDropdownRef, setOpen, setActiveIndex]);
 }
 
 /** Inputs to the auto-open check, all primitive/stable so effect deps stay complete. */
@@ -120,7 +141,7 @@ interface AutoOpenArgs {
   isInputFocused: boolean;
   composition: boolean;
   justCompletedGhost: boolean;
-  userClosedDropdown: boolean;
+  userClosedDropdownRef: React.RefObject<boolean>;
   activeIndex: number;
   setOpen: Setter<boolean>;
   setActiveIndex: Setter<number>;
@@ -133,7 +154,7 @@ function maybeAutoOpen(a: AutoOpenArgs, hasResults: boolean): void {
     a.isInputFocused &&
     !a.composition &&
     !a.justCompletedGhost &&
-    !a.userClosedDropdown;
+    !a.userClosedDropdownRef.current;
   if (!canAutoOpen) return;
   a.setOpen(true);
   if (hasResults && a.activeIndex === -1) a.setActiveIndex(0);
@@ -146,7 +167,7 @@ function useLocalFilter<T>(p: AutocompleteProps<T>, s: AutocompleteState<T>): vo
   const async = Boolean(p.async);
   const {
     inputValue, isInputFocused, composition, justCompletedGhost, userClosedDropdown, activeIndex,
-    setFilteredSuggestions, setOpen, setActiveIndex,
+    setFilteredSuggestions, setOpen, setActiveIndex, userClosedDropdownRef,
   } = s;
   useEffect(() => {
     const suggestions = propSuggestions ?? [];
@@ -157,12 +178,17 @@ function useLocalFilter<T>(p: AutocompleteProps<T>, s: AutocompleteState<T>): vo
     const filtered = filterSuggestions(suggestions, inputValue, matchMode, getLabel);
     setFilteredSuggestions(filtered);
     maybeAutoOpen(
-      { inputValue, isInputFocused, composition, justCompletedGhost, userClosedDropdown, activeIndex, setOpen, setActiveIndex },
+      { inputValue, isInputFocused, composition, justCompletedGhost, userClosedDropdownRef, activeIndex, setOpen, setActiveIndex },
       filtered.length > 0,
     );
+    // `userClosedDropdown` (state) stays a dependency so this effect still
+    // reruns on every change of it, same as before — only the VALUE read
+    // inside `maybeAutoOpen` moved to the ref (see `userClosedDropdownRef`'s
+    // doc comment).
   }, [
     propSuggestions, inputValue, async, getLabel, matchMode, isInputFocused, composition,
     justCompletedGhost, userClosedDropdown, activeIndex, setFilteredSuggestions, setOpen, setActiveIndex,
+    userClosedDropdownRef,
   ]);
 }
 
@@ -189,7 +215,7 @@ function commitMultiSelect<T>(item: T, p: AutocompleteProps<T>, s: AutocompleteS
   if (!current.some((sel) => getKey(sel) === getKey(item))) p.onSelectedItemsChange?.([...current, item]);
   s.setInputValue('');
   onChange('');
-  s.setUserClosedDropdown(false);
+  setDeliberateClose(s, false);
 }
 
 function commitSingleSelect<T>(item: T, p: AutocompleteProps<T>, s: AutocompleteState<T>, onChange: (v: string) => void): void {
@@ -227,8 +253,11 @@ function runSelectItem<T>(item: T, p: AutocompleteProps<T>, s: AutocompleteState
   // Set LAST so a re-fired `onFocus` cannot clear the flag. The close itself
   // relies on the input never blurring during a pick (the option's
   // `onMouseDown` preventDefault, and Enter keeps focus): `onFocus` reopens a
-  // non-empty input directly, without reading this flag.
-  if (isSingleSelectPick) s.setUserClosedDropdown(true);
+  // non-empty input directly, without reading this flag. The REF half is set
+  // in the same synchronous tick as the pick, so an effect scheduled by an
+  // earlier keystroke — and still pending when this runs — reads the
+  // up-to-date value instead of the one it closed over (FUT-2780).
+  if (isSingleSelectPick) setDeliberateClose(s, true);
 }
 
 function buildKeyContext<T>(
@@ -244,7 +273,8 @@ function buildKeyContext<T>(
     multiple: Boolean(p.multiple), selectedItems: p.selectedItems ?? [],
     getLabel: p.getLabel ?? defaultGetLabel,
     getSuggestionType: p.getSuggestionType ?? defaultGetSuggestionType,
-    setOpen: s.setOpen, setActiveIndex: s.setActiveIndex, setUserClosedDropdown: s.setUserClosedDropdown,
+    setOpen: s.setOpen, setActiveIndex: s.setActiveIndex,
+    setUserClosedDropdown: (closed: boolean) => setDeliberateClose(s, closed),
     setInputValue: s.setInputValue, setGhost: s.setGhost, setJustCompletedGhost: s.setJustCompletedGhost,
     debouncedOnChange: onChange, selectItem, onSelectedItemsChange: p.onSelectedItemsChange,
   };
@@ -287,7 +317,7 @@ export function useAutocomplete<T>(p: AutocompleteProps<T>): AutocompleteView<T>
     Boolean(p.isLoading),
     s.inputValue,
     Boolean(p.disabled),
-    s.userClosedDropdown,
+    s.userClosedDropdownRef,
     s.setOpen,
     s.setActiveIndex,
   );
@@ -315,11 +345,11 @@ export function useAutocomplete<T>(p: AutocompleteProps<T>): AutocompleteView<T>
       s.setInputValue(e.target.value);
       debouncedOnChange(e.target.value);
       if (!s.open || s.filteredSuggestions.length === 0) s.setActiveIndex(-1);
-      s.setUserClosedDropdown(false);
+      setDeliberateClose(s, false);
     },
     onFocus: (): void => {
       s.setIsInputFocused(true);
-      s.setUserClosedDropdown(false);
+      setDeliberateClose(s, false);
       if (!s.inputValue.trim()) return;
       s.setOpen(true);
       if (s.filteredSuggestions.length > 0 && s.activeIndex === -1) s.setActiveIndex(0);
@@ -330,7 +360,7 @@ export function useAutocomplete<T>(p: AutocompleteProps<T>): AutocompleteView<T>
     onClickAway: (): void => {
       s.setOpen(false);
       s.setActiveIndex(-1);
-      s.setUserClosedDropdown(true);
+      setDeliberateClose(s, true);
     },
   };
 }

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

@@ -143,6 +143,7 @@ export const Input = React.forwardRef<HTMLInputElement, InputProps>(
       'aria-label': ariaLabel,
       'aria-describedby': ariaDescribedBy,
       'aria-busy': ariaBusy,
+      inputProps,
       ...rest
     },
     ref,
@@ -178,6 +179,7 @@ export const Input = React.forwardRef<HTMLInputElement, InputProps>(
          */
         inputProps={{
           'data-testid': dataTestId,
+          ...inputProps,
           ...inputAriaOf({ id, helperText, label: ariaLabel, describedBy: ariaDescribedBy, busy: ariaBusy }),
         }}
         InputProps={{

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 it builds from `aria-label` / `aria-describedby` /
+   * `aria-busy` still lands 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,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';