makersclaw 0.2.0 → 0.3.0

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

@@ -0,0 +1,608 @@
+"use client";
+
+import { useEffect, useId, useMemo, useRef, useState } from "react";
+import { cx } from "./cx";
+import { Icon } from "./icon";
+import { Button } from "./button";
+import { Sheet } from "./sheet";
+import { panelClass, usePopoverPosition } from "./popover";
+import {
+  CommandInput,
+  CommandList,
+  ItemIcon,
+  commandFilter,
+  listKeyDown,
+  optionId,
+  resolveActive,
+  useAsyncSearch,
+  useIsPhone,
+  withValues,
+} from "./command";
+
+// Combobox — pick one or many from a list you can search: a person, a
+// company, a country, tags. A field-shaped trigger shows the choice; the
+// panel beside it holds a search input and the options — Command's list and
+// filter (./command), so the keys and the matching are the same everywhere.
+// With `searchable={false}` it is the rich Select: the same trigger and
+// options (icons, descriptions, groups) with no input, for a short list the
+// native <select> cannot draw.
+//
+//   options        [{ value, label, description?, icon?, group?, keywords?,
+//                  count?, disabled? }] — `icon` a glyph name or a node (an
+//                  Avatar); `count` a number or short text at the option's
+//                  right, muted ("15" beside a facet's value)
+//   value, defaultValue, onValueChange(value, option) — a value (null for
+//                  none), or with `multiple` an array of values (and the
+//                  options chosen)
+//   multiple       chips in the trigger, each with a remove button; the
+//                  panel stays open while you pick; Backspace in an empty
+//                  search (or on the trigger) removes the last
+//   searchable     true (default): a search input in the panel · false: the
+//                  rich Select — focus stays on the trigger, arrows move,
+//                  typing a letter jumps to the next option starting with it
+//   creatable      offer `Create "typed"` when nothing matches exactly; true,
+//                  or (text) => its label. onCreate(text) may return (or
+//                  resolve) the new option; else it is { value: text, label: text }
+//   onSearch       async (query, { signal }) → options, debounced; the list
+//                  shows what it answers (a spinner meanwhile). A chosen
+//                  option stays named after the results move on
+//   loading        true while you fetch `options` yourself
+//   clearable      an × that empties the choice
+//   disabled, invalid, name (hidden inputs, so a <form> posts the value)
+//   placeholder, searchPlaceholder, empty (shown when nothing matches)
+//   open, defaultOpen, onOpenChange(open) — the panel's state, controlled
+//                  or not (default closed); light dismiss, Escape and a
+//                  pick that closes report onOpenChange(false)
+//   label          the name when it is not in a <Field> (a Field's label
+//                  names it through `id`, and titles the phone sheet)
+//   side, align    the panel's place, as Popover (default bottom · start);
+//                  it is the trigger's width, 14rem at the least
+//   mobile         sheet (default) · popover — on a phone (under 640px) the
+//                  panel opens as a bottom Sheet: a popover under a field
+//                  there is squeezed by the on-screen keyboard and half
+//                  hidden; a sheet is the full width, within thumb reach,
+//                  and its search sits above the keyboard. Multiple adds a
+//                  Done button to it
+//
+// Every prop not named goes to the trigger button (aria-describedby for a
+// Field's hint, onBlur…). In a Field, pass the same `id`:
+//
+//   <Field id="owner" label="Owner"><Combobox id="owner" options={people} /></Field>
+//
+// ARIA: the trigger is role=combobox (its text is the value, the Field's
+// label its name); the search input inside is a combobox too, pointing at
+// the listbox with aria-activedescendant. Without a search, the trigger
+// itself carries aria-activedescendant — the APG "select-only combobox".
+
+const CREATE = "\u0000create";
+const same = (a, b) => String(a).trim().toLowerCase() === String(b).trim().toLowerCase();
+
+export function Combobox({
+  id,
+  options,
+  value,
+  defaultValue,
+  onValueChange,
+  multiple = false,
+  searchable = true,
+  creatable = false,
+  onCreate,
+  onSearch,
+  loading = false,
+  clearable = false,
+  disabled = false,
+  invalid = false,
+  name,
+  placeholder = "Select…",
+  searchPlaceholder = "Search…",
+  empty = "No results.",
+  label,
+  side = "bottom",
+  align = "start",
+  mobile = "sheet",
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  className,
+  onKeyDown,
+  onKeyUp,
+  onBlur,
+  ...rest
+}) {
+  const uid = useId().replace(/[^\w-]/g, "");
+  const panelId = `${uid}-panel`;
+  const listId = `${uid}-list`;
+  const wrap = useRef(null);
+  const btn = useRef(null);
+  const panel = useRef(null);
+  const input = useRef(null);
+  const list = useRef(null);
+  const sheetBody = useRef(null);
+  const phone = useIsPhone() && mobile === "sheet";
+
+  const [isOpen, setIsOpen] = useState(false);
+  const lastOpen = useRef(false);
+  // Every change of the panel's state passes here, so onOpenChange hears
+  // each one once, whoever made it (the trigger, a pick, light dismiss).
+  const setOpen = (now) => {
+    setIsOpen(now);
+    if (now !== lastOpen.current) {
+      lastOpen.current = now;
+      onOpenChange?.(now);
+    }
+  };
+  const [query, setQuery] = useState("");
+  const [active, setActive] = useState(null);
+  const [title, setTitle] = useState(label ?? placeholder);
+  const [width, setWidth] = useState(0);
+  const [created, setCreated] = useState([]);
+  const seed = useRef("");
+  const wasOpen = useRef(false);
+  const swallowSpace = useRef(false);
+  const typed = useRef({ text: "", at: 0 });
+
+  // The choice, as an array of string values either way.
+  const controlled = value !== undefined;
+  const [own, setOwn] = useState(defaultValue ?? (multiple ? [] : null));
+  const raw = controlled ? value : own;
+  const chosen = multiple ? (Array.isArray(raw) ? raw.map(String) : []) : raw == null || raw === "" ? [] : [String(raw)];
+  const key = chosen.join("\u0001");
+  const chosenSet = useMemo(() => new Set(key ? key.split("\u0001") : []), [key]);
+
+  // Every option seen, so a chosen one keeps its label (and icon) after a
+  // search replaced the list it came from.
+  const known = useRef(new Map());
+  const search = useAsyncSearch(onSearch, query, { enabled: isOpen });
+  const base = withValues(onSearch ? search.items ?? options : options);
+  const source = [...base, ...created.filter((c) => !base.some((o) => o.value === c.value))];
+  for (const o of source) known.current.set(o.value, o);
+  const optionOf = (v) => known.current.get(v) ?? { value: v, label: v };
+
+  let visible = searchable && !onSearch ? commandFilter(source, query) : source;
+  const text = query.trim();
+  if (creatable && text && !source.some((o) => same(o.label, text))) {
+    visible = [
+      ...visible,
+      { value: CREATE, label: typeof creatable === "function" ? creatable(text) : `Create "${text}"`, icon: "plus", create: true },
+    ];
+  }
+  const current = resolveActive(visible, active);
+  const activeIndex = visible.findIndex((o) => o.value === current);
+  const activeId = activeIndex >= 0 ? optionId(listId, activeIndex) : null;
+  const busy = loading || search.loading;
+  // The list draws a count at an option's right inside its label: the
+  // filter, the typeahead and the chips keep reading the plain label.
+  const shown = visible.some((o) => o.count != null && o.count !== "")
+    ? visible.map((o) =>
+        o.count == null || o.count === ""
+          ? o
+          : {
+              ...o,
+              label: (
+                <span className="flex items-center gap-2">
+                  <span className="min-w-0 flex-1 truncate">{o.label}</span>
+                  <span className="sr-only">, </span>
+                  <span className="shrink-0 text-xs tabular-nums text-muted-foreground">{o.count}</span>
+                </span>
+              ),
+            },
+      )
+    : visible;
+
+  usePopoverPosition(wrap, panel, { side, align });
+
+  // The panel is the trigger's width, kept as the field resizes.
+  useEffect(() => {
+    const el = wrap.current;
+    if (!el) return;
+    const ro = new ResizeObserver(() => setWidth(el.offsetWidth));
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  // `open` drives the panel; `defaultOpen` opens it once, on mount.
+  const want = open ?? null;
+  useEffect(() => {
+    if (want === null) return;
+    if (want && !lastOpen.current) show();
+    else if (!want && lastOpen.current) hide();
+  }, [want]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    if (defaultOpen && open === undefined) show();
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Focus into the panel once it shows: the search, or (a phone sheet with
+  // no search) the list itself.
+  useEffect(() => {
+    if (!isOpen) return;
+    if (searchable) input.current?.focus({ preventScroll: true });
+    else if (phone) list.current?.focus({ preventScroll: true });
+  }, [isOpen, searchable, phone]);
+
+  // ─── open and close ────────────────────────────────────────────────
+
+  function fieldLabel() {
+    if (!id || typeof document === "undefined") return null;
+    const el = document.querySelector(`label[for="${CSS.escape(id)}"]`);
+    return el?.textContent?.replace(/\s*\*$/, "").trim() || null;
+  }
+
+  // Every opening starts here: the typed seed (or nothing), the choice
+  // active, the title read from the Field.
+  function begin() {
+    setQuery(searchable ? seed.current : "");
+    seed.current = "";
+    setActive(chosen[0] ?? null);
+    setTitle(label ?? fieldLabel() ?? placeholder);
+  }
+
+  function show() {
+    if (disabled) return;
+    // Read the width live: a `defaultOpen` shows from the first effect,
+    // before the hydrated render has learnt it is on a phone.
+    if (phone || (mobile === "sheet" && window.matchMedia("(max-width: 639.98px)").matches)) {
+      begin();
+      setOpen(true);
+    } else if (!panel.current?.matches(":popover-open")) {
+      panel.current?.showPopover();
+    }
+  }
+
+  function hide() {
+    if (phone) {
+      // Close the <dialog> itself: it hands focus back to the trigger.
+      const dialog = sheetBody.current?.closest("dialog");
+      if (dialog?.open) dialog.close();
+      else setOpen(false);
+    } else if (panel.current?.matches(":popover-open")) {
+      panel.current.hidePopover();
+    }
+  }
+
+  // The popover's own opens and closes (the trigger, light dismiss, Esc).
+  function onToggle(e) {
+    const now = e.newState === "open";
+    if (now) begin();
+    else {
+      const at = document.activeElement;
+      if (!at || at === document.body || panel.current?.contains(at)) btn.current?.focus({ preventScroll: true });
+    }
+    setOpen(now);
+  }
+
+  // ─── choosing ──────────────────────────────────────────────────────
+
+  function commit(next) {
+    if (multiple) {
+      if (!controlled) setOwn(next);
+      onValueChange?.(next, next.map(optionOf));
+    } else {
+      const v = next[0] ?? null;
+      if (!controlled) setOwn(v);
+      onValueChange?.(v, v == null ? null : optionOf(v));
+    }
+  }
+
+  function choose(v) {
+    if (multiple) {
+      commit(chosenSet.has(v) ? chosen.filter((x) => x !== v) : [...chosen, v]);
+      setActive(v);
+    } else {
+      commit([v]);
+      hide();
+    }
+  }
+
+  async function create(typedText) {
+    let made = null;
+    try {
+      made = await onCreate?.(typedText);
+    } catch {
+      return; // the caller refused it; its own error shows where it chose
+    }
+    const option = made && typeof made === "object" ? withValues([made])[0] : { value: typedText, label: typedText };
+    known.current.set(option.value, option);
+    setCreated((c) => [...c.filter((o) => o.value !== option.value), option]);
+    setQuery("");
+    if (multiple) {
+      commit([...chosen.filter((x) => x !== option.value), option.value]);
+      setActive(option.value);
+    } else {
+      commit([option.value]);
+      hide();
+    }
+  }
+
+  function pick(item) {
+    if (item.create) create(text);
+    else choose(item.value);
+  }
+
+  function remove(v) {
+    commit(chosen.filter((x) => x !== v));
+    btn.current?.focus({ preventScroll: true });
+  }
+
+  // ─── keys ──────────────────────────────────────────────────────────
+
+  const printable = (e) => e.key.length === 1 && e.key !== " " && !e.metaKey && !e.ctrlKey && !e.altKey;
+
+  // Select-only: a letter jumps to the next option starting with it;
+  // letters typed quickly spell a prefix; one letter repeated cycles.
+  function typeahead(ch) {
+    const now = Date.now();
+    const t = typed.current;
+    t.text = now - t.at > 700 ? ch : t.text + ch;
+    t.at = now;
+    const repeat = [...t.text].every((c) => c === t.text[0]);
+    const q = (repeat ? t.text[0] : t.text).toLowerCase();
+    const live = visible.filter((o) => !o.disabled);
+    const at = Math.max(0, live.findIndex((o) => o.value === current));
+    const from = repeat ? at + 1 : at;
+    const order = [...live.slice(from), ...live.slice(0, from)];
+    const hit = order.find((o) => String(o.label).toLowerCase().startsWith(q));
+    if (hit) setActive(hit.value);
+  }
+
+  function onTriggerKey(e) {
+    onKeyDown?.(e);
+    if (e.defaultPrevented || disabled) return;
+    const open = isOpen && !phone;
+    if (!open) {
+      if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+        e.preventDefault();
+        show();
+      } else if (e.key === "Backspace" && multiple && chosen.length) {
+        e.preventDefault();
+        commit(chosen.slice(0, -1));
+      } else if (printable(e)) {
+        e.preventDefault();
+        if (searchable) seed.current = e.key;
+        show();
+      }
+      return;
+    }
+    // Open without a search: the keys work the list from the trigger.
+    if (e.key === "Tab") return hide();
+    if (e.key === " " || e.key === "Enter") {
+      e.preventDefault();
+      swallowSpace.current = e.key === " ";
+      const item = visible.find((o) => o.value === current);
+      if (item && !item.disabled) pick(item);
+      return;
+    }
+    if (listKeyDown(e, visible, current, setActive, pick)) return;
+    if (printable(e)) {
+      e.preventDefault();
+      typeahead(e.key);
+    }
+  }
+
+  // A Space that picked must not also click the trigger open again.
+  function onTriggerKeyUp(e) {
+    onKeyUp?.(e);
+    if (e.key === " " && swallowSpace.current) {
+      e.preventDefault();
+      swallowSpace.current = false;
+    }
+  }
+
+  function onSearchKey(e) {
+    if (listKeyDown(e, visible, current, setActive, pick)) return;
+    if (e.key === "Backspace" && multiple && !query && chosen.length) {
+      e.preventDefault();
+      commit(chosen.slice(0, -1));
+    }
+  }
+
+  // A phone sheet without a search: the focused listbox takes the keys.
+  function onListKey(e) {
+    if (e.key === " ") {
+      e.preventDefault();
+      const item = visible.find((o) => o.value === current);
+      if (item && !item.disabled) pick(item);
+      return;
+    }
+    if (listKeyDown(e, visible, current, setActive, pick)) return;
+    if (printable(e)) typeahead(e.key);
+  }
+
+  // Focus leaving for anything outside the field and its panel closes it.
+  function leaving(e) {
+    const to = e.relatedTarget;
+    if (!to || phone) return;
+    if (panel.current?.contains(to) || wrap.current?.contains(to)) return;
+    hide();
+  }
+
+  // ─── the trigger ───────────────────────────────────────────────────
+
+  const one = !multiple && chosen.length ? optionOf(chosen[0]) : null;
+  const showClear = clearable && chosen.length > 0 && !disabled;
+
+  const body = (
+    <>
+      {searchable ? (
+        <CommandInput
+          inputRef={input}
+          listId={listId}
+          activeId={activeId}
+          busy={busy && visible.length > 0}
+          aria-label={searchPlaceholder || `Search ${title}`}
+          placeholder={searchPlaceholder}
+          value={query}
+          onChange={(e) => {
+            setQuery(e.target.value);
+            setActive(null);
+          }}
+          onKeyDown={onSearchKey}
+        />
+      ) : null}
+      <CommandList
+        id={listId}
+        label={title}
+        items={shown}
+        active={current}
+        onActive={setActive}
+        onPick={pick}
+        selected={chosenSet}
+        multiple={multiple}
+        empty={empty}
+        loading={busy}
+        error={search.error}
+        focusable={phone && !searchable}
+        onKeyDown={phone && !searchable ? onListKey : undefined}
+        listRef={list}
+        // On a phone the list scrolls, not the sheet, so the search stays put.
+        className={phone ? "max-h-[55dvh]" : undefined}
+      />
+    </>
+  );
+
+  return (
+    <>
+      <div
+        ref={wrap}
+        onPointerDown={() => {
+          wasOpen.current = isOpen;
+        }}
+        // A press on the field (not on one of its buttons) opens it; a
+        // press while open was the light dismiss that closed it.
+        onClick={(e) => {
+          if (disabled || e.target.closest("button")) return;
+          btn.current?.focus({ preventScroll: true });
+          if (!wasOpen.current) show();
+        }}
+        className={cx(
+          "relative flex w-full min-h-11 cursor-pointer flex-wrap items-center gap-1 rounded-md border border-input bg-background pl-3 text-sm text-foreground",
+          "has-[[data-combobox-trigger]:focus-visible]:ring-2 has-[[data-combobox-trigger]:focus-visible]:ring-ring",
+          "has-[[data-combobox-trigger][aria-invalid=true]]:border-destructive",
+          showClear ? "pr-16" : "pr-9",
+          multiple && chosen.length > 0 && "py-1.5 pl-1.5",
+          disabled && "cursor-not-allowed opacity-50",
+          className,
+        )}
+      >
+        {multiple
+          ? chosen.map((v) => {
+              const o = optionOf(v);
+              return (
+                <span
+                  key={v}
+                  className="inline-flex min-h-7 max-w-full items-center gap-1 rounded-sm border border-border bg-secondary pl-2 pr-0.5 text-xs text-secondary-foreground"
+                >
+                  {typeof o.icon === "string" ? <Icon name={o.icon} size={12} className="shrink-0 text-muted-foreground" /> : null}
+                  <span className="truncate">{o.label}</span>
+                  {disabled ? (
+                    <span className="w-1.5" />
+                  ) : (
+                    <button
+                      type="button"
+                      aria-label={`Remove ${o.label}`}
+                      onClick={() => remove(v)}
+                      className="grid size-6 shrink-0 place-items-center rounded-sm text-muted-foreground outline-none hover:bg-accent hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+                    >
+                      <Icon name="x" size={12} />
+                    </button>
+                  )}
+                </span>
+              );
+            })
+          : null}
+        <button
+          ref={btn}
+          id={id}
+          type="button"
+          role="combobox"
+          data-combobox-trigger=""
+          disabled={disabled}
+          aria-label={label}
+          aria-haspopup={searchable ? "dialog" : "listbox"}
+          aria-expanded={isOpen}
+          aria-controls={isOpen ? (searchable && !phone ? panelId : listId) : undefined}
+          aria-activedescendant={isOpen && !searchable && !phone ? activeId ?? undefined : undefined}
+          aria-invalid={invalid || undefined}
+          popoverTarget={phone ? undefined : panelId}
+          onClick={phone ? () => show() : undefined}
+          onKeyDown={onTriggerKey}
+          onKeyUp={onTriggerKeyUp}
+          onBlur={(e) => {
+            onBlur?.(e);
+            if (!searchable) leaving(e);
+          }}
+          className={cx(
+            "flex min-h-9 min-w-12 flex-1 items-center gap-2 self-stretch text-left outline-none disabled:cursor-not-allowed",
+            multiple && chosen.length > 0 && "pl-1",
+          )}
+          {...rest}
+        >
+          {multiple ? (
+            chosen.length ? (
+              <span className="sr-only">{chosen.map((v) => optionOf(v).label).join(", ")}</span>
+            ) : (
+              <span className="truncate text-muted-foreground">{placeholder}</span>
+            )
+          ) : one ? (
+            <>
+              <ItemIcon icon={one.icon} />
+              <span className="truncate">{one.label}</span>
+            </>
+          ) : (
+            <span className="truncate text-muted-foreground">{placeholder}</span>
+          )}
+        </button>
+        {showClear ? (
+          <button
+            type="button"
+            aria-label="Clear"
+            onClick={() => {
+              commit([]);
+              btn.current?.focus({ preventScroll: true });
+            }}
+            className="absolute right-8 top-1/2 grid size-7 -translate-y-1/2 place-items-center rounded-sm text-muted-foreground outline-none hover:bg-accent hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            <Icon name="x" size={14} />
+          </button>
+        ) : null}
+        <Icon name="chevrons-up-down" className="pointer-events-none absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground" />
+        {name ? chosen.map((v) => <input key={v} type="hidden" name={name} value={v} />) : null}
+      </div>
+
+      {phone ? (
+        isOpen ? (
+          <Sheet
+            open
+            side="bottom"
+            title={title}
+            onClose={() => setOpen(false)}
+            footer={
+              multiple ? (
+                <Button variant="primary" onClick={hide} className="w-full">
+                  Done{chosen.length ? ` · ${chosen.length} chosen` : ""}
+                </Button>
+              ) : null
+            }
+          >
+            <div ref={sheetBody} className="-mx-4 -my-4">
+              {body}
+            </div>
+          </Sheet>
+        ) : null
+      ) : (
+        <div
+          ref={panel}
+          id={panelId}
+          popover="auto"
+          role={searchable ? "dialog" : undefined}
+          aria-label={searchable ? title : undefined}
+          onToggle={onToggle}
+          onBlur={leaving}
+          className={panelClass("auto", "overflow-hidden p-0 text-sm")}
+          style={width ? { width: `max(${width}px, 14rem)` } : undefined}
+        >
+          {body}
+        </div>
+      )}
+    </>
+  );
+}