makersclaw 0.1.0 → 0.3.0

package/templates/next/files/components/ui/command.jsx

@@ -0,0 +1,577 @@
+"use client";
+
+import { isValidElement, useCallback, useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { cx } from "./cx";
+import { Icon } from "./icon";
+import { KbdGroup } from "./separator";
+import { Spinner } from "./feedback";
+import { Sheet } from "./sheet";
+
+// Command — a searchable list of actions: type to narrow, arrows to move,
+// Enter to run. The inline list of a "jump to…" panel, and (CommandDialog)
+// the ⌘K palette. No command package: the list is plain data, the filter
+// is commandScore below, and the ARIA is the combobox + listbox pattern —
+// focus stays in the input, aria-activedescendant names the active option,
+// so a screen reader follows the highlight while the caret stays put.
+//
+//   items        [{ value?, label, description?, icon?, shortcut?, keywords?,
+//                group?, disabled?, onSelect? }] — `value` defaults to the
+//                label and must be unique; `icon` a glyph name from ./icon or
+//                a node (an Avatar); `shortcut` "⌘N" or ["⌘", "N"] (a hint
+//                only, shown from md up: bind the key yourself); `keywords`
+//                are matched but never shown; `group` is the heading items
+//                sit under, in the order groups first appear
+//   onSelect     (item) — after the item's own onSelect
+//   label        what a screen reader calls the input and the list
+//   placeholder  the input's; empty — shown when nothing matches (a string
+//                or a node)
+//   query, defaultQuery, onQueryChange(query) — the typed text,
+//                controlled or not
+//   onSearch     async (query, { signal }) → items: results come from you
+//                (a server search), debounced; the spinner shows while it
+//                runs, a stale answer is dropped. `items` show until the
+//                first answer
+//   loading      true while you fetch `items` yourself
+//   filter       false when `items` arrive already filtered
+//   autoFocus    focus the input on mount
+//
+// Keys: ↑ ↓ move (disabled items are skipped), Home · End jump to the
+// first · last, PageUp · PageDown by eight, Enter runs the active item. The
+// first match is always active, so typing then Enter runs the best hit.
+//
+// CommandDialog — the same list in the kit's Sheet (center; a bottom sheet
+// on a phone). `open` + `onOpenChange` or uncontrolled; `hotkey="k"` binds
+// ⌘K / Ctrl+K to open and close it. Running an item closes it.
+//
+// commandScore(text, query) → 0…1 (0 = no match) and commandFilter(items,
+// query) → the matching items, best first within their group, are exported
+// for the parts built on this (Combobox) and for a list of your own.
+//
+// The one rule: the list is data. Never map items into your own markup —
+// the ids, roles and keys here are what make it work for everyone.
+
+// ─── matching ──────────────────────────────────────────────────────────
+
+const fold = (s) =>
+  String(s ?? "")
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase();
+
+const BOUNDARY = /[\s\-_/.,:;()@&+]/;
+
+/**
+ * How well `text` matches `query`, 0 (not at all) to 1 (exactly). Accents
+ * and case are ignored. Best to worst: equal, a prefix, a substring at a
+ * word start, a substring inside a word, then the query's letters in order
+ * ("nyc" in "New York City"), scored by how many land on word starts.
+ */
+export function commandScore(text, query) {
+  const t = fold(text);
+  const q = fold(query).trim();
+  if (!q) return 1;
+  if (!t) return 0;
+  if (t === q) return 1;
+  if (t.startsWith(q)) return 0.9;
+  const at = t.indexOf(q);
+  if (at > 0) return (BOUNDARY.test(t[at - 1]) ? 0.8 : 0.6) - Math.min(at, 40) * 0.002;
+  // The letters in order.
+  let from = 0;
+  let prev = -2;
+  let points = 0;
+  let count = 0;
+  for (const ch of q) {
+    if (ch === " ") continue;
+    const found = t.indexOf(ch, from);
+    if (found < 0) return 0;
+    points += found === 0 || BOUNDARY.test(t[found - 1]) ? 1 : found === prev + 1 ? 0.6 : 0.2;
+    count++;
+    prev = found;
+    from = found + 1;
+  }
+  return 0.1 + 0.3 * (points / count);
+}
+
+// An item's best field: the label counts most, keywords nearly as much,
+// the description least.
+function scoreItem(item, q) {
+  const best = (query) =>
+    Math.max(
+      commandScore(item.label, query),
+      ...(item.keywords ?? []).map((k) => commandScore(k, query) * 0.95),
+      item.description && typeof item.description === "string" ? commandScore(item.description, query) * 0.7 : 0,
+    );
+  const whole = best(q);
+  if (whole > 0) return whole;
+  // Words in any order ("lovelace ada"): every word must match somewhere.
+  const words = fold(q).split(/\s+/).filter(Boolean);
+  if (words.length < 2) return 0;
+  let sum = 0;
+  for (const w of words) {
+    const s = best(w);
+    if (!s) return 0;
+    sum += s;
+  }
+  return (sum / words.length) * 0.9;
+}
+
+/** Every item with a `value` (the label when it has none). */
+export function withValues(items) {
+  return (items ?? []).filter(Boolean).map((it) => (it.value === undefined ? { ...it, value: String(it.label) } : { ...it, value: String(it.value) }));
+}
+
+/**
+ * The items that match `query`, best first within their group; the groups
+ * keep the order they first appear in. An empty query returns them all,
+ * in order.
+ */
+export function commandFilter(items, query) {
+  const all = withValues(items);
+  if (!fold(query).trim()) return all;
+  const order = [];
+  const byGroup = new Map();
+  all.forEach((item, i) => {
+    const score = scoreItem(item, query);
+    if (!score) return;
+    const g = item.group ?? "";
+    if (!byGroup.has(g)) {
+      byGroup.set(g, []);
+      order.push(g);
+    }
+    byGroup.get(g).push({ item, score, i });
+  });
+  return order.flatMap((g) => byGroup.get(g).sort((a, b) => b.score - a.score || a.i - b.i).map((x) => x.item));
+}
+
+// ─── pieces shared with Combobox ───────────────────────────────────────
+
+/** The option's DOM id: stable for a list id and an index. */
+export const optionId = (listId, i) => `${listId}-o${i}`;
+
+/** The active value as the list shows it: the asked one while it is
+ *  visible and enabled, else the first enabled item. */
+export function resolveActive(items, active) {
+  if (active != null && items.some((it) => it.value === active && !it.disabled)) return active;
+  return items.find((it) => !it.disabled)?.value ?? null;
+}
+
+/**
+ * The list keys. Returns true (and prevents the default) when it handled
+ * the key: ↑ ↓ Home End PageUp PageDown move, Enter picks.
+ */
+export function listKeyDown(e, items, active, setActive, onPick) {
+  const live = items.filter((it) => !it.disabled);
+  if (!live.length) return false;
+  const i = live.findIndex((it) => it.value === active);
+  const last = live.length - 1;
+  let next;
+  switch (e.key) {
+    case "ArrowDown":
+      next = i < 0 ? 0 : Math.min(i + 1, last);
+      break;
+    case "ArrowUp":
+      next = i < 0 ? last : Math.max(i - 1, 0);
+      break;
+    case "Home":
+      next = 0;
+      break;
+    case "End":
+      next = last;
+      break;
+    case "PageDown":
+      next = Math.min((i < 0 ? 0 : i) + 8, last);
+      break;
+    case "PageUp":
+      next = Math.max((i < 0 ? 0 : i) - 8, 0);
+      break;
+    case "Enter":
+      // An IME composing a word owns Enter.
+      if (i < 0 || e.nativeEvent?.isComposing) return false;
+      e.preventDefault();
+      onPick(live[i]);
+      return true;
+    default:
+      return false;
+  }
+  e.preventDefault();
+  setActive(live[next].value);
+  return true;
+}
+
+/**
+ * Results from an async `onSearch(query, { signal })`, debounced by
+ * `delay` ms (none for the empty query). A newer query aborts the older
+ * one; a failed search keeps the last results and sets `error`.
+ */
+export function useAsyncSearch(onSearch, query, { enabled = true, delay = 200 } = {}) {
+  const fn = useRef(onSearch);
+  fn.current = onSearch;
+  const has = Boolean(onSearch);
+  const [state, setState] = useState({ items: null, loading: false, error: null });
+  useEffect(() => {
+    if (!has || !enabled) return;
+    const ctl = new AbortController();
+    setState((s) => (s.loading ? s : { ...s, loading: true }));
+    const timer = setTimeout(async () => {
+      try {
+        const items = await fn.current(query, { signal: ctl.signal });
+        if (!ctl.signal.aborted) setState({ items: items ?? [], loading: false, error: null });
+      } catch (error) {
+        if (!ctl.signal.aborted) setState((s) => ({ items: s.items ?? [], loading: false, error }));
+      }
+    }, query.trim() ? delay : 0);
+    return () => {
+      clearTimeout(timer);
+      ctl.abort();
+    };
+  }, [has, enabled, query, delay]);
+  return state;
+}
+
+const PHONE = "(max-width: 639.98px)";
+const subscribePhone = (cb) => {
+  const m = window.matchMedia(PHONE);
+  m.addEventListener("change", cb);
+  return () => m.removeEventListener("change", cb);
+};
+/** True under the kit's `sm` breakpoint (640px), where Sheet turns every
+ *  overlay into a bottom sheet. False on the server. */
+export function useIsPhone() {
+  return useSyncExternalStore(
+    subscribePhone,
+    () => window.matchMedia(PHONE).matches,
+    () => false,
+  );
+}
+
+/** An item's icon: a glyph name, or a node (an Avatar) as it is. */
+export function ItemIcon({ icon, className }) {
+  if (!icon) return null;
+  if (typeof icon === "string") return <Icon name={icon} className={cx("shrink-0 text-muted-foreground", className)} />;
+  return isValidElement(icon) ? <span className={cx("flex shrink-0 items-center", className)}>{icon}</span> : null;
+}
+/**
+ * The search bar at the top of a Command or a Combobox panel: a glyph, the
+ * input (role=combobox, pointing at `listId`), a spinner while `busy`.
+ * Every other prop goes to the <input>.
+ */
+export function CommandInput({ listId, activeId, busy, inputRef, className, ...rest }) {
+  return (
+    <div className={cx("flex items-center gap-2 border-b border-border px-3", className)}>
+      <Icon name="search" className="shrink-0 text-muted-foreground" />
+      <input
+        ref={inputRef}
+        type="text"
+        role="combobox"
+        aria-expanded="true"
+        aria-controls={listId}
+        aria-activedescendant={activeId ?? undefined}
+        aria-autocomplete="list"
+        autoComplete="off"
+        autoCorrect="off"
+        spellCheck={false}
+        // 16px on a phone, or iOS zooms the page when it takes focus.
+        className="min-h-11 min-w-0 flex-1 bg-transparent py-2 text-base text-foreground outline-none placeholder:text-muted-foreground sm:text-sm"
+        {...rest}
+      />
+      {busy ? <Spinner size="sm" label="Searching" className="text-muted-foreground" /> : null}
+    </div>
+  );
+}
+
+/**
+ * The listbox: groups under their headings, options with icon, label,
+ * description and shortcut; the empty, loading and error lines around it.
+ *
+ *   id, label      the listbox's id and name
+ *   items          already filtered, in the order shown
+ *   active         the active value; onActive(value) on hover
+ *   onPick(item)   click, or Enter through listKeyDown
+ *   selected       a Set of chosen values (a Combobox): each option shows a
+ *                  check (`multiple`: a box at the start) and aria-selected
+ *                  says chosen; without it aria-selected marks the active
+ *   className      the scroll box's; its max height (default max-h-72)
+ *   focusable      the listbox takes focus itself (aria-activedescendant on
+ *                  it, `onKeyDown` for the keys) — when there is no input
+ */
+export function CommandList({
+  id,
+  label,
+  items,
+  active,
+  onActive,
+  onPick,
+  selected,
+  multiple = false,
+  empty = "No results.",
+  loading = false,
+  error,
+  focusable = false,
+  onKeyDown,
+  listRef,
+  className,
+}) {
+  const box = useRef(null);
+  const activeIndex = items.findIndex((it) => it.value === active);
+
+  // Keep the active option in view as the keys move it.
+  useEffect(() => {
+    if (activeIndex < 0) return;
+    document.getElementById(optionId(id, activeIndex))?.scrollIntoView({ block: "nearest" });
+  }, [id, activeIndex]);
+
+  // Consecutive items with one group share a heading.
+  const sections = [];
+  items.forEach((item, i) => {
+    const g = item.group ?? "";
+    const tail = sections[sections.length - 1];
+    if (tail && tail.group === g) tail.rows.push([item, i]);
+    else sections.push({ group: g, rows: [[item, i]] });
+  });
+
+  function option([item, i]) {
+    const isActive = item.value === active;
+    const chosen = selected ? selected.has(item.value) : false;
+    const keys = item.shortcut ? (Array.isArray(item.shortcut) ? item.shortcut : [item.shortcut]) : null;
+    return (
+      <div
+        key={item.value}
+        id={optionId(id, i)}
+        role="option"
+        aria-selected={selected ? chosen : isActive}
+        aria-disabled={item.disabled || undefined}
+        data-active={isActive || undefined}
+        // The input keeps focus; a press on an option must not take it.
+        onMouseDown={(e) => e.preventDefault()}
+        onMouseMove={() => {
+          if (!item.disabled && !isActive) onActive?.(item.value);
+        }}
+        onClick={() => {
+          if (!item.disabled) onPick?.(item);
+        }}
+        className={cx(
+          "flex min-h-11 cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm text-popover-foreground md:min-h-9",
+          "data-[active]:bg-accent data-[active]:text-accent-foreground",
+          "aria-disabled:cursor-not-allowed aria-disabled:opacity-50",
+        )}
+      >
+        {selected && multiple ? (
+          <span
+            aria-hidden="true"
+            className={cx(
+              "grid size-4 shrink-0 place-items-center rounded-sm border",
+              chosen ? "border-primary bg-primary text-primary-foreground" : "border-input bg-background",
+            )}
+          >
+            {chosen ? <Icon name="check" size={12} /> : null}
+          </span>
+        ) : null}
+        <ItemIcon icon={item.icon} />
+        <span className="min-w-0 flex-1">
+          <span className="block truncate">{item.label}</span>
+          {item.description ? <span className="block truncate text-xs text-muted-foreground">{item.description}</span> : null}
+        </span>
+        {keys ? (
+          <span className="hidden shrink-0 md:inline-flex" aria-hidden="true">
+            <KbdGroup keys={keys} />
+          </span>
+        ) : null}
+        {selected && !multiple ? (
+          <Icon name="check" className={cx("shrink-0 text-foreground", !chosen && "invisible")} />
+        ) : null}
+      </div>
+    );
+  }
+
+  const status = error ? "Search failed. Try again." : loading ? null : items.length === 0 ? empty : null;
+
+  return (
+    <div className={cx("overflow-y-auto overscroll-contain", className ?? "max-h-72")}>
+      {loading && items.length === 0 ? (
+        <div role="status" className="flex items-center justify-center gap-2 px-3 py-6 text-sm text-muted-foreground">
+          <Spinner size="sm" label={null} />
+          Searching…
+        </div>
+      ) : null}
+      {status && !(loading && items.length === 0) ? (
+        <div role="status" className="px-3 py-6 text-center text-sm text-muted-foreground">
+          {status}
+        </div>
+      ) : null}
+      <div
+        ref={(el) => {
+          box.current = el;
+          if (listRef) listRef.current = el;
+        }}
+        id={id}
+        role="listbox"
+        aria-label={label}
+        aria-multiselectable={multiple || undefined}
+        tabIndex={focusable ? 0 : undefined}
+        aria-activedescendant={focusable && activeIndex >= 0 ? optionId(id, activeIndex) : undefined}
+        onKeyDown={onKeyDown}
+        className={cx("scroll-py-1 outline-none", items.length ? "p-1" : "hidden")}
+      >
+        {sections.map((s, n) =>
+          s.group ? (
+            <div
+              key={`${s.group}-${n}`}
+              role="group"
+              aria-labelledby={`${id}-g${n}`}
+              className={cx(n > 0 && "mt-1 border-t border-border pt-1")}
+            >
+              <div id={`${id}-g${n}`} className="px-2 pb-1 pt-1.5 text-xs font-medium text-muted-foreground">
+                {s.group}
+              </div>
+              {s.rows.map(option)}
+            </div>
+          ) : (
+            <div key={`-${n}`} role="presentation" className={cx(n > 0 && "mt-1 border-t border-border pt-1")}>
+              {s.rows.map(option)}
+            </div>
+          ),
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ─── Command ───────────────────────────────────────────────────────────
+
+export function Command({
+  items,
+  onSelect,
+  label = "Commands",
+  placeholder = "Type a command or search…",
+  empty = "No results.",
+  query,
+  defaultQuery = "",
+  onQueryChange,
+  onSearch,
+  loading = false,
+  filter = true,
+  autoFocus = false,
+  className,
+  listClassName,
+  bare = false,
+}) {
+  const listId = `${useId().replace(/[^\w-]/g, "")}-list`;
+  const input = useRef(null);
+  const [own, setOwn] = useState(defaultQuery);
+  const text = query ?? own;
+  const [active, setActive] = useState(null);
+  const search = useAsyncSearch(onSearch, text);
+
+  const source = onSearch ? search.items ?? items : items;
+  const visible = useMemo(
+    () => (filter && !onSearch ? commandFilter(source, text) : withValues(source)),
+    [source, text, filter, onSearch],
+  );
+  const current = resolveActive(visible, active);
+  const activeIndex = visible.findIndex((it) => it.value === current);
+
+  useEffect(() => {
+    if (autoFocus) input.current?.focus({ preventScroll: true });
+  }, [autoFocus]);
+
+  function setText(v) {
+    if (query === undefined) setOwn(v);
+    onQueryChange?.(v);
+    // A new query starts from its best match.
+    setActive(null);
+  }
+
+  function pick(item) {
+    item.onSelect?.(item);
+    onSelect?.(item);
+  }
+
+  const busy = loading || search.loading;
+
+  return (
+    <div
+      className={cx(
+        "flex min-w-0 flex-col overflow-hidden bg-popover text-popover-foreground",
+        !bare && "rounded-md border border-border has-[input:focus-visible]:ring-2 has-[input:focus-visible]:ring-ring",
+        className,
+      )}
+    >
+      <CommandInput
+        inputRef={input}
+        listId={listId}
+        activeId={activeIndex >= 0 ? optionId(listId, activeIndex) : null}
+        busy={busy && visible.length > 0}
+        aria-label={label}
+        placeholder={placeholder}
+        value={text}
+        onChange={(e) => setText(e.target.value)}
+        onKeyDown={(e) => listKeyDown(e, visible, current, setActive, pick)}
+      />
+      <CommandList
+        id={listId}
+        label={label}
+        items={visible}
+        active={current}
+        onActive={setActive}
+        onPick={pick}
+        empty={empty}
+        loading={busy}
+        error={search.error}
+        className={listClassName ?? "max-h-80"}
+      />
+    </div>
+  );
+}
+
+export function CommandDialog({ open, defaultOpen = false, onOpenChange, hotkey, label = "Command menu", onSelect, className, ...command }) {
+  const controlled = open !== undefined;
+  const [own, setOwn] = useState(defaultOpen);
+  const isOpen = controlled ? open : own;
+  const openRef = useRef(isOpen);
+  openRef.current = isOpen;
+
+  const change = useCallback(
+    (next) => {
+      if (next === openRef.current) return;
+      openRef.current = next;
+      if (!controlled) setOwn(next);
+      onOpenChange?.(next);
+    },
+    [controlled, onOpenChange],
+  );
+  const changeRef = useRef(change);
+  changeRef.current = change;
+
+  // ⌘K / Ctrl+K opens it, and closes it again.
+  useEffect(() => {
+    if (!hotkey) return;
+    function onKey(e) {
+      if (e.key?.toLowerCase() !== String(hotkey).toLowerCase() || !(e.metaKey || e.ctrlKey) || e.altKey || e.shiftKey) return;
+      e.preventDefault();
+      changeRef.current(!openRef.current);
+    }
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [hotkey]);
+
+  // A bare Sheet: no header (Esc and a press outside close it), a flush
+  // body so the input sits at the top edge, the dialog named by `label`.
+  return (
+    <Sheet bare label={label} open={isOpen} onClose={() => change(false)} side="center" className={cx("sm:mt-[12dvh]", className)}>
+      {/* Mounted only while open, so each opening starts empty. */}
+      {isOpen ? (
+        <Command
+          bare
+          label={label}
+          autoFocus={isOpen}
+          listClassName="max-h-[min(24rem,60dvh)]"
+          onSelect={(item) => {
+            change(false);
+            onSelect?.(item);
+          }}
+          {...command}
+        />
+      ) : null}
+    </Sheet>
+  );
+}