@12-apps/ui 6.40.0 → 6.41.0

package/dist/types/components/layout/SettingCard/SettingCard.types.d.ts

@@ -0,0 +1,127 @@
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+import type { ReactNode } from 'react';
+import type { SettingCardCopy, SettingSwitchCopy } from '../../../copy';
+import type { ColorValue } from '../../../tokens/vocabulary';
+export type { SettingCardCopy, SettingSwitchCopy } from '../../../copy';
+/**
+ * What a save handler may return. A promise holds the card in its saving
+ * state until it settles; a rejection is the failure path. A plain return is
+ * a synchronous success.
+ */
+export type SettingSaveResult = void | Promise<unknown>;
+/**
+ * Turns whatever a rejected save threw into the sentence the card shows.
+ * Return `undefined` to fall back to the copy's `saveFailed`. The card never
+ * renders an `Error.message` on its own: that string is usually written for a
+ * developer, in the developer's language.
+ */
+export type SettingErrorFormatter = (error: unknown) => string | undefined;
+/** The heading level a card's title renders at, so it fits the page outline. */
+export type SettingHeadingLevel = 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+/** The pill beside a closed card's title: the setting's current state, in words. */
+export interface SettingStatus {
+    /** What the state IS, in the host's language: "On", "Not configured". */
+    label: string;
+    /** A house colour. Colour is never the only carrier: `label` is always shown. Defaults to `neutral`. */
+    color?: ColorValue;
+}
+/** What every card in the family shares. */
+interface SettingSurfaceProps {
+    /** The setting's name. Also the accessible name of the card's region. */
+    title: string;
+    /** The heading level of `title`. Defaults to `h3`. */
+    headingLevel?: SettingHeadingLevel;
+    /** A decorative glyph before the title. */
+    icon?: ReactNode;
+    /** Maps a rejected save to the sentence shown; see {@link SettingErrorFormatter}. */
+    formatError?: SettingErrorFormatter;
+    /** Root test id. Parts derive theirs from it (`<id>-edit`, `<id>-save`, …). */
+    dataTestId?: string;
+    className?: string;
+    sx?: SxProps<Theme>;
+}
+export interface SettingCardProps extends SettingSurfaceProps {
+    /** The chrome words (Edit, Cancel, Save, …). REQUIRED — no default copy. */
+    copy: SettingCardCopy;
+    /** The one line a closed card shows under its title: the setting's current value. */
+    summary?: ReactNode;
+    /** The pill beside the title. Omit for none. */
+    status?: SettingStatus;
+    /** The form, rendered only while the card is open (so an uncontrolled draft is discarded on close). */
+    children: ReactNode;
+    /** Longer explanation behind a "learn more" disclosure in the open card. Omit for no disclosure. */
+    learnMore?: ReactNode;
+    /**
+     * Persist the draft. The card stays in its saving state while a returned
+     * promise is pending, closes when it resolves, and STAYS OPEN showing the
+     * error when it rejects.
+     */
+    onSave: () => SettingSaveResult;
+    /** The card closed without saving — reset the host's draft here. */
+    onCancel?: () => void;
+    /** Controlled open state. Pair with `onOpenChange`. */
+    open?: boolean;
+    /** Uncontrolled initial open state. */
+    defaultOpen?: boolean;
+    /** Every open/close request: Edit, Cancel, Escape, and a successful save. */
+    onOpenChange?: (open: boolean) => void;
+    /** Disables Edit on a closed card (the setting cannot be changed from here). */
+    disabled?: boolean;
+    /** Disables Save — for a draft the host knows is invalid. */
+    saveDisabled?: boolean;
+}
+interface SettingSwitchProps extends SettingSurfaceProps {
+    /** The saving and failure words. REQUIRED — no default copy. */
+    copy: SettingSwitchCopy;
+    /** Explanation under the title. Read to screen readers as the switch's description. */
+    summary?: ReactNode;
+    /** The persisted value. The switch shows the flip optimistically while it saves, then this again. */
+    checked: boolean;
+    /**
+     * Persist a flip. The switch shows the new value and a saving state while a
+     * returned promise is pending; a rejection reverts it and shows the error.
+     */
+    onChange: (checked: boolean) => SettingSaveResult;
+    /** Disables the switch. */
+    disabled?: boolean;
+}
+/**
+ * `card` draws the surface; `row` draws the same content flat, for a
+ * dependent row inside a `SettingGroup` (a card inside a card reads as two
+ * subjects).
+ */
+export type SettingToggleVariant = 'card' | 'row';
+export interface SettingToggleProps extends SettingSwitchProps {
+    /** Defaults to `card`. */
+    variant?: SettingToggleVariant;
+}
+export interface SettingGroupProps extends SettingSwitchProps {
+    /**
+     * Why the dependent rows are inactive while the main switch is off —
+     * "Turn on notifications to choose which ones you get". Shown only then.
+     */
+    inactiveHint: string;
+    /** The dependent rows. Stay rendered while the main switch is off, dimmed and inert. */
+    children: ReactNode;
+}
+/** The most columns a `SettingGrid` lays out. */
+export type SettingGridColumns = 1 | 2 | 3;
+export interface SettingGridProps {
+    children: ReactNode;
+    /**
+     * The narrowest a column may get, in design px (scaled with the type
+     * scale). The grid adds a column each time its OWN width fits one more.
+     * Defaults to 320.
+     */
+    minColumnWidth?: number;
+    /** Defaults to 3. */
+    maxColumns?: SettingGridColumns;
+    /** Gap between cards, in theme spacing units. Defaults to 2. */
+    gap?: number;
+    /** Accessible name. When set the grid renders as a labelled `region`. */
+    'aria-label'?: string;
+    dataTestId?: string;
+    className?: string;
+    sx?: SxProps<Theme>;
+}
+//# sourceMappingURL=SettingCard.types.d.ts.map

package/dist/types/components/layout/SettingCard/SettingCard.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SettingCard.types.d.ts","sourceRoot":"","sources":["../../../../../src/components/layout/SettingCard/SettingCard.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;AAE3E,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEnE,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,wGAAwG;IACxG,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,4CAA4C;AAC5C,UAAU,mBAAmB;IAC3B,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,2CAA2C;IAC3C,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,qFAAqF;IACrF,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAED,MAAM,WAAW,gBAAiB,SAAQ,mBAAmB;IAC3D,4EAA4E;IAC5E,IAAI,EAAE,eAAe,CAAC;IACtB,qFAAqF;IACrF,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,gDAAgD;IAChD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,uGAAuG;IACvG,QAAQ,EAAE,SAAS,CAAC;IACpB,oGAAoG;IACpG,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;OAIG;IACH,MAAM,EAAE,MAAM,iBAAiB,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,uDAAuD;IACvD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uCAAuC;IACvC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,UAAU,kBAAmB,SAAQ,mBAAmB;IACtD,gEAAgE;IAChE,IAAI,EAAE,iBAAiB,CAAC;IACxB,uFAAuF;IACvF,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,qGAAqG;IACrG,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,iBAAiB,CAAC;IAClD,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,KAAK,CAAC;AAElD,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,0BAA0B;IAC1B,OAAO,CAAC,EAAE,oBAAoB,CAAC;CAChC;AAED,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IAC3D;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,iDAAiD;AACjD,MAAM,MAAM,kBAAkB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB;IACrB,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB"}

package/dist/types/components/layout/SettingCard/SettingGrid.d.ts

@@ -0,0 +1,33 @@
+import { type CSSObject, type Theme } from '@mui/material/styles/index.js';
+import type { SettingGridColumns, SettingGridProps } from './SettingCard.types';
+/** The container the grid's own queries are asked of. Named, so a nested grid answers to its own. */
+export declare const SETTING_GRID_CONTAINER = "setting-grid";
+/**
+ * The grid itself.
+ *
+ * - Columns come from CONTAINER queries, not viewport ones: a settings grid
+ *   lives beside a rail, inside a drawer, in half a split view, and the
+ *   viewport says nothing about how wide any of those are.
+ * - `grid-auto-rows: auto` with `align-items: stretch` is the equal-height
+ *   rule: each row is as tall as its tallest card and every card in it
+ *   stretches to match. Not `1fr` rows — those would make EVERY row as tall as
+ *   the tallest, so one open card would inflate the whole page.
+ * - An open card spans the row. The card sets `grid-column` on itself; the
+ *   `:has()` rule covers a card the host wrapped in an element of its own.
+ */
+export interface SettingGridLayout {
+    /** The narrowest column, in DESIGN px (drawn through `rem`). */
+    minColumnPx: number;
+    maxColumns: SettingGridColumns;
+    /** The gap, in theme SPACING units. */
+    gapUnits: number;
+}
+export declare function settingGridStyles(theme: Theme, { minColumnPx, maxColumns, gapUnits }: SettingGridLayout): CSSObject;
+/**
+ * Lays setting cards out in one, two or three columns by the width it is
+ * GIVEN — see {@link settingGridStyles}. Two elements, because a container
+ * query is answered by an ANCESTOR: the outer one is the container, the inner
+ * one the grid.
+ */
+export declare const SettingGrid: import("react").ForwardRefExoticComponent<SettingGridProps & import("react").RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=SettingGrid.d.ts.map

package/dist/types/components/layout/SettingCard/SettingGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SettingGrid.d.ts","sourceRoot":"","sources":["../../../../../src/components/layout/SettingCard/SettingGrid.tsx"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,SAAS,EAAE,KAAK,KAAK,EAAE,MAAM,+BAA+B,CAAC;AAQrF,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,qGAAqG;AACrG,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AAarD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,iBAAiB,GAAG,SAAS,CAgBnH;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,6GAgCtB,CAAC"}

package/dist/types/components/layout/SettingCard/SettingGroup.context.d.ts

@@ -0,0 +1,13 @@
+/**
+ * What a `SettingGroup` tells the rows inside it: whether its main switch is
+ * off. `inert` on the rows' container already makes every descendant
+ * unreachable; this is for the family's own rows (`SettingToggle`) to ALSO
+ * draw and announce themselves as disabled, which `inert` does not do.
+ */
+export declare const SettingGroupContext: import("react").Context<{
+    inactive: boolean;
+}>;
+export declare const useSettingGroup: () => {
+    inactive: boolean;
+};
+//# sourceMappingURL=SettingGroup.context.d.ts.map

package/dist/types/components/layout/SettingCard/SettingGroup.context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SettingGroup.context.d.ts","sourceRoot":"","sources":["../../../../../src/components/layout/SettingCard/SettingGroup.context.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;cAA6B,OAAO;EAAwB,CAAC;AAE7F,eAAO,MAAM,eAAe,QAAO;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAqC,CAAC"}

package/dist/types/components/layout/SettingCard/SettingGroup.d.ts

@@ -0,0 +1,18 @@
+import type { SettingGroupProps } from './SettingCard.types';
+/**
+ * ONE subject: a main switch, and the settings that only mean something while
+ * it is on, indented beneath it.
+ *
+ * With the main switch off the dependent rows stay where they are — dimmed,
+ * `inert`, and explained by `inactiveHint` — rather than disappearing. A
+ * reader deciding whether to turn a feature on is helped by seeing what it
+ * would let them configure, and a layout that jumps when a switch flips moves
+ * the thing they were about to press.
+ *
+ * The rows are active only while the main switch is on AND saved: turning it
+ * on lights them once the save lands; turning it off dims them at once.
+ *
+ * Several subjects are several cards, never one group — see `SettingGroup.md`.
+ */
+export declare const SettingGroup: import("react").ForwardRefExoticComponent<SettingGroupProps & import("react").RefAttributes<HTMLElement>>;
+//# sourceMappingURL=SettingGroup.d.ts.map

package/dist/types/components/layout/SettingCard/SettingGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SettingGroup.d.ts","sourceRoot":"","sources":["../../../../../src/components/layout/SettingCard/SettingGroup.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAI7D;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,2GA0CvB,CAAC"}

package/dist/types/components/layout/SettingCard/SettingSwitch.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+import { useAsyncSwitch } from './SettingCard.hooks';
+import type { SettingToggleProps } from './SettingCard.types';
+/** Everything the switch-driven cards share, minus the surface each draws around it. */
+export type SettingSwitchBlockProps = Pick<SettingToggleProps, 'title' | 'headingLevel' | 'icon' | 'summary' | 'checked' | 'onChange' | 'copy' | 'formatError' | 'dataTestId'> & {
+    disabled: boolean;
+};
+/** The ids one switch block wires its label, description and failure line with. */
+export interface SettingSwitchIds {
+    titleId: string;
+    inputId: string;
+    summaryId: string;
+    errorId: string;
+}
+export declare const useSettingSwitchIds: () => SettingSwitchIds;
+/**
+ * Title-as-label, the switch, its explanation and the failure line.
+ *
+ * The switch is never `disabled` while it saves, for the reason Save is not
+ * (`SettingCard.tsx`): a disabled control drops keyboard focus. It says
+ * `aria-busy` instead, ignores flips until the save settles (see
+ * `useAsyncSwitch`), shows a spinner, and a polite live region says the words.
+ */
+export declare const SettingSwitchBlock: React.FC<SettingSwitchBlockProps & {
+    ids: SettingSwitchIds;
+    state: ReturnType<typeof useAsyncSwitch>;
+}>;
+//# sourceMappingURL=SettingSwitch.d.ts.map

package/dist/types/components/layout/SettingCard/SettingSwitch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SettingSwitch.d.ts","sourceRoot":"","sources":["../../../../../src/components/layout/SettingCard/SettingSwitch.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAgB,MAAM,OAAO,CAAC;AAKrC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,wFAAwF;AACxF,MAAM,MAAM,uBAAuB,GAAG,IAAI,CACxC,kBAAkB,EAClB,OAAO,GAAG,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,aAAa,GAAG,YAAY,CAC/G,GAAG;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1B,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,mBAAmB,QAAO,gBAQtC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,EAAE,CACvC,uBAAuB,GAAG;IAAE,GAAG,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAA;CAAE,CA8C9F,CAAC"}

package/dist/types/components/layout/SettingCard/SettingToggle.d.ts

@@ -0,0 +1,13 @@
+import type { SettingToggleProps } from './SettingCard.types';
+/**
+ * A setting that is one switch and nothing else. There is no edit state:
+ * flipping it IS the edit, and it saves at once.
+ *
+ * `onChange` may be async. The switch shows the new value while the promise is
+ * pending, with a spinner and an announced "saving"; a rejection flips it back
+ * to `checked` and shows the error under it.
+ *
+ * Inside a `SettingGroup` whose main switch is off, it renders disabled.
+ */
+export declare const SettingToggle: import("react").ForwardRefExoticComponent<SettingToggleProps & import("react").RefAttributes<HTMLElement>>;
+//# sourceMappingURL=SettingToggle.d.ts.map

package/dist/types/components/layout/SettingCard/SettingToggle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SettingToggle.d.ts","sourceRoot":"","sources":["../../../../../src/components/layout/SettingCard/SettingToggle.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAI9D;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,4GAqBxB,CAAC"}

package/dist/types/components/layout/SettingCard/index.d.ts

@@ -0,0 +1,6 @@
+export { SettingCard } from './SettingCard';
+export { SettingToggle } from './SettingToggle';
+export { SettingGroup } from './SettingGroup';
+export { SettingGrid, SETTING_GRID_CONTAINER } from './SettingGrid';
+export type { SettingCardCopy, SettingCardProps, SettingErrorFormatter, SettingGridColumns, SettingGridProps, SettingGroupProps, SettingHeadingLevel, SettingSaveResult, SettingStatus, SettingSwitchCopy, SettingToggleProps, SettingToggleVariant, } from './SettingCard.types';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/components/layout/SettingCard/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/layout/SettingCard/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACpE,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC"}

package/dist/types/components/layout/index.d.ts

@@ -8,6 +8,7 @@ export * from './Drawer';
 export * from './Resizable';
 export * from './ScrollArea';
 export * from './Separator';
+export * from './SettingCard';
 export * from './Sidebar';
 export * from './Skeleton/Skeleton';
 export * from './TableFilter';

package/dist/types/components/layout/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/components/layout/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,QAAQ,CAAC;AACvB,cAAc,2BAA2B,CAAC;AAC1C,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/components/layout/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,QAAQ,CAAC;AACvB,cAAc,2BAA2B,CAAC;AAC1C,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC"}

package/dist/types/copy/layout.d.ts

@@ -15,4 +15,31 @@ export interface TableFilterCopy {
     rangeMin: string;
     rangeMax: string;
 }
+/**
+ * The chrome words of an editable `SettingCard`. The card's own title, summary
+ * and status are per-card props; these are the words every card repeats.
+ */
+export interface SettingCardCopy {
+    /** The closed card's trigger. Its accessible name also carries the card's title. */
+    edit: string;
+    /** Discard the draft and close. */
+    cancel: string;
+    save: string;
+    /** Announced (and shown to sighted users as the Save label) while the save is pending. */
+    saving: string;
+    /** The disclosure that reveals the card's longer explanation. */
+    learnMore: string;
+    /** Shown when the save rejected and the host's `formatError` gave no sentence of its own. */
+    saveFailed: string;
+}
+/**
+ * What a switch that saves the moment it flips says about that save — shared
+ * by `SettingToggle` and `SettingGroup`'s main switch.
+ */
+export interface SettingSwitchCopy {
+    /** Announced while the flip is being saved. */
+    saving: string;
+    /** Shown when the save rejected and the host's `formatError` gave no sentence of its own. */
+    saveFailed: string;
+}
 //# sourceMappingURL=layout.d.ts.map

package/dist/types/copy/layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/copy/layout.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/copy/layout.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/types/en-US.layout.d.ts

@@ -2,6 +2,8 @@
  * The en-US pack for the layout family. Split the same way `pt-BR.layout.ts`
  * is — see `en-US.ts` for why the packs live in per-family files.
  */
-import type { TableFilterCopy } from './copy';
+import type { SettingCardCopy, SettingSwitchCopy, TableFilterCopy } from './copy';
 export declare const EN_US_TABLE_FILTER_COPY: TableFilterCopy;
+export declare const EN_US_SETTING_CARD_COPY: SettingCardCopy;
+export declare const EN_US_SETTING_SWITCH_COPY: SettingSwitchCopy;
 //# sourceMappingURL=en-US.layout.d.ts.map

package/dist/types/en-US.layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"en-US.layout.d.ts","sourceRoot":"","sources":["../../src/en-US.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":"en-US.layout.d.ts","sourceRoot":"","sources":["../../src/en-US.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/types/locales.d.ts

@@ -19,7 +19,7 @@
  */
 import type { DataViewsCopy } from './components/data-display/DataViews/data-views-copy';
 import type { SavedViewsLabels } from './components/layout/ContentToolbar/ContentToolbar.types';
-import type { AddressAutocompleteCopy, AutocompleteCopy, BreadcrumbCopy, CarouselCopy, CategorySelectCopy, CepFieldCopy, ChromeCopy, CodeEditorCopy, CommandPaletteCopy, ConfirmActionCopy, DataStateCopy, InstallPromptCopy, LightboxCopy, MapPreviewCopy, PasswordStrengthCopy, PhoneInputCopy, RichEditorToolbarCopy, SectionOnboardingCopy, SocialLoginCopy, TableFilterCopy, TimingDiagramCopy, TutorialCopy, UploadButtonCopy, UserAvatarCopy } from "./copy";
+import type { AddressAutocompleteCopy, AutocompleteCopy, BreadcrumbCopy, CarouselCopy, CategorySelectCopy, CepFieldCopy, ChromeCopy, CodeEditorCopy, CommandPaletteCopy, ConfirmActionCopy, DataStateCopy, InstallPromptCopy, LightboxCopy, MapPreviewCopy, PasswordStrengthCopy, PhoneInputCopy, RichEditorToolbarCopy, SectionOnboardingCopy, SettingCardCopy, SettingSwitchCopy, SocialLoginCopy, TableFilterCopy, TimingDiagramCopy, TutorialCopy, UploadButtonCopy, UserAvatarCopy } from "./copy";
 type LocalePack<T> = {
     readonly 'pt-BR': T;
     readonly 'en-US': T;
@@ -41,6 +41,8 @@ export declare const RICH_EDITOR_TOOLBAR_COPY: LocalePack<RichEditorToolbarCopy>
 export declare const PHONE_INPUT_COPY: LocalePack<PhoneInputCopy>;
 export declare const UPLOAD_BUTTON_COPY: LocalePack<UploadButtonCopy>;
 export declare const TABLE_FILTER_COPY: LocalePack<TableFilterCopy>;
+export declare const SETTING_CARD_COPY: LocalePack<SettingCardCopy>;
+export declare const SETTING_SWITCH_COPY: LocalePack<SettingSwitchCopy>;
 export declare const COMMAND_PALETTE_COPY: LocalePack<CommandPaletteCopy>;
 export declare const BREADCRUMB_COPY: LocalePack<BreadcrumbCopy>;
 export declare const SECTION_ONBOARDING_COPY: LocalePack<SectionOnboardingCopy>;

package/dist/types/locales.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locales.d.ts","sourceRoot":"","sources":["../../src/locales.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAC;AACzF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yDAAyD,CAAC;AAChG,OAAO,KAAK,EACV,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACf,MAAM,QAAQ,CAAC;AAIhB,KAAK,UAAU,CAAC,CAAC,IAAI;IAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAKlE,eAAO,MAAM,aAAa,0BAAqE,CAAC;AAChG,eAAO,MAAM,gBAAgB,4BAG5B,CAAC;AACF,eAAO,MAAM,aAAa,0BAAqE,CAAC;AAChG,eAAO,MAAM,mBAAmB,+BAG/B,CAAC;AACF,eAAO,MAAM,eAAe,2BAG3B,CAAC;AACF,eAAO,MAAM,eAAe,2BAG3B,CAAC;AAGF,eAAO,MAAM,aAAa,0BAAqE,CAAC;AAChG,eAAO,MAAM,WAAW,wBAA+D,CAAC;AAGxF,eAAO,MAAM,iBAAiB,6BAG7B,CAAC;AACF,eAAO,MAAM,yBAAyB,qCAGrC,CAAC;AACF,eAAO,MAAM,iBAAiB,8BAG7B,CAAC;AACF,eAAO,MAAM,gBAAgB,4BAG5B,CAAC;AACF,eAAO,MAAM,sBAAsB,kCAGlC,CAAC;AACF,eAAO,MAAM,wBAAwB,mCAGpC,CAAC;AACF,eAAO,MAAM,gBAAgB,4BAG5B,CAAC;AACF,eAAO,MAAM,kBAAkB,8BAG9B,CAAC;AAGF,eAAO,MAAM,iBAAiB,6BAG7B,CAAC;AAGF,eAAO,MAAM,oBAAoB,gCAGhC,CAAC;AACF,eAAO,MAAM,eAAe,4BAG3B,CAAC;AAGF,eAAO,MAAM,uBAAuB,mCAGnC,CAAC;AACF,eAAO,MAAM,mBAAmB,+BAG/B,CAAC;AACF,eAAO,MAAM,oBAAoB,gCAGhC,CAAC;AACF,eAAO,MAAM,cAAc,0BAAuE,CAAC;AACnG,eAAO,MAAM,kBAAkB,8BAG9B,CAAC;AAGF,eAAO,MAAM,mBAAmB,+BAG/B,CAAC;AACF,eAAO,MAAM,gBAAgB,4BAG5B,CAAC"}
+{"version":3,"file":"locales.d.ts","sourceRoot":"","sources":["../../src/locales.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAC;AACzF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yDAAyD,CAAC;AAChG,OAAO,KAAK,EACV,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACf,MAAM,QAAQ,CAAC;AAIhB,KAAK,UAAU,CAAC,CAAC,IAAI;IAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAKlE,eAAO,MAAM,aAAa,0BAAqE,CAAC;AAChG,eAAO,MAAM,gBAAgB,4BAG5B,CAAC;AACF,eAAO,MAAM,aAAa,0BAAqE,CAAC;AAChG,eAAO,MAAM,mBAAmB,+BAG/B,CAAC;AACF,eAAO,MAAM,eAAe,2BAG3B,CAAC;AACF,eAAO,MAAM,eAAe,2BAG3B,CAAC;AAGF,eAAO,MAAM,aAAa,0BAAqE,CAAC;AAChG,eAAO,MAAM,WAAW,wBAA+D,CAAC;AAGxF,eAAO,MAAM,iBAAiB,6BAG7B,CAAC;AACF,eAAO,MAAM,yBAAyB,qCAGrC,CAAC;AACF,eAAO,MAAM,iBAAiB,8BAG7B,CAAC;AACF,eAAO,MAAM,gBAAgB,4BAG5B,CAAC;AACF,eAAO,MAAM,sBAAsB,kCAGlC,CAAC;AACF,eAAO,MAAM,wBAAwB,mCAGpC,CAAC;AACF,eAAO,MAAM,gBAAgB,4BAG5B,CAAC;AACF,eAAO,MAAM,kBAAkB,8BAG9B,CAAC;AAGF,eAAO,MAAM,iBAAiB,6BAG7B,CAAC;AACF,eAAO,MAAM,iBAAiB,6BAG7B,CAAC;AACF,eAAO,MAAM,mBAAmB,+BAG/B,CAAC;AAGF,eAAO,MAAM,oBAAoB,gCAGhC,CAAC;AACF,eAAO,MAAM,eAAe,4BAG3B,CAAC;AAGF,eAAO,MAAM,uBAAuB,mCAGnC,CAAC;AACF,eAAO,MAAM,mBAAmB,+BAG/B,CAAC;AACF,eAAO,MAAM,oBAAoB,gCAGhC,CAAC;AACF,eAAO,MAAM,cAAc,0BAAuE,CAAC;AACnG,eAAO,MAAM,kBAAkB,8BAG9B,CAAC;AAGF,eAAO,MAAM,mBAAmB,+BAG/B,CAAC;AACF,eAAO,MAAM,gBAAgB,4BAG5B,CAAC"}

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

@@ -2,6 +2,8 @@
  * The pt-BR pack for the layout family. Split out of `pt-BR.ts`, which is a
  * barrel over this folder — see that file for why.
  */
-import type { TableFilterCopy } from './copy';
+import type { SettingCardCopy, SettingSwitchCopy, TableFilterCopy } from './copy';
 export declare const PT_BR_TABLE_FILTER_COPY: TableFilterCopy;
+export declare const PT_BR_SETTING_CARD_COPY: SettingCardCopy;
+export declare const PT_BR_SETTING_SWITCH_COPY: SettingSwitchCopy;
 //# sourceMappingURL=pt-BR.layout.d.ts.map

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/user-avatar.js

@@ -1,7 +1,7 @@
 import {
   UserAvatar,
   UserMenu
-} from "./chunk-V7A5ZAAF.js";
+} from "./chunk-YWJDUJAR.js";
 import "./chunk-UDQSIRAP.js";
 import "./chunk-NYFGFELX.js";
 import "./chunk-3ZVUNSFF.js";
@@ -10,22 +10,22 @@ import "./chunk-6ZZGK5DT.js";
 import "./chunk-MTEQEPNY.js";
 import "./chunk-VUHLNYAE.js";
 import "./chunk-2GSIEDGN.js";
-import "./chunk-OTWMG7B2.js";
+import "./chunk-WN5PNP6F.js";
+import "./chunk-FKUYRQSP.js";
 import "./chunk-76X6JRVI.js";
 import "./chunk-JH7EEJEQ.js";
-import "./chunk-FKUYRQSP.js";
 import "./chunk-BA4RHQ3B.js";
-import "./chunk-BLUURKCY.js";
-import "./chunk-KOX2AEFW.js";
+import "./chunk-K6LNHHSH.js";
+import "./chunk-ZKWVCSAB.js";
 import "./chunk-LN46DSMF.js";
 import "./chunk-TAMIZE4Q.js";
 import "./chunk-MKLIMY3D.js";
 import "./chunk-PAT2BQOQ.js";
 import "./chunk-TYJR4GOF.js";
-import "./chunk-EXFX3JRN.js";
-import "./chunk-GDN2LUTZ.js";
+import "./chunk-M47ZOUGF.js";
 import "./chunk-7FDU3FIN.js";
 import "./chunk-EPEJMTCQ.js";
+import "./chunk-GDN2LUTZ.js";
 import "./chunk-YFODI4KT.js";
 import "./chunk-VBP46YP4.js";
 import "./chunk-2BYKTBDL.js";

package/dist/utility/InstallPrompt.js

@@ -1,7 +1,8 @@
 import "../chunk-3QQVEYOR.js";
 import {
   InstallPrompt
-} from "../chunk-JE6RZ5L6.js";
+} from "../chunk-5ZOJLYD2.js";
+import "../chunk-GY62N32G.js";
 import {
   usePwaInstall
 } from "../chunk-5GMHJ7Y5.js";
@@ -13,7 +14,6 @@ import {
   readPwaInstallStash,
   resetPwaInstallStash
 } from "../chunk-UUL44SUX.js";
-import "../chunk-GY62N32G.js";
 import "../chunk-PZ5AY32C.js";
 export {
   InstallPrompt,

package/dist/utility/WorkflowStep.js

@@ -6,13 +6,13 @@ import "../chunk-7OO3BELX.js";
 import "../chunk-KJID4PRD.js";
 import "../chunk-RXNIOPOA.js";
 import "../chunk-ZSTSISM6.js";
-import "../chunk-TRTX4BDI.js";
+import "../chunk-DJKVSUXH.js";
 import "../chunk-7ZPUN7TV.js";
 import "../chunk-PT6TCWIW.js";
-import "../chunk-EXFX3JRN.js";
-import "../chunk-GDN2LUTZ.js";
+import "../chunk-M47ZOUGF.js";
 import "../chunk-7FDU3FIN.js";
 import "../chunk-EPEJMTCQ.js";
+import "../chunk-GDN2LUTZ.js";
 import "../chunk-YFODI4KT.js";
 import "../chunk-VBP46YP4.js";
 import "../chunk-2BYKTBDL.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.40.0",
+  "version": "6.41.0",
   "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

@@ -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);
+}