@eifi1/ui-kit 0.5.1 → 0.6.0

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>
+  );
+}

package/src/components/tile-radio.tsx

@@ -0,0 +1,228 @@
+import { useId, useRef } from "react";
+import type { KeyboardEvent, ReactNode } from "react";
+import { Ban, Check } from "lucide-react";
+import { cn } from "../lib/cn";
+import { Tooltip } from "./tooltip";
+
+/**
+ * The machinery {@link SwatchPicker} and {@link IconPicker} share: a row of square
+ * tiles that behaves as ONE radio group. Private to the package — not re-exported
+ * from the barrel.
+ *
+ * Keksdose had three of these (the category colours, the category symbols, the
+ * transaction flags) and all three were rows of `aria-pressed` buttons: a separate
+ * tab stop per tile, and "pressed" on a choice that is really one-of-n. The APG radio
+ * group is the shape a screen reader expects for that ("Red, radio, 2 of 7, checked")
+ * and the one a keyboard expects too — a single tab stop, arrows to move.
+ */
+
+export type TileSize = "sm" | "md" | "lg";
+
+/** 28 / 32 / 44px. `lg` is the touch target a phone surface wants (`min-h-11`). */
+export const TILE_SIZE: Record<TileSize, { tile: string; glyph: string; swatch: string }> = {
+  sm: { tile: "size-7", glyph: "size-3.5", swatch: "size-4" },
+  md: { tile: "size-8", glyph: "size-4", swatch: "size-5" },
+  lg: { tile: "size-11", glyph: "size-5", swatch: "size-6" },
+};
+
+/** One tile, whatever it shows. `key` is `null` for the "none" entry. */
+export interface TileItem<T extends string> {
+  key: T | null;
+  label: string;
+  /** Said after the name, and shown in the bubble under it. Marks the tile with a
+   *  dot, so the note is visible without hovering every tile to find it. */
+  note?: string;
+  disabled?: boolean;
+}
+
+export interface TileRadioGroupProps<T extends string> {
+  items: TileItem<T>[];
+  /** The checked key, or `undefined` for "nothing is checked" (the mixed state, or
+   *  a value that is not among the options). */
+  checked: T | null | undefined;
+  onSelect: (key: T | null) => void;
+  /** "automatic": an arrow key moves AND checks, the APG default. "manual": arrows
+   *  move focus only, Space or Enter checks — for a picker whose change is expensive
+   *  (a bulk edit that saves on every change). */
+  activation: "automatic" | "manual";
+  disabled: boolean;
+  size: TileSize;
+  /** What goes inside a tile. The frame, the tick and the note's dot are drawn here. */
+  renderTile: (item: TileItem<T>, selected: boolean) => ReactNode;
+  /** Extra classes for a tile, per item. */
+  tileClassName?: (item: TileItem<T>, selected: boolean) => string | undefined;
+}
+
+/**
+ * The tile's frame. Selection is a thicker, darker frame AND a tick in the corner —
+ * never a colour change alone,
+ * because the thing inside a swatch tile IS a colour, and a red frame round a red dot
+ * says nothing to a reader who cannot see red.
+ *
+ * `focus-visible` with an offset in the surface colour, as the checkbox does: the ring
+ * must not be painted in the colour of the frame it touches.
+ */
+const TILE_BASE =
+  "relative inline-flex shrink-0 items-center justify-center rounded-md border transition-colors " +
+  "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface)] " +
+  "disabled:cursor-not-allowed disabled:opacity-50";
+const TILE_IDLE =
+  "border-[var(--border)] bg-[var(--bg-surface)] hover:border-[var(--border-strong)] hover:bg-[var(--bg-hover)]";
+const TILE_SELECTED =
+  "border-[var(--text-primary)] bg-[var(--bg-surface)] ring-1 ring-[var(--text-primary)]";
+
+export function TileRadioGroup<T extends string>({
+  items,
+  checked,
+  onSelect,
+  activation,
+  disabled,
+  size,
+  renderTile,
+  tileClassName,
+}: TileRadioGroupProps<T>) {
+  const refs = useRef<Array<HTMLButtonElement | null>>([]);
+  const noteId = useId();
+  const s = TILE_SIZE[size];
+  const checkedIndex =
+    checked === undefined ? -1 : items.findIndex((it) => it.key === checked);
+  // The ONE tab stop: the checked tile, else the first that can be chosen — the APG
+  // rule, so Tab into a group with nothing checked still lands somewhere.
+  const tabStop =
+    checkedIndex >= 0 && !items[checkedIndex].disabled
+      ? checkedIndex
+      : items.findIndex((it) => !it.disabled);
+
+  const onKeyDown = (e: KeyboardEvent<HTMLButtonElement>, index: number) => {
+    // Left and right are VISUAL directions: in a right-to-left page the row runs the
+    // other way. Up and down follow reading order either way — the APG's radio group
+    // treats them as previous/next, and the tiles wrap, so there is no column to keep.
+    const rtl = e.currentTarget.closest("[dir]")?.getAttribute("dir") === "rtl";
+    let step: number | "first" | "last";
+    switch (e.key) {
+      case "ArrowRight":
+        step = rtl ? -1 : 1;
+        break;
+      case "ArrowLeft":
+        step = rtl ? 1 : -1;
+        break;
+      case "ArrowDown":
+        step = 1;
+        break;
+      case "ArrowUp":
+        step = -1;
+        break;
+      case "Home":
+        step = "first";
+        break;
+      case "End":
+        step = "last";
+        break;
+      default:
+        return;
+    }
+    e.preventDefault();
+    const enabled = items.map((it, i) => (it.disabled ? -1 : i)).filter((i) => i >= 0);
+    if (!enabled.length) return;
+    const at = enabled.indexOf(index);
+    let target: number;
+    if (step === "first") target = enabled[0];
+    else if (step === "last") target = enabled[enabled.length - 1];
+    // Wrapping, as a native radio group does: the last tile's "next" is the first.
+    else target = enabled[(at + step + enabled.length) % enabled.length];
+    refs.current[target]?.focus();
+    if (activation === "automatic") onSelect(items[target].key);
+  };
+
+  return (
+    <>
+      {items.map((item, i) => {
+        const selected = i === checkedIndex;
+        const button = (
+          <button
+            ref={(el) => {
+              refs.current[i] = el;
+            }}
+            type="button"
+            role="radio"
+            aria-checked={selected}
+            aria-label={item.label}
+            // The note is a DESCRIPTION, read after the name and the state, not glued
+            // into the name — the punctuation between the two would be English's.
+            aria-describedby={item.note ? `${noteId}-${i}` : undefined}
+            tabIndex={i === tabStop ? 0 : -1}
+            disabled={disabled || item.disabled}
+            // Clicking the checked tile again does nothing: a radio is not a toggle.
+            // "None" is the way back to nothing, and it is a tile of its own.
+            onClick={() => !selected && onSelect(item.key)}
+            onKeyDown={(e) => onKeyDown(e, i)}
+            className={cn(
+              TILE_BASE,
+              s.tile,
+              selected ? TILE_SELECTED : TILE_IDLE,
+              tileClassName?.(item, selected),
+            )}
+          >
+            {item.key === null ? (
+              <Ban aria-hidden className={cn(s.glyph, "text-[var(--text-muted)]")} />
+            ) : (
+              renderTile(item, selected)
+            )}
+            {item.note && (
+              <>
+                {/* A dot rather than a dimmed tile: dimming reads as "disabled", and a
+                    tile with a note is entirely available. */}
+                <span
+                  aria-hidden
+                  className="absolute end-0.5 top-0.5 size-1.5 rounded-full bg-[var(--text-muted)]"
+                />
+                {/* `hidden` still serves as a description: aria-describedby reads
+                    hidden text, which is what keeps it out of the layout. */}
+                <span id={`${noteId}-${i}`} hidden>
+                  {item.note}
+                </span>
+              </>
+            )}
+            {selected && <SelectedTick />}
+          </button>
+        );
+        return (
+          // The bubble is the SIGHTED user's name for the tile — eight unlabelled
+          // squares are the complaint that put a bubble on Keksdose's (live #289).
+          // It wraps a span rather than the button, because a Tooltip hands its
+          // child an `aria-describedby`, and a tile named "Red" and described as
+          // "Red" is read out twice.
+          <Tooltip
+            key={item.key ?? "\u0000none"}
+            label={
+              item.note ? (
+                <>
+                  <span className="block">{item.label}</span>
+                  <span className="block font-normal text-[var(--text-muted)]">{item.note}</span>
+                </>
+              ) : (
+                item.label
+              )
+            }
+            portal
+          >
+            <span className="inline-flex">{button}</span>
+          </Tooltip>
+        );
+      })}
+    </>
+  );
+}
+
+/** The tick on a selected tile — a small badge in the corner, in the text colour on
+ *  the surface colour, so it reads the same over every swatch colour. */
+function SelectedTick() {
+  return (
+    <span
+      aria-hidden
+      className="absolute -bottom-1 -end-1 inline-flex size-3.5 items-center justify-center rounded-full bg-[var(--text-primary)] text-[var(--bg-surface)]"
+    >
+      <Check strokeWidth={3} className="size-2.5" />
+    </span>
+  );
+}