@cosxai/ui 1.0.0-alpha.1 → 1.0.0-alpha.11

package/src/components/VirtualList.tsx

@@ -0,0 +1,90 @@
+import { useVirtualizer } from '@tanstack/react-virtual';
+import { useEffect, useRef, type CSSProperties, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { Spinner } from './Spinner';
+
+export type VirtualListProps<T> = {
+  items: readonly T[];
+  /** Estimated row height in px (rows may differ; they are measured). @default 42 */
+  estimateSize?: number | undefined;
+  renderItem: (item: T, index: number) => ReactNode;
+  getKey?: ((item: T, index: number) => string | number) | undefined;
+  /** Rows rendered beyond the viewport. @default 8 */
+  overscan?: number | undefined;
+  /** The scroll box's height (the list scrolls inside it). */
+  height: number | string;
+  /** Accessible name of the list. */
+  label: string;
+  className?: string | undefined;
+  /** Rendered after the last row: an InfiniteLoader. */
+  footer?: ReactNode;
+};
+
+/**
+ * VirtualList — renders only the visible rows of a long list (thousands of
+ * items), measuring each as it appears. The rows are list items.
+ */
+export function VirtualList<T>({ items, estimateSize = 42, renderItem, getKey, overscan = 8, height, label, className, footer }: VirtualListProps<T>) {
+  const scroller = useRef<HTMLDivElement | null>(null);
+  const v = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => scroller.current,
+    estimateSize: () => estimateSize,
+    overscan,
+    ...(getKey ? { getItemKey: (i: number) => getKey(items[i]!, i) } : {}),
+  });
+  return (
+    <div ref={scroller} className={cn('overflow-auto', className)} style={{ height }}>
+      <ul aria-label={label} className="relative m-0 list-none p-0" style={{ height: v.getTotalSize() }}>
+        {v.getVirtualItems().map((row) => (
+          <li
+            key={row.key}
+            data-index={row.index}
+            ref={v.measureElement}
+            className="absolute top-0 left-0 w-full"
+            style={{ transform: `translateY(${row.start}px)` } satisfies CSSProperties}
+          >
+            {renderItem(items[row.index]!, row.index)}
+          </li>
+        ))}
+      </ul>
+      {footer}
+    </div>
+  );
+}
+
+export type InfiniteLoaderProps = {
+  /** Called when the sentinel comes within `margin` of the viewport. */
+  onLoadMore: () => void;
+  hasMore: boolean;
+  loading?: boolean | undefined;
+  /** How early to load: the spec asks for 200px before the end. @default 200 */
+  margin?: number | undefined;
+  /** Read out while loading. @default "Loading more" */
+  loadingLabel?: string | undefined;
+  className?: string | undefined;
+};
+
+/** InfiniteLoader — a sentinel at the end of a list that asks for the next
+ *  page 200px before it comes into view. */
+export function InfiniteLoader({ onLoadMore, hasMore, loading = false, margin = 200, loadingLabel = 'Loading more', className }: InfiniteLoaderProps) {
+  const el = useRef<HTMLDivElement | null>(null);
+  const latest = useRef(onLoadMore);
+  latest.current = onLoadMore;
+
+  useEffect(() => {
+    const node = el.current;
+    if (!node || !hasMore || loading || typeof IntersectionObserver === 'undefined') return;
+    const io = new IntersectionObserver((entries) => entries.some((e) => e.isIntersecting) && latest.current(), { rootMargin: `0px 0px ${margin}px 0px` });
+    io.observe(node);
+    return () => io.disconnect();
+  }, [hasMore, loading, margin]);
+
+  if (!hasMore && !loading) return null;
+  return (
+    <div ref={el} className={cn('flex h-10 items-center justify-center text-fg-secondary', className)}>
+      {loading && <Spinner label={loadingLabel} />}
+    </div>
+  );
+}

package/src/components/WindowDrop.tsx

@@ -0,0 +1,131 @@
+import { Upload } from 'lucide-react';
+import { createContext, useCallback, useContext, useEffect, useRef, useState, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { Icon } from './Icon';
+import { hasFiles, readDataTransfer, type DroppedFile } from './status-files';
+
+type WindowDropContextValue = {
+  /** Files are being dragged over the window: every drop target lights up. */
+  dragging: boolean;
+  /** A local zone under the pointer names its folder here (null on leave). */
+  setHoverTarget: (target: string | null) => void;
+};
+
+const WindowDropContext = createContext<WindowDropContextValue>({ dragging: false, setHoverTarget: () => {} });
+
+/** Inside a WindowDrop: whether files are being dragged over the window. */
+export function useWindowDrop(): WindowDropContextValue {
+  return useContext(WindowDropContext);
+}
+
+export type WindowDropProps = {
+  children: ReactNode;
+  /** Where a drop anywhere goes: the current folder, or "My uploads". */
+  target: string;
+  /** A drop outside any local zone. */
+  onDrop: (items: DroppedFile[], target: string) => void;
+  /** Read-only page: no layer — a line says you can only view here. */
+  readOnly?: boolean | undefined;
+  /** Force the layer open (previews, screenshots). */
+  open?: boolean | undefined;
+  onOpenChange?: ((open: boolean) => void) | undefined;
+  labels?: { release?: (target: string) => string; viewOnly?: string; close?: string } | undefined;
+};
+
+const dialogOpen = () => typeof document !== 'undefined' && document.querySelector('[role="dialog"], [role="alertdialog"]') !== null;
+
+/**
+ * WindowDrop — the whole window accepts a drop while files are dragged in
+ * (only files: text, links or cards dragged on the page never trigger it).
+ * A layer above the page, below dialogs, names where the files will go;
+ * hovering a folder or a local Dropzone changes that wording. It leaves at
+ * once when the drag exits the window, on Esc, or after the drop.
+ */
+export function WindowDrop({ children, target, onDrop, readOnly = false, open, onOpenChange, labels }: WindowDropProps) {
+  const [dragging, setDragging] = useState(false);
+  const [hoverTarget, setHoverTarget] = useState<string | null>(null);
+  const depth = useRef(0);
+
+  const set = useCallback(
+    (v: boolean) => {
+      setDragging(v);
+      if (!v) setHoverTarget(null);
+      onOpenChange?.(v);
+    },
+    [onOpenChange],
+  );
+
+  useEffect(() => {
+    const enter = (e: DragEvent) => {
+      if (!hasFiles(e.dataTransfer) || dialogOpen()) return;
+      depth.current += 1;
+      if (depth.current === 1) set(true);
+    };
+    const over = (e: DragEvent) => {
+      if (!hasFiles(e.dataTransfer) || dialogOpen()) return;
+      e.preventDefault(); // allow the drop
+      if (e.dataTransfer) e.dataTransfer.dropEffect = readOnly ? 'none' : 'copy';
+    };
+    const leave = (e: DragEvent) => {
+      if (!hasFiles(e.dataTransfer)) return;
+      depth.current = Math.max(0, depth.current - 1);
+      if (depth.current === 0) set(false);
+    };
+    const drop = (e: DragEvent) => {
+      if (!hasFiles(e.dataTransfer)) return;
+      e.preventDefault();
+      depth.current = 0;
+      set(false);
+      if (readOnly || !e.dataTransfer) return;
+      void readDataTransfer(e.dataTransfer).then((items) => items.length && onDrop(items, target));
+    };
+    const key = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        depth.current = 0;
+        set(false);
+      }
+    };
+    window.addEventListener('dragenter', enter);
+    window.addEventListener('dragover', over);
+    window.addEventListener('dragleave', leave);
+    window.addEventListener('drop', drop);
+    window.addEventListener('keydown', key);
+    return () => {
+      window.removeEventListener('dragenter', enter);
+      window.removeEventListener('dragover', over);
+      window.removeEventListener('dragleave', leave);
+      window.removeEventListener('drop', drop);
+      window.removeEventListener('keydown', key);
+    };
+  }, [onDrop, readOnly, set, target]);
+
+  const shown = open ?? dragging;
+  const release = labels?.release ?? ((t: string) => `Release to upload to ${t}`);
+
+  return (
+    <WindowDropContext.Provider value={{ dragging: shown, setHoverTarget }}>
+      {children}
+      {shown && (
+        <div
+          data-window-drop
+          role="presentation"
+          onClick={() => set(false)}
+          className="pointer-events-none fixed inset-0 z-40 flex items-end justify-center bg-page/60 p-6 font-sans"
+        >
+          <div
+            role="status"
+            aria-live="polite"
+            className={cn(
+              'pointer-events-auto flex items-center gap-3 rounded-lg px-5 py-4 text-body font-medium',
+              readOnly ? 'bg-ink text-linen' : 'border-2 border-ink bg-brand-field text-ink',
+            )}
+          >
+            {!readOnly && <Icon icon={Upload} size={18} />}
+            {readOnly ? (labels?.viewOnly ?? 'You can only view here') : release(hoverTarget ?? target)}
+          </div>
+        </div>
+      )}
+    </WindowDropContext.Provider>
+  );
+}

package/src/components/WorkspaceRow.tsx

@@ -0,0 +1,80 @@
+import { ChevronRight } from 'lucide-react';
+import { forwardRef, useEffect, useRef, useState, type ComponentProps, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { Badge } from './Badge';
+import { Spinner } from './Spinner';
+
+export type WorkspaceMarkProps = {
+  name: string;
+  /** The workspace's logo; its initial on the yellow when unset or it fails to load. */
+  logoUrl?: string | undefined;
+  /** px. @default 36 */
+  size?: number | undefined;
+};
+
+/** WorkspaceMark — a workspace's logo, or its initial on the brand yellow. */
+export function WorkspaceMark({ name, logoUrl, size = 36 }: WorkspaceMarkProps) {
+  const [failed, setFailed] = useState(false);
+  const img = useRef<HTMLImageElement>(null);
+  // A server-rendered page can fail the image before React is listening:
+  // onError never fires, so look once it is.
+  useEffect(() => {
+    const el = img.current;
+    if (el?.complete && el.naturalWidth === 0) setFailed(true);
+  }, [logoUrl]);
+  if (logoUrl && !failed) {
+    return <img ref={img} src={logoUrl} alt="" aria-hidden style={{ width: size, height: size }} className="shrink-0 rounded-[8px] object-cover" onError={() => setFailed(true)} />;
+  }
+  return (
+    <span aria-hidden style={{ width: size, height: size }} className="grid shrink-0 place-items-center rounded-[8px] bg-brand-field text-[13px] font-semibold text-ink">
+      {name.trim().charAt(0).toUpperCase()}
+    </span>
+  );
+}
+
+export type WorkspaceRowProps = Omit<ComponentProps<'button'>, 'children'> & {
+  name: string;
+  /** The second line: the workspace's short name or address. */
+  detail?: ReactNode;
+  logoUrl?: string | undefined;
+  /** Being opened: a spinner in place of the chevron. */
+  busy?: boolean | undefined;
+  /** A state beside the chevron, as an attention badge: "Needs setup". */
+  badge?: ReactNode;
+};
+
+/**
+ * WorkspaceRow — one workspace in a chooser: mark, name, detail, chevron;
+ * `badge` says what it still needs ("Needs setup").
+ * The whole row is the button; `busy` shows it opening (disable the others).
+ */
+export const WorkspaceRow = forwardRef<HTMLButtonElement, WorkspaceRowProps>(function WorkspaceRow(
+  { name, detail, logoUrl, busy = false, badge, className, ...rest },
+  ref,
+) {
+  return (
+    <button
+      ref={ref}
+      type="button"
+      aria-busy={busy || undefined}
+      className={cn(
+        'flex w-full cursor-pointer items-center gap-3 rounded-[12px] border-0 bg-page px-3.5 py-3 text-left text-fg shadow-[inset_0_0_0_1px_var(--rule)] outline-none transition-colors duration-[120ms] hover:bg-hover focus-visible:shadow-(--focus-ring) disabled:cursor-default',
+        className,
+      )}
+      {...rest}
+    >
+      <WorkspaceMark name={name} logoUrl={logoUrl} />
+      <span className="flex min-w-0 flex-1 flex-col leading-[1.35]">
+        <span className="truncate text-[14px] font-medium">{name}</span>
+        {detail && <span className="truncate text-[12px] text-fg-secondary">{detail}</span>}
+      </span>
+      {badge && (
+        <span className="flex shrink-0">
+          <Badge status="attention">{badge}</Badge>
+        </span>
+      )}
+      {busy ? <Spinner size={16} /> : <ChevronRight size={16} aria-hidden className="text-fg-secondary" />}
+    </button>
+  );
+});

package/src/components/inputs-aria.ts

@@ -0,0 +1,5 @@
+/** Only the aria props that were given — Radix roots reject explicit
+ *  undefined under exactOptionalPropertyTypes. */
+export function definedAria(aria: Record<string, string | undefined>): Record<string, string> {
+  return Object.fromEntries(Object.entries(aria).filter(([, v]) => v !== undefined)) as Record<string, string>;
+}

package/src/components/inputs-date.ts

@@ -0,0 +1,92 @@
+// Date parsing for DateInput / FuzzyDateInput. Values are ISO strings
+// (YYYY-MM-DD, or YYYY-MM / YYYY for a fuzzy date) — no time zones.
+
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+const MONTH_NAMES = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+export type PartialDate = { year: number; month?: number | undefined; day?: number | undefined };
+
+const pad = (n: number) => String(n).padStart(2, '0');
+
+export function daysIn(year: number, month: number): number {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+function valid(p: PartialDate): boolean {
+  if (!Number.isInteger(p.year) || p.year < 1000 || p.year > 9999) return false;
+  if (p.month === undefined) return p.day === undefined;
+  if (p.month < 1 || p.month > 12) return false;
+  if (p.day === undefined) return true;
+  return p.day >= 1 && p.day <= daysIn(p.year, p.month);
+}
+
+function monthOf(word: string): number | undefined {
+  const i = MONTHS.indexOf(word.slice(0, 3).toLowerCase());
+  return i < 0 ? undefined : i + 1;
+}
+
+/**
+ * Parse what people type: 12/03/2019 (day first, British), 12.03.2019,
+ * 2019-03-12, 12 Mar 2019, March 12 2019, 2019年3月12日 — and, when
+ * `partial`, 2019-03, 03/2019, Mar 2019, 2019年3月, 2019. Returns null when
+ * it cannot tell.
+ */
+export function parseDate(text: string, { partial = false }: { partial?: boolean } = {}): PartialDate | null {
+  const t = text.trim().replace(/\s+/g, ' ');
+  if (!t) return null;
+  let m: RegExpMatchArray | null;
+  let p: PartialDate | null = null;
+  if ((m = t.match(/^(\d{4})[-/.](\d{1,2})[-/.](\d{1,2})$/))) p = { year: +m[1]!, month: +m[2]!, day: +m[3]! };
+  else if ((m = t.match(/^(\d{1,2})[-/.](\d{1,2})[-/.](\d{4})$/))) p = { year: +m[3]!, month: +m[2]!, day: +m[1]! };
+  else if ((m = t.match(/^(\d{1,2}) ([a-z]+)\.?,? (\d{4})$/i)) && monthOf(m[2]!)) p = { year: +m[3]!, month: monthOf(m[2]!), day: +m[1]! };
+  else if ((m = t.match(/^([a-z]+)\.? (\d{1,2}),? (\d{4})$/i)) && monthOf(m[1]!)) p = { year: +m[3]!, month: monthOf(m[1]!), day: +m[2]! };
+  else if ((m = t.match(/^(\d{4}) ?年 ?(\d{1,2}) ?月 ?(\d{1,2}) ?日?$/))) p = { year: +m[1]!, month: +m[2]!, day: +m[3]! };
+  else if (partial) {
+    if ((m = t.match(/^(\d{4})[-/.](\d{1,2})$/))) p = { year: +m[1]!, month: +m[2]! };
+    else if ((m = t.match(/^(\d{1,2})[-/.](\d{4})$/))) p = { year: +m[2]!, month: +m[1]! };
+    else if ((m = t.match(/^([a-z]+)\.? (\d{4})$/i)) && monthOf(m[1]!)) p = { year: +m[2]!, month: monthOf(m[1]!) };
+    else if ((m = t.match(/^(\d{4}) ?年 ?(\d{1,2}) ?月$/))) p = { year: +m[1]!, month: +m[2]! };
+    else if ((m = t.match(/^(\d{4})$/))) p = { year: +m[1]! };
+  }
+  return p && valid(p) ? p : null;
+}
+
+/** 2019-03-12 · 2019-03 · 2019 */
+export function toIso(p: PartialDate): string {
+  if (p.month === undefined) return String(p.year);
+  if (p.day === undefined) return `${p.year}-${pad(p.month)}`;
+  return `${p.year}-${pad(p.month)}-${pad(p.day)}`;
+}
+
+/** Inverse of toIso; null for anything else. */
+export function fromIso(iso: string | null | undefined): PartialDate | null {
+  if (!iso) return null;
+  const m = iso.match(/^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/);
+  if (!m) return null;
+  const p: PartialDate = { year: +m[1]!, month: m[2] ? +m[2] : undefined, day: m[3] ? +m[3] : undefined };
+  return valid(p) ? p : null;
+}
+
+/** 12 Mar 2019 · Mar 2019 · 2019 — or 2019 年 3 月 12 日 in Chinese. */
+export function formatDate(p: PartialDate, lang: 'en' | 'zh' = 'en'): string {
+  if (lang === 'zh') {
+    return `${p.year} 年${p.month ? ` ${p.month} 月` : ''}${p.day ? ` ${p.day} 日` : ''}`;
+  }
+  if (p.month === undefined) return String(p.year);
+  const mon = MONTH_NAMES[p.month - 1]!;
+  return p.day === undefined ? `${mon} ${p.year}` : `${p.day} ${mon} ${p.year}`;
+}
+
+export function toDate(p: PartialDate): Date {
+  return new Date(p.year, (p.month ?? 1) - 1, p.day ?? 1);
+}
+
+export function fromDate(d: Date): PartialDate {
+  return { year: d.getFullYear(), month: d.getMonth() + 1, day: d.getDate() };
+}
+
+/** zh when the element (or page) is Chinese. */
+export function langOf(el: Element | null): 'en' | 'zh' {
+  const lang = (el?.closest('[lang]')?.getAttribute('lang') ?? (typeof document !== 'undefined' ? document.documentElement.lang : '')).toLowerCase();
+  return lang.startsWith('zh') ? 'zh' : 'en';
+}

package/src/components/inputs-listbox.tsx

@@ -0,0 +1,154 @@
+import { Plus } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import type { SearchStatus } from './inputs-search';
+import { Spinner } from './Spinner';
+
+export type ListItem = {
+  value: string;
+  label: string;
+  /** Right-hand line: Customer · 3 projects. */
+  meta?: string | undefined;
+  /** Initials in the avatar square (HV). Derived from the label if omitted. */
+  initials?: string | undefined;
+};
+
+export function initialsOf(item: ListItem): string {
+  if (item.initials) return item.initials;
+  const words = item.label.trim().split(/\s+/);
+  const first = words[0] ?? '';
+  // One hanzi reads as an initial on its own (王).
+  if (/[㐀-鿿]/.test(first)) return first[0]!;
+  return ((first[0] ?? '') + (words.length > 1 ? (words[words.length - 1]![0] ?? '') : '')).toUpperCase();
+}
+
+export function Avatar({ item, className }: { item: ListItem; className?: string | undefined }) {
+  return (
+    <span aria-hidden className={cn('inline-grid size-6 shrink-0 place-items-center rounded-pill bg-well text-[10.5px] font-semibold text-fg', className)}>
+      {initialsOf(item)}
+    </span>
+  );
+}
+
+export type ListboxLabels = {
+  searching: string;
+  empty: (query: string) => string;
+  error: string;
+  retry: string;
+  create: (query: string) => string;
+};
+
+export const DEFAULT_LABELS: ListboxLabels = {
+  searching: 'Searching',
+  empty: (q) => `Nothing matches “${q}”.`,
+  error: 'Couldn’t load results.',
+  retry: 'Retry',
+  create: (q) => `Create “${q}”`,
+};
+
+/** Rows of an async listbox: results, then an optional Create row; or one state row. */
+export function ListboxBody({
+  id,
+  optionId,
+  items,
+  active,
+  status,
+  query,
+  canCreate,
+  labels,
+  onActive,
+  onChoose,
+  onRetry,
+  selectedValues,
+}: {
+  id: string;
+  optionId: (i: number) => string;
+  items: ListItem[];
+  /** Index of the active row; items.length means the Create row. */
+  active: number;
+  status: SearchStatus;
+  query: string;
+  canCreate: boolean;
+  labels: ListboxLabels;
+  onActive: (i: number) => void;
+  onChoose: (i: number) => void;
+  onRetry: () => void;
+  selectedValues?: ReadonlySet<string>;
+}) {
+  const row = (i: number, content: ReactNode, selected = false) => (
+    <div
+      key={optionId(i)}
+      id={optionId(i)}
+      role="option"
+      aria-selected={selected}
+      data-active={i === active || undefined}
+      onMouseMove={() => i !== active && onActive(i)}
+      onMouseDown={(e) => e.preventDefault()}
+      onClick={() => onChoose(i)}
+      className={cn(
+        'flex cursor-pointer items-center gap-2 rounded-md px-2 py-1.5 text-[13px] leading-[1.35] text-fg',
+        i === active ? 'bg-brand-field text-ink' : selected && 'bg-hover',
+      )}
+    >
+      {content}
+    </div>
+  );
+
+  let state: ReactNode = null;
+  if (status === 'searching') {
+    state = (
+      <div className="flex items-center gap-2 px-2.5 py-2.5 text-[12.5px] text-fg-secondary">
+        <Spinner size={12} /> {labels.searching}
+      </div>
+    );
+  } else if (status === 'error') {
+    state = (
+      <div className="flex items-center gap-2 px-2.5 py-2 text-[12.5px] text-fg-secondary">
+        <span className="flex-1">{labels.error}</span>
+        <button
+          type="button"
+          onMouseDown={(e) => e.preventDefault()}
+          onClick={onRetry}
+          className="cursor-pointer rounded-xs font-medium text-fg underline underline-offset-3 outline-none focus-visible:shadow-(--focus-ring)"
+        >
+          {labels.retry}
+        </button>
+      </div>
+    );
+  } else if (status === 'done' && items.length === 0 && !canCreate) {
+    state = <div className="px-2.5 py-2.5 text-[12.5px] text-fg-secondary">{labels.empty(query)}</div>;
+  }
+
+  return (
+    <div id={id} role="listbox" className="flex max-h-[260px] flex-col overflow-y-auto">
+      {status === 'done' &&
+        items.map((it, i) =>
+          row(
+            i,
+            <>
+              <Avatar item={it} className={i === active ? 'bg-ink text-linen' : undefined} />
+              <span className="min-w-0 flex-1 truncate">{it.label}</span>
+              {it.meta && <span className="shrink-0 text-meta text-fg-secondary">{it.meta}</span>}
+            </>,
+            selectedValues?.has(it.value),
+          ),
+        )}
+      {status === 'done' && items.length === 0 && canCreate && (
+        <div className="px-2.5 pt-1.5 pb-1 text-meta text-fg-secondary">{labels.empty(query)}</div>
+      )}
+      {status === 'done' &&
+        canCreate &&
+        row(
+          items.length,
+          <>
+            <span aria-hidden className="inline-grid size-6 shrink-0 place-items-center rounded-sm border border-dashed border-rule text-fg-secondary">
+              <Plus size={13} />
+            </span>
+            <span className="font-medium">{labels.create(query)}</span>
+          </>,
+        )}
+      {state}
+    </div>
+  );
+}

package/src/components/inputs-search.ts

@@ -0,0 +1,60 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+export type SearchStatus = 'idle' | 'searching' | 'done' | 'error';
+
+/**
+ * Debounced, cancellable search. Each new query aborts the previous
+ * request (its AbortSignal fires) and a late answer to an old query is
+ * dropped, so results never flicker back. While a request is pending the
+ * status is "searching" — callers show a spinner, never "No results".
+ */
+export function useDebouncedSearch<T>(
+  query: string,
+  search: ((query: string, signal: AbortSignal) => Promise<T>) | undefined,
+  { delay = 250, minLength = 1 }: { delay?: number; minLength?: number } = {},
+) {
+  const [status, setStatus] = useState<SearchStatus>('idle');
+  const [result, setResult] = useState<T | undefined>(undefined);
+  const [error, setError] = useState<unknown>(null);
+  const [attempt, setAttempt] = useState(0);
+  const seq = useRef(0);
+  const ctrl = useRef<AbortController | null>(null);
+
+  useEffect(() => {
+    const q = query.trim();
+    ctrl.current?.abort();
+    ctrl.current = null;
+    if (!search || q.length < minLength) {
+      seq.current++;
+      setStatus('idle');
+      setResult(undefined);
+      setError(null);
+      return;
+    }
+    setStatus('searching');
+    const mine = ++seq.current;
+    const timer = setTimeout(() => {
+      const c = new AbortController();
+      ctrl.current = c;
+      search(q, c.signal).then(
+        (r) => {
+          if (mine !== seq.current || c.signal.aborted) return;
+          setResult(r);
+          setError(null);
+          setStatus('done');
+        },
+        (e: unknown) => {
+          if (mine !== seq.current || c.signal.aborted) return;
+          setError(e);
+          setStatus('error');
+        },
+      );
+    }, delay);
+    return () => clearTimeout(timer);
+  }, [query, search, delay, minLength, attempt]);
+
+  useEffect(() => () => ctrl.current?.abort(), []);
+
+  const retry = useCallback(() => setAttempt((a) => a + 1), []);
+  return { status, result, error, retry };
+}