@eifi1/ui-kit 0.5.1 → 0.6.1

package/src/components/icon-picker.tsx

@@ -0,0 +1,181 @@
+import { useId, useMemo, useState } from "react";
+import type { ComponentPropsWithoutRef, ComponentType } from "react";
+import { cn } from "../lib/cn";
+import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import { SearchField } from "./search-field";
+import { TILE_SIZE, TileRadioGroup } from "./tile-radio";
+import type { TileItem, TileSize } from "./tile-radio";
+
+export interface IconPickerLabels {
+  /** The "no icon" tile's name, when `allowNone` is set. */
+  none: string;
+  /** Describes the group while `mixed` is set — a bulk edit over rows that disagree. */
+  mixed: string;
+  /** The search box's accessible name and placeholder, when `searchable` is set. */
+  search: string;
+  /** Shown in place of the tiles when the search matches nothing. */
+  noResults: string;
+  /** Announced as the search narrows the grid. Receives the number of matches. */
+  resultCount: (count: number) => string;
+}
+
+export const DEFAULT_ICON_PICKER_LABELS: IconPickerLabels = {
+  none: "No icon",
+  mixed: "Mixed: the selected items have different icons",
+  search: "Search icons",
+  noResults: "No icons match",
+  resultCount: (count) => (count === 1 ? "1 icon" : `${count} icons`),
+};
+
+export interface IconOption<T extends string> {
+  value: T;
+  /** A Lucide icon, or any component that takes a `className`. Rendered `aria-hidden`
+   *  — the tile's name is `label`. */
+  icon: ComponentType<{ className?: string; "aria-hidden"?: boolean }>;
+  /** What the symbol IS, in the user's language ("Game controller") — not the icon
+   *  library's identifier (`Gamepad2`), which is nobody's word for anything. */
+  label: string;
+  /** More words the search matches ("games", "play"), besides `label`. */
+  keywords?: string[];
+  /** A remark read after the name and shown under it in the bubble ("used by
+   *  Leisure"). The tile wears a dot while it has one. */
+  note?: string;
+  disabled?: boolean;
+}
+
+export interface IconPickerProps<T extends string>
+  extends Omit<ComponentPropsWithoutRef<"div">, "onChange" | "children" | "defaultValue"> {
+  options: IconOption<T>[];
+  /** The chosen icon, or `null` for none. */
+  value: T | null;
+  onChange: (value: T | null) => void;
+  /** Lead with a "no icon" tile whose value is `null`. */
+  allowNone?: boolean;
+  /** See {@link SwatchPickerProps.mixed}: nothing is checked, and the group is
+   *  described as mixed. */
+  mixed?: boolean;
+  /**
+   * "automatic" (default): an arrow key moves AND chooses, the APG radio group.
+   * "manual": arrows move focus only; Space or Enter chooses. For a picker whose every
+   * change is expensive — a bulk edit that saves as it goes.
+   */
+  activation?: "automatic" | "manual";
+  /** A search box above the grid, matching `label` and `keywords`. For a set large
+   *  enough that scanning it is slower than typing. */
+  searchable?: boolean;
+  /** 28 / 32 / 44px tiles. Default "md"; "lg" is the touch-target size. */
+  size?: TileSize;
+  disabled?: boolean;
+  labels?: Partial<IconPickerLabels>;
+}
+
+/** Case- and accent-insensitive, so "cafe" finds "Café". */
+function fold(text: string, locale: string | undefined): string {
+  return text.normalize("NFD").replace(/\p{M}/gu, "").toLocaleLowerCase(locale);
+}
+
+/**
+ * A grid of symbols that is one radio group, with an optional search.
+ *
+ * Name the group with `aria-label` or `aria-labelledby`. The name lands on the
+ * radiogroup itself, not on the outer box: with `searchable` the outer box also holds
+ * the search field, which has a name of its own.
+ *
+ * Keyboard is {@link SwatchPicker}'s: one tab stop, arrows to move (flipped in a
+ * right-to-left page), Home and End.
+ */
+export function IconPicker<T extends string>({
+  options,
+  value,
+  onChange,
+  allowNone = false,
+  mixed = false,
+  activation = "automatic",
+  searchable = false,
+  size = "md",
+  disabled = false,
+  labels,
+  className,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  "aria-describedby": ariaDescribedBy,
+  ...rest
+}: IconPickerProps<T>) {
+  const text = useKitLabels("iconPicker", DEFAULT_ICON_PICKER_LABELS, labels);
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const locale = useKitLocale();
+  const mixedId = useId();
+  const [query, setQuery] = useState("");
+  const needle = fold(query.trim(), locale);
+
+  const visible = useMemo(
+    () =>
+      needle
+        ? options.filter((o) =>
+            [o.label, ...(o.keywords ?? [])].some((w) => fold(w, locale).includes(needle)),
+          )
+        : options,
+    [options, needle, locale],
+  );
+  const byValue = useMemo(() => new Map(options.map((o) => [o.value, o])), [options]);
+  const items: TileItem<T>[] = [
+    // "None" stays through a search: it is the way back to no icon, and it matches
+    // no word anybody would type for it.
+    ...(allowNone ? [{ key: null, label: text.none }] : []),
+    ...visible.map((o) => ({ key: o.value, label: o.label, note: o.note, disabled: o.disabled })),
+  ];
+
+  return (
+    <div {...rest} className={cn("space-y-2", className)}>
+      {searchable && (
+        <SearchField
+          value={query}
+          onChange={setQuery}
+          aria-label={text.search}
+          clearLabel={common.clear}
+          disabled={disabled}
+        />
+      )}
+      <div
+        role="radiogroup"
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        aria-describedby={[ariaDescribedBy, mixed && mixedId].filter(Boolean).join(" ") || undefined}
+        aria-disabled={disabled || undefined}
+        className="flex flex-wrap items-center gap-1.5"
+      >
+        <TileRadioGroup
+          items={items}
+          checked={mixed ? undefined : value}
+          onSelect={onChange}
+          activation={activation}
+          disabled={disabled}
+          size={size}
+          renderTile={(item) => {
+            const Icon = item.key === null ? undefined : byValue.get(item.key)?.icon;
+            return Icon ? <Icon aria-hidden className={TILE_SIZE[size].glyph} /> : null;
+          }}
+          tileClassName={(_item, selected) =>
+            selected ? "text-[var(--text-primary)]" : "text-[var(--text-secondary)]"
+          }
+        />
+      </div>
+      {needle && visible.length === 0 && (
+        <p className="text-xs text-[var(--text-muted)]">{text.noResults}</p>
+      )}
+      {mixed && (
+        <span id={mixedId} hidden>
+          {text.mixed}
+        </span>
+      )}
+      {searchable && (
+        // Typing moves no focus and the grid changes silently, so the count is said.
+        // `sr-only-fixed`: this sits inside a consumer's markup and must not extend
+        // the document height (see tokens.css).
+        <span role="status" aria-live="polite" aria-atomic className="sr-only-fixed">
+          {needle ? text.resultCount(visible.length) : ""}
+        </span>
+      )}
+    </div>
+  );
+}

package/src/components/mini-calendar.tsx

@@ -4,7 +4,7 @@ import { ChevronLeft, ChevronRight } from "lucide-react";
 import { cn } from "../lib/cn";
 import { useAnnounce } from "../hooks/use-announce";
 import { parseIsoDate, sameYmd, toLocalIso } from "../lib/dates";
-import { useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import { useKitLabels, useKitLocale, useKitWeekStart } from "../i18n/kit-labels";
 
 /**
  * Every string this calendar can speak — the `miniCalendar` namespace of
@@ -95,6 +95,9 @@ export interface MiniCalendarProps extends Omit<ComponentPropsWithoutRef<"div">,
    * Saturday in much of the Arab world — which is what the user's own wall calendar
    * does. It was hard-wired to Monday before, which is wrong for most of the people
    * who use a Sunday-first calendar and invisible to the people who wrote this one.
+   *
+   * Resolved as: this prop, else `<UiKitProvider weekStartsOn>`, else the locale's
+   * week info, else Monday.
    */
   weekStartsOn?: WeekDay;
   onSelect: (from: string, to: string) => void;
@@ -198,9 +201,10 @@ export function MiniCalendar({
 }: MiniCalendarProps) {
   const labels = useKitLabels("miniCalendar", DEFAULT_MINI_CALENDAR_LABELS, labelsProp);
   const locale = useKitLocale(localeProp);
+  const providerWeekStart = useKitWeekStart();
   const weekStart = useMemo(
-    () => weekStartsOn ?? localeWeekStart(locale),
-    [weekStartsOn, locale],
+    () => weekStartsOn ?? providerWeekStart ?? localeWeekStart(locale),
+    [weekStartsOn, providerWeekStart, locale],
   );
   // Day numbers through `Intl` too: `getDate()` is always ASCII digits, and a locale
   // that writes its own (Arabic, Persian, Bengali …) would get a grid of foreign

package/src/components/modal.tsx

@@ -1,4 +1,4 @@
-import { useRef, useState } from "react";
+import { createContext, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import type {
   ComponentPropsWithoutRef,
@@ -79,6 +79,14 @@ function useDragOffset(enabled: boolean) {
   };
 }
 
+/**
+ * The panel's own ANIMATED dismissal, for chrome rendered inside it. `DialogFrame`'s X
+ * and its `actions(close)` read this, so a Cancel or an X lowers the panel exactly the
+ * way Escape does — calling `onClose` from inside unmounts with no exit, which is the
+ * documented limit of {@link useCloseTransition}. `null` outside a `Modal`.
+ */
+export const ModalCloseContext = createContext<(() => void) | null>(null);
+
 /**
  * Backdrop handlers that close only when a press starts AND ends on the
  * backdrop itself. A plain onClick fires on mouseup, so dragging a text
@@ -279,7 +287,7 @@ export function Modal({
           className,
         )}
       >
-        {children}
+        <ModalCloseContext.Provider value={requestClose}>{children}</ModalCloseContext.Provider>
       </div>
     </div>,
     document.body,

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

@@ -2,7 +2,12 @@ import { useId, useMemo, type ComponentPropsWithoutRef, type ReactNode } from "r
 import { X } from "lucide-react";
 import { cn } from "../lib/cn";
 import { FieldChevron, FieldLabel, FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID } from "./ui";
-import { ComboboxPanel, useComboboxCore, type ComboOption } from "./combobox-core";
+import {
+  ComboboxPanel,
+  useComboboxCore,
+  useComboboxFieldError,
+  type ComboOption,
+} from "./combobox-core";
 import {
   DEFAULT_COMBOBOX_LABELS,
   DEFAULT_COMMON_LABELS,
@@ -19,8 +24,8 @@ export interface MultiEntityComboboxProps<V extends string | number>
   onChange: (value: V[]) => void;
   /** Already-loaded options (client-side filtered); also resolves selected labels. */
   options?: ComboOption<V>[];
-  /** Async option source, debounced + race-safe. When set, `options` resolves
-   *  labels only. */
+  /** Async option source, debounced + race-safe; a rejection shows
+   *  `loadErrorLabel`. When set, `options` resolves labels only. */
   loadOptions?: (query: string) => Promise<ComboOption<V>[]>;
   loading?: boolean;
   label?: ReactNode;
@@ -44,6 +49,19 @@ export interface MultiEntityComboboxProps<V extends string | number>
   createLabel?: (query: string) => string;
   /** 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
+   *  field, on the trigger's `aria-describedby`, and implies `invalid`. */
+  error?: ReactNode;
+  /** Narrow `options` client-side by the query. Default `true`; `false` shows them
+   *  as given (a server-ranked list). */
+  filter?: boolean;
+  /** Offer nothing, and call no `loadOptions`, below this many characters. Default
+   *  `0`, i.e. the list loads as the panel opens. */
+  minChars?: number;
+  /** `loadOptions` debounce. Default 150 ms. */
+  debounceMs?: number;
+  /** Shown when `loadOptions` rejects. Default: `combobox.loadError`. */
+  loadErrorLabel?: string;
 }
 
 /**
@@ -70,10 +88,23 @@ export function MultiEntityCombobox<V extends string | number>({
   createLabel,
   className,
   invalid,
+  error,
+  filter,
+  minChars,
+  debounceMs,
+  loadErrorLabel,
   "aria-label": ariaLabel,
   ...rest
 }: MultiEntityComboboxProps<V>) {
-  const core = useComboboxCore<V>({ options, loadOptions, loading });
+  const core = useComboboxCore<V>({
+    options,
+    loadOptions,
+    loading,
+    filter,
+    minChars,
+    debounceMs,
+  });
+  const field = useComboboxFieldError(error, invalid);
   // The props are the per-instance overrides, the provider the app-wide ones; a
   // prop left `undefined` falls through to the provider rather than masking it.
   const labels = useKitLabels("combobox", DEFAULT_COMBOBOX_LABELS, {
@@ -155,7 +186,8 @@ export function MultiEntityCombobox<V extends string | number>({
           (typeof label === "string" ? common.fieldValue(label, summary) : undefined)
         }
         disabled={disabled}
-        aria-invalid={invalid || undefined}
+        aria-invalid={field.isInvalid || undefined}
+        aria-describedby={field.describedBy}
         onClick={() => !disabled && setOpen((o) => !o)}
         // Down/Up opens the list from the closed trigger, per the APG. Enter and
         // Space already do it through the button's own click.
@@ -171,7 +203,7 @@ export function MultiEntityCombobox<V extends string | number>({
           "pr-9",
           label !== undefined && FIELD_FLOATING_PAD,
           disabled && "cursor-not-allowed opacity-50",
-          invalid && FIELD_INVALID,
+          field.isInvalid && FIELD_INVALID,
         )}
       >
         <span
@@ -212,6 +244,7 @@ export function MultiEntityCombobox<V extends string | number>({
         searchPlaceholder={labels.search}
         emptyLabel={labels.noResults}
         closeLabel={closeLabel}
+        loadErrorLabel={loadErrorLabel}
         isSelected={(v) => valueSet.has(v)}
         onChoose={toggle}
         showCreate={showCreate}
@@ -221,6 +254,7 @@ export function MultiEntityCombobox<V extends string | number>({
         }}
         createContent={labels.create(q)}
       />
+      {field.errorEl}
     </div>
   );
 }

package/src/components/number-field.tsx

@@ -1,7 +1,7 @@
 import { useEffect, useId, useState } from "react";
 import type { ComponentProps, ReactNode } from "react";
 import { NumberInput } from "./number-input";
-import { formatResult } from "../lib/calc";
+import { evaluateExpression, formatResult } from "../lib/calc";
 import { useKitLocale } from "../i18n/kit-labels";
 
 type NumberInputProps = ComponentProps<typeof NumberInput>;
@@ -16,6 +16,25 @@ export interface NumberFieldProps
    * into `[min, max]`. `null` only when `nullable` and the field was emptied.
    */
   onCommit: (value: number | null) => void;
+  /**
+   * LIVE MODE: the number the text reads as, on every keystroke (and every step
+   * key) — for a calculator that recomputes as the user types, while `onCommit`
+   * stays the one to save on.
+   *
+   * What it is NOT, until the commit: rounded to `digits` or clamped into
+   * `[min, max]` — a half-typed "1" on the way to "150" must not read as the
+   * minimum of 100. A calculation reads as its result ("12+5" → 17); an empty field
+   * as `null` (whether or not `nullable`); a draft that is no number yet ("-", "12+")
+   * fires nothing, so the last number stands. On blur/Enter it fires once more with
+   * the committed value if that differs from the last one it reported — the rounded,
+   * clamped or snapped-back number — so a live consumer always ends where `onCommit`
+   * does.
+   *
+   * Feeding it back into `value` is safe: a `value` equal to the number this field
+   * last reported does not re-render the text, so "1," stays "1," while the rest of
+   * the form already shows 1. Not called when `value` changes from outside.
+   */
+  onValueChange?: (value: number | null) => void;
   /** Round to this many decimals on commit, and show at most this many (trailing
    *  zeros are trimmed: `digits={2}` shows 12.5, not 12.50). Omit for no rounding. */
   digits?: number;
@@ -59,6 +78,20 @@ function decimalMark(locale: string | undefined): "," | "." {
   }
 }
 
+/** What the draft reads as while it is being typed — see `onValueChange`. `undefined`
+ *  is "not a number yet", distinct from `null` (empty). */
+function parseLive(text: string): number | null | undefined {
+  const t = text.trim().replace(/,/g, ".");
+  if (t === "") return null;
+  if (/^-?\d*\.?\d*$/.test(t)) {
+    // "-", "." and "-." pass the pattern and are no number yet.
+    if (!/\d/.test(t)) return undefined;
+    const n = Number(t);
+    return Number.isFinite(n) ? n : 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. */
 function roundTo(n: number, digits: number | undefined): number {
@@ -92,6 +125,20 @@ const FIELD_ERROR_CLASS = "mt-1 text-[11px] leading-tight text-[var(--danger)]";
  * The draft follows `value` when it changes from outside (a reset, a loaded record);
  * a change that came from here arrives back identical and is a no-op.
  *
+ * LIVE MODE. A calculator that recomputes per keystroke used to have to pick: this
+ * field (limits, rounding, but a number only on blur) or a bare NumberInput (every
+ * keystroke, but a string and no limits). `onValueChange` is the per-keystroke
+ * channel here, next to the commit rather than instead of it: live numbers for the
+ * read-out, `onCommit` for the save. It lives on this field rather than as
+ * `min`/`max`/`digits` on NumberInput because parsing, the locale's mark and the
+ * limits are what this field already is — a second copy on the string field would be
+ * a second, subtly different NumberField.
+ *
+ * STEPS. `step` (with `min`/`max` as bounds) turns on ArrowUp/ArrowDown and PageUp/
+ * PageDown (×10) — see NumberInput's `step`. A step is a draft change like a
+ * keystroke: `onValueChange` hears it at once, `onCommit` on blur/Enter. Pick a
+ * `step` that `digits` can show (0.25 needs `digits={2}`), or the commit rounds it.
+ *
  * LOCALE. The decimal mark is the locale's: a German user sees and types "1,5".
  * NumberInput normalises every keystroke to a dot (so its evaluator reads one
  * alphabet); this field maps the dot back before the draft is shown, which also
@@ -102,6 +149,7 @@ const FIELD_ERROR_CLASS = "mt-1 text-[11px] leading-tight text-[var(--danger)]";
 export function NumberField({
   value,
   onCommit,
+  onValueChange,
   digits,
   min,
   max,
@@ -128,34 +176,59 @@ export function NumberField({
   const [draft, setDraft] = useState(() => format(value));
   // Everything the displayed text depends on, not just `value`: switching the
   // provider's language or a field's `digits` has to re-render the draft too.
-  const shownFor = `${value}|${mark}|${digits}`;
-  const [seen, setSeen] = useState(shownFor);
+  const [seen, setSeen] = useState({ value, mark, digits });
   // The last number handed to `onCommit`, so Enter-then-blur (both commit) and a
   // parent that does not echo the value back cannot commit the same number twice.
   // State rather than a ref because the external-change branch below resets it
   // during render, and a ref may not be written there.
   const [committed, setCommitted] = useState(value);
+  // The last number handed to `onValueChange` — state for the same reason.
+  const [reported, setReported] = useState(value);
 
   // Adjust state during render rather than in an effect: React re-renders at once
   // with the new draft, before anything is painted, so there is no frame showing
   // the old text.
-  if (shownFor !== seen) {
-    setSeen(shownFor);
-    setDraft(format(value));
-    setCommitted(value);
+  if (seen.value !== value || seen.mark !== mark || seen.digits !== digits) {
+    setSeen({ value, mark, digits });
+    // Live mode echoing back what it was just told: the draft already says it, in
+    // the typist's own spelling ("1," or "12+5"), and reformatting would fight them.
+    // Only a changed `value` qualifies — a new mark or `digits` still re-renders.
+    const echo =
+      onValueChange !== undefined && value === reported && seen.mark === mark && seen.digits === digits;
+    if (!echo) {
+      setDraft(format(value));
+      setCommitted(value);
+      setReported(value);
+    }
   }
 
+  const report = (next: number | null) => {
+    if (next === reported) return;
+    setReported(next);
+    onValueChange?.(next);
+  };
+
+  const onText = (text: string) => {
+    setDraft(localize(text));
+    const live = parseLive(text);
+    if (live !== undefined) report(live);
+  };
+
   const commit = (text: string) => {
     const trimmed = text.trim();
     let next: number | null;
+    const snapBack = () => {
+      setDraft(format(committed));
+      report(committed);
+    };
     if (trimmed === "") {
-      if (!nullable) return setDraft(format(committed));
+      if (!nullable) return snapBack();
       next = null;
     } else {
       // `text` is NumberInput's committed form: an evaluated calculation, dot-decimal.
       // What survives its digits-only fallback can still be "-" or "." alone.
       const parsed = Number(trimmed.replace(/,/g, "."));
-      if (!Number.isFinite(parsed)) return setDraft(format(committed));
+      if (!Number.isFinite(parsed)) return snapBack();
       next = roundTo(parsed, digits);
       if (min !== undefined) next = Math.max(min, next);
       if (max !== undefined) next = Math.min(max, next);
@@ -163,6 +236,7 @@ export function NumberField({
     // Always re-render the draft from the result — "007" becomes "7", a clamped 500
     // shows the 100 it was clamped to — even when there is nothing new to commit.
     setDraft(format(next));
+    report(next);
     if (next !== committed) {
       setCommitted(next);
       onCommit(next);
@@ -205,8 +279,10 @@ export function NumberField({
       id={fieldId}
       label={labelWithUnit}
       value={draft}
-      onChange={(text) => setDraft(localize(text))}
+      onChange={onText}
       onCommit={commit}
+      min={min}
+      max={max}
       suffix={unitPlacement === "suffix" ? unit : undefined}
       invalid={invalid || hasError || ariaInvalid === true || ariaInvalid === "true"}
     />

package/src/components/number-input.tsx

@@ -4,7 +4,7 @@ import { CalculatorButton, type CalculatorButtonLabels } from "./calculator";
 import { NumberPadSheet, type NumberPadSheetLabels } from "./numpad-sheet";
 import { FIELD_BASE, FIELD_DISPLAY, FIELD_INVALID, FLOATING_INPUT_CLASS, FloatingField, PHONE_QUERY } from "./ui";
 import { cn } from "../lib/cn";
-import { commitExpression, sanitizeLive } from "../lib/calc";
+import { commitExpression, formatResult, sanitizeLive } from "../lib/calc";
 import { useMediaQuery } from "../hooks/use-media-query";
 
 interface NumberInputProps {
@@ -73,6 +73,64 @@ interface NumberInputProps {
    * every value reads as part of the number.
    */
   suffix?: ReactNode;
+  /**
+   * Turns on the step keys: ArrowUp / ArrowDown add or subtract `step`, PageUp /
+   * PageDown ten of them. The result lands on the grid `min + k × step` (or `0 + k ×
+   * step` without a `min`), so 3.1 with `step={0.25}` goes up to 3.25, not 3.35 —
+   * what a native number input does. Decimal-exact: `0.1 + 0.2` steps to "0.3".
+   *
+   * A step changes the text through `onChange` like a keystroke would; `onCommit`
+   * still fires on blur/Enter. Without `step` the arrow keys move the caret as before.
+   */
+  step?: number;
+  /** Bounds for the step keys only — a step never leaves `[min, max]`. This field's
+   *  value is a STRING, so typed text is not clamped: {@link NumberField} is the
+   *  numeric field that clamps what is typed as well. */
+  min?: number;
+  max?: number;
+}
+
+/** Decimal places of `n` as written ("0.25" → 2, "1e-7" → 7), for decimal-exact
+ *  stepping. */
+function decimalsOf(n: number): number {
+  const text = formatResult(n);
+  const dot = text.indexOf(".");
+  return dot === -1 ? 0 : text.length - dot - 1;
+}
+
+/**
+ * `current` moved by `count` steps (negative = down), on the grid `origin + k × step`
+ * and clamped into `[min, max]`. An off-grid value moves to the NEXT grid point in
+ * that direction first, so one press is never more than one step.
+ *
+ * The grid index is found by division and the result rebuilt as `origin + k × step`,
+ * then cut to the decimals `step` and `origin` are written with — which is where
+ * binary noise goes: `0.1 × 3` is 0.30000000000000004, and `toFixed(1)` of it is
+ * "0.3". Summing steps would accumulate that noise press by press instead.
+ */
+export function stepNumber(
+  current: number | null,
+  count: number,
+  step: number,
+  min?: number,
+  max?: number,
+): number {
+  const clamp = (n: number) => Math.min(max ?? Infinity, Math.max(min ?? -Infinity, n));
+  // Nothing to step from: land on the value nearest zero the bounds allow, rather
+  // than on ±step — a room count with `min={1}` goes to 1, a rate to 0.
+  if (current === null || !Number.isFinite(current)) return clamp(0);
+  const origin = min !== undefined && Number.isFinite(min) ? min : 0;
+  const raw = (current - origin) / step;
+  const nearest = Math.round(raw);
+  // "On the grid" within float tolerance: (0.3 - 0) / 0.1 is 2.9999999999999996.
+  const onGrid = Math.abs(raw - nearest) < 1e-9;
+  const k = onGrid
+    ? nearest + count
+    : count > 0
+      ? Math.ceil(raw) + count - 1
+      : Math.floor(raw) + count + 1;
+  const places = Math.min(Math.max(decimalsOf(step), decimalsOf(origin)), 20);
+  return clamp(Number((origin + k * step).toFixed(places)));
 }
 
 /**
@@ -100,6 +158,9 @@ export function NumberInput({
   hint,
   invalid,
   suffix,
+  step,
+  min,
+  max,
 }: NumberInputProps) {
   const generatedId = useId();
   const fieldId = id ?? generatedId;
@@ -121,8 +182,24 @@ export function NumberInput({
     onCommit?.(next);
   };
 
+  const stepBy = (count: number) => {
+    // The step starts from the text as a commit would read it, so "12+5" steps from 17.
+    const resolved = commitExpression(value).trim();
+    const n = resolved === "" ? NaN : Number(resolved);
+    const next = formatResult(stepNumber(Number.isFinite(n) ? n : null, count, step as number, min, max));
+    if (next !== value) onChange(next);
+  };
+
   const onKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
-    if (e.key === "Enter") commit();
+    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;
+    const count =
+      e.key === "ArrowUp" ? 1 : e.key === "ArrowDown" ? -1 : e.key === "PageUp" ? 10 : e.key === "PageDown" ? -10 : 0;
+    if (count === 0) return;
+    // Otherwise ArrowUp/Down also jump the caret to the start/end of the text.
+    e.preventDefault();
+    stepBy(count);
   };
 
   return (