@eifi1/ui-kit 0.33.0 → 0.34.0

package/src/components/nav-pills.tsx

@@ -1,6 +1,7 @@
-import type { ComponentPropsWithoutRef, ComponentType, MouseEvent, ReactElement, ReactNode } from "react";
+import type { ComponentPropsWithoutRef, ComponentType, MouseEvent, ReactElement, ReactNode, Ref } from "react";
 import { cn } from "../lib/cn";
 import { useKitLink } from "../i18n/kit-labels";
+import { FOCUS_RING } from "./focus-ring";
 import { pickLinkRenderer, RenderedKitLink } from "./text-link";
 
 export interface NavPillItem<T extends string> {
@@ -49,17 +50,21 @@ export interface NavPillsProps<T extends string> extends Omit<ComponentPropsWith
   landmark?: boolean;
   /** Classes for every pill. */
   itemClassName?: string;
+  /** The `<nav>` (or the `<div role="group">`) — hence `HTMLElement` (0.34, API-2,
+   *  refactor audit 2026-10). */
+  ref?: Ref<HTMLElement>;
 }
 
 // The pill is a ToggleGroup segment's (`rounded`, `px-3 py-1.5`, the inverse fill for
 // the current one), so a strip of these beside a segmented control reads as the same
-// family. Unlike the segments, a pill never truncates: the strip WRAPS instead.
-const PILL =
-  "inline-flex items-center gap-1.5 whitespace-nowrap rounded-md px-3 py-1.5 text-sm font-medium transition-colors focus:outline-none focus-visible:ring-[length:var(--focus-ring-width)] focus-visible:ring-[var(--border-strong)] [&_svg]:size-4 [&_svg]:shrink-0";
+// family. Unlike the segments, a pill never truncates: the strip WRAPS instead. Its focus
+// ring is the kit's one focus frame (text-size §5), in brand; until 0.34 it copied the
+// segment's `ring-strong` too (refactor audit 2026-10, DOC-7).
+const PILL = `inline-flex items-center gap-1.5 whitespace-nowrap rounded-md px-3 py-1.5 text-sm font-medium transition-colors focus:outline-none ${FOCUS_RING} [&_svg]:size-4 [&_svg]:shrink-0`;
 const PILL_SM = "gap-1 px-2 py-1 text-xs [&_svg]:size-3.5";
-const PILL_CURRENT = "bg-[var(--bg-inverse)] text-[var(--text-inverse)]";
-const PILL_IDLE = "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-primary)]";
-const PILL_DISABLED = "cursor-not-allowed opacity-50 hover:bg-transparent hover:text-[var(--text-secondary)]";
+const PILL_CURRENT = "bg-inverse text-inverse";
+const PILL_IDLE = "text-secondary hover:bg-hover hover:text-primary";
+const PILL_DISABLED = "cursor-not-allowed opacity-50 hover:bg-transparent hover:text-secondary";
 
 /**
  * A set of links or buttons that WRAPS onto as many rows as it needs, the current one
@@ -85,12 +90,18 @@ export function NavPills<T extends string>({
   landmark = true,
   itemClassName,
   className,
+  ref,
   ...rest
 }: NavPillsProps<T>) {
   const kitLink = useKitLink();
   const Root = landmark ? "nav" : "div";
   return (
-    <Root {...rest} role={landmark ? undefined : "group"} className={cn("min-w-0", className)}>
+    <Root
+      {...rest}
+      ref={ref as Ref<HTMLDivElement> | undefined}
+      role={landmark ? undefined : "group"}
+      className={cn("min-w-0", className)}
+    >
       <ul className="m-0 flex list-none flex-wrap gap-1 p-0">
         {items.map((item) => {
           const isCurrent = item.value === current;

package/src/components/number-field.tsx

@@ -3,6 +3,7 @@ import type { ComponentProps, ReactNode } from "react";
 import { NumberInput } from "./number-input";
 import { evaluateExpression, formatResult } from "../lib/calc";
 import { decimalMark } from "../lib/decimal-marks";
+import { roundHalfAway } from "../lib/round";
 import { useKitLocale } from "../i18n/kit-labels";
 
 type NumberInputProps = ComponentProps<typeof NumberInput>;
@@ -87,13 +88,14 @@ function parseLive(text: string): number | null | undefined {
   return evaluateExpression(t) ?? undefined;
 }
 
-/** `toFixed` rounding rather than `Math.round(n * 10^d)`, which turns 1.005 into
- *  1.00 by way of 100.49999999999999 — the same choice the lenkbank field made. */
+/** `n` at `digits` decimals, half away from zero as WRITTEN — lib/round's
+ *  `roundHalfAway`, shared with `roundToCurrency` and AmountInput (BUG-11 follow-up,
+ *  refactor audit 2026-10). The `toFixed` this was turned 1.005 into 1.00 (1.005 is
+ *  1.00499… in binary) and −0.004 into −0; neither `Math.round(n * 10^d)` nor `toFixed`
+ *  rounds the figure a person typed. `digits` is cut to a whole 0–100. */
 function roundTo(n: number, digits: number | undefined): number {
   if (digits === undefined) return n;
-  const d = Math.min(Math.max(Math.trunc(digits), 0), 100);
-  const rounded = Number(n.toFixed(d));
-  return Number.isFinite(rounded) ? rounded : n;
+  return roundHalfAway(n, Math.min(Math.max(Math.trunc(digits), 0), 100));
 }
 
 /**
@@ -141,6 +143,13 @@ function roundTo(n: number, digits: number | undefined): number {
  * or a dot typed as the decimal in a comma locale); it is re-spelt in the locale's mark
  * when it commits.
  *
+ * LOCKED (0.33.1, Kurvenschmiede). A field that saves itself takes `commit` (or a
+ * `disabledReason` of its own), NumberInput's: under a locked `WriteLockProvider` it
+ * stays in the tab order showing its value, `readOnly`, with the lock's reason in the
+ * kit Tooltip and its description; the step keys, the calculator and the numpad are
+ * off, and nothing reaches `onValueChange` or `onCommit`. `disabled` takes it out of
+ * the tab order, which is what a lock must not do.
+ *
  * NOT FOR MONEY. `digits={2}` rounds, but a currency is more than two decimals: JPY has
  * none, a unit price has four, and the chip, the minor-unit default and `min`/`max` on
  * the SIGNED figure are {@link MoneyField}'s (number value) and {@link AmountInput}'s

package/src/components/number-input.tsx

@@ -1,18 +1,24 @@
-import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
-import type { KeyboardEvent, ReactNode } from "react";
+import { useEffect, useId, useMemo, useRef } from "react";
+import type { KeyboardEvent, ReactNode, Ref } from "react";
 import { CalculatorButton, type CalculatorButtonLabels } from "./calculator";
 import { NumberPadSheet, type NumberPadSheetLabels } from "./numpad-sheet";
-import { FIELD_BASE, FIELD_DISPLAY, FIELD_INVALID, FLOATING_INPUT_CLASS, FloatingField } from "./ui";
+import {
+  FIELD_BASE,
+  FIELD_DISPLAY,
+  FIELD_INVALID,
+  FLOATING_INPUT_CLASS,
+  FloatingField,
+} from "./field-base";
 import { CURRENCIES } from "./currency-select";
-import { hasMessage, mergeDescribedBy } from "./choice-parts";
-import { useInlineHint } from "./field-parts";
+import { FieldCaption, LockedReason, mergeRefs, type DisabledReasonDisplay } from "./field-parts";
+import { useEndWidth, useNumericField } from "./numeric-field";
+import type { CommitScope } from "./write-lock";
 import { cn } from "../lib/cn";
 import { commitExpression, formatResult } from "../lib/calc";
-import { decimalMark, localizeMark, readTyped, showsTyped } from "../lib/decimal-marks";
-import { usePhoneLayout } from "../hooks/use-breakpoint";
-import { useKitLocale } from "../i18n/kit-labels";
 
-interface NumberInputProps {
+/** {@link NumberInput}'s props — exported since 0.34 (refactor audit 2026-10, API-9): a
+ *  wrapper typed itself off `ComponentProps<typeof NumberInput>` until then. */
+export interface NumberInputProps {
   /** The text, DOT-decimal ("1234.5", or a calculation being typed: "12+5"), as
    *  `onChange` reports it — so a caller's `Number(value)` reads it. The field SHOWS it
    *  in the locale's mark (see `locale`). A comma here is read as the decimal mark too,
@@ -26,6 +32,11 @@ interface NumberInputProps {
    * fields so the save always sees the resolved number, never "10+5". */
   onCommit?: (value: string) => void;
   label?: ReactNode;
+  /** Names the field when it has no visible `label` (a table cell, a phone's display
+   *  shape). */
+  "aria-label"?: string;
+  /** @deprecated 0.34 — use `aria-label`; removed in 0.35 (refactor audit 2026-10, API-1).
+   *  Names the field only when `aria-label` is absent. */
   ariaLabel?: string;
   /** Names for the calculator this field renders — its trigger, and the controls
    *  inside the popover — and for the numpad sheet it opens on a phone. Overrides
@@ -135,6 +146,46 @@ interface NumberInputProps {
    *  numeric field that clamps what is typed as well. */
   min?: number;
   max?: number;
+  /**
+   * Why the value cannot be changed — {@link Button}'s `disabledReason`, for a number
+   * that SAVES itself: a setting committed on blur, a figure in a row editor
+   * (Kurvenschmiede's session page, 0.33.1). `disabled` takes the field out of the tab
+   * order, so the reason never reached a keyboard, and Kurvenschmiede wrote its own
+   * `CommitInput` to keep it in.
+   *
+   * With a reason the field stays in the tab order and shows its value, `readOnly` (the
+   * settled grey FIELD_BASE gives a `[readonly]` field) and `aria-disabled`, as the
+   * Combobox family's lock is. Nothing changes the value: the step keys do nothing, the
+   * calculator and the phone's numpad are not offered, and neither blur nor Enter
+   * commits — so `onChange` and `onCommit` are never called. Enter is swallowed, so the
+   * field does not submit the form around it. The reason is a line under the field at
+   * Large and on a touch screen, else in the kit {@link Tooltip} (`disabledReasonDisplay`),
+   * and on the input's `aria-describedby`, between the caption and the error. Wins over
+   * `disabled`.
+   */
+  disabledReason?: ReactNode;
+  /**
+   * Where the reason shows — {@link Button}'s `disabledReasonDisplay`: by default a line
+   * under the field at Large and on a touch screen, the tooltip otherwise (§4 "No fact
+   * only in a tooltip"; DUP-3, refactor audit 2026-10).
+   */
+  disabledReasonDisplay?: DisabledReasonDisplay;
+  /**
+   * This field COMMITS — {@link Button}'s `commit`: under a locked
+   * {@link WriteLockProvider} it is locked the `disabledReason` way with the lock's reason
+   * (which wins over its own). A field whose value only reaches the server through the
+   * form's Save leaves this off and stays editable under the lock; the Save takes
+   * `commit`. No provider, or an unlocked one: no effect. {@link NumberField} and
+   * {@link IntegerField} pass it on.
+   */
+  commit?: CommitScope;
+  /**
+   * The `<input>`, as a React 19 ref prop (0.34, API-3, refactor audit 2026-10): the one
+   * focusable field of its family with no ref at all, so react-hook-form's focus-on-error
+   * could reach it only through /rhf's id lookup, and an app not at all.
+   * {@link NumberField} and {@link IntegerField} pass it on.
+   */
+  ref?: Ref<HTMLInputElement>;
 }
 
 /** Decimal places of `n` as written ("0.25" → 2, "1e-7" → 7), for decimal-exact
@@ -180,9 +231,8 @@ export function stepNumber(
   return clamp(Number((origin + k * step).toFixed(places)));
 }
 
-// The error line under a field — the type of `ui.tsx`'s (module-private) one, so a
-// NumberInput's message is indistinguishable from an Input's.
-const FIELD_ERROR_CLASS = "mt-1 text-caption leading-tight text-[var(--danger)]";
+/** NumberInput never rounds: what was typed (or calculated) is what it reports. */
+const asTyped = (text: string) => text;
 
 // ── The money guard (kastlan 5, Kurvenschmiede) ─────────────────────────────────
 
@@ -205,7 +255,7 @@ function namesMoney(node: ReactNode): boolean {
 
 /**
  * Is this field being used for MONEY? A currency in the unit (`suffix="CHF"`), or in
- * the label, `ariaLabel` or placeholder of a field with no unit at all ("Estimated
+ * the label, `aria-label` or placeholder of a field with no unit at all ("Estimated
  * cost (CHF)"). Any other suffix is a unit — "%", "mm", "N·m" — and says what the
  * digits are, whatever the label says. `digits` plays no part: NumberInput has none,
  * and Kurvenschmiede's engineering fields at 2 and 3 decimals are exactly what this
@@ -264,59 +314,44 @@ function devWarnings(): boolean {
  */
 export function NumberInput(props: NumberInputProps) {
   const {
+    ref,
     value,
     onChange,
     onCommit,
     label,
-    ariaLabel,
+    "aria-label": ariaLabelAttr,
+    ariaLabel: ariaLabelProp,
     labels,
     placeholder,
-    disabled,
     autoFocus,
     className,
     inputClassName,
     id,
-    calculator = true,
-    variant = "field",
-    hint: hintProp,
-    invalid: invalidProp,
-    error,
-    locale: localeProp,
-    "aria-describedby": ariaDescribedBy,
-    "aria-invalid": ariaInvalid,
     "aria-required": ariaRequired,
     suffix,
     step,
     min,
     max,
+    disabledReasonDisplay,
   } = props;
+  // The DOM spelling wins; `ariaLabel` is the fallback for call sites not moved yet.
+  const ariaLabel = ariaLabelAttr ?? ariaLabelProp;
   const generatedId = useId();
   const fieldId = id ?? generatedId;
-  const hintId = useId();
-  const errorId = useId();
-  // §4 "No fact only in a tooltip" (docs/text-size-harmonization.md): at Large and on a
-  // touch screen a FieldHint is its words, so it takes the caption's path below — the
-  // other kit fields do the same through `useFieldHint`.
-  const hint = useInlineHint(hintProp);
-  // Text is a caption under the field; a FieldHint rides the label line. See `hint`.
-  const textHint = (typeof hint === "string" && hint !== "") || typeof hint === "number";
-  const hasError = hasMessage(error);
+  // The engine AmountInput shares (DUP-10): the lock (focusable, `readOnly`, nothing
+  // changes or commits — see `disabledReason`), the hint — a FieldHint is its words at
+  // Large and on touch, §4 — the error, the description's order, the typist's draft and
+  // the locale's mark (see the component's note), the calculator and the numpad.
+  // NumberInput never rounds; it shows the value as it is.
+  const numeric = useNumericField(props, { settle: asTyped, display: () => value });
+  const { lock, locked, off, isMobile, asDisplay, showCalc, showNumpad, setFocused, mark, setDraft, derived } = numeric;
+  const invalid = numeric.isInvalid;
   // Passed at all — even as `undefined` — the field keeps its box; see `error`.
   const reserve = "error" in props || "hint" in props;
-  // The standing advice first, the news second: the caller's ids, the caption, the error.
-  const describedBy = mergeDescribedBy(ariaDescribedBy, textHint && hintId, hasError && errorId);
-  const invalid = Boolean(invalidProp) || hasError || ariaInvalid === true || ariaInvalid === "true";
   const labelled = label !== undefined;
-  // On phones we suppress the OS keyboard (inputMode="none" below) for our own
-  // calculator numpad, so the desktop popover trigger is hidden (feedback #334).
-  const isMobile = usePhoneLayout();
-  const asDisplay = isMobile && variant === "display";
-  const showCalc = calculator && !disabled && !isMobile;
-  const [focused, setFocused] = useState(false);
   // The unit and the calculator's measured width, reserved as the field's end padding.
-  const endRef = useRef<HTMLDivElement>(null);
-  const [endWidth, setEndWidth] = useState<number | null>(null);
   const hasEnd = showCalc || suffix !== undefined;
+  const [endRef, endWidth] = useEndWidth(hasEnd);
   // Before the first measurement (and wherever there is no layout), a TEXT unit
   // reserves an estimate from its length — one `ch` a character, in the input's own
   // (larger) font, so it errs wide — plus the span's `pe-2` and the 4px gap, and the
@@ -325,36 +360,20 @@ export function NumberInput(props: NumberInputProps) {
   const suffixChars = typeof suffix === "string" || typeof suffix === "number" ? String(suffix).length : null;
   const estimatedEnd =
     suffixChars !== null ? `calc(${suffixChars}ch + 0.75rem${showCalc ? " + 2.25rem" : ""})` : undefined;
-  useLayoutEffect(() => {
-    const el = endRef.current;
-    if (!hasEnd || !el || typeof ResizeObserver === "undefined") return;
-    // The first callback fires on `observe`; no layout (jsdom) keeps the class fallback.
-    const observer = new ResizeObserver(() => {
-      const width = el.getBoundingClientRect().width;
-      setEndWidth(width > 0 ? Math.ceil(width) : null);
-    });
-    observer.observe(el);
-    return () => observer.disconnect();
-  }, [hasEnd]);
   // On mobile, focusing opens the numpad bottom sheet instead of the native
-  // keyboard (#334); the ref lets its "Done" blur → commit + close.
-  const showNumpad = isMobile && !disabled && focused;
+  // keyboard (#334); the ref lets its "Done" blur → commit + close. The caller's `ref`
+  // gets the same element.
   const inputRef = useRef<HTMLInputElement>(null);
+  const setInput = useMemo(() => mergeRefs(inputRef, ref), [ref]);
 
-  // The mark is the locale's; see the component's note. `derived` is the value in that
-  // mark — one character for one, no grouping — and `draft` the typist's own text,
-  // shown only while it still says what the value says (see `showsTyped`).
-  const mark = decimalMark(useKitLocale(localeProp));
-  const [draft, setDraft] = useState<string | null>(null);
-  const derived = localizeMark(value, mark);
-  const display = draft !== null && showsTyped(draft, mark, value) ? draft : derived;
+  // `derived` is the value in the locale's mark — one character for one, no grouping —
+  // and the draft the typist's own text, shown only while it still says what the value
+  // says (see `showsTyped`).
+  const display = numeric.typedFor(value) ?? derived;
 
   // A keystroke, a paste or a numpad key: the typist's text is kept, the value is what
   // a number reads it as.
-  const typed = (raw: string) => {
-    setDraft(raw);
-    onChange(readTyped(raw, mark));
-  };
+  const typed = (raw: string) => onChange(numeric.read(raw));
   // A RESULT — the calculator's, the numpad's "=" — is dot-decimal already. It does not
   // go through `typed`: "1.234" out of `100/81.03…` is never a thousand.
   const result = (next: string) => {
@@ -380,7 +399,7 @@ export function NumberInput(props: NumberInputProps) {
 
   const commit = () => {
     setDraft(null);
-    const next = commitExpression(value);
+    const next = numeric.settle(commitExpression(value));
     if (next !== value) onChange(next);
     onCommit?.(next);
   };
@@ -395,6 +414,12 @@ export function NumberInput(props: NumberInputProps) {
   };
 
   const onKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
+    // Locked: Enter submits no form and commits nothing, and no key steps the value.
+    // The arrows and Home/End stay the caret's, for a long value someone is reading.
+    if (locked) {
+      if (e.key === "Enter") e.preventDefault();
+      return;
+    }
     if (e.key === "Enter") return commit();
     // A zero, negative or non-finite step is no step: the keys stay the caret's.
     if (!step || !(step > 0) || !Number.isFinite(step) || e.altKey || e.ctrlKey || e.metaKey) return;
@@ -406,16 +431,19 @@ export function NumberInput(props: NumberInputProps) {
     stepBy(count);
   };
 
+  // While locked the field sits in the reason's frame (line or Tooltip), its outermost
+  // box — so `className` (a width, a flex or grid cell) moves onto that, and the form
+  // keeps its layout, as on Select.
   const field = (
     <FloatingField
-      className={cn("w-full", className)}
+      className={cn("w-full", !locked && className)}
       htmlFor={fieldId}
       label={label}
       srOnlyLabel={asDisplay}
-      hint={textHint ? undefined : hint}
+      hint={numeric.hint.labelHint}
     >
       <input
-        ref={inputRef}
+        ref={setInput}
         id={fieldId}
         aria-label={ariaLabel}
         type="text"
@@ -425,21 +453,28 @@ export function NumberInput(props: NumberInputProps) {
         autoComplete="off"
         // eslint-disable-next-line jsx-a11y/no-autofocus -- a documented prop the caller opts into (off by default); the field never takes focus on its own.
         autoFocus={autoFocus}
-        disabled={disabled}
+        disabled={off}
+        // Locked: focusable, `readOnly`, `aria-disabled` — see `disabledReason`.
+        readOnly={locked || undefined}
+        aria-disabled={locked || undefined}
         // Display mode has no floating label to feed the blank-placeholder trick,
         // and an empty borderless figure shows nothing — so it keeps whatever
         // placeholder the caller gave, falling back to a zero to aim at.
         placeholder={asDisplay ? (placeholder ?? "0") : labelled ? " " : placeholder}
         value={display}
-        onChange={(e) => typed(e.target.value)}
+        onChange={(e) => {
+          if (!locked) typed(e.target.value);
+        }}
         onFocus={() => setFocused(true)}
         onBlur={() => {
-          commit();
+          // Nothing commits under the lock — not even a draft typed before it arrived,
+          // which stays in the field for when it lifts.
+          if (!locked) commit();
           setFocused(false);
         }}
         onKeyDown={onKeyDown}
         aria-invalid={invalid || undefined}
-        aria-describedby={describedBy}
+        aria-describedby={numeric.describedBy}
         aria-required={ariaRequired}
         // The end padding sits last so it always wins over an inputClassName that
         // sets its own px. Both trailing controls can be on at once, so the room
@@ -455,6 +490,7 @@ export function NumberInput(props: NumberInputProps) {
           inputClassName,
           showCalc && suffix !== undefined ? "pe-16" : showCalc ? "pe-9" : suffix !== undefined ? "pe-8" : undefined,
           invalid && FIELD_INVALID,
+          locked && "cursor-not-allowed",
         )}
         // The classes above are the fallback; once the end controls are measured the
         // field reserves exactly their width (+4px). A fixed pe-8 for any unit left a
@@ -468,7 +504,7 @@ export function NumberInput(props: NumberInputProps) {
               : undefined
         }
       />
-      {(showCalc || suffix !== undefined) && (
+      {hasEnd && (
         // One flex track for both, so the unit and the calculator sit side by side
         // instead of stacking on the same corner — AmountInput's arrangement, which
         // has carried a chip and a calculator together since #430.
@@ -480,7 +516,7 @@ export function NumberInput(props: NumberInputProps) {
               value={derived}
               onChange={result}
               className="self-stretch px-2.5"
-              ariaLabel={labels?.calculatorTrigger}
+              aria-label={labels?.calculatorTrigger}
               labels={labels?.calculator}
             />
           )}
@@ -489,7 +525,7 @@ export function NumberInput(props: NumberInputProps) {
               aria-hidden
               // pe-2, not the input's px-3: the unit is chrome at the box's edge, and
               // with pe-3 plus the 4px gap it took ~26px of a narrow table cell.
-              className="pointer-events-none pe-2 text-xs font-medium text-[var(--text-muted)]"
+              className="pointer-events-none pe-2 text-xs font-medium text-muted"
             >
               {suffix}
             </span>
@@ -511,23 +547,22 @@ export function NumberInput(props: NumberInputProps) {
       )}
     </FloatingField>
   );
-  if (!textHint && !hasError && !reserve) return field;
+  const box = locked ? (
+    <LockedReason lock={lock} display={disabledReasonDisplay} className={cn("block w-full", className)}>
+      {field}
+    </LockedReason>
+  ) : (
+    field
+  );
+  if (numeric.hint.captionText === undefined && numeric.errorEl === null && !reserve) return box;
   // Outside the field's own `relative` box, as Select's caption is: the calculator
   // and the unit are `inset-y-0` in it and would stretch down over a second line.
   // `className` stays on the field, so adding a caption cannot change what it styles.
   return (
     <div>
-      {field}
-      {textHint && (
-        <p id={hintId} className="mt-1 text-caption leading-tight text-[var(--text-muted)]">
-          {hint}
-        </p>
-      )}
-      {hasError && (
-        <p id={errorId} className={FIELD_ERROR_CLASS}>
-          {error}
-        </p>
-      )}
+      {box}
+      <FieldCaption parts={numeric.hint} />
+      {numeric.errorEl}
     </div>
   );
 }

package/src/components/numeric-field.ts

@@ -0,0 +1,161 @@
+import { useLayoutEffect, useRef, useState } from "react";
+import type { ReactNode, RefObject } from "react";
+import { usePhoneLayout } from "../hooks/use-breakpoint";
+import { useKitLocale } from "../i18n/kit-labels";
+import { decimalMark, localizeMark, readTyped, showsTyped } from "../lib/decimal-marks";
+import {
+  mergeDescribedBy,
+  useFieldError,
+  useFieldHint,
+  useLockReason,
+  type FieldHintParts,
+  type LockReason,
+} from "./field-parts";
+import type { CommitScope } from "./write-lock";
+
+/**
+ * The engine NumberInput and AmountInput share (DUP-10, refactor audit 2026-10): the
+ * lock, the hint and its caption, the error, the `aria-describedby` order, the typist's
+ * draft and what the field shows, the calculator and the phone's numpad, and the room
+ * its end controls take. They were two copies of it, and each fix had to be made twice —
+ * some reached only one: NumberInput measured its end controls (keksdose live #367) and
+ * took a `locale`, AmountInput did neither; the 0.32 FieldHint caption reached
+ * AmountInput two releases late.
+ *
+ * Each field keeps what is its own: the settle (money's minor unit and `min`/`max`
+ * against NumberInput's "what was typed"), the caller-owned sign, and its trailing
+ * controls. Package-private — not re-exported from the barrel.
+ */
+
+/** The props both fields take and this engine reads. */
+export interface NumericFieldProps {
+  hint?: ReactNode;
+  error?: ReactNode;
+  invalid?: boolean;
+  disabled?: boolean;
+  disabledReason?: ReactNode;
+  commit?: CommitScope;
+  /** Show the desktop calculator trigger. Default `true`. */
+  calculator?: boolean;
+  variant?: "field" | "display";
+  locale?: string;
+  "aria-describedby"?: string;
+  "aria-invalid"?: boolean | "true" | "false";
+}
+
+export interface NumericFieldOptions {
+  /** The field's own settle, dot-decimal in and out — AmountInput's minor unit and
+   *  `min` / `max`; NumberInput's identity (it never rounds). */
+  settle: (text: string) => string;
+  /** What the field shows while no typed draft stands, dot-decimal, given whether it
+   *  has focus — spelt in the locale's mark here (`derived`). */
+  display: (focused: boolean) => string;
+}
+
+export interface NumericField {
+  /** The write lock: focusable, `readOnly`, nothing changes or commits. */
+  lock: LockReason;
+  locked: boolean;
+  /** Natively `disabled`: `disabled`, and no lock — a reason wins over it. */
+  off: boolean;
+  /** The hint, split into the caption under the field and the label line's "?". */
+  hint: FieldHintParts;
+  /** `invalid`, a message, or a form library's `aria-invalid`. */
+  isInvalid: boolean;
+  /** The caller's ids, the caption, a lock's reason, the error — Select's order. */
+  describedBy: string | undefined;
+  /** The message under the field, or `null`. */
+  errorEl: ReactNode;
+  /** The phone layout: the numpad sheet replaces the keyboard and the calculator. */
+  isMobile: boolean;
+  /** `variant="display"`, on a phone. */
+  asDisplay: boolean;
+  showCalc: boolean;
+  showNumpad: boolean;
+  focused: boolean;
+  setFocused: (focused: boolean) => void;
+  /** The locale's decimal mark — the field's `locale`, else the provider's. */
+  mark: "," | ".";
+  /** The typist's own text while a figure is typed, else `null`. */
+  draft: string | null;
+  setDraft: (draft: string | null) => void;
+  /** `display(focused)` in the locale's mark. */
+  derived: string;
+  /** The draft, while it still says what `canonical` (dot-decimal) says and holds
+   *  nothing the field would drop — see `showsTyped`; else `null`. */
+  typedFor: (canonical: string) => string | null;
+  /** A keystroke's raw text: kept as the draft, and read as a number reads it —
+   *  grouping off, dot-decimal. */
+  read: (raw: string) => string;
+  settle: (text: string) => string;
+}
+
+export function useNumericField(props: NumericFieldProps, { settle, display }: NumericFieldOptions): NumericField {
+  const lock = useLockReason(props.commit, props.disabledReason);
+  const locked = lock.locked;
+  // §4: a FieldHint is the caption at Large and on touch, as on every field.
+  const hint = useFieldHint(props.hint, props["aria-describedby"]);
+  // The standing advice first, the news second: the caller's ids, the caption, the
+  // error — a lock's reason between the last two, as on Select.
+  const field = useFieldError(
+    props.error,
+    props.invalid,
+    mergeDescribedBy(hint.describedBy, locked && lock.reasonId),
+    props["aria-invalid"],
+  );
+  // On phones the OS keyboard is suppressed (`inputMode="none"`) for the kit's numpad
+  // sheet, so the desktop calculator trigger is hidden (feedback #334). A locked field
+  // offers neither: their result would be a value.
+  const isMobile = usePhoneLayout();
+  const [focused, setFocused] = useState(false);
+  const mark = decimalMark(useKitLocale(props.locale));
+  const [draft, setDraft] = useState<string | null>(null);
+  return {
+    lock,
+    locked,
+    off: Boolean(props.disabled) && !locked,
+    hint,
+    isInvalid: field.isInvalid,
+    describedBy: field.describedBy,
+    errorEl: field.errorEl,
+    isMobile,
+    asDisplay: isMobile && props.variant === "display",
+    showCalc: (props.calculator ?? true) && !props.disabled && !locked && !isMobile,
+    showNumpad: isMobile && !props.disabled && !locked && focused,
+    focused,
+    setFocused,
+    mark,
+    draft,
+    setDraft,
+    derived: localizeMark(display(focused), mark),
+    typedFor: (canonical) => (draft !== null && showsTyped(draft, mark, canonical) ? draft : null),
+    read: (raw) => {
+      setDraft(raw);
+      return readTyped(raw, mark);
+    },
+    settle,
+  };
+}
+
+/**
+ * The measured width of a field's end controls (keksdose live #367), and the ref for
+ * their track: `null` before the first measurement and wherever there is no layout
+ * (jsdom), where the field keeps its class fallback. A `ResizeObserver` calls back once
+ * on `observe`, and again whenever the controls change size (a chip's code, a translated
+ * label, the text size). A pair, so the width reads as the plain number it is.
+ */
+export function useEndWidth(present: boolean): [RefObject<HTMLDivElement | null>, number | null] {
+  const ref = useRef<HTMLDivElement>(null);
+  const [width, setWidth] = useState<number | null>(null);
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!present || !el || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(() => {
+      const measured = el.getBoundingClientRect().width;
+      setWidth(measured > 0 ? Math.ceil(measured) : null);
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [present]);
+  return [ref, width];
+}