@eifi1/ui-kit 0.5.0 → 0.6.0

package/README.md

@@ -521,7 +521,56 @@ re-slicing of it, never a second API.
 `Input`, `Select`, `Textarea` and `AmountInput` forward their `ref` to the
 underlying DOM element, so they work directly with react-hook-form:
 `<Input {...field} />` (from `Controller`/`register`) attaches RHF's ref, giving
-focus-and-scroll-to-error for free.
+focus-and-scroll-to-error for free. For the full `FormField`/`FormControl` scaffolding,
+see `@eifi1/ui-kit/rhf` below.
+
+### react-hook-form — `@eifi1/ui-kit/rhf` (optional)
+
+A thin adapter in shadcn's `form.tsx` shape, and the only entry that needs
+`react-hook-form` (an **optional** peer, `^7.55.0`). The main barrel does not import it,
+so apps without a form library install nothing.
+
+```tsx
+import { Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage } from "@eifi1/ui-kit/rhf";
+
+<Form {...form}>
+  <FormField control={form.control} name="amount" render={({ field }) => (
+    <FormItem>
+      <FormLabel required>Amount</FormLabel>
+      <FormControl>
+        <NumberField value={field.value} onCommit={field.onChange} />
+      </FormControl>
+      <FormMessage />
+    </FormItem>
+  )} />
+</Form>
+```
+
+`FormControl` gives its one child `id`, `aria-describedby` (only the description and
+message actually rendered, merged after the child's own) and `aria-invalid` — which every
+kit field now also PAINTS from, so no extra `invalid` prop is needed. `FormMessage` shows
+the form's own message; the kit adds no text. `useFormField()` exposes the ids and field
+state for custom parts.
+
+### Pasted and imported tables — `@eifi1/ui-kit/table-text`
+
+Pure functions over strings (no React, nothing to install): one lexer for a table pasted
+out of a spreadsheet or read from a CSV, with the comma decided by a named rule rather
+than a guess.
+
+- `parseTable(text, { decimal, columns?, headerLines? })` → `{ rows, header, decimalComma, skipped }`
+  - `decimal: "whole-text"` — a **file**: separator and decimal mark decided once for the
+    whole text, and reported back as `decimalComma`.
+  - `decimal: "per-line"` — a **paste**: each line read on its own evidence.
+  - `columns` slices extra columns off and reports shorter lines; `skipped` holds 1-based
+    line numbers as they stand in the text.
+- `parseRows(text, width)` — the paste door: `{ rows }`, or `{ error: line }` naming the
+  first unreadable line (never a silent empty table).
+- `splitRow(line)`, `cellNumber(cell)`, `isCellNumber(cell)` — a single cell's comma is
+  always a decimal mark.
+
+Not handled, on purpose: thousands separators (reported, not guessed), quoted fields,
+empty cells held open as holes.
 
 ## i18n
 

package/dist/components/amount-input.d.ts

@@ -20,6 +20,13 @@ import './sparkline.js';
 import './stat-tile.js';
 import './signature-pad.js';
 import './password-strength.js';
+import './danger-confirm.js';
+import './swatch-picker.js';
+import './tile-radio.js';
+import './icon-picker.js';
+import './dialog-frame.js';
+import './modal.js';
+import './file-button.js';
 
 interface AmountInputProps {
     value: string;

package/dist/components/autocomplete.d.ts

@@ -0,0 +1,101 @@
+import { ComponentPropsWithoutRef, ReactNode, RefAttributes, ReactElement } from 'react';
+import { ComboOption } from './combobox-core.js';
+import '../hooks/use-anchored-rect.js';
+import '../hooks/use-anchored-panel.js';
+
+/**
+ * `value`/`onChange` are the TEXT's, and `onSelect` is "a suggestion was taken" —
+ * not the DOM's text-selection event — so the input's own spellings of those three
+ * are omitted. Everything else reaches the `<input>`, the way it does on {@link Input}.
+ */
+interface AutocompleteProps<V extends string | number = string> extends Omit<ComponentPropsWithoutRef<"input">, "value" | "defaultValue" | "onChange" | "onSelect" | "children" | "type"> {
+    /** What is in the field. Controlled, and never reset by the component: opening,
+     *  closing and a failed lookup all leave it exactly as typed. */
+    value: string;
+    /** Every keystroke — and, with `fillOnSelect`, the label of a taken suggestion. */
+    onChange: (text: string) => void;
+    /** Suggestions the caller already has (e.g. from its own query hook). Narrowed by
+     *  the text unless `filter={false}`. */
+    options?: ComboOption<V>[];
+    /** Or: fetch them. Debounced (`debounceMs`), race-safe, only at `minChars` and up,
+     *  never while the field is idle; a rejection shows `loadErrorLabel` and empties
+     *  the list rather than leaving the previous text's rows under it. */
+    loadOptions?: (query: string) => Promise<ComboOption<V>[]>;
+    /** Narrow `options` by label/sublabel substring. Default `true`. Pass `false` for
+     *  a list a server has already searched and ranked — it is shown as given. */
+    filter?: boolean;
+    /** External loading flag (a caller-side fetch), OR-ed with `loadOptions`'. */
+    loading?: boolean;
+    /** Below this many characters nothing is offered or fetched. Default 1: an empty
+     *  field asks nothing — focusing it is not a search. */
+    minChars?: number;
+    /** Quiet time before `loadOptions` runs. Default 300 ms — an ordinary typist's
+     *  inter-key interval is 150–250 ms, so the pickers' 150 fires on nearly every
+     *  letter, which a rate-limited geocoder cannot afford. */
+    debounceMs?: number;
+    /** A suggestion was taken (click, or Enter on the highlighted row). */
+    onSelect?: (option: ComboOption<V>) => void;
+    /**
+     * Put the taken suggestion's label into the field (`onChange(label)`). Default
+     * `true` — the free-text case, where the text IS the value and a suggestion only
+     * completes it (an address field). Pass `false` where taking a row is an ACTION
+     * and the field is only the search that found it; the text then stays as typed.
+     */
+    fillOnSelect?: boolean;
+    /** A floating label, as on {@link Combobox}. Names the field (`aria-labelledby`)
+     *  unless an `aria-label` is given. */
+    label?: ReactNode;
+    /** Leading decoration inside the field (a pin, a magnifier). Decorative: the
+     *  label names the field. */
+    icon?: ReactNode;
+    /** Required and unanswered — {@link FIELD_INVALID}. */
+    invalid?: boolean;
+    /** What is wrong with the VALUE, as {@link Input}'s `error`: under the field, on
+     *  its `aria-describedby`, implies `invalid`. Not a failed lookup — that is
+     *  `loadErrorLabel`, shown in the list. */
+    error?: ReactNode;
+    /**
+     * The caller's own line in the list, replacing the automatic one (loading / failed
+     * / no results). For what only the caller knows: "offline", "the address service
+     * is switched off", a privacy note, the hint a caller-fetched list needs below its
+     * own minimum. While set, the list opens even with no rows. Announced politely.
+     */
+    status?: ReactNode;
+    /** Default: `combobox.noResults` from the {@link UiKitProvider}, else English. */
+    emptyLabel?: string;
+    /** Default: `combobox.loadError`. */
+    loadErrorLabel?: string;
+    /** Classes for the `<input>` itself; `className` styles the wrapper. */
+    inputClassName?: string;
+}
+/**
+ * An inline, async-capable text field with a suggestion list under it — the
+ * WAI-ARIA APG "editable combobox with list autocomplete".
+ *
+ * Two jobs, one control:
+ *  - **free text** (kastlan's address field): the text is the value, the list only
+ *    offers completions, and taking one fills the field (`fillOnSelect`, default);
+ *  - **search-then-act** (keksdose's address search): the text is a query, taking a
+ *    row calls `onSelect` and nothing is held (`fillOnSelect={false}`).
+ *
+ * How it differs from its siblings: {@link Combobox} is free text over a STATIC
+ * string pool and opens on focus; {@link EntityCombobox} is a trigger holding an id.
+ * This one keeps no value of its own, never resets the text, asks nothing below
+ * `minChars`, and reports a failed lookup instead of showing stale rows.
+ *
+ * Focus never leaves the `<input>`: `aria-activedescendant` names the highlighted
+ * row, `aria-controls` the list, and a polite live region says what the list now
+ * holds. Keyboard: ↓/↑ move (↓ opens), Enter takes the highlighted row (with none,
+ * Enter is left to the form), Escape closes, Tab closes and moves on; Home/End stay
+ * with the caret. A caller's `onKeyDown` runs first and may `preventDefault()` to
+ * keep a key for itself.
+ *
+ * The list is portalled and anchored under the field on every screen size: the
+ * field already carries the keyboard, and `useAnchoredPanel` keeps the list clear
+ * of it on a phone. There is no full-screen sheet as {@link Combobox} has.
+
+ * Generic over the option value (`ComboOption<V>`); the ref is the `<input>`'s.
+ */
+declare const Autocomplete: <V extends string | number = string>(props: AutocompleteProps<V> & RefAttributes<HTMLInputElement>) => ReactElement | null;
+
+export { Autocomplete, type AutocompleteProps };

package/dist/components/autocomplete.js

@@ -0,0 +1,260 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, forwardRef, useId, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { cn } from "../lib/cn.js";
+import { FieldLabel, FIELD_BASE, FIELD_FLOATING_PAD, FIELD_INVALID, Spinner } from "./ui.js";
+import { useAnchoredPanel } from "../hooks/use-anchored-panel.js";
+import {
+  useActiveOptionScroll,
+  useComboboxFieldError,
+  useOptionSource
+} from "./combobox-core.js";
+import { DEFAULT_COMBOBOX_LABELS, useKitLabels } from "../i18n/kit-labels.js";
+function AutocompleteInner({
+  value,
+  onChange,
+  options,
+  loadOptions,
+  filter,
+  loading,
+  minChars = 1,
+  debounceMs = 300,
+  onSelect,
+  fillOnSelect = true,
+  label,
+  icon,
+  invalid,
+  error,
+  status,
+  emptyLabel,
+  loadErrorLabel,
+  className,
+  inputClassName,
+  id,
+  disabled,
+  onKeyDown,
+  onFocus,
+  onBlur,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  "aria-describedby": ariaDescribedBy,
+  ...rest
+}, ref) {
+  const generated = useId();
+  const fieldId = id ?? generated;
+  const listboxId = `${generated}-listbox`;
+  const labelId = `${generated}-label`;
+  const optionId = (index) => `${generated}-option-${index}`;
+  const fieldRef = useRef(null);
+  const labels = useKitLabels("combobox", DEFAULT_COMBOBOX_LABELS, {
+    noResults: emptyLabel,
+    loadError: loadErrorLabel
+  });
+  const field = useComboboxFieldError(error, invalid, ariaDescribedBy);
+  const [open, setOpen] = useState(false);
+  const [active, setActive] = useState(-1);
+  const live = open && !disabled;
+  const { results, busy, failed, tooShort } = useOptionSource({
+    options,
+    loadOptions,
+    loading,
+    filter,
+    minChars,
+    debounceMs,
+    query: value,
+    active: live
+  });
+  const hasStatus = status !== void 0 && status !== null && status !== false && status !== "";
+  const statusLine = hasStatus ? status : tooShort ? null : busy && results.length === 0 ? labels.loading : failed ? labels.loadError : !busy && results.length === 0 ? labels.noResults : null;
+  const expanded = live && (results.length > 0 || statusLine !== null);
+  const activeId = expanded && active >= 0 && active < results.length ? optionId(active) : void 0;
+  useActiveOptionScroll(activeId);
+  const { rect, top, maxHeight } = useAnchoredPanel(fieldRef, expanded, { preferredHeight: 256 });
+  const close = () => {
+    setOpen(false);
+    setActive(-1);
+  };
+  const take = (o) => {
+    if (fillOnSelect) onChange(o.label);
+    onSelect?.(o);
+    close();
+  };
+  const hasLabel = label !== void 0;
+  const labelledBy = ariaLabel === void 0 ? ariaLabelledBy ?? (hasLabel ? labelId : void 0) : void 0;
+  return (
+    // `relative`: the floating label and the live region's `sr-only` both need a
+    // local containing block.
+    /* @__PURE__ */ jsxs("div", { className: cn("relative", className), children: [
+      hasLabel && /* @__PURE__ */ jsx(FieldLabel, { id: labelId, children: label }),
+      /* @__PURE__ */ jsxs("div", { ref: fieldRef, className: "relative", children: [
+        icon && /* @__PURE__ */ jsx(
+          "span",
+          {
+            "aria-hidden": true,
+            className: "pointer-events-none absolute start-2.5 top-1/2 flex -translate-y-1/2 text-[var(--text-muted)] [&>svg]:size-4",
+            children: icon
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "input",
+          {
+            ...rest,
+            ref,
+            id: fieldId,
+            type: "text",
+            value,
+            disabled,
+            role: "combobox",
+            "aria-autocomplete": "list",
+            "aria-expanded": expanded,
+            "aria-controls": listboxId,
+            "aria-activedescendant": activeId,
+            "aria-label": ariaLabel,
+            "aria-labelledby": labelledBy,
+            "aria-invalid": field.isInvalid || rest["aria-invalid"] || void 0,
+            "aria-describedby": field.describedBy,
+            autoComplete: "off",
+            onFocus: (e) => {
+              onFocus?.(e);
+              setOpen(true);
+            },
+            onBlur: (e) => {
+              onBlur?.(e);
+              close();
+            },
+            onChange: (e) => {
+              onChange(e.target.value);
+              setOpen(true);
+              setActive(-1);
+            },
+            onKeyDown: (e) => {
+              onKeyDown?.(e);
+              if (e.defaultPrevented) return;
+              const last = results.length - 1;
+              if (e.key === "ArrowDown") {
+                e.preventDefault();
+                if (!open) setOpen(true);
+                else setActive((i) => Math.min(i + 1, last));
+              } else if (e.key === "ArrowUp") {
+                e.preventDefault();
+                if (!open) setOpen(true);
+                else setActive((i) => i < 0 ? last : Math.max(i - 1, 0));
+              } else if (e.key === "Enter") {
+                if (expanded && activeId) {
+                  e.preventDefault();
+                  take(results[active]);
+                }
+              } else if (e.key === "Escape") {
+                if (expanded) {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  close();
+                }
+              } else if (e.key === "Tab") {
+                close();
+              }
+            },
+            className: cn(
+              FIELD_BASE,
+              hasLabel && FIELD_FLOATING_PAD,
+              icon ? "ps-8" : void 0,
+              busy && "pe-9",
+              field.isInvalid && FIELD_INVALID,
+              inputClassName
+            )
+          }
+        ),
+        busy && live && // Decorative: the live region below already says "Loading…".
+        /* @__PURE__ */ jsx("span", { className: "pointer-events-none absolute end-2.5 top-1/2 flex -translate-y-1/2", children: /* @__PURE__ */ jsx(Spinner, { label: null, className: "h-4 w-4" }) })
+      ] }),
+      field.errorEl,
+      /* @__PURE__ */ jsx("div", { role: "status", "aria-live": "polite", className: "sr-only", children: !live ? null : statusLine !== null ? statusLine : results.length > 0 ? labels.resultCount(results.length) : null }),
+      expanded && rect && typeof document !== "undefined" && createPortal(
+        /* @__PURE__ */ jsxs(
+          "div",
+          {
+            role: "presentation",
+            onMouseDown: (e) => e.preventDefault(),
+            className: "fixed z-50 flex flex-col overflow-hidden rounded-md border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg",
+            style: { top, left: rect.left, width: rect.width, maxHeight },
+            children: [
+              results.length > 0 && /* @__PURE__ */ jsx(
+                "ul",
+                {
+                  id: listboxId,
+                  role: "listbox",
+                  "aria-label": ariaLabel,
+                  "aria-labelledby": labelledBy,
+                  className: "min-h-0 flex-1 overflow-y-auto py-1",
+                  children: results.map((o, i) => {
+                    const startsGroup = o.group != null && o.group !== results[i - 1]?.group;
+                    return (
+                      // Keyed by group AND value, as in the core panel: an option may
+                      // appear once per group.
+                      /* @__PURE__ */ jsxs(Fragment, { children: [
+                        startsGroup && /* @__PURE__ */ jsx(
+                          "li",
+                          {
+                            role: "presentation",
+                            className: "px-3 pb-0.5 pt-2 text-[11px] font-semibold uppercase tracking-wide text-[var(--text-muted)] first:pt-1",
+                            children: o.group
+                          }
+                        ),
+                        /* @__PURE__ */ jsx("li", { role: "presentation", children: /* @__PURE__ */ jsxs(
+                          "button",
+                          {
+                            type: "button",
+                            id: optionId(i),
+                            role: "option",
+                            "aria-selected": fillOnSelect && o.label === value,
+                            tabIndex: -1,
+                            onClick: () => take(o),
+                            onMouseEnter: () => setActive(i),
+                            className: cn(
+                              "flex w-full items-center gap-2 px-3 py-1.5 text-start text-sm",
+                              i === active ? "bg-[var(--bg-active)]" : "hover:bg-[var(--bg-hover)]",
+                              o.group != null && "ps-6"
+                            ),
+                            children: [
+                              o.icon && /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: "shrink-0 text-[var(--text-muted)]", children: o.icon }),
+                              /* @__PURE__ */ jsxs("span", { className: "min-w-0 flex-1", children: [
+                                /* @__PURE__ */ jsx("span", { className: "block truncate text-[var(--text-primary)]", children: o.label }),
+                                o.sublabel && /* @__PURE__ */ jsx("span", { className: "block truncate text-xs text-[var(--text-placeholder)]", children: o.sublabel })
+                              ] })
+                            ]
+                          }
+                        ) })
+                      ] }, `${o.group ?? ""}|${String(o.value)}`)
+                    );
+                  })
+                }
+              ),
+              statusLine !== null && // Visible, not live — the region above speaks for it.
+              /* @__PURE__ */ jsx(
+                "div",
+                {
+                  "aria-hidden": true,
+                  className: cn(
+                    "px-3 py-2 text-sm",
+                    failed && !hasStatus ? "text-[var(--danger)]" : "text-[var(--text-muted)]",
+                    results.length > 0 && "border-t border-[var(--border)] text-xs"
+                  ),
+                  children: statusLine
+                }
+              )
+            ]
+          }
+        ),
+        document.body
+      )
+    ] })
+  );
+}
+const AutocompleteBase = forwardRef(AutocompleteInner);
+AutocompleteBase.displayName = "Autocomplete";
+const Autocomplete = AutocompleteBase;
+export {
+  Autocomplete
+};
+//# sourceMappingURL=autocomplete.js.map

package/dist/components/autocomplete.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/autocomplete.tsx"],"sourcesContent":["import { Fragment, forwardRef, useId, useRef, useState } from \"react\";\nimport type {\n  ComponentPropsWithoutRef,\n  ForwardedRef,\n  ReactElement,\n  ReactNode,\n  RefAttributes,\n} from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { cn } from \"../lib/cn\";\nimport { FieldLabel, FIELD_BASE, FIELD_FLOATING_PAD, FIELD_INVALID, Spinner } from \"./ui\";\nimport { useAnchoredPanel } from \"../hooks/use-anchored-panel\";\nimport {\n  useActiveOptionScroll,\n  useComboboxFieldError,\n  useOptionSource,\n  type ComboOption,\n} from \"./combobox-core\";\nimport { DEFAULT_COMBOBOX_LABELS, useKitLabels } from \"../i18n/kit-labels\";\n\n/**\n * `value`/`onChange` are the TEXT's, and `onSelect` is \"a suggestion was taken\" —\n * not the DOM's text-selection event — so the input's own spellings of those three\n * are omitted. Everything else reaches the `<input>`, the way it does on {@link Input}.\n */\nexport interface AutocompleteProps<V extends string | number = string>\n  extends Omit<\n    ComponentPropsWithoutRef<\"input\">,\n    \"value\" | \"defaultValue\" | \"onChange\" | \"onSelect\" | \"children\" | \"type\"\n  > {\n  /** What is in the field. Controlled, and never reset by the component: opening,\n   *  closing and a failed lookup all leave it exactly as typed. */\n  value: string;\n  /** Every keystroke — and, with `fillOnSelect`, the label of a taken suggestion. */\n  onChange: (text: string) => void;\n  /** Suggestions the caller already has (e.g. from its own query hook). Narrowed by\n   *  the text unless `filter={false}`. */\n  options?: ComboOption<V>[];\n  /** Or: fetch them. Debounced (`debounceMs`), race-safe, only at `minChars` and up,\n   *  never while the field is idle; a rejection shows `loadErrorLabel` and empties\n   *  the list rather than leaving the previous text's rows under it. */\n  loadOptions?: (query: string) => Promise<ComboOption<V>[]>;\n  /** Narrow `options` by label/sublabel substring. Default `true`. Pass `false` for\n   *  a list a server has already searched and ranked — it is shown as given. */\n  filter?: boolean;\n  /** External loading flag (a caller-side fetch), OR-ed with `loadOptions`'. */\n  loading?: boolean;\n  /** Below this many characters nothing is offered or fetched. Default 1: an empty\n   *  field asks nothing — focusing it is not a search. */\n  minChars?: number;\n  /** Quiet time before `loadOptions` runs. Default 300 ms — an ordinary typist's\n   *  inter-key interval is 150–250 ms, so the pickers' 150 fires on nearly every\n   *  letter, which a rate-limited geocoder cannot afford. */\n  debounceMs?: number;\n  /** A suggestion was taken (click, or Enter on the highlighted row). */\n  onSelect?: (option: ComboOption<V>) => void;\n  /**\n   * Put the taken suggestion's label into the field (`onChange(label)`). Default\n   * `true` — the free-text case, where the text IS the value and a suggestion only\n   * completes it (an address field). Pass `false` where taking a row is an ACTION\n   * and the field is only the search that found it; the text then stays as typed.\n   */\n  fillOnSelect?: boolean;\n  /** A floating label, as on {@link Combobox}. Names the field (`aria-labelledby`)\n   *  unless an `aria-label` is given. */\n  label?: ReactNode;\n  /** Leading decoration inside the field (a pin, a magnifier). Decorative: the\n   *  label names the field. */\n  icon?: ReactNode;\n  /** Required and unanswered — {@link FIELD_INVALID}. */\n  invalid?: boolean;\n  /** What is wrong with the VALUE, as {@link Input}'s `error`: under the field, on\n   *  its `aria-describedby`, implies `invalid`. Not a failed lookup — that is\n   *  `loadErrorLabel`, shown in the list. */\n  error?: ReactNode;\n  /**\n   * The caller's own line in the list, replacing the automatic one (loading / failed\n   * / no results). For what only the caller knows: \"offline\", \"the address service\n   * is switched off\", a privacy note, the hint a caller-fetched list needs below its\n   * own minimum. While set, the list opens even with no rows. Announced politely.\n   */\n  status?: ReactNode;\n  /** Default: `combobox.noResults` from the {@link UiKitProvider}, else English. */\n  emptyLabel?: string;\n  /** Default: `combobox.loadError`. */\n  loadErrorLabel?: string;\n  /** Classes for the `<input>` itself; `className` styles the wrapper. */\n  inputClassName?: string;\n}\n\nfunction AutocompleteInner<V extends string | number = string>(\n  {\n    value,\n    onChange,\n    options,\n    loadOptions,\n    filter,\n    loading,\n    minChars = 1,\n    debounceMs = 300,\n    onSelect,\n    fillOnSelect = true,\n    label,\n    icon,\n    invalid,\n    error,\n    status,\n    emptyLabel,\n    loadErrorLabel,\n    className,\n    inputClassName,\n    id,\n    disabled,\n    onKeyDown,\n    onFocus,\n    onBlur,\n    \"aria-label\": ariaLabel,\n    \"aria-labelledby\": ariaLabelledBy,\n    \"aria-describedby\": ariaDescribedBy,\n    ...rest\n  }: AutocompleteProps<V>,\n  ref: ForwardedRef<HTMLInputElement>,\n) {\n  const generated = useId();\n  const fieldId = id ?? generated;\n  // Off the GENERATED id: a caller's `id` is theirs to collide with.\n  const listboxId = `${generated}-listbox`;\n  const labelId = `${generated}-label`;\n  const optionId = (index: number) => `${generated}-option-${index}`;\n  const fieldRef = useRef<HTMLDivElement>(null);\n  const labels = useKitLabels(\"combobox\", DEFAULT_COMBOBOX_LABELS, {\n    noResults: emptyLabel,\n    loadError: loadErrorLabel,\n  });\n  const field = useComboboxFieldError(error, invalid, ariaDescribedBy);\n\n  /** The user's intent: the field is focused and the list has not been dismissed.\n   *  Whether anything SHOWS is decided below, from what there is to show. */\n  const [open, setOpen] = useState(false);\n  const [active, setActive] = useState(-1);\n  const live = open && !disabled;\n  const { results, busy, failed, tooShort } = useOptionSource<V>({\n    options,\n    loadOptions,\n    loading,\n    filter,\n    minChars,\n    debounceMs,\n    query: value,\n    active: live,\n  });\n\n  const hasStatus = status !== undefined && status !== null && status !== false && status !== \"\";\n  // The visible line under the rows. Nothing below `minChars` unless the caller has\n  // something to say — an empty field opening a box that says \"type more\" is noise.\n  const statusLine: ReactNode = hasStatus\n    ? status\n    : tooShort\n      ? null\n      : busy && results.length === 0\n        ? labels.loading\n        : failed\n          ? labels.loadError\n          : !busy && results.length === 0\n            ? labels.noResults\n            : null;\n  const expanded = live && (results.length > 0 || statusLine !== null);\n  const activeId =\n    expanded && active >= 0 && active < results.length ? optionId(active) : undefined;\n  useActiveOptionScroll(activeId);\n  const { rect, top, maxHeight } = useAnchoredPanel(fieldRef, expanded, { preferredHeight: 256 });\n\n  const close = () => {\n    setOpen(false);\n    setActive(-1);\n  };\n  const take = (o: ComboOption<V>) => {\n    if (fillOnSelect) onChange(o.label);\n    onSelect?.(o);\n    close();\n  };\n\n  const hasLabel = label !== undefined;\n  // The caller's name wins; else the floating label, by reference so a non-string\n  // label still names the field.\n  const labelledBy =\n    ariaLabel === undefined ? (ariaLabelledBy ?? (hasLabel ? labelId : undefined)) : undefined;\n\n  return (\n    // `relative`: the floating label and the live region's `sr-only` both need a\n    // local containing block.\n    <div className={cn(\"relative\", className)}>\n      {hasLabel && <FieldLabel id={labelId}>{label}</FieldLabel>}\n      <div ref={fieldRef} className=\"relative\">\n        {icon && (\n          <span\n            aria-hidden\n            className=\"pointer-events-none absolute start-2.5 top-1/2 flex -translate-y-1/2 text-[var(--text-muted)] [&>svg]:size-4\"\n          >\n            {icon}\n          </span>\n        )}\n        <input\n          {...rest}\n          ref={ref}\n          id={fieldId}\n          type=\"text\"\n          value={value}\n          disabled={disabled}\n          role=\"combobox\"\n          aria-autocomplete=\"list\"\n          aria-expanded={expanded}\n          // Required by the role, and set while closed too, as on the siblings.\n          aria-controls={listboxId}\n          aria-activedescendant={activeId}\n          aria-label={ariaLabel}\n          aria-labelledby={labelledBy}\n          aria-invalid={field.isInvalid || rest[\"aria-invalid\"] || undefined}\n          aria-describedby={field.describedBy}\n          autoComplete=\"off\"\n          onFocus={(e) => {\n            onFocus?.(e);\n            // A seeded field (keksdose's `initialQuery`) is looked up as it is\n            // focused; an empty one asks nothing, because of `minChars`.\n            setOpen(true);\n          }}\n          onBlur={(e) => {\n            onBlur?.(e);\n            close();\n          }}\n          onChange={(e) => {\n            onChange(e.target.value);\n            setOpen(true);\n            setActive(-1);\n          }}\n          onKeyDown={(e) => {\n            onKeyDown?.(e);\n            if (e.defaultPrevented) return;\n            const last = results.length - 1;\n            if (e.key === \"ArrowDown\") {\n              e.preventDefault();\n              if (!open) setOpen(true);\n              else setActive((i) => Math.min(i + 1, last));\n            } else if (e.key === \"ArrowUp\") {\n              e.preventDefault();\n              if (!open) setOpen(true);\n              // From \"nothing highlighted\", Up goes to the bottom, as the APG has it.\n              else setActive((i) => (i < 0 ? last : Math.max(i - 1, 0)));\n            } else if (e.key === \"Enter\") {\n              // No row highlighted: the text is the answer, and a form's own submit\n              // is left alone.\n              if (expanded && activeId) {\n                e.preventDefault();\n                take(results[active]);\n              }\n            } else if (e.key === \"Escape\") {\n              // Only when there is a list to close — otherwise the Escape belongs to\n              // whatever this field sits in (a dialog), and must reach it.\n              if (expanded) {\n                e.preventDefault();\n                e.stopPropagation();\n                close();\n              }\n            } else if (e.key === \"Tab\") {\n              close();\n            }\n          }}\n          className={cn(\n            FIELD_BASE,\n            hasLabel && FIELD_FLOATING_PAD,\n            icon ? \"ps-8\" : undefined,\n            busy && \"pe-9\",\n            field.isInvalid && FIELD_INVALID,\n            inputClassName,\n          )}\n        />\n        {busy && live && (\n          // Decorative: the live region below already says \"Loading…\".\n          <span className=\"pointer-events-none absolute end-2.5 top-1/2 flex -translate-y-1/2\">\n            <Spinner label={null} className=\"h-4 w-4\" />\n          </span>\n        )}\n      </div>\n      {field.errorEl}\n      {/* The live region, kept mounted so a change IS an announcement: focus stays\n          in the field, and without it a reader typed into a geocoder and heard only\n          their own letters. The panel's visible line is aria-hidden in favour of\n          this, which also carries the row count the eye reads off the list. */}\n      <div role=\"status\" aria-live=\"polite\" className=\"sr-only\">\n        {!live\n          ? null\n          : statusLine !== null\n            ? statusLine\n            : results.length > 0\n              ? labels.resultCount(results.length)\n              : null}\n      </div>\n      {expanded &&\n        rect &&\n        typeof document !== \"undefined\" &&\n        createPortal(\n          <div\n            // Every press inside the list keeps focus in the field — rows, the status\n            // line, the scrollbar — or the input's blur would close the list first.\n            role=\"presentation\"\n            onMouseDown={(e) => e.preventDefault()}\n            className=\"fixed z-50 flex flex-col overflow-hidden rounded-md border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg\"\n            style={{ top, left: rect.left, width: rect.width, maxHeight }}\n          >\n            {results.length > 0 && (\n              <ul\n                id={listboxId}\n                role=\"listbox\"\n                aria-label={ariaLabel}\n                aria-labelledby={labelledBy}\n                className=\"min-h-0 flex-1 overflow-y-auto py-1\"\n              >\n                {results.map((o, i) => {\n                  const startsGroup = o.group != null && o.group !== results[i - 1]?.group;\n                  return (\n                    // Keyed by group AND value, as in the core panel: an option may\n                    // appear once per group.\n                    <Fragment key={`${o.group ?? \"\"}|${String(o.value)}`}>\n                      {startsGroup && (\n                        <li\n                          role=\"presentation\"\n                          className=\"px-3 pb-0.5 pt-2 text-[11px] font-semibold uppercase tracking-wide text-[var(--text-muted)] first:pt-1\"\n                        >\n                          {o.group}\n                        </li>\n                      )}\n                      <li role=\"presentation\">\n                        <button\n                          type=\"button\"\n                          id={optionId(i)}\n                          role=\"option\"\n                          // CHOSEN, never \"highlighted\" — the family's rule. This\n                          // field holds no value, so the only row that can be chosen\n                          // is the one whose label the text already is.\n                          aria-selected={fillOnSelect && o.label === value}\n                          tabIndex={-1}\n                          onClick={() => take(o)}\n                          onMouseEnter={() => setActive(i)}\n                          className={cn(\n                            \"flex w-full items-center gap-2 px-3 py-1.5 text-start text-sm\",\n                            i === active ? \"bg-[var(--bg-active)]\" : \"hover:bg-[var(--bg-hover)]\",\n                            o.group != null && \"ps-6\",\n                          )}\n                        >\n                          {o.icon && (\n                            <span aria-hidden className=\"shrink-0 text-[var(--text-muted)]\">\n                              {o.icon}\n                            </span>\n                          )}\n                          <span className=\"min-w-0 flex-1\">\n                            <span className=\"block truncate text-[var(--text-primary)]\">\n                              {o.label}\n                            </span>\n                            {o.sublabel && (\n                              <span className=\"block truncate text-xs text-[var(--text-placeholder)]\">\n                                {o.sublabel}\n                              </span>\n                            )}\n                          </span>\n                        </button>\n                      </li>\n                    </Fragment>\n                  );\n                })}\n              </ul>\n            )}\n            {statusLine !== null && (\n              // Visible, not live — the region above speaks for it.\n              <div\n                aria-hidden\n                className={cn(\n                  \"px-3 py-2 text-sm\",\n                  failed && !hasStatus ? \"text-[var(--danger)]\" : \"text-[var(--text-muted)]\",\n                  results.length > 0 && \"border-t border-[var(--border)] text-xs\",\n                )}\n              >\n                {statusLine}\n              </div>\n            )}\n          </div>,\n          document.body,\n        )}\n    </div>\n  );\n}\n\nconst AutocompleteBase = forwardRef(AutocompleteInner);\nAutocompleteBase.displayName = \"Autocomplete\";\n\n/**\n * An inline, async-capable text field with a suggestion list under it — the\n * WAI-ARIA APG \"editable combobox with list autocomplete\".\n *\n * Two jobs, one control:\n *  - **free text** (kastlan's address field): the text is the value, the list only\n *    offers completions, and taking one fills the field (`fillOnSelect`, default);\n *  - **search-then-act** (keksdose's address search): the text is a query, taking a\n *    row calls `onSelect` and nothing is held (`fillOnSelect={false}`).\n *\n * How it differs from its siblings: {@link Combobox} is free text over a STATIC\n * string pool and opens on focus; {@link EntityCombobox} is a trigger holding an id.\n * This one keeps no value of its own, never resets the text, asks nothing below\n * `minChars`, and reports a failed lookup instead of showing stale rows.\n *\n * Focus never leaves the `<input>`: `aria-activedescendant` names the highlighted\n * row, `aria-controls` the list, and a polite live region says what the list now\n * holds. Keyboard: ↓/↑ move (↓ opens), Enter takes the highlighted row (with none,\n * Enter is left to the form), Escape closes, Tab closes and moves on; Home/End stay\n * with the caret. A caller's `onKeyDown` runs first and may `preventDefault()` to\n * keep a key for itself.\n *\n * The list is portalled and anchored under the field on every screen size: the\n * field already carries the keyboard, and `useAnchoredPanel` keeps the list clear\n * of it on a phone. There is no full-screen sheet as {@link Combobox} has.\n\n * Generic over the option value (`ComboOption<V>`); the ref is the `<input>`'s.\n */\nexport const Autocomplete = AutocompleteBase as <V extends string | number = string>(\n  props: AutocompleteProps<V> & RefAttributes<HTMLInputElement>,\n) => ReactElement | null;\n"],"mappings":"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","names":[]}

package/dist/components/calculator.d.ts

@@ -17,6 +17,13 @@ import './sparkline.js';
 import './stat-tile.js';
 import './signature-pad.js';
 import './password-strength.js';
+import './danger-confirm.js';
+import './swatch-picker.js';
+import './tile-radio.js';
+import './icon-picker.js';
+import './dialog-frame.js';
+import './modal.js';
+import './file-button.js';
 
 /** Screen-reader names for the calculator panel's own controls — any part of the
  *  kit's `calculator` namespace. Once three optional keys of its own; widened, not

package/dist/components/chip.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode, KeyboardEvent, ComponentPropsWithoutRef } from 'react';
+import { ReactNode, MouseEvent, KeyboardEvent, ComponentPropsWithoutRef } from 'react';
 import { LucideIcon } from 'lucide-react';
 
 /**
@@ -16,19 +16,28 @@ import { LucideIcon } from 'lucide-react';
  * "choose one of eight things to do" and a row of eight chips says "here are eight
  * things". Using `Button` for both is the mistake this exists to prevent.
  */
-type ChipTone = "neutral" | "brand" | "danger" | "warning" | "success" | "info";
-type ChipSize = "sm" | "md";
+type ChipTone = "neutral" | "brand" | "danger" | "warning" | "success" | "info" | "income" | "expense";
+/** `lg` is the 44px touch target (`min-h-11`) a phone surface wants; `md` is ~28px. */
+type ChipSize = "sm" | "md" | "lg";
 interface ChipProps {
     children: ReactNode;
     tone?: ChipTone;
     size?: ChipSize;
     icon?: LucideIcon;
-    /** Marks the chip as the current one — `aria-current` on a link, `aria-pressed` on a toggle. */
+    /**
+     * Marks the chip as the current one — `aria-current` on a link, `aria-pressed` on a
+     * toggle.
+     *
+     * On a toggle, keep the LABEL the same in both states and let `selected` carry the
+     * state. A label that flips with it ("Skip this month" / "Ask again this month") is
+     * announced together with "pressed", and then says the opposite of what it does.
+     */
     selected?: boolean;
     /** Renders the chip as a link. Mutually exclusive with `onClick`. */
     href?: string;
-    /** Renders the chip as a toggle button. Mutually exclusive with `href`. */
-    onClick?: () => void;
+    /** Renders the chip as a toggle button. Mutually exclusive with `href`. Receives the
+     *  click, so a chip inside a clickable row can `stopPropagation()`. */
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
     /** Renders a dismiss affordance. Works alongside `href`/`onClick` — see the note below. */
     onRemove?: () => void;
     /** Accessible name for the dismiss button. Default: `common.remove` from the
@@ -47,8 +56,14 @@ interface ChipProps {
     onFocus?: () => void;
     /** Accessible name, when the visible text is not the whole story. */
     "aria-label"?: string;
-    /** Escape hatch for a test id, a `data-tour` anchor, or an `aria-describedby`. */
+    /** Any other ARIA attribute — `aria-describedby`, `aria-expanded`, `aria-controls`,
+     *  `aria-haspopup` — reaches the chip's interactive element. */
+    [key: `aria-${string}`]: string | boolean | number | undefined;
+    /** A test id, a `data-tour` anchor, or any other data attribute. */
     [key: `data-${string}`]: unknown;
+    id?: string;
+    /** A native tooltip. For anything a user must read, prefer the kit's `Tooltip`. */
+    title?: string;
 }
 /**
  * Note on `onRemove` with `href`/`onClick`: a button cannot be nested inside a button or

package/dist/components/chip.js

@@ -29,11 +29,24 @@ const TONE = {
   info: {
     idle: "border-[var(--info-border)] bg-[var(--info-bg)] text-[var(--info)]",
     selected: "border-[var(--info)] bg-[var(--info-bg)] text-[var(--info)]"
+  },
+  // The money pair (Keksdose's direction toggle). Only the TEXT and the BORDER carry
+  // the tint, on the neutral chip's own surfaces: the money tokens are chosen for text
+  // contrast, and a filled amber pill beside an amber figure reads as one smear.
+  // `border-current` takes its hue from the text, so the two cannot drift apart.
+  income: {
+    idle: "border-current/40 bg-[var(--bg-surface-2)] text-[var(--money-income)]",
+    selected: "border-current bg-[var(--bg-active)] text-[var(--money-income)]"
+  },
+  expense: {
+    idle: "border-current/40 bg-[var(--bg-surface-2)] text-[var(--money-expense)]",
+    selected: "border-current bg-[var(--bg-active)] text-[var(--money-expense)]"
   }
 };
 const SIZE = {
   sm: { body: "gap-1 px-2 py-0.5 text-xs", icon: "size-3", remove: "size-3" },
-  md: { body: "gap-1.5 px-2.5 py-1 text-sm", icon: "size-3.5", remove: "size-3.5" }
+  md: { body: "gap-1.5 px-2.5 py-1 text-sm", icon: "size-3.5", remove: "size-3.5" },
+  lg: { body: "min-h-11 gap-2 px-4 py-2 text-sm", icon: "size-4", remove: "size-4" }
 };
 const CHIP_BASE = "inline-flex max-w-full items-center rounded-full border transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] focus-visible:ring-offset-1 focus-visible:ring-offset-[var(--bg-surface)]";
 const Chip = forwardRef(function Chip2({