@12-apps/ui 6.30.1 → 6.30.3

package/src/components/data-display/DataViews/data-views-more-fields.tsx

@@ -9,15 +9,15 @@
  *
  * A field with one or two options renders FLAT: inside a panel there is no
  * space to win back, and two labelled checkboxes are faster than a dropdown
- * needing a second click. Past that it becomes a {@link MultiSelectDropdown} —
- * see `INLINE_OPTION_LIMIT`.
+ * needing a second click. Past that — or whenever the field asks for a tree or
+ * a search — it is the bar's own {@link PillControl}; see `sharesBarControl`.
  */
 import Checkbox from "@mui/material/Checkbox/index.js";
 
-import { MultiSelectDropdown } from "../../layout/ContentToolbar";
 import { Box } from "../../../mui/Box";
 import { Text } from "../../typography/Text";
 
+import { PillControl } from "./data-views-category-pill";
 import type { OverflowField } from "./data-views-overflow";
 import { RangeBounds } from "./data-views-range-pill";
 import { isRangeSet } from "./data-views-range-values";
@@ -41,42 +41,59 @@ export interface MoreFieldProps {
  */
 const INLINE_OPTION_LIMIT = 2;
 
-/** One overflowed pill: its options as checkboxes, all visible at once. */
+/**
+ * Whether an overflowed pill keeps the SAME control it has on the bar.
+ *
+ * The panel used to build its own flat dropdown for every field past two
+ * options, so a field's config only held while it fitted: `control:
+ * "category"` lost its tree (subcategories flattened into one list, no
+ * "Marcar tudo", no count footer) and `searchEnabled` lost its search, on
+ * exactly the phone widths where most filters live in here. Anything the bar
+ * would render as a dropdown now renders as the bar's own {@link PillControl};
+ * only a plain two-option field — one that did not ask for a dropdown, a tree
+ * or a search — stays a flat checkbox row, which is a panel layout rather than
+ * a different control (the filter panel draws the same line).
+ */
+function sharesBarControl<T extends Record<string, unknown>>(field: OverflowField<T>): boolean {
+  const pill = field.pill;
+  if (!pill) return false;
+  return (
+    pill.control === "category" ||
+    pill.control === "multiselect" ||
+    pill.searchEnabled === true ||
+    pill.options.length > INLINE_OPTION_LIMIT
+  );
+}
+
+/** One overflowed pill: the bar's control, or its options as checkboxes. */
 function OverflowPill<T extends Record<string, unknown>>({
   field,
   values,
-  onToggle,
+  onTogglePill,
   onClear,
   testIdPrefix,
 }: {
   field: OverflowField<T>;
   values: string[];
-  onToggle: (value: string, checked: boolean) => void;
+  onTogglePill: (fieldId: string, value: string, checked: boolean) => void;
   onClear: () => void;
   testIdPrefix: string;
 }): React.JSX.Element {
-  const copy = useDataViewsCopy();
-  const options = field.pill?.options ?? [];
-  if (options.length > INLINE_OPTION_LIMIT) {
+  const testId = `${testIdPrefix}-more-${field.id}`;
+  if (field.pill && sharesBarControl(field)) {
     return (
-      <MultiSelectDropdown
-        extraOptionsHeading={copy.filters.optionsHeading}
-        clearText={copy.filters.clear}
-        clearLabel={copy.filters.clearRange(field.label)}
-        label={field.pill?.label ?? field.label}
-        options={options}
-        selected={new Set(values)}
-        onToggle={onToggle}
-        onClear={onClear}
-        allLabel={copy.filters.allOption}
-        searchable={options.length > 6 ? true : undefined}
-        searchPlaceholder={copy.filters.optionSearchPlaceholder}
-        noResultsLabel={copy.filters.optionsEmpty}
-        layout="pill"
-        data-testid={`${testIdPrefix}-more-${field.id}`}
+      <PillControl
+        fieldId={field.id}
+        pill={field.pill}
+        selected={values}
+        onTogglePill={onTogglePill}
+        onClearField={onClear}
+        testIdPrefix={testIdPrefix}
+        testId={testId}
       />
     );
   }
+  const onToggle = (value: string, checked: boolean) => onTogglePill(field.id, value, checked);
   return (
     <Box sx={{ display: "flex", flexWrap: "wrap", gap: 0.75 }}>
       {(field.pill?.options ?? []).map((option) => {
@@ -85,7 +102,7 @@ function OverflowPill<T extends Record<string, unknown>>({
           <Box
             key={option.value}
             component="label"
-            data-testid={`${testIdPrefix}-more-${field.id}-${option.value}`}
+            data-testid={`${testId}-${option.value}`}
             sx={{
               display: "inline-flex",
               alignItems: "center",
@@ -163,17 +180,6 @@ function OverflowRange<T extends Record<string, unknown>>({
   );
 }
 
-/**
- * The trigger, badged with how many fields had no room on the bar — and told
- * apart when some of them are APPLIED.
- *
- * An applied filter can land in here now (it is ranked first, not exempt), so
- * this button is the only thing on screen still saying it exists. A neutral
- * badge reading "3" would make "three filters you have not used" and "three
- * filters narrowing this list" look identical, which is the whole failure the
- * old exemption was written to avoid. So an overflow holding applied filters
- * takes the applied tone and counts them in its own badge.
-
 /**
  * Whether a field has anything applied, and how to unapply it — the two shapes
  * (a pill's selected values, a range's bounds) answered in one place so the
@@ -257,7 +263,7 @@ export function MoreGroup<T extends Record<string, unknown>>({
         <OverflowPill
           field={field}
           values={pills[field.id] ?? []}
-          onToggle={(value, checked) => onTogglePill(field.id, value, checked)}
+          onTogglePill={onTogglePill}
           onClear={() => (pills[field.id] ?? []).forEach((v) => onTogglePill(field.id, v, false))}
           testIdPrefix={testIdPrefix}
         />

package/src/components/data-display/DataViews/data-views-overflow.ts

@@ -347,5 +347,16 @@ export function useFilterOverflow<T extends Record<string, unknown>>(
   if (cache.current === null || (!frozen && cache.current.signature !== signature)) {
     cache.current = { signature, split: computeSplit(all, pills, ranges, width, hasExport) };
   }
-  return { ...cache.current.split, barRef };
+  // The cache holds the ARRANGEMENT — which ids sit on the bar, which in "Mais"
+  // — never the fields themselves. The signature keys on ids, so a field whose
+  // options arrive after the first measurement (a category list still loading)
+  // does not re-split, and handing back the cached objects served the empty
+  // list for good: "Categoria" in "Mais" rendered a label with no control under
+  // it (FUT-2828). Re-reading each field from `all` keeps the slots and the
+  // current config.
+  const { split } = cache.current;
+  const current = new Map(all.map((field) => [field.id, field]));
+  const fresh = (fields: OverflowField<T>[]): OverflowField<T>[] =>
+    fields.map((field) => current.get(field.id) ?? field);
+  return { ...split, inline: fresh(split.inline), overflow: fresh(split.overflow), barRef };
 }

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