@eifi1/ui-kit 0.8.1 → 0.10.0

package/src/search/search-index.ts

@@ -0,0 +1,295 @@
+import type { ReactNode } from "react";
+
+/**
+ * The matcher behind {@link GlobalSearch} — pure, React-free, testable on its own.
+ *
+ * WHY IT EXISTS. `CommandPalette` is deliberately domain-free: it shows whatever a
+ * `search(query)` provider returns. So every app wrote that provider, and every app wrote
+ * the same one — `label.toLowerCase().includes(q)` over its pages and actions (kastlan's
+ * command palette, keksdose's global search) plus a second copy with keywords for the
+ * settings catalogue (keksdose's `matchSettingsEntries`). A substring test answers "does
+ * this string contain that one", which is not what a search box is asked:
+ *
+ *  - "range date" finds nothing, because the words are in the other order;
+ *  - "Uberweisung" misses "Überweisung", and "Tooltp" misses "Tooltip";
+ *  - "del" matches "model" as happily as "delete", and every hit ranks the same, so the
+ *    exact page name can sit under six unrelated rows.
+ *
+ * What it does instead, per entry:
+ *
+ *  - NORMALISES both sides: lower case, accents stripped (NFD minus combining marks),
+ *    `ß` → `ss`, punctuation as a word break, and camelCase split so `DateRangePicker`
+ *    is also the words date, range, picker.
+ *  - Requires EVERY query word to match SOMEWHERE in the entry — title, keywords or
+ *    description, in any order.
+ *  - A word matches a word of the entry exactly, as its prefix, inside it (four letters or
+ *    more, for compounds: "bereich" in "Datumsbereich"), or — for words of five letters
+ *    or more — at edit distance one, transpositions included ("tooltp", "calender").
+ *  - RANKS in tiers: exact title > title prefix > all words in the title > some word only
+ *    in the keywords > some word only in the description. Within a tier, better word
+ *    matches (exact over prefix over infix over typo) score higher, and `weight` is added
+ *    last. The tiers are {@link SEARCH_TIER_POINTS} points apart, so a weight below that reorders within
+ *    a tier and never across one.
+ *  - Caps each group (`groupLimit`, default 8) after ranking, so one broad group cannot
+ *    push every other group off the list.
+ */
+
+/** One searchable thing: a page, an action, a record, a settings row. */
+export interface SearchEntry {
+  /** Unique across the entries handed to one index. */
+  id: string;
+  /** What the row says, and what ranks highest. */
+  title: string;
+  /** Other words or phrases that should find it — synonyms, a translated name, tags.
+   *  Matched like the title, ranked below it. */
+  keywords?: readonly string[];
+  /** Longer text, matched last and ranked lowest. Not shown in the row. */
+  description?: string;
+  /** Heading the row is grouped under in the palette. */
+  group?: string;
+  /** Secondary text on the row's trailing side (the page it lives on, an amount). */
+  hint?: string;
+  /** Leading icon. */
+  icon?: ReactNode;
+  /** Where it leads — the app's own path, handed to `GlobalSearch`'s `navigate`. */
+  href?: string;
+  /** Run instead of navigating. Wins over `href` for a plain click and ↵; `href` still
+   *  makes the row a real link for a middle-/⌘-click. */
+  onSelect?: () => void;
+  /** Added to the score. Below {@link SEARCH_TIER_POINTS} it reorders within a tier. */
+  weight?: number;
+  /** Masks the row for session replay (see `CommandItem.redact`). */
+  redact?: boolean;
+}
+
+export type SearchMatchField = "title" | "keywords" | "description";
+
+export interface SearchHit<E extends SearchEntry = SearchEntry> {
+  entry: E;
+  score: number;
+  /** The weakest field any query word had to be found in. */
+  field: SearchMatchField;
+}
+
+export interface SearchIndexOptions {
+  /** Hits kept per `group` after ranking. Default 8; `Infinity` for no cap. */
+  groupLimit?: number;
+  /** Hits kept in total. Default: no cap beyond `groupLimit`. */
+  limit?: number;
+  /** Shortest query word allowed an edit-distance-1 match. Default 5 — below that a
+   *  single typo is a different word ("cat" / "car"). */
+  typoMinLength?: number;
+  /** Shortest query word matched INSIDE an entry word. Default 4. */
+  infixMinLength?: number;
+}
+
+export interface SearchIndex<E extends SearchEntry = SearchEntry> {
+  /** Ranked hits for `query`; an empty query returns none. */
+  search: (query: string) => SearchHit<E>[];
+  readonly entries: readonly E[];
+}
+
+/** Points between two ranking tiers. */
+export const SEARCH_TIER_POINTS = 1000;
+
+const TIERS = {
+  exact: 5,
+  prefix: 4,
+  title: 3,
+  keywords: 2,
+  description: 1,
+} as const;
+
+/** How well one query word matched one entry word — higher is better. */
+const WORD_SCORE = { exact: 40, prefix: 30, infix: 15, typo: 10 } as const;
+/** How much the field a word matched in is worth, multiplied with the above. */
+const FIELD_FACTOR: Record<SearchMatchField, number> = { title: 3, keywords: 2, description: 1 };
+
+/**
+ * Lower case, accents off, punctuation to spaces — the form both sides are compared in.
+ * Exported so an app can normalise its own keys the same way.
+ */
+export function normalizeSearchText(text: string): string {
+  return text
+    .normalize("NFD")
+    .replace(/\p{M}+/gu, "")
+    .toLowerCase()
+    .replace(/ß/g, "ss")
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim();
+}
+
+/** The words of a text, camelCase split too: "DateRangePicker" → daterangepicker, date,
+ *  range, picker. The joined word stays so "daterange" still prefixes it. */
+function words(text: string): string[] {
+  const out = new Set<string>();
+  // Split camelCase BEFORE lower-casing, or the boundaries are gone.
+  const spaced = text.replace(/(\p{Ll}|\p{N})(\p{Lu})/gu, "$1 $2").replace(/(\p{Lu})(\p{Lu}\p{Ll})/gu, "$1 $2");
+  for (const w of normalizeSearchText(text).split(" ")) if (w) out.add(w);
+  for (const w of normalizeSearchText(spaced).split(" ")) if (w) out.add(w);
+  return [...out];
+}
+
+/** Restricted Damerau–Levenshtein distance, early-exiting once it must exceed `max`. */
+function withinDistance(a: string, b: string, max: number): boolean {
+  if (Math.abs(a.length - b.length) > max) return false;
+  if (a === b) return true;
+  const n = a.length;
+  const m = b.length;
+  let prev2: number[] = [];
+  let prev = Array.from({ length: m + 1 }, (_, j) => j);
+  for (let i = 1; i <= n; i++) {
+    const cur = [i];
+    let rowMin = i;
+    for (let j = 1; j <= m; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let v = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        v = Math.min(v, prev2[j - 2] + 1);
+      }
+      cur.push(v);
+      if (v < rowMin) rowMin = v;
+    }
+    if (rowMin > max) return false;
+    prev2 = prev;
+    prev = cur;
+  }
+  return prev[m] <= max;
+}
+
+type WordKind = keyof typeof WORD_SCORE;
+
+function matchWord(q: string, word: string, opts: Required<Pick<SearchIndexOptions, "typoMinLength" | "infixMinLength">>): WordKind | null {
+  if (word === q) return "exact";
+  if (word.startsWith(q)) return "prefix";
+  if (q.length >= opts.infixMinLength && word.includes(q)) return "infix";
+  if (q.length >= opts.typoMinLength) {
+    // The whole word, or the word's start as long as the query (a typo in a prefix:
+    // "calender" is one edit from "calendar", the start of "calendars").
+    if (withinDistance(q, word, 1)) return "typo";
+    if (word.length > q.length && withinDistance(q, word.slice(0, q.length), 1)) return "typo";
+  }
+  return null;
+}
+
+interface Prepared<E> {
+  entry: E;
+  title: string;
+  titleCompact: string;
+  fields: Array<[SearchMatchField, string[]]>;
+}
+
+/**
+ * Build an index over `entries`. Normalisation happens once here, so `search` is a scan
+ * over prepared words — a few thousand entries per keystroke is nothing.
+ */
+export function createSearchIndex<E extends SearchEntry>(
+  entries: readonly E[],
+  options: SearchIndexOptions = {},
+): SearchIndex<E> {
+  const { groupLimit = 8, limit = Infinity, typoMinLength = 5, infixMinLength = 4 } = options;
+  const wordOpts = { typoMinLength, infixMinLength };
+  const prepared: Prepared<E>[] = entries.map((entry) => {
+    const title = normalizeSearchText(entry.title);
+    return {
+      entry,
+      title,
+      titleCompact: title.replace(/ /g, ""),
+      fields: [
+        ["title", words(entry.title)],
+        ["keywords", (entry.keywords ?? []).flatMap(words)],
+        ["description", entry.description ? words(entry.description) : []],
+      ],
+    };
+  });
+
+  const search = (query: string): SearchHit<E>[] => {
+    const q = normalizeSearchText(query);
+    if (!q) return [];
+    const qWords = [...new Set(q.split(" "))];
+    const qCompact = q.replace(/ /g, "");
+    const hits: SearchHit<E>[] = [];
+
+    for (const p of prepared) {
+      let quality = 0;
+      let weakest: SearchMatchField = "title";
+      let ok = true;
+      for (const qw of qWords) {
+        let best = 0;
+        let bestField: SearchMatchField | null = null;
+        for (const [field, fieldWords] of p.fields) {
+          for (const w of fieldWords) {
+            const kind = matchWord(qw, w, wordOpts);
+            if (!kind) continue;
+            const s = WORD_SCORE[kind] * FIELD_FACTOR[field];
+            if (s > best) {
+              best = s;
+              bestField = field;
+            }
+          }
+        }
+        if (!bestField) {
+          ok = false;
+          break;
+        }
+        quality += best;
+        if (FIELD_FACTOR[bestField] < FIELD_FACTOR[weakest]) weakest = bestField;
+      }
+      if (!ok) continue;
+
+      let tier: number = TIERS[weakest];
+      if (p.title === q || p.titleCompact === qCompact) tier = TIERS.exact;
+      else if (
+        p.title.startsWith(q) ||
+        p.titleCompact.startsWith(qCompact) ||
+        // The whole title, mistyped once ("Tooltp") — as good as a prefix, not exact.
+        (qCompact.length >= typoMinLength && withinDistance(qCompact, p.titleCompact, 1))
+      ) {
+        tier = TIERS.prefix;
+      }
+      // Within a tier: how well the words matched (≤ 120 each, averaged so a long query
+      // cannot climb by word count), and how much of the title the query covers — so
+      // "Tooltip" beats "Popovers, menus & tooltips" for the same one-word match.
+      const coverage = Math.min(1, qCompact.length / Math.max(1, p.titleCompact.length)) * 40;
+      const score =
+        tier * SEARCH_TIER_POINTS +
+        Math.min(quality / qWords.length + coverage, SEARCH_TIER_POINTS / 2 - 1) +
+        (p.entry.weight ?? 0);
+      hits.push({ entry: p.entry, score, field: weakest });
+    }
+
+    hits.sort((a, b) => b.score - a.score || a.entry.title.localeCompare(b.entry.title));
+    return capByGroup(hits, groupLimit, limit);
+  };
+
+  return { search, entries };
+}
+
+function capByGroup<E extends SearchEntry>(hits: SearchHit<E>[], groupLimit: number, limit: number): SearchHit<E>[] {
+  const perGroup = new Map<string, number>();
+  const out: SearchHit<E>[] = [];
+  for (const hit of hits) {
+    if (out.length >= limit) break;
+    const g = hit.entry.group ?? "";
+    const n = perGroup.get(g) ?? 0;
+    if (n >= groupLimit) continue;
+    perGroup.set(g, n + 1);
+    out.push(hit);
+  }
+  return out;
+}
+
+/**
+ * One-shot form of {@link createSearchIndex}: the matching entries, best first. For a
+ * list that changes on every call (a server response, a store selector); build an index
+ * once when the entries are stable.
+ */
+export function matchEntries<E extends SearchEntry>(
+  entries: readonly E[],
+  query: string,
+  options?: SearchIndexOptions,
+): E[] {
+  return createSearchIndex(entries, options)
+    .search(query)
+    .map((hit) => hit.entry);
+}

package/src/search.ts

@@ -1,3 +1,5 @@
 // `@eifi1/ui-kit/search` — the command palette / global search.
 // A re-slicing of the main barrel, not a new API.
 export * from "./search/command-palette";
+export * from "./search/search-index";
+export * from "./search/global-search";

package/src/wizard/stepper-nav.tsx

@@ -42,6 +42,7 @@ export function StepperNav<TData extends Record<string, unknown>>({
   labels,
   finishVariant = "brand",
   finishDisabled = false,
+  doneDisabled = false,
   renderFinish,
 }: {
   wizard: UseWizardReturn<TData>;
@@ -56,6 +57,15 @@ export function StepperNav<TData extends Record<string, unknown>>({
   /** Disable Finish for a reason of the app's own, on top of the kit's gates
    *  (`canFinish`, submitting, validating). */
   finishDisabled?: boolean;
+  /**
+   * Disable Done — the button of the last step after a commit — while the step still
+   * has work of its own running. keksdose's YNAB import ends on a recurring step whose
+   * convert loop writes one rule at a time (ynab-import-panel.tsx): leaving mid-loop
+   * abandons the rest. Until now the panel dropped `onDone` for the duration, which
+   * takes the button away instead of saying "not yet": disabled, it stays where the
+   * eye left it and comes back to life when the loop ends.
+   */
+  doneDisabled?: boolean;
   /**
    * Wrap the Finish button: receives the kit's button element — already labelled,
    * gated and wired to `wizard.finish` — and returns what to render in its place.
@@ -97,7 +107,8 @@ export function StepperNav<TData extends Record<string, unknown>>({
   const pending = wizard.isValidating;
   const stepNextLabel = wizard.currentStep.nextLabel;
 
-  let forwardButton: ReactNode = null;
+  // Every branch below assigns it; no initial value to overwrite.
+  let forwardButton: ReactNode;
   if (wizard.isCommitStep) {
     const finishButton = (
       <Button
@@ -117,7 +128,7 @@ export function StepperNav<TData extends Record<string, unknown>>({
     // The last step after a commit. Nothing to finish; Done only when the app gave
     // an `onDone` — otherwise the step carries its own way out.
     forwardButton = wizard.canDone ? (
-      <Button variant="brand" data-tour="wizard-done" onClick={wizard.done}>
+      <Button variant="brand" data-tour="wizard-done" onClick={wizard.done} disabled={doneDisabled}>
         {stepNextLabel ?? l.done ?? DEFAULT_WIZARD_LABELS.done}
       </Button>
     ) : null;

package/src/wizard/types.ts

@@ -109,8 +109,8 @@ export interface UseWizardOptions<TData extends Record<string, unknown>> {
    */
   missingRequiredMessage?: string;
   /**
-   * How to surface {@link missingRequiredMessage}. Defaults to a `sonner` toast
-   * (an optional peer, imported only when this actually fires). Pass your own to
+   * How to surface {@link missingRequiredMessage}. Defaults to the kit's `toast.error`
+   * (sonner, an optional peer, is loaded only when a toast is shown). Pass your own to
    * route it somewhere else, or to a no-op to silence it.
    */
   onValidationFailed?: (message: string) => void;

package/src/wizard/use-wizard.ts

@@ -18,6 +18,7 @@ import { useCallback, useEffect, useReducer, useRef, useState } from "react";
 import { useSearchParams } from "react-router";
 import { useKitLabels } from "../i18n/kit-labels";
 import { DEFAULT_WIZARD_LABELS } from "./types";
+import { toast } from "../components/toast";
 import type {
   FieldErrors,
   StepStatus,
@@ -312,9 +313,8 @@ export function useWizard<TData extends Record<string, unknown>>(
         if (onValidationFailed) {
           onValidationFailed(message);
         } else {
-          // sonner is an optional peer: imported here, on the failure path only,
-          // so an app that never trips this never has to install it.
-          const { toast } = await import("sonner");
+          // The kit's `toast` loads sonner (an optional peer) lazily, so an app
+          // that never trips this never has to install it.
           toast.error(message);
         }
       }

package/src/wizard/wizard-summary.tsx

@@ -1,5 +1,6 @@
 import { Pencil } from "lucide-react";
 import { Card, CardAction, CardContent, CardHeader, CardTitle, IconButton } from "../components/ui";
+import { Tooltip } from "../components/tooltip";
 import type { SummarySection, WizardLabels } from "./types";
 import { DEFAULT_WIZARD_LABELS } from "./types";
 import { useKitLabels } from "../i18n/kit-labels";
@@ -44,16 +45,19 @@ export function WizardSummary({
             <CardTitle className="text-base">{section.label}</CardTitle>
             {section.stepIndex !== undefined && onEditStep && (
               <CardAction>
-                <IconButton
-                  size="sm"
-                  variant="ghost"
-                  aria-label={l.edit}
-                  title={l.edit}
-                  disabled={disabled}
-                  onClick={() => onEditStep(section.stepIndex as number)}
-                >
-                  <Pencil />
-                </IconButton>
+                {/* The kit Tooltip, not a native `title`: it shows on keyboard focus too,
+                    and an app with a one-tooltip rule (keksdose dev#523) sees one. */}
+                <Tooltip label={l.edit}>
+                  <IconButton
+                    size="sm"
+                    variant="ghost"
+                    aria-label={l.edit}
+                    disabled={disabled}
+                    onClick={() => onEditStep(section.stepIndex as number)}
+                  >
+                    <Pencil />
+                  </IconButton>
+                </Tooltip>
               </CardAction>
             )}
           </CardHeader>

package/tokens.css

@@ -233,6 +233,103 @@
   --success-bg: rgba(6, 78, 59, 0.25);
 }
 
+/* ── Toasts ─────────────────────────────────────────────────────────────────
+   The kit `<Toaster>` (components/toast.tsx) paints sonner with the AlertBanner
+   tones. These are ALIASES, not new colours, and they exist for one reason: sonner
+   declares its own `--success-bg` / `--success-border` (and info, warning) on the
+   toaster element, so that element cannot read the kit's value under the same name
+   — `--success-bg: var(--success-bg)` is a cycle. Declared here, they are computed
+   on `<html>` and inherited down under a name sonner does not touch.
+
+   The background is the tone's wash layered on the surface, as AlertBanner's
+   `elevated` frame does: the dark washes are translucent, and a toast floats over
+   content. `--z-toast` is above every kit overlay (modal and sheets z-50, tour
+   z-60/61, command palette z-70) and above whatever an app stacks on top of those —
+   a toast confirming a dialog's action must not land under the dialog. */
+:root,
+.dark {
+  --z-toast: 2147483647;
+  --toast-success-bg: linear-gradient(var(--success-bg), var(--success-bg)) var(--bg-surface);
+  --toast-success-border: var(--success-border);
+  --toast-info-bg: linear-gradient(var(--info-bg), var(--info-bg)) var(--bg-surface);
+  --toast-info-border: var(--info-border);
+  --toast-warning-bg: linear-gradient(var(--warning-bg), var(--warning-bg)) var(--bg-surface);
+  --toast-warning-border: var(--warning-border);
+  --toast-danger-bg: linear-gradient(var(--danger-bg), var(--danger-bg)) var(--bg-surface);
+  --toast-danger-border: var(--danger-border);
+}
+
+/* The description of an untoned toast in the secondary text colour (sonner hard-codes
+   #3f3f3f, unreadable in the dark theme); a toned toast's inherits its tone. */
+.kit-toaster [data-sonner-toast][data-styled="true"]:not([data-type="success"], [data-type="info"], [data-type="warning"], [data-type="error"]) [data-description] {
+  color: var(--text-secondary);
+}
+/* The action button in the tone's own colour rather than sonner's black pill. */
+.kit-toaster [data-sonner-toast][data-styled="true"] [data-button]:not([data-cancel]) {
+  background: var(--toast-action-bg, var(--text-primary));
+  color: var(--bg-surface);
+}
+.kit-toaster [data-sonner-toast][data-type="success"] { --toast-action-bg: var(--success); }
+.kit-toaster [data-sonner-toast][data-type="info"] { --toast-action-bg: var(--info); }
+.kit-toaster [data-sonner-toast][data-type="warning"] { --toast-action-bg: var(--warning); }
+.kit-toaster [data-sonner-toast][data-type="error"] { --toast-action-bg: var(--danger); }
+/* The kit's focus ring on the toast's buttons — sonner's is a black shadow that
+   vanishes on the dark theme. */
+.kit-toaster [data-sonner-toast][data-styled="true"] :is([data-button], [data-close-button]):focus-visible {
+  outline: 2px solid var(--brand);
+  outline-offset: 2px;
+}
+
+/* ── Categorical hues ───────────────────────────────────────────────────────
+   Colours that MEAN nothing but "this is a different value": kastlan's status
+   enums (status-badge.tsx over enum-meta.ts), where ~15 enums map to 9 Tailwind
+   hues. Four of those are semantic and already have tokens — green = --success,
+   yellow = --warning, red = --danger, gray = the neutral chip — so only the five
+   below are new: blue (open / sent / rented), purple (assigned / accepted),
+   orange (terminated / high urgency), teal (invoiced) and indigo (a meeting
+   stage). The smallest set that covers every enum; deliberately not a ramp.
+
+   Same triple and same shades as the status family (700 text / 300 border /
+   100 surface in light, 300 text / translucent 700 border / 900 wash in dark),
+   so a categorical chip sits beside a semantic one at the same weight. Not in
+   `TokenSet`: like `--danger`, a hue is a specific colour, not a tint of the
+   palette preset, so it lives here and nowhere else. */
+:root {
+  --hue-blue: #1d4ed8;            /* blue-700 */
+  --hue-blue-border: #93c5fd;     /* blue-300 */
+  --hue-blue-bg: #dbeafe;         /* blue-100 */
+  --hue-indigo: #4338ca;          /* indigo-700 */
+  --hue-indigo-border: #a5b4fc;   /* indigo-300 */
+  --hue-indigo-bg: #e0e7ff;       /* indigo-100 */
+  --hue-purple: #7e22ce;          /* purple-700 */
+  --hue-purple-border: #d8b4fe;   /* purple-300 */
+  --hue-purple-bg: #f3e8ff;       /* purple-100 */
+  --hue-teal: #0f766e;            /* teal-700 */
+  --hue-teal-border: #5eead4;     /* teal-300 */
+  --hue-teal-bg: #ccfbf1;         /* teal-100 */
+  --hue-orange: #c2410c;          /* orange-700 */
+  --hue-orange-border: #fdba74;   /* orange-300 */
+  --hue-orange-bg: #ffedd5;       /* orange-100 */
+}
+
+.dark {
+  --hue-blue: #93c5fd;            /* blue-300 */
+  --hue-blue-border: rgba(29, 78, 216, 0.6);
+  --hue-blue-bg: rgba(30, 58, 138, 0.25);
+  --hue-indigo: #a5b4fc;          /* indigo-300 */
+  --hue-indigo-border: rgba(67, 56, 202, 0.6);
+  --hue-indigo-bg: rgba(49, 46, 129, 0.25);
+  --hue-purple: #d8b4fe;          /* purple-300 */
+  --hue-purple-border: rgba(126, 34, 206, 0.6);
+  --hue-purple-bg: rgba(88, 28, 135, 0.25);
+  --hue-teal: #5eead4;            /* teal-300 */
+  --hue-teal-border: rgba(15, 118, 110, 0.6);
+  --hue-teal-bg: rgba(19, 78, 74, 0.25);
+  --hue-orange: #fdba74;          /* orange-300 */
+  --hue-orange-border: rgba(194, 65, 12, 0.6);
+  --hue-orange-bg: rgba(124, 45, 18, 0.25);
+}
+
 /* Semantic colour utilities backed by the tokens above. Unlayered so they win
    over Tailwind's layered colour utilities, and theme-aware for free (the var
    flips under .dark) — no dark: variant needed at the call site. */