@eifi1/ui-kit 0.32.2 → 0.33.1

package/src/components/file-button.tsx

@@ -5,7 +5,7 @@ import { useAnnounce } from "../hooks/use-announce";
 import { useKitFileLabels, useKitLabels } from "../i18n/kit-labels";
 import { Button, Spinner } from "./ui";
 import { Tooltip } from "./tooltip";
-import { useCommitReason } from "./write-lock";
+import { useCommitReason, type CommitScope } from "./write-lock";
 
 /**
  * A button that opens the file picker — the shape all three apps kept writing by hand
@@ -444,7 +444,7 @@ export interface FileButtonProps
    * one: no effect. A picker that only fills a form the user saves later is not a
    * commit, and is left live — the form's Save carries the lock.
    */
-  commit?: boolean;
+  commit?: CommitScope;
 }
 
 /** A reason that is really there — `null`, `false` and `""` are no reason. */
@@ -612,7 +612,8 @@ export const FileButton = forwardRef<HTMLButtonElement, FileButtonProps>(functio
   }
   return (
     // One inline row, so the name sits beside the button wherever the button sits; the
-    // name truncates rather than pushing the row wider, and the full list is in the
+    // name truncates rather than pushing the row wider (at Normal: from Large up it wraps,
+    // `truncate-until-large`, text size §10.17), and the full list is in the
     // kit's own Tooltip — not a native `title` (0.16.0 shipped one: the one-tooltip rule
     // since keksdose dev#523, and a title never opens on touch). Lazy, so the closed
     // bubble adds nothing to the read-out's text.
@@ -628,7 +629,7 @@ export const FileButton = forwardRef<HTMLButtonElement, FileButtonProps>(functio
         className="flex min-w-0 text-sm text-[var(--text-secondary)]"
       >
         <Tooltip label={picked.map((f) => f.name).join(", ")} lazy className="min-w-0">
-          <span className="block truncate">{pickedText}</span>
+          <span className="block truncate-until-large">{pickedText}</span>
         </Tooltip>
       </span>
       {picker.element}

package/src/components/file-dropzone.tsx

@@ -15,7 +15,7 @@ import {
 import type { FilePickHandler, FilePickerLabels, FileRejection } from "./file-button";
 import { useDragTarget } from "../hooks/use-file-drop";
 import { toast } from "./toast";
-import { useCommitReason } from "./write-lock";
+import { useCommitReason, type CommitScope } from "./write-lock";
 
 /**
  * Where a refused file's message goes.
@@ -160,7 +160,7 @@ export interface FileDropzoneProps extends Omit<ComponentPropsWithoutRef<"div">,
    * reason (which wins over one of its own). No provider, or an unlocked one: no
    * effect. A zone that only stages a file for a form saved later is not a commit.
    */
-  commit?: boolean;
+  commit?: CommitScope;
   /**
    * Replace the zone's body — the icon, the text and the chosen-file list — with your
    * own, given the zone's state: keksdose's spinner-plus-"uploading", its multi-shot

package/src/components/floating-panel.tsx

@@ -243,7 +243,7 @@ export function FloatingActionButton({
               pressed === false &&
                 "bg-[var(--bg-surface)] text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-primary)]",
               pressed === true &&
-                "border-[var(--brand)] bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)]",
+                "border-[var(--brand)] bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)] hover:text-brand-muted",
               "outline-none focus-visible:ring-offset-2",
               FOCUS_RING,
               className,
@@ -650,10 +650,12 @@ export interface FloatingActionProps extends Omit<ButtonHTMLAttributes<HTMLButto
   ref?: Ref<HTMLButtonElement>;
 }
 
+// Each fill under its own foreground (0.33): warning borrowed `--text-inverse`, the
+// surface colour, which was 4.24:1 on the light warning fill.
 const BADGE_TONE: Record<NonNullable<FloatingActionProps["badgeTone"]>, string> = {
-  warning: "bg-[var(--warning)] text-[var(--text-inverse)]",
-  danger: "bg-[var(--danger)] text-[var(--danger-contrast)]",
-  brand: "bg-[var(--brand)] text-[var(--brand-contrast)]",
+  warning: "bg-warning text-warning-contrast",
+  danger: "bg-danger text-danger-contrast",
+  brand: "bg-brand text-brand-contrast",
 };
 
 /**
@@ -695,7 +697,7 @@ export function FloatingAction({
     variant === "primary"
       ? "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)]"
       : pressed && !isLink && pressedStyle === "tint"
-        ? "bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)]"
+        ? "bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)] hover:text-brand-muted"
         : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-primary)]",
     className,
   );

package/src/components/form-actions.tsx

@@ -8,6 +8,7 @@ import { useLargeText } from "../hooks/use-large-text";
 import { isApplePlatform } from "../hooks/use-hotkey";
 import { Button, Spinner, type ButtonProps, type ButtonSize, type ButtonVariant } from "./ui";
 import { useWriteLock } from "./write-lock";
+import type { CommitScope } from "./write-lock";
 
 /** The words {@link FormActions} renders on its own behalf — the `form` namespace. */
 export interface FormActionsLabels {
@@ -197,8 +198,11 @@ export interface FormActionsProps extends Omit<ComponentPropsWithoutRef<"div">,
    * keksdose wrote `submitDisabled={lock.locked || …}` and
    * `submitDisabledReason={lock.locked ? lock.reason : undefined}` at each form; this is
    * that pair, read from the provider.
+   *
+   * 0.33: a {@link CommitScope} — `COMMIT_EXCEPT_BILLING` for a form a lapsed plan still
+   * allows (the account's own settings, docs/billing-harmonization.md §12.36).
    */
-  commit?: boolean;
+  commit?: CommitScope;
   /** The save button's variant. Default `brand`; `danger` for a save that destroys
    *  (kastlan's `destructive` flag on its own FormActions). */
   submitVariant?: ButtonVariant;
@@ -392,7 +396,9 @@ export function FormActions({
   // column stretches but which keeps its control at the control's own width.
   const full = stacked ? "w-full" : undefined;
   const labels = useKitLabels("form", DEFAULT_FORM_ACTIONS_LABELS);
-  const lock = useWriteLock();
+  // The lock as Save sees it: with its scope, so a billing lock leaves a
+  // `COMMIT_EXCEPT_BILLING` form's shortcut live too.
+  const lock = useWriteLock(commit);
   const rootRef = useRef<HTMLDivElement>(null);
   const saveRef = useRef<HTMLButtonElement | null>(null);
   // The caller's own `submitProps.ref` still gets the element.
@@ -422,7 +428,7 @@ export function FormActions({
   }, [pending]);
   // Read by the shortcut's listener at the moment of the key press, so the listener
   // itself is attached once and never sees a stale `pending`.
-  const canSave = !pending && !submitDisabled && !(commit && lock.locked);
+  const canSave = !pending && !submitDisabled && !lock.locked;
   const canSaveRef = useRef(canSave);
   useEffect(() => {
     canSaveRef.current = canSave;
@@ -535,8 +541,9 @@ export function FormActions({
           disabled={pending || submitDisabled}
           disabledReason={pending ? undefined : submitDisabledReason}
           // Not while pending: the save already left, and the lock's look over the
-          // spinner would say it had not.
-          commit={commit && !pending}
+          // spinner would say it had not. A ternary, not `commit && !pending`, which
+          // turned a `{ except }` scope into `true` (§12.36).
+          commit={pending ? false : commit}
           aria-busy={pending || undefined}
           className={cn(submitProps?.className, full)}
         >

package/src/components/full-bleed-dialog.tsx

@@ -154,6 +154,12 @@ export function FullBleedDialog({
   // This is the phone's row EDITOR and its first child is usually an input; focusing it
   // would pull the software keyboard up over half the form before the user has said
   // which field they came for. `Modal` made the same call for the same reason.
+  //
+  // That default only decides when nothing inside asked for focus. A field the app
+  // autofocuses on purpose keeps it (0.33.1): keksdose's create card autofocuses its
+  // amount, and the trap used to take focus straight back to the dialog — and on a
+  // phone the numpad sheet, which shows only while the field is focused, went with it
+  // (live #402). Closing still hands focus back to whatever opened the dialog.
   useFocusTrap(dialogRef, { active: open });
 
   const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {

package/src/components/inline-edit-field.tsx

@@ -6,7 +6,7 @@ import { useKitLabels } from "../i18n/kit-labels";
 import { Input, Spinner } from "./ui";
 import { FOCUS_RING } from "./focus-ring";
 import { Tooltip } from "./tooltip";
-import { useCommitReason } from "./write-lock";
+import { useCommitReason, type CommitScope } from "./write-lock";
 
 /**
  * Every string {@link InlineEditField} says on its own behalf — the `inlineEdit`
@@ -101,7 +101,7 @@ interface InlineEditFieldBaseProps<T> {
   /** This field COMMITS — under a locked {@link WriteLockProvider} it takes the
    *  `disabledReason` path with the lock's reason (which wins over its own). No
    *  provider, or an unlocked one: no effect. */
-  commit?: boolean;
+  commit?: CommitScope;
   /** The value is the user's own data: `data-private` on the display and the editor,
    *  so the app's demo-mode blur covers both. */
   redact?: boolean;
@@ -164,13 +164,13 @@ function RenderEditor<T>({ render, ...props }: InlineEditorProps<T> & { render:
  * big type cannot recover a cut-off end by squinting. A `large:` class, so a table of
  * these keeps its one-line cells at Normal.
  *
- * `break-words`, not `[overflow-wrap:anywhere]`: these live in table cells (keksdose's
- * budget and invoice lines), and `anywhere` lowers the value's min-content width to one
- * letter, so an auto-sized column could squeeze an amount to a digit per line. With
- * `break-word` a column keeps each word whole; the button is `w-full`, so a word wider
- * than a sized cell still breaks.
+ * 0.33 (§10.17): the kit's one `truncate-until-large` (tokens.css) in place of this
+ * file's own `truncate` + `large:whitespace-normal large:break-words`. The utility
+ * breaks with `overflow-wrap: anywhere`, which lowers the value's min-content width: in
+ * an auto-sized table column (keksdose's budget and invoice lines) give the column a
+ * width, or an amount can be squeezed to a digit per line.
  */
-const VALUE_WRAP_AT_LARGE = "large:whitespace-normal large:break-words";
+const VALUE_TRUNCATE = "truncate-until-large";
 
 /** `onCommit`'s result, if it is a promise. */
 function asPromise(result: unknown): Promise<unknown> | null {
@@ -432,7 +432,7 @@ export function InlineEditField<T = string>(props: InlineEditFieldProps<T>) {
   let body: ReactNode;
   if (readOnly) {
     body = (
-      <span {...private_} className={cn("block min-w-0 truncate", VALUE_WRAP_AT_LARGE, alignClass)}>
+      <span {...private_} className={cn("block min-w-0", VALUE_TRUNCATE, alignClass)}>
         {content}
       </span>
     );
@@ -508,8 +508,8 @@ export function InlineEditField<T = string>(props: InlineEditFieldProps<T>) {
             aria-describedby={reasonId}
             onClick={(e) => e.preventDefault()}
             className={cn(
-              "block w-full min-w-0 cursor-not-allowed truncate rounded-sm focus:outline-none",
-              VALUE_WRAP_AT_LARGE,
+              "block w-full min-w-0 cursor-not-allowed rounded-sm focus:outline-none",
+              VALUE_TRUNCATE,
               FOCUS_RING,
               alignClass,
             )}
@@ -533,8 +533,8 @@ export function InlineEditField<T = string>(props: InlineEditFieldProps<T>) {
           {...private_}
           onClick={() => setOpen(true)}
           className={cn(
-            "block w-full min-w-0 truncate rounded-sm underline-offset-2 hover:underline focus:outline-none",
-            VALUE_WRAP_AT_LARGE,
+            "block w-full min-w-0 rounded-sm underline-offset-2 hover:underline focus:outline-none",
+            VALUE_TRUNCATE,
             FOCUS_RING,
             alignClass,
           )}

package/src/components/list.tsx

@@ -12,6 +12,7 @@ import { useKitLabels, useKitLink } from "../i18n/kit-labels";
 import { pickLinkRenderer } from "./text-link";
 import { mergeDescribedBy } from "./choice-parts";
 import { LockedReason, useLockReason } from "./field-parts";
+import type { CommitScope } from "./write-lock";
 
 /* ── Labels ───────────────────────────────────────────────────────────────── */
 
@@ -122,11 +123,11 @@ const TARGET_RING = cn(FOCUS_RING, "focus-visible:ring-inset");
  * §4 "ListItem: title, subtitle and meta wrap instead of truncating" at Large and Extra
  * large (docs/text-size-harmonization.md). `large:` variants over the Normal look, so
  * a list keeps its one-height rows at Normal and costs no render to switch: a one-line
- * `truncate` wraps (and breaks a word too long for the row), a `line-clamp-2` lets go.
- * An ellipsis hides the end of a name, which is the part a reader who needs big type
- * cannot recover by squinting.
+ * line is `truncate-until-large` (tokens.css, 0.33 §10.17: `truncate`, and at Large a
+ * wrap that breaks a word too long for the row — the kit's one name for what this file
+ * spelt as `WRAP_AT_LARGE`), a `line-clamp-2` lets go. An ellipsis hides the end of a
+ * name, which is the part a reader who needs big type cannot recover by squinting.
  */
-const WRAP_AT_LARGE = "large:whitespace-normal large:[overflow-wrap:anywhere]";
 const UNCLAMP_AT_LARGE = "large:line-clamp-none";
 
 interface ListItemBaseProps {
@@ -341,7 +342,7 @@ export type ListItemProps = ListItemBaseProps &
          * the `disabledReason` way with the lock's reason (which wins over its own). No
          * provider, or an unlocked one: no effect. Button's `commit`, for keksdose K3.
          */
-        commit?: boolean;
+        commit?: CommitScope;
         href?: never;
         renderLink?: never;
         external?: never;
@@ -528,7 +529,7 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
           now-wrapping title into a column one word wide (§4, 240 px effective width). */}
       <span className={cn("flex min-w-0 flex-1 flex-col", trailing != null && "large:basis-40")}>
         {overline != null && (
-          <span className={cn("block truncate text-caption font-medium leading-snug text-[var(--text-muted)]", WRAP_AT_LARGE)}>
+          <span className="block truncate-until-large text-caption font-medium leading-snug text-[var(--text-muted)]">
             {overline}
           </span>
         )}
@@ -538,7 +539,7 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
           className={cn(
             "block text-sm text-[var(--text-primary)]",
             titleLines === 1
-              ? cn("truncate", WRAP_AT_LARGE)
+              ? "truncate-until-large"
               : titleLines === 2
                 ? cn("line-clamp-2 break-words", UNCLAMP_AT_LARGE)
                 : "break-words",
@@ -553,7 +554,7 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
           <span
             className={cn(
               "block text-xs text-[var(--text-muted)]",
-              subtitleLines === 2 ? cn("line-clamp-2 break-words", UNCLAMP_AT_LARGE) : cn("truncate", WRAP_AT_LARGE),
+              subtitleLines === 2 ? cn("line-clamp-2 break-words", UNCLAMP_AT_LARGE) : "truncate-until-large",
             )}
           >
             {subtitle}
@@ -563,7 +564,7 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
           <span
             className={cn(
               "mt-0.5 text-caption leading-snug text-[var(--text-muted)]",
-              metaWrap ? "flex flex-wrap items-center gap-1" : cn("block truncate", WRAP_AT_LARGE),
+              metaWrap ? "flex flex-wrap items-center gap-1" : "block truncate-until-large",
             )}
           >
             {meta}

package/src/components/modal.tsx

@@ -333,6 +333,11 @@ function ModalPanel({
   // hook adds per-keystroke recomputation, a guard on restoring to a detached node,
   // and nesting, none of which this copy had. Released when `open` turns false, which
   // hands focus back to the trigger while the panel is still on its way out.
+  //
+  // "The panel itself" only when nothing inside asked for focus: a field the app
+  // autofocuses on purpose keeps it (0.33.1, keksdose live #402 — the same trap took
+  // an autofocused amount straight back in `FullBleedDialog`). Its keyboard is then the
+  // one the app chose to show; the trigger still gets focus back on close.
   useFocusTrap(panelRef, { active, initialFocus: "container" });
   const leaving = closing || exiting;
 

package/src/components/month-picker.tsx

@@ -10,7 +10,7 @@ import { Popover } from "./popover";
 import { splitTriggerAria } from "./trigger-aria";
 import type { TriggerAria } from "./trigger-aria";
 import { useKitDateFormatter, useKitLabels, useKitLocale } from "../i18n/kit-labels";
-import { FieldBox, FieldLabelLine, hasContent, useFieldMessages } from "./field-parts";
+import { FieldBox, FieldLabelLine, hasContent, LABEL_ABOVE_BOX, useFieldMessages } from "./field-parts";
 
 /**
  * Every string the month picker can speak. The month and year names are NOT here —
@@ -1005,7 +1005,13 @@ export function MonthPicker(props: MonthPickerProps) {
   const field = (
     // `w-fit` for the toolbar size: the calendar glyph is placed against this box, and a
     // full-width box would park it at the far end of the row, away from its trigger.
-    <div {...wrapperRest} ref={rootRef} className={cn("relative", small && "w-fit max-w-full", className)}>
+    // At Large a labelled box is a grid: the label above, the calendar glyph measured
+    // against the trigger's row (LABEL_ABOVE_BOX, 0.33 §10.17).
+    <div
+      {...wrapperRest}
+      ref={rootRef}
+      className={cn("relative", small && "w-fit max-w-full", label !== undefined && LABEL_ABOVE_BOX, className)}
+    >
       {label !== undefined && <FieldLabelLine label={label} hint={messages.labelHint} />}
       {/* The hidden twin the trigger is named by — see DateField. `sr-only-fixed`,
           and inside this `relative` root either way. */}

package/src/components/multi-entity-combobox.tsx

@@ -26,7 +26,7 @@ import {
   useLockReason,
 } from "./field-parts";
 import { assignRef, mergeDescribedBy } from "./choice-parts";
-import { useCommitReason } from "./write-lock";
+import { useCommitReason, type CommitScope } from "./write-lock";
 
 /** `onChange` is the kit's — "a selection was made", carrying values — rather
  *  than the div's form event, so the DOM's spelling of it is omitted. */
@@ -65,7 +65,7 @@ export interface MultiEntityComboboxProps<V extends string | number>
   disabledReason?: ReactNode;
   /** This picker COMMITS — toggling saves. Locked the `disabledReason` way under a
    *  locked {@link WriteLockProvider}. See {@link EntityCombobox}'s `commit`. */
-  commit?: boolean;
+  commit?: CommitScope;
   /** When set, a "create" row appears for a non-empty query with no exact match.
    *  The panel stays open (adding the new entity to `value` is the caller's job). */
   onCreate?: (query: string) => void;
@@ -75,7 +75,7 @@ export interface MultiEntityComboboxProps<V extends string | number>
   createEmptyLabel?: string;
   /** The create row is a write while toggling is not: locked on its own under a locked
    *  {@link WriteLockProvider}. See {@link EntityCombobox}'s `createCommit`. */
-  createCommit?: boolean;
+  createCommit?: CommitScope;
   /** Required and unanswered — {@link FIELD_INVALID}. See {@link Input}'s `invalid`. */
   invalid?: boolean;
   /** What is wrong with the value, as {@link Input}'s `error`: rendered under the

package/src/components/number-field.tsx

@@ -141,6 +141,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

@@ -5,7 +5,8 @@ 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 { useInlineHint } from "./field-parts";
+import { LockedReason, useInlineHint, useLockReason } from "./field-parts";
+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";
@@ -135,6 +136,32 @@ 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 in the kit {@link Tooltip}
+   * and on the input's `aria-describedby`, between the caption and the error. Wins over
+   * `disabled`.
+   */
+  disabledReason?: ReactNode;
+  /**
+   * 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;
 }
 
 /** Decimal places of `n` as written ("0.25" → 2, "1e-7" → 7), for decimal-exact
@@ -289,11 +316,18 @@ export function NumberInput(props: NumberInputProps) {
     step,
     min,
     max,
+    disabledReason,
+    commit: commitScope,
   } = 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`.
@@ -303,15 +337,17 @@ export function NumberInput(props: NumberInputProps) {
   const hasError = hasMessage(error);
   // 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);
+  // 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";
-  const showCalc = calculator && !disabled && !isMobile;
+  // 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);
@@ -338,7 +374,7 @@ export function NumberInput(props: NumberInputProps) {
   }, [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;
+  const showNumpad = isMobile && !disabled && !locked && focused;
   const inputRef = useRef<HTMLInputElement>(null);
 
   // The mark is the locale's; see the component's note. `derived` is the value in that
@@ -395,6 +431,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,9 +448,12 @@ export function NumberInput(props: NumberInputProps) {
     stepBy(count);
   };
 
+  // While locked the field sits in the reason's Tooltip, which becomes 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}
@@ -425,16 +470,23 @@ 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}
@@ -455,6 +507,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
@@ -511,13 +564,20 @@ export function NumberInput(props: NumberInputProps) {
       )}
     </FloatingField>
   );
-  if (!textHint && !hasError && !reserve) return field;
+  const box = locked ? (
+    <LockedReason lock={lock} className={cn("block w-full", className)}>
+      {field}
+    </LockedReason>
+  ) : (
+    field
+  );
+  if (!textHint && !hasError && !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}
+      {box}
       {textHint && (
         <p id={hintId} className="mt-1 text-caption leading-tight text-[var(--text-muted)]">
           {hint}

package/src/components/numpad-sheet.tsx

@@ -87,11 +87,15 @@ const PAD_KEYS: PadKey[] = [
  *  thinner than an outward ring plus the neighbour it would spill onto — inset keeps the
  *  ring inside the key it describes.
  *
- *  --brand rather than --border-strong: the operator keys are filled with --border, and
- *  a ring in the colour of the thing it surrounds is not an indicator. */
+ *  --brand rather than --border-strong: the operator keys are filled with a step of the
+ *  ink, and a ring in the colour of the thing it surrounds is not an indicator. */
 const PAD_BTN = `flex h-14 items-center justify-center rounded-lg text-lg font-medium transition-transform select-none focus:outline-none ${FOCUS_RING} focus-visible:ring-inset active:scale-[0.97]`;
-const PAD_DIGIT = "bg-[var(--bg-surface-2)] text-[var(--text-primary)] active:bg-[var(--border)]";
-const PAD_ACCENT = "bg-[var(--border)] text-[var(--text-primary)] active:bg-[var(--bg-surface-2)]";
+// Digits on the well, operators a step down on `--bg-active`, each pressing toward the
+// other. `--bg-active`, not `--border` (0.33, docs/colour-roles-harmonization.md §12.9):
+// More contrast steps the border until it is a 3:1 LINE, and as a fill under the label
+// that left 2.7–3.3:1; `--bg-active` carries the ink at 7:1 and up at both levels.
+const PAD_DIGIT = "bg-surface-2 text-primary active:bg-active";
+const PAD_ACCENT = "bg-active text-primary active:bg-surface-2";
 
 export function NumberPadSheet({
   value,

package/src/components/popover.tsx

@@ -144,7 +144,10 @@ export function Popover({
     : 0;
   const pos = rect
     ? {
-        top: placement.top,
+        // Flipped above, the panel hangs from its bottom edge, so one shorter than its
+        // cap still meets the trigger (keksdose K1); the edge not in use is cleared.
+        top: placement.above ? undefined : placement.top,
+        bottom: placement.above ? placement.bottom : undefined,
         left: Math.min(
           Math.max(EDGE, dir === "rtl" ? rect.left : rect.right - panelWidth),
           window.innerWidth - panelWidth - EDGE,
@@ -213,12 +216,13 @@ export function Popover({
             tabIndex={-1}
             onKeyDown={handleKeyDown}
             style={{
-              // Merged over the caller's, never replaced by it: these four are measured
+              // Merged over the caller's, never replaced by it: these are measured
               // against the trigger every scroll and resize, and a panel that dropped
               // them would paint at the top-left of the viewport.
               ...style,
               position: "fixed",
               top: pos.top,
+              bottom: pos.bottom,
               left: pos.left,
               width: panelWidth,
               maxHeight: placement.maxHeight,