@eifi1/ui-kit 0.4.0 → 0.5.0

package/src/search/command-palette.tsx

@@ -0,0 +1,342 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { ReactNode } from "react";
+import { createPortal } from "react-dom";
+import { Search } from "lucide-react";
+import { cn } from "../lib/cn";
+import { useOverlayHistory } from "../hooks/use-overlay-history";
+import { useKitLabels } from "../i18n/kit-labels";
+
+export interface CommandItem {
+  id: string;
+  /** Primary text. */
+  label: string;
+  /** Secondary text on the right (e.g. an amount, a date, a group hint). */
+  hint?: string;
+  /** Heading this item is grouped under. */
+  group: string;
+  /** Leading icon / element. */
+  icon?: ReactNode;
+  /** Invoked when the item is chosen (navigate, run an action, …). */
+  onSelect: () => void;
+  /** Where this item leads, when it is a navigation rather than an action. Renders
+   *  the row as a real anchor so it can be middle-/⌘-clicked into a new tab
+   *  (Keksdose feedback #451); `onSelect` still runs for a plain click and for ↵, so
+   *  in-app navigation stays client-side. `href` only adds what the browser can do
+   *  with a link and JavaScript cannot fake — the rejected alternative, an
+   *  `onAuxClick` calling `window.open`, gets the middle click and nothing else. */
+  href?: string;
+}
+
+export interface CommandPaletteLabels {
+  placeholder: string;
+  empty: string;
+  loading: string;
+  /** Hint shown in the footer, e.g. "↑↓ to navigate · ↵ to select · esc to close". */
+  hint?: string;
+  /**
+   * Accessible name of the dialog itself. It used to borrow `placeholder`, which is
+   * written to sit greyed-out in an empty box ("Search…", "Type a command"), not to
+   * name a window — and a reader heard the ellipsis read out as part of the name.
+   *
+   * Optional, unlike `placeholder`, so a translation annotated as
+   * `CommandPaletteLabels` keeps compiling; the default always carries it.
+   */
+  dialog?: string;
+}
+
+export const DEFAULT_COMMAND_PALETTE_LABELS: CommandPaletteLabels = {
+  placeholder: "Search…",
+  empty: "No results",
+  loading: "Searching…",
+  dialog: "Search",
+};
+
+/** The defaults minus `dialog`, so a resolved `dialog` means someone SUPPLIED one —
+ *  see the dialog's `aria-label` for why that distinction matters. */
+const { dialog: DEFAULT_DIALOG_NAME, ...DEFAULTS_WITHOUT_DIALOG } = DEFAULT_COMMAND_PALETTE_LABELS;
+
+interface CommandPaletteProps {
+  open: boolean;
+  onClose: () => void;
+  /**
+   * Returns results for a query (called debounced as the user types; an empty
+   * query is allowed — return defaults like pages/recent). Sync or async; stale
+   * async responses are ignored.
+   *
+   * Its IDENTITY is not a re-run signal — it is read through a ref, so the palette
+   * never re-searches merely because the caller rebuilt the callback. That is
+   * deliberate: a provider closing over a list rendered from a query allocates a new
+   * function on most renders, and re-running the search on each would make typing
+   * stutter. Use {@link CommandPaletteProps.revision} when the DATA behind the
+   * provider changes.
+   */
+  search: (query: string) => CommandItem[] | Promise<CommandItem[]>;
+  /**
+   * Anything whose change means the current results are out of date — typically the
+   * arrays the provider searches over. Compared by identity (as an effect dependency
+   * would be), so pass stable references: a `data = []` default allocates a fresh
+   * array on every render while a query is pending and would re-search forever.
+   *
+   * Without it, a provider whose data arrives AFTER the palette opened never gets
+   * asked again: the user's last keystroke settles the debounce, the queries resolve a
+   * moment later, and the groups they would have contributed are simply absent until
+   * another keystroke. That is the ordinary first open on a cold cache.
+   */
+  revision?: unknown;
+  labels?: Partial<CommandPaletteLabels>;
+}
+
+/** Registers a global ⌘K / Ctrl-K shortcut that calls `onOpen`. */
+export function useCommandKey(onOpen: () => void): void {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && (e.key === "k" || e.key === "K")) {
+        e.preventDefault();
+        onOpen();
+      }
+    };
+    document.addEventListener("keydown", handler);
+    return () => document.removeEventListener("keydown", handler);
+  }, [onOpen]);
+}
+
+/**
+ * A ⌘K-style command palette: a top-centred modal with a search field and a
+ * grouped, keyboard-navigable result list. Domain-free — the app supplies
+ * results via the `search` provider (pages, actions, records, …); each result
+ * carries its own `onSelect`.
+ */
+export function CommandPalette({
+  open,
+  onClose,
+  search,
+  revision,
+  labels,
+}: CommandPaletteProps) {
+  const l = useKitLabels("commandPalette", DEFAULTS_WITHOUT_DIALOG, labels);
+  // `dialog` is new, and until it existed the dialog was named by `placeholder`. An
+  // app that translated `placeholder` and has not heard of `dialog` would otherwise
+  // go from a German name to an English "Search" on update — so a translated
+  // placeholder keeps doing the job until a `dialog` is supplied.
+  const dialogName =
+    l.dialog ??
+    (l.placeholder !== DEFAULT_COMMAND_PALETTE_LABELS.placeholder ? l.placeholder : DEFAULT_DIALOG_NAME);
+  const [query, setQuery] = useState("");
+  const [results, setResults] = useState<CommandItem[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [active, setActive] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listRef = useRef<HTMLUListElement>(null);
+  const searchRef = useRef(search);
+  searchRef.current = search;
+  const reqId = useRef(0);
+
+  // Back dismisses the palette (Keksdose feedback #172). Declared with the other
+  // hooks, above the `if (!open) return null` below — a hook past a conditional
+  // return changes the hook order between renders. Passing `open` rather than
+  // mounting-while-open is what lets it sit here.
+  useOverlayHistory(open, onClose);
+
+  // Reset + focus when opened.
+  useEffect(() => {
+    if (!open) return;
+    setQuery("");
+    setActive(0);
+    const id = requestAnimationFrame(() => inputRef.current?.focus());
+    return () => cancelAnimationFrame(id);
+  }, [open]);
+
+  // Debounced, race-safe search.
+  useEffect(() => {
+    if (!open) return;
+    const id = ++reqId.current;
+    setLoading(true);
+    const run = async () => {
+      try {
+        const r = await Promise.resolve(searchRef.current(query));
+        if (reqId.current === id) {
+          setResults(r);
+          setActive(0);
+        }
+      } finally {
+        if (reqId.current === id) setLoading(false);
+      }
+    };
+    const t = setTimeout(run, query ? 150 : 0);
+    return () => clearTimeout(t);
+    // `revision`, not `search`: see the prop's docstring. The debounce is re-armed on a
+    // revision change, which is right — data arriving is not a keystroke and there is
+    // nothing to feel laggy about.
+  }, [query, open, revision]);
+
+  // Group results, preserving first-seen group order; keep a flat list for nav.
+  const { groups, flat } = useMemo(() => {
+    const order: string[] = [];
+    const byGroup = new Map<string, CommandItem[]>();
+    for (const item of results) {
+      if (!byGroup.has(item.group)) {
+        byGroup.set(item.group, []);
+        order.push(item.group);
+      }
+      byGroup.get(item.group)!.push(item);
+    }
+    return {
+      groups: order.map((g) => ({ group: g, items: byGroup.get(g)! })),
+      flat: order.flatMap((g) => byGroup.get(g)!),
+    };
+  }, [results]);
+
+  const choose = (item: CommandItem | undefined) => {
+    if (!item) return;
+    onClose();
+    item.onSelect();
+  };
+
+  const onKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      setActive((i) => Math.min(i + 1, flat.length - 1));
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setActive((i) => Math.max(i - 1, 0));
+    } else if (e.key === "Enter") {
+      e.preventDefault();
+      choose(flat[active]);
+    } else if (e.key === "Escape") {
+      e.preventDefault();
+      onClose();
+    }
+  };
+
+  // Keep the active row scrolled into view.
+  useEffect(() => {
+    const el = listRef.current?.querySelector<HTMLElement>(`[data-index="${active}"]`);
+    el?.scrollIntoView({ block: "nearest" });
+  }, [active]);
+
+  if (!open) return null;
+
+  let flatIndex = -1;
+  return createPortal(
+    <div
+      className="fixed inset-0 z-[70] flex items-start justify-center bg-black/40 p-4 pt-[10vh]"
+      onMouseDown={(e) => {
+        if (e.target === e.currentTarget) onClose();
+      }}
+    >
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label={dialogName}
+        className="flex max-h-[70vh] w-full max-w-xl flex-col overflow-hidden rounded-xl border border-[var(--border)] bg-[var(--bg-surface)] shadow-2xl"
+      >
+        <div className="flex items-center gap-2 border-b border-[var(--border)] px-3">
+          <Search className="size-4 shrink-0 text-[var(--text-placeholder)]" />
+          <input
+            ref={inputRef}
+            role="combobox"
+            aria-expanded
+            aria-controls="command-palette-list"
+            aria-activedescendant={flat[active] ? `command-item-${flat[active].id}` : undefined}
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            onKeyDown={onKeyDown}
+            placeholder={l.placeholder}
+            className="w-full bg-transparent py-3 text-sm outline-none placeholder:text-[var(--text-placeholder)] text-[var(--text-primary)]"
+          />
+          {loading && <span className="shrink-0 text-[11px] text-[var(--text-placeholder)]">{l.loading}</span>}
+        </div>
+
+        <ul id="command-palette-list" ref={listRef} role="listbox" className="min-h-0 flex-1 overflow-y-auto py-1">
+          {flat.length === 0 && !loading && (
+            <li className="px-3 py-6 text-center text-sm text-[var(--text-muted)]">{l.empty}</li>
+          )}
+          {groups.map(({ group, items }) => (
+            <li key={group}>
+              <div className="px-3 pb-0.5 pt-2 text-[10px] font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
+                {group}
+              </div>
+              <ul>
+                {items.map((item) => {
+                  flatIndex += 1;
+                  const idx = flatIndex;
+                  const isActive = idx === active;
+                  // Written once and worn by either tag below, so the anchor and the
+                  // button can never drift apart in looks or in listbox semantics.
+                  // `role="option"` on an <a href> is fine: the browser's middle-click
+                  // behaviour keys off the element, not the ARIA role.
+                  const shared = {
+                    id: `command-item-${item.id}`,
+                    role: "option" as const,
+                    "aria-selected": isActive,
+                    "data-index": idx,
+                    onMouseMove: () => setActive(idx),
+                    className: cn(
+                      "flex w-full items-center gap-2.5 px-3 py-2 text-left text-sm",
+                      isActive
+                        ? "bg-[var(--bg-active)] text-[var(--text-primary)]"
+                        : "text-[var(--text-secondary)]",
+                    ),
+                  };
+                  const inner = (
+                    <>
+                      {item.icon && (
+                        <span className="flex size-4 shrink-0 items-center justify-center text-[var(--text-placeholder)]">
+                          {item.icon}
+                        </span>
+                      )}
+                      <span className="min-w-0 flex-1 truncate">{item.label}</span>
+                      {item.hint && (
+                        <span className="shrink-0 text-xs text-[var(--text-placeholder)]">{item.hint}</span>
+                      )}
+                    </>
+                  );
+                  return (
+                    <li key={item.id}>
+                      {item.href ? (
+                        <a
+                          {...shared}
+                          href={item.href}
+                          draggable={false}
+                          onClick={(e) => {
+                            // A modified click belongs to the browser (feedback
+                            // #451) — and the palette deliberately stays OPEN for
+                            // it: ⌘-clicking three results in a row is the reason to
+                            // want this, and closing after the first would undo it.
+                            if (
+                              e.button !== 0 ||
+                              e.metaKey ||
+                              e.ctrlKey ||
+                              e.shiftKey ||
+                              e.altKey
+                            )
+                              return;
+                            e.preventDefault();
+                            choose(item);
+                          }}
+                        >
+                          {inner}
+                        </a>
+                      ) : (
+                        <button type="button" {...shared} onClick={() => choose(item)}>
+                          {inner}
+                        </button>
+                      )}
+                    </li>
+                  );
+                })}
+              </ul>
+            </li>
+          ))}
+        </ul>
+
+        {l.hint && (
+          <div className="border-t border-[var(--border)] px-3 py-1.5 text-[11px] text-[var(--text-placeholder)]">
+            {l.hint}
+          </div>
+        )}
+      </div>
+    </div>,
+    document.body,
+  );
+}

package/src/search.ts

@@ -0,0 +1,3 @@
+// `@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";