@eifi1/ui-kit 0.5.0 → 0.6.0

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 (

package/src/components/popover.tsx

@@ -19,7 +19,10 @@ export interface PopoverLabels {
 // Exported since the kit grew one label tree (`UiKitLabels`, src/i18n): the complete
 // English reference a translator works from has to be able to name every namespace.
 export const DEFAULT_POPOVER_LABELS: PopoverLabels = {
-  panel: "Popover",
+  // "Pop-up", not "Popover": the panel's accessible name is read to USERS, and
+  // "popover" is a developer's word for it (reported by keksdose, 0.5.0). Only a
+  // bare Popover falls back to this — the kit's own pickers name their panels.
+  panel: "Pop-up",
 };
 
 /**

package/src/components/search-field.tsx

@@ -27,8 +27,30 @@ interface SearchFieldOwnProps
    *  decision, not a default: a filter you can type into and not untype is the
    *  complaint that produced the button on three of these four screens. */
   clearLabel?: string;
+  /**
+   * `"field"` (default): the bordered filter box that sits on a page.
+   *
+   * `"inline"`: no box at all — no border, no fill, no padding of its own — and no
+   * type size of its own either, so it takes the size of the header it sits in.
+   * For a search that IS the header: a command-palette sheet, a picker's top line
+   * (Keksdose's transaction search, which lost its `text-base` headline to a
+   * bordered `text-sm` box when it moved onto this component). The container is
+   * what frames it, so give the container the focus cue if it needs one
+   * (`focus-within:`); the caret is the field's own.
+   */
+  variant?: "field" | "inline";
+  /** Classes for the `<input>` itself. `className` styles the wrapper — the box the
+   *  icon and the clear button are positioned against — so it could set a width
+   *  and nothing else. See {@link Input}'s `inputClassName`. */
+  inputClassName?: string;
 }
 
+// The inline look: FIELD_DISPLAY's idea (the chrome gone, the value the thing
+// itself) without even its baseline, because the header it sits in already draws
+// the line. No `text-*` size, on purpose — the input inherits the caller's.
+const SEARCH_INLINE =
+  "block w-full min-w-0 border-0 bg-transparent py-1 text-[var(--text-primary)] shadow-none placeholder:text-[var(--text-placeholder)] focus:outline-none focus:ring-0";
+
 /**
  * One of the two spellings is REQUIRED, and the union is how that survives the
  * deprecation. Making `label` merely optional would have been the easy change and the
@@ -70,7 +92,18 @@ export type SearchFieldProps = SearchFieldOwnProps &
  * the next query can be typed straight away.
  */
 export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(function SearchField(
-  { value, onChange, label, clearLabel, className, placeholder, "aria-label": ariaLabel, ...rest },
+  {
+    value,
+    onChange,
+    label,
+    clearLabel,
+    className,
+    inputClassName,
+    placeholder,
+    variant = "field",
+    "aria-label": ariaLabel,
+    ...rest
+  },
   ref,
 ) {
   const innerRef = useRef<HTMLInputElement>(null);
@@ -78,11 +111,17 @@ export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(functi
   // fallback, so a box named only by `aria-label` still says what it is before anyone
   // has typed in it — the same deal `label` has always had.
   const name = ariaLabel ?? label;
+  const inline = variant === "inline";
   return (
     <div className={cn("relative", className)}>
       <Search
         aria-hidden
-        className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2 text-[var(--text-placeholder)]"
+        className={cn(
+          "pointer-events-none absolute top-1/2 size-4 -translate-y-1/2 text-[var(--text-placeholder)]",
+          // Logical sides throughout, so a right-to-left page gets the icon at the
+          // start of the line and the clear button at its end.
+          inline ? "start-0" : "start-3",
+        )}
       />
       <input
         ref={(node) => {
@@ -117,12 +156,13 @@ export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(functi
         spellCheck={false}
         {...rest}
         className={cn(
-          FIELD_BASE,
-          "pl-9",
+          inline ? SEARCH_INLINE : FIELD_BASE,
+          inline ? "ps-7" : "ps-9",
           // Room for our own "×" only when there is one; a field that can't be
           // cleared has no reason to reserve the space.
-          clearLabel === undefined ? "pr-3" : "pr-9",
+          clearLabel === undefined ? (inline ? "pe-0" : "pe-3") : inline ? "pe-8" : "pe-9",
           "[&::-webkit-search-cancel-button]:appearance-none",
+          inputClassName,
         )}
       />
       {clearLabel !== undefined && value !== "" && (
@@ -135,7 +175,10 @@ export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(functi
             innerRef.current?.focus();
           }}
           aria-label={clearLabel}
-          className="absolute right-2 top-1/2 -translate-y-1/2 rounded p-1 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]"
+          className={cn(
+            "absolute top-1/2 -translate-y-1/2 rounded p-1 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]",
+            inline ? "end-0" : "end-2",
+          )}
         >
           <X className="size-4" />
         </button>

package/src/components/signature-pad.tsx

@@ -72,6 +72,12 @@ export interface SignaturePadLabels {
   /** Live-region messages after the matching button. */
   cleared: string;
   undone: string;
+  /** {@link SignatureView}: what it says when there is no signature to show. */
+  viewEmpty: string;
+  /** {@link SignatureView}: the saved PNG's alternative text. */
+  viewDrawn: string;
+  /** {@link SignatureView}: the accessible name of a typed-name signature. */
+  viewTyped: (name: string) => string;
 }
 
 export const DEFAULT_SIGNATURE_PAD_LABELS: SignaturePadLabels = {
@@ -88,6 +94,9 @@ export const DEFAULT_SIGNATURE_PAD_LABELS: SignaturePadLabels = {
   typedName: "Full name",
   cleared: "Signature cleared",
   undone: "Last stroke removed",
+  viewEmpty: "Not signed",
+  viewDrawn: "Handwritten signature",
+  viewTyped: (name) => `Signed with the typed name ${name}`,
 };
 
 /* ── Types ───────────────────────────────────────────────────────────────── */
@@ -628,3 +637,106 @@ export const SignaturePad = forwardRef<SignaturePadHandle, SignaturePadProps>(fu
   );
 });
 SignaturePad.displayName = "SignaturePad";
+
+/* ── Read-only ───────────────────────────────────────────────────────────── */
+
+export interface SignatureViewProps extends ComponentPropsWithoutRef<"figure"> {
+  /** The saved PNG — what `SignaturePad` handed to `onChange`/`onSave`, as stored. */
+  value?: string | null;
+  /**
+   * A signature given as a typed name (`detail.typedName`), for a host that stores the
+   * text rather than its PNG. Rendered in the same script face the pad draws it in.
+   * Ignored while `value` is set.
+   */
+  typedName?: string | null;
+  /** Visible caption above the signature; defaults to `labels.label`. `null` hides it
+   *  (the image keeps its alternative text) — for a signature block whose own heading
+   *  already says whose signature it is. */
+  label?: ReactNode;
+  /**
+   * The exported PNG is dark ink on a transparent ground (`exportInk`), which is
+   * invisible on the dark theme's surface. By default the image is colour-inverted
+   * under `.dark`, so the ink reads light; `false` keeps the pixels as stored — for a
+   * PNG exported with its own `exportBackground`, which inverting would turn black.
+   */
+  adaptInk?: boolean;
+  /** Classes for the frame — its height, chiefly (default `h-40`, the pad's). */
+  frameClassName?: string;
+  /** User-facing strings; see {@link SignaturePadLabels} (`view*`). */
+  labels?: Partial<SignaturePadLabels>;
+}
+
+/**
+ * A saved signature, shown — the read side of {@link SignaturePad}: the same frame and
+ * signing line, none of the drawing chrome (no canvas, buttons, instructions or live
+ * region). A separate component rather than a `readOnly` pad because there is nothing
+ * of the pad to reuse: the pad's scene is STROKES, and a stored signature is a PNG
+ * (or a name) that cannot be turned back into them.
+ *
+ * Kastlan's handover protocol, reopened after signing, is the case: two signatures
+ * that must be visible, and must not look editable.
+ */
+export function SignatureView({
+  value,
+  typedName,
+  label,
+  adaptInk = true,
+  frameClassName,
+  labels: labelsProp,
+  className,
+  ...rest
+}: SignatureViewProps) {
+  const labels = useKitLabels("signaturePad", DEFAULT_SIGNATURE_PAD_LABELS, labelsProp);
+  const name = typedName?.trim() ?? "";
+  const kind = value ? "drawn" : name ? "typed" : "empty";
+  const caption = label === undefined ? labels.label : label;
+  const captionId = useId();
+  const captioned = caption !== null && caption !== false;
+  return (
+    <figure
+      // Named explicitly: the figcaption-to-figure name is not computed everywhere.
+      aria-labelledby={captioned ? captionId : undefined}
+      {...rest}
+      className={cn("m-0 space-y-1.5", className)}
+      data-empty={kind === "empty" || undefined}
+    >
+      {captioned && (
+        <figcaption id={captionId} className="block text-sm font-medium text-[var(--text-primary)]">{caption}</figcaption>
+      )}
+      <div
+        className={cn(
+          "relative flex h-40 items-center justify-center overflow-hidden rounded-md border border-[var(--border)] bg-[var(--bg-surface)]",
+          frameClassName,
+        )}
+      >
+        {kind === "drawn" && (
+          <img
+            src={value as string}
+            alt={labels.viewDrawn}
+            className={cn("relative max-h-full max-w-full object-contain", adaptInk && "dark:invert")}
+          />
+        )}
+        {kind === "typed" && (
+          // One name for the whole thing: the visible text alone would be read as a bare
+          // name, with nothing saying it IS the signature.
+          <span
+            role="img"
+            aria-label={labels.viewTyped(name)}
+            className="relative max-w-[85%] truncate px-2 text-4xl italic text-[var(--text-primary)]"
+            style={{ fontFamily: SCRIPT_FONT }}
+          >
+            {name}
+          </span>
+        )}
+        {kind === "empty" && (
+          <span className="relative text-xs text-[var(--text-muted)]">{labels.viewEmpty}</span>
+        )}
+        {/* The signing line, as on the pad. Decoration only. */}
+        <div
+          aria-hidden="true"
+          className="pointer-events-none absolute inset-x-6 bottom-8 border-b border-dashed border-[var(--border-strong)]"
+        />
+      </div>
+    </figure>
+  );
+}

package/src/components/swatch-picker.tsx

@@ -0,0 +1,141 @@
+import { useId, useMemo } from "react";
+import type { ComponentPropsWithoutRef } from "react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { TILE_SIZE, TileRadioGroup } from "./tile-radio";
+import type { TileItem, TileSize } from "./tile-radio";
+
+export interface SwatchPickerLabels {
+  /** The "no colour" 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;
+}
+
+export const DEFAULT_SWATCH_PICKER_LABELS: SwatchPickerLabels = {
+  none: "No colour",
+  mixed: "Mixed: the selected items have different colours",
+};
+
+export interface SwatchOption<T extends string> {
+  value: T;
+  /** Any CSS colour — a token (`var(--chart-3)`), a hex, an `oklch()`. Painted as an
+   *  inline background, so it does not have to be a class the kit's CSS knows.
+   *  Leave it out when `swatchClassName` paints the dot instead. */
+  color?: string;
+  /** The colour's name, in the user's language. Shown in the bubble and read out;
+   *  required, because a swatch with no name is a colour only some people can read. */
+  label: string;
+  /** Classes for the swatch dot, for a palette that lives in classes rather than
+   *  values (a light/dark pair). An inline `color` would win over a class, so pass
+   *  one or the other. */
+  swatchClassName?: string;
+  /** A remark read after the name and shown under it in the bubble ("used by
+   *  Groceries"). The tile wears a dot while it has one. */
+  note?: string;
+  disabled?: boolean;
+}
+
+/**
+ * `onChange` is the picker's own — the chosen VALUE, not a DOM event — so the div's
+ * is omitted rather than shadowed, as on {@link ToggleGroup}.
+ */
+export interface SwatchPickerProps<T extends string>
+  extends Omit<ComponentPropsWithoutRef<"div">, "onChange" | "children" | "defaultValue"> {
+  options: SwatchOption<T>[];
+  /** The chosen colour, or `null` for none. */
+  value: T | null;
+  onChange: (value: T | null) => void;
+  /** Lead with a "no colour" tile whose value is `null`. Clearing a colour has to be
+   *  as reachable as setting one, and a radio cannot be unchecked by clicking it. */
+  allowNone?: boolean;
+  /**
+   * "Some of each" — a bulk edit over rows whose colours differ. Nothing is checked
+   * (not even "none", whatever `value` says), and the group is described as mixed.
+   * Distinct from `value={null}`, which is an answer: "no colour".
+   */
+  mixed?: boolean;
+  /** See {@link IconPickerProps.activation}. Default "automatic". */
+  activation?: "automatic" | "manual";
+  /** 28 / 32 / 44px tiles. Default "md"; "lg" is the touch-target size. */
+  size?: TileSize;
+  disabled?: boolean;
+  labels?: Partial<SwatchPickerLabels>;
+}
+
+/**
+ * A row of colour swatches that is one radio group.
+ *
+ * Name the group with `aria-label` or `aria-labelledby` — usually the visible heading
+ * above it. Each swatch is named by its `label` and shows it in a bubble on hover and
+ * focus, so the name is not the screen reader's alone.
+ *
+ * Keyboard (the APG radio group): Tab reaches the checked swatch, or the first one
+ * while nothing is checked; the arrow keys move between swatches and, by default,
+ * choose as they go; Home and End jump to the ends. Left and right follow the page's
+ * direction.
+ */
+export function SwatchPicker<T extends string>({
+  options,
+  value,
+  onChange,
+  allowNone = false,
+  mixed = false,
+  activation = "automatic",
+  size = "md",
+  disabled = false,
+  labels,
+  className,
+  ...rest
+}: SwatchPickerProps<T>) {
+  const text = useKitLabels("swatchPicker", DEFAULT_SWATCH_PICKER_LABELS, labels);
+  const mixedId = useId();
+  const byValue = useMemo(() => new Map(options.map((o) => [o.value, o])), [options]);
+  const items: TileItem<T>[] = [
+    ...(allowNone ? [{ key: null, label: text.none }] : []),
+    ...options.map((o) => ({ key: o.value, label: o.label, note: o.note, disabled: o.disabled })),
+  ];
+  return (
+    <div
+      {...rest}
+      role="radiogroup"
+      aria-disabled={disabled || undefined}
+      aria-describedby={
+        [rest["aria-describedby"], mixed && mixedId].filter(Boolean).join(" ") || undefined
+      }
+      className={cn("flex flex-wrap items-center gap-1.5", className)}
+    >
+      <TileRadioGroup
+        items={items}
+        checked={mixed ? undefined : value}
+        onSelect={onChange}
+        activation={activation}
+        disabled={disabled}
+        size={size}
+        renderTile={(item) => {
+          const opt = item.key === null ? undefined : byValue.get(item.key);
+          return (
+            <span
+              aria-hidden
+              // A hairline round the dot, drawn over whatever colour it is: a pale
+              // yellow swatch on a white surface is otherwise a hole in the row.
+              className={cn(
+                "rounded-full ring-1 ring-inset ring-black/10 dark:ring-white/15",
+                TILE_SIZE[size].swatch,
+                opt?.swatchClassName,
+              )}
+              style={{ background: opt?.color }}
+            />
+          );
+        }}
+      />
+      {/* `hidden`, not `sr-only`: a description is read from hidden text, and this
+          way it takes no room in the row. */}
+      {mixed && (
+        <span id={mixedId} hidden>
+          {text.mixed}
+        </span>
+      )}
+    </div>
+  );
+}