@eifi1/ui-kit 0.54.0 → 0.55.0

package/src/components/number-field.tsx

@@ -1,327 +0,0 @@
-import { useId, useState } from "react";
-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>;
-
-export interface NumberFieldProps extends Omit<
-  NumberInputProps,
-  "value" | "onChange" | "onCommit" | "suffix" | "invalid" | "error" | "locale"
-> {
-  /** The committed number. `null` is "no value" — shown as an empty field. So is a
-   *  number that is not finite (NaN, ±Infinity). */
-  value: number | null;
-  /**
-   * The parsed number, on blur or Enter and once per calculator session (see
-   * {@link NumberInput}'s `onCommit`) — never per keystroke — and only when it differs
-   * from the last one committed. Already rounded to `digits` and clamped 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;
-  /** Clamp the committed number into `[min, max]`. Applied after rounding. */
-  min?: number;
-  max?: number;
-  /** An emptied field commits `null`. Without it an empty field is not an answer
-   *  and snaps back to the last value, like any other unparsable text. */
-  nullable?: boolean;
-  /** The unit — "mm", "%", "km/h". */
-  unit?: ReactNode;
-  /** Where `unit` goes: `"suffix"` (default) is NumberInput's read-out at the
-   *  field's end edge; `"label"` appends it to the label as "Label (unit)", for rows
-   *  of narrow fields where a suffix would eat the digits. */
-  unitPlacement?: "suffix" | "label";
-  /** BCP 47 tag for the decimal mark, else the `<UiKitProvider locale>`, else the
-   *  runtime's. */
-  locale?: string;
-  /** See {@link Input}'s `invalid`. */
-  invalid?: boolean;
-  /** See {@link Input}'s `error`: shown under the field, attached via
-   *  `aria-describedby`, implies `invalid`. */
-  error?: ReactNode;
-  /** Merged with the error's id. Accepted so a form library's control slot (which
-   *  injects `id` / `aria-describedby` / `aria-invalid`) can wrap this directly. */
-  "aria-describedby"?: string;
-  "aria-invalid"?: boolean | "true" | "false";
-  /**
-   * Set on the `<input>`. Declared, with `id` (from NumberInput) and the two above, so
-   * `Field`'s render-prop spread — `{(ids) => <NumberField {...ids} … />}`, kastlan's
-   * wizard steps — is typed and reaches the input rather than being dropped: before
-   * this, `aria-required` was not in the type and a required number was announced as
-   * optional.
-   */
-  "aria-required"?: boolean | "true" | "false";
-}
-
-/** 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;
-}
-
-/** `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;
-  return roundHalfAway(n, Math.min(Math.max(Math.trunc(digits), 0), 100));
-}
-
-/**
- * A number field whose value IS a number: {@link NumberInput}'s text, calculator and
- * numpad, with the parse/commit/revert loop every consumer was writing on top of it.
- *
- * WHY THE DRAFT. Half-typed values — "-", "1,", "12+" — are not numbers, and
- * reformatting them mid-keystroke moves the caret and fights the typist; committing
- * per keystroke would also fire whatever a commit fires (a recalculation, a save) for
- * every meaningless intermediate. So the field keeps a draft STRING while it is being
- * typed and resolves it on blur/Enter:
- *
- *  - a number (or a calculation, "2700+50") → rounded to `digits`, clamped into
- *    `[min, max]`, committed, and the draft re-rendered from the result;
- *  - empty → `null` when `nullable`, otherwise the same as the next case — `Number("")`
- *    is 0, and clearing a wheelbase and tabbing away must not set it to zero;
- *  - anything else unparsable → the draft SNAPS BACK to the last committed value
- *    rather than sending NaN on for a server to reject.
- *
- * 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. The field never
- * WRITES digit grouping — "1.000" would read as a thousand in German and as one in
- * English, and a field that parses its own display back must not have that ambiguity —
- * but since 0.22 it READS it, through NumberInput (keksdose K5): "1.234,56" typed by a
- * German user commits 1234.56 rather than 1.23456, and "1,234.56" by an English one
- * likewise. While a figure is typed the typist's own text stays on screen ("1.234,5",
- * 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
- * (string value). A NumberField whose `unit` is a currency says so on the console in
- * development — see NumberInput's money guard.
- */
-export function NumberField(props: NumberFieldProps) {
-  const {
-    value: stored,
-    onCommit,
-    onValueChange,
-    digits,
-    min,
-    max,
-    nullable = false,
-    unit,
-    unitPlacement = "suffix",
-    locale: localeProp,
-    label,
-    invalid,
-    error,
-    id,
-    "aria-describedby": ariaDescribedBy,
-    "aria-invalid": ariaInvalid,
-    "aria-required": ariaRequired,
-    ...rest
-  } = props;
-  // A number that is not finite is no value. NaN in particular never equals itself, and
-  // the external-change check below re-read it as new on every render until React threw
-  // "Too many re-renders" (refactor audit 2026-10-30, INP-11).
-  const value = stored === null || Number.isFinite(stored) ? stored : null;
-  const locale = useKitLocale(localeProp);
-  const mark = decimalMark(locale);
-  const localize = (text: string) => (mark === "," ? text.replace(/\./g, ",") : text);
-  // `formatResult` for fixed notation: `String(1e-7)` is "1e-7", which the field
-  // would read back as 17 (see calc.ts).
-  const format = (n: number | null) =>
-    n === null || !Number.isFinite(n) ? "" : localize(formatResult(roundTo(n, digits)));
-
-  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 [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. `Object.is`, not `!==`, under which NaN is new on every render: the
-  // value is read above, but a NaN `digits` looped the same way.
-  if (!Object.is(seen.value, value) || seen.mark !== mark || !Object.is(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 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 snapBack();
-      next = roundTo(parsed, digits);
-      if (min !== undefined) next = Math.max(min, next);
-      if (max !== undefined) next = Math.min(max, next);
-    }
-    // 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);
-    }
-  };
-
-  const generatedId = useId();
-  const fieldId = id ?? generatedId;
-
-  // Straight onto NumberInput's <input>, which declares both now. They used to be set
-  // on the DOM node from an effect, because NumberInput had no props for them.
-  const required = ariaRequired === true || ariaRequired === "true";
-
-  const labelWithUnit =
-    unit !== undefined && unitPlacement === "label" ? (
-      label === undefined || label === "" ? (
-        unit
-      ) : typeof label === "string" && typeof unit === "string" ? (
-        `${label} (${unit})`
-      ) : (
-        <>
-          {label} ({unit})
-        </>
-      )
-    ) : (
-      label
-    );
-
-  return (
-    <NumberInput
-      {...rest}
-      id={fieldId}
-      aria-describedby={ariaDescribedBy}
-      aria-required={required || undefined}
-      label={labelWithUnit}
-      value={draft}
-      onChange={onText}
-      onCommit={commit}
-      min={min}
-      max={max}
-      // The mark this field spells its draft in, so the two can never disagree when
-      // this field's `locale` is not the provider's.
-      locale={locale}
-      suffix={unitPlacement === "suffix" ? unit : undefined}
-      invalid={invalid || ariaInvalid === true || ariaInvalid === "true"}
-      // NumberInput's `error` — the message, the description, the paint, and Input's
-      // steady box: no wrapper for a field that never takes `error`, and the SAME one
-      // for a field that does, message or not, so the message coming or going never
-      // remounts the <input> mid-keystroke. Only forwarded when it was passed, since
-      // passing the key is what asks for the box.
-      {...("error" in props ? { error } : {})}
-    />
-  );
-}
-
-/**
- * A {@link NumberField} for whole numbers: `digits={0}` and `calculator={false}` as
- * defaults, each overridable — the preset `RhfIntegerField` (`@eifi1/ui-kit/rhf`) applies to a
- * form-bound field, for the plain one (kastlan 51: a building's construction year in a
- * wizard's local state, an entity id in the document upload spelled the two props out
- * by hand).
- *
- * `??` rather than a spread over the defaults, so a wrapper forwarding its own optional
- * `digits={props.digits}` still gets the preset.
- */
-export function IntegerField(props: NumberFieldProps) {
-  return <NumberField {...props} digits={props.digits ?? 0} calculator={props.calculator ?? false} />;
-}