@eifi1/ui-kit 0.33.1 → 0.35.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));
 }
 
 /**

package/src/components/number-input.tsx

@@ -1,19 +1,25 @@
-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 { CURRENCIES } from "./currency-select";
-import { hasMessage, mergeDescribedBy } from "./choice-parts";
-import { LockedReason, useInlineHint, useLockReason } from "./field-parts";
+import {
+  FIELD_BASE,
+  FIELD_DISPLAY,
+  FIELD_INVALID,
+  FLOATING_INPUT_CLASS,
+  FloatingField,
+} from "./field-base";
+// The data alone (0.35): not the picker, which this field does not render.
+import { CURRENCIES } from "../currencies";
+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,
@@ -27,7 +33,9 @@ interface NumberInputProps {
    * fields so the save always sees the resolved number, never "10+5". */
   onCommit?: (value: string) => void;
   label?: ReactNode;
-  ariaLabel?: string;
+  /** Names the field when it has no visible `label` (a table cell, a phone's display
+   *  shape). */
+  "aria-label"?: 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
    *  for THIS field only: both resolve the `calculator` namespace of
@@ -148,11 +156,18 @@ interface NumberInputProps {
    * 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 in the kit {@link Tooltip}
+   * 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
@@ -162,6 +177,13 @@ interface NumberInputProps {
    * {@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
@@ -207,9 +229,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) ─────────────────────────────────
 
@@ -232,7 +253,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
@@ -291,68 +312,41 @@ function devWarnings(): boolean {
  */
 export function NumberInput(props: NumberInputProps) {
   const {
+    ref,
     value,
     onChange,
     onCommit,
     label,
-    ariaLabel,
+    "aria-label": ariaLabel,
     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,
-    disabledReason,
-    commit: commitScope,
+    disabledReasonDisplay,
   } = props;
   const generatedId = useId();
   const fieldId = id ?? generatedId;
-  const hintId = useId();
-  const errorId = useId();
-  // The lock: focusable, `readOnly`, nothing changes or commits — see `disabledReason`.
-  const lock = useLockReason(commitScope, disabledReason);
-  const locked = lock.locked;
-  // Locked wins over `disabled`: the point of a reason is a field a keyboard reaches.
-  const off = Boolean(disabled) && !locked;
-  // §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 — a lock's reason between the last two, as on Select.
-  const describedBy = mergeDescribedBy(ariaDescribedBy, textHint && hintId, locked && lock.reasonId, 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";
-  // A locked field offers no calculator: its result would be a value.
-  const showCalc = calculator && !disabled && !locked && !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
@@ -361,36 +355,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 && !locked && 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) => {
@@ -416,7 +394,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);
   };
@@ -448,7 +426,7 @@ export function NumberInput(props: NumberInputProps) {
     stepBy(count);
   };
 
-  // While locked the field sits in the reason's Tooltip, which becomes its outermost
+  // 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 = (
@@ -457,10 +435,10 @@ export function NumberInput(props: NumberInputProps) {
       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"
@@ -491,7 +469,7 @@ export function NumberInput(props: NumberInputProps) {
         }}
         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
@@ -521,7 +499,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.
@@ -533,7 +511,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}
             />
           )}
@@ -542,7 +520,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>
@@ -565,29 +543,21 @@ export function NumberInput(props: NumberInputProps) {
     </FloatingField>
   );
   const box = locked ? (
-    <LockedReason lock={lock} className={cn("block w-full", className)}>
+    <LockedReason lock={lock} display={disabledReasonDisplay} className={cn("block w-full", className)}>
       {field}
     </LockedReason>
   ) : (
     field
   );
-  if (!textHint && !hasError && !reserve) return box;
+  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>
       {box}
-      {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>
-      )}
+      <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];
+}

package/src/components/numpad-sheet.tsx

@@ -4,7 +4,7 @@ import { useMemo } from "react";
 import type { ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { FOCUS_RING } from "./focus-ring";
-import { useEscapeKey } from "../hooks/use-dismiss";
+import { useDismissLayer } from "../hooks/use-dismiss";
 import { evaluateExpression, formatResult, sanitizeLive } from "../lib/calc";
 import {
   DEFAULT_CALCULATOR_LABELS,
@@ -179,17 +179,17 @@ export function NumberPadSheet({
   // `role="group"`, not a dialog. A keyboard does not trap focus; it is what you type
   // WITH.
   //
-  // What was genuinely missing is a way OUT that is not a tap. `useEscapeKey` and not
-  // a handler on the sheet, because the sheet never has the focus a keydown would
-  // bubble from — the host does, and the host is not this component. Escape does what
-  // the Done key does rather than cancelling, because committing on blur is the
-  // host's contract and a cancel would have to be the host's to offer.
+  // What was genuinely missing is a way OUT that is not a tap. A layer on the kit's
+  // Escape stack and not a handler on the sheet, because the sheet never has the focus
+  // a keydown would bubble from — the host does, and the host is not this component.
+  // Escape does what the Done key does rather than cancelling, because committing on
+  // blur is the host's contract and a cancel would have to be the host's to offer.
   //
-  // The limit, since it is better written down than discovered: inside a `Modal` the
-  // dialog's own Escape handler sits on the focus path and stops the event before a
-  // document listener sees it, so there the press closes the dialog — which it did
-  // before this line existed too, and which takes the pad with it either way.
-  useEscapeKey(onDone);
+  // Inside a `Modal` the pad opened over the dialog, so the stack hands the first
+  // Escape to the pad and the next to the dialog (Wave 2, DUP-1). It used to be the
+  // other way round, written down here as the limit: the dialog's own handler stopped
+  // the key before a document listener saw it, and the press closed the dialog.
+  useDismissLayer(true, onDone);
 
   const result = evaluateExpression(value);
   const preview = result !== null && formatResult(result) !== value.trim() ? `= ${formatResult(result)}` : "";
@@ -212,20 +212,20 @@ export function NumberPadSheet({
       // Keep the host input focused when tapping the pad: preventDefault on
       // pointerdown blocks the focus/blur, while the buttons' click still fires.
       onPointerDown={(e) => e.preventDefault()}
-      className="fixed inset-x-0 bottom-0 z-50 border-t border-[var(--border)] bg-[var(--bg-surface)] px-2 pt-2 shadow-[0_-4px_24px_rgba(0,0,0,0.12)]"
+      className="fixed inset-x-0 bottom-0 z-50 border-t border-subtle bg-surface px-2 pt-2 shadow-[0_-4px_24px_rgba(0,0,0,0.12)]"
       style={{ paddingBottom: "max(0.5rem, env(safe-area-inset-bottom))" }}
     >
       {/* Header display: which field + the running expression and live result, so
           the value stays visible even when the sheet covers the field. */}
       <div className="flex items-end justify-between gap-3 px-2 pb-2">
         {label != null && (
-          <span className="truncate pb-1 text-xs font-medium text-[var(--money-neutral)]">{label}</span>
+          <span className="truncate pb-1 text-xs font-medium text-money-neutral">{label}</span>
         )}
         {/* At the logical end, opposite the label; the figures themselves stay
             left-to-right and right-aligned, like the desktop calculator's. */}
         <div className="ms-auto min-w-0">
-          <div dir="ltr" className="truncate text-right font-mono text-lg leading-tight text-[var(--text-primary)]">{value || "0"}</div>
-          <div dir="ltr" className="h-4 text-right font-mono text-xs text-[var(--money-neutral)]">{preview}</div>
+          <div dir="ltr" className="truncate text-right font-mono text-lg leading-tight text-primary">{value || "0"}</div>
+          <div dir="ltr" className="h-4 text-right font-mono text-xs text-money-neutral">{preview}</div>
         </div>
       </div>
 
@@ -271,7 +271,7 @@ export function NumberPadSheet({
           // on screen, which is the defect this change exists to fix.
           className={cn(
             PAD_BTN,
-            "col-span-2 bg-[var(--brand)] text-[var(--brand-contrast)] focus-visible:ring-[var(--brand-contrast)] active:bg-[var(--brand-hover)]",
+            "col-span-2 bg-brand text-brand-contrast focus-visible:ring-brand-contrast active:bg-brand-hover",
           )}
         >
           {text.done}