@cosxai/ui 0.1.0

package/src/command/CommandPalette.tsx

@@ -0,0 +1,277 @@
+import {
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+} from "react";
+import { createPortal } from "react-dom";
+import { CommandContext } from "./command-context";
+import { rankItems } from "./rank";
+import { Kbd } from "../primitives/Kbd";
+import type { CommandItem } from "./types";
+
+// The palette UI. Mounts inside <CommandProvider>; reads items from
+// the registry, filters, groups, navigates. Arrow keys + Enter +
+// Esc bound while open. Cmd+K toggle lives in the provider.
+
+export interface CommandPaletteProps {
+  // Order in which groups appear. Items in groups not listed
+  // here come last in registration order.
+  groupOrder?: string[];
+  placeholder?: string;
+}
+
+export function CommandPalette({
+  groupOrder = [],
+  placeholder = "Type a command or search…",
+}: CommandPaletteProps) {
+  const ctx = useContext(CommandContext);
+  if (!ctx) throw new Error("<CommandPalette> must be inside <CommandProvider>");
+  const { open, setOpen, items } = ctx;
+  const [q, setQ] = useState("");
+  const [selectedIdx, setSelectedIdx] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+
+  // Reset query + focus on every open.
+  useEffect(() => {
+    if (open) {
+      setQ("");
+      setSelectedIdx(0);
+      // RAF so the modal element exists before focus.
+      requestAnimationFrame(() => inputRef.current?.focus());
+    }
+  }, [open]);
+
+  // Filter + flat-group ordering.
+  const filtered = useMemo(() => rankItems(items, q), [items, q]);
+  const grouped = useMemo(() => {
+    const byGroup: Record<string, CommandItem[]> = {};
+    for (const it of filtered) {
+      (byGroup[it.group] ??= []).push(it);
+    }
+    const seen = new Set<string>();
+    const ordered: { group: string; items: CommandItem[] }[] = [];
+    for (const g of groupOrder) {
+      if (byGroup[g]) {
+        ordered.push({ group: g, items: byGroup[g] });
+        seen.add(g);
+      }
+    }
+    for (const g of Object.keys(byGroup)) {
+      if (seen.has(g)) continue;
+      ordered.push({ group: g, items: byGroup[g]! });
+    }
+    return ordered;
+  }, [filtered, groupOrder]);
+
+  // Flat array for keyboard navigation (sequential across groups).
+  const flat = useMemo(() => grouped.flatMap((g) => g.items), [grouped]);
+
+  // Clamp selectedIdx when results shrink.
+  useEffect(() => {
+    if (selectedIdx >= flat.length) setSelectedIdx(Math.max(0, flat.length - 1));
+  }, [flat.length, selectedIdx]);
+
+  const close = () => setOpen(false);
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        close();
+        return;
+      }
+      if (e.key === "ArrowDown") {
+        e.preventDefault();
+        setSelectedIdx((i) => (i + 1) % Math.max(1, flat.length));
+        return;
+      }
+      if (e.key === "ArrowUp") {
+        e.preventDefault();
+        setSelectedIdx((i) => (i - 1 + Math.max(1, flat.length)) % Math.max(1, flat.length));
+        return;
+      }
+      if (e.key === "Enter") {
+        e.preventDefault();
+        const pick = flat[selectedIdx];
+        if (pick) pick.run({ close });
+        return;
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+    // close + flat + selectedIdx are stable enough; intentionally omit
+    // close from deps so we don't re-bind every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open, flat, selectedIdx]);
+
+  // Scroll selected row into view.
+  useEffect(() => {
+    if (!open) return;
+    const node = listRef.current?.querySelector(`[data-row-idx="${selectedIdx}"]`);
+    (node as HTMLElement | null)?.scrollIntoView({ block: "nearest" });
+  }, [open, selectedIdx]);
+
+  if (!open) return null;
+
+  return createPortal(
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label="Command palette"
+      style={{
+        position: "fixed",
+        inset: 0,
+        background: "rgba(10, 14, 26, 0.5)",
+        backdropFilter: "blur(2px)",
+        display: "flex",
+        alignItems: "flex-start",
+        justifyContent: "center",
+        padding: "10vh 16px 16px",
+        zIndex: 110,
+      }}
+      onMouseDown={(e) => {
+        if (e.target === e.currentTarget) close();
+      }}
+      className="ck-anim-fade"
+    >
+      <div
+        className="ck-anim-popover"
+        style={
+          {
+            width: "100%",
+            maxWidth: 560,
+            background: "var(--ck-bg-surface)",
+            border: "1px solid var(--ck-border-subtle)",
+            borderRadius: "var(--ck-radius-md)",
+            boxShadow: "var(--ck-shadow-3)",
+            overflow: "hidden",
+            display: "flex",
+            flexDirection: "column",
+            maxHeight: "70vh",
+            fontFamily: "var(--ck-font-sans)",
+            color: "var(--ck-text-primary)",
+          } as CSSProperties
+        }
+      >
+        <input
+          ref={inputRef}
+          value={q}
+          onChange={(e) => {
+            setQ(e.target.value);
+            setSelectedIdx(0);
+          }}
+          placeholder={placeholder}
+          style={{
+            height: 44,
+            padding: "0 16px",
+            border: "none",
+            borderBottom: "1px solid var(--ck-border-subtle)",
+            background: "transparent",
+            color: "var(--ck-text-primary)",
+            font: "400 14px/1 var(--ck-font-sans)",
+            outline: "none",
+          }}
+        />
+        <div ref={listRef} style={{ flex: 1, minHeight: 0, overflowY: "auto", padding: 4 }}>
+          {flat.length === 0 ? (
+            <div
+              style={{
+                padding: "24px 16px",
+                color: "var(--ck-text-tertiary)",
+                fontSize: 13,
+                textAlign: "center",
+              }}
+            >
+              No matches.
+            </div>
+          ) : (
+            grouped.map((g) => (
+              <div key={g.group} style={{ marginBottom: 6 }}>
+                <div
+                  className="ck-eyebrow"
+                  style={{ padding: "8px 12px 4px", color: "var(--ck-text-tertiary)" }}
+                >
+                  {g.group}
+                </div>
+                {g.items.map((it) => {
+                  const idx = flat.indexOf(it);
+                  const selected = idx === selectedIdx;
+                  return (
+                    <div
+                      key={it.key}
+                      data-row-idx={idx}
+                      onMouseEnter={() => setSelectedIdx(idx)}
+                      onClick={() => it.run({ close })}
+                      style={{
+                        display: "flex",
+                        alignItems: "center",
+                        gap: 10,
+                        padding: "8px 12px",
+                        borderRadius: "var(--ck-radius-sm)",
+                        background: selected ? "var(--ck-accent-muted)" : "transparent",
+                        color: selected ? "var(--ck-accent)" : "var(--ck-text-primary)",
+                        cursor: "pointer",
+                        font: "400 13px/1.3 var(--ck-font-sans)",
+                      }}
+                    >
+                      {it.icon && (
+                        <span style={{ display: "inline-flex", color: "var(--ck-text-tertiary)" }}>
+                          {it.icon}
+                        </span>
+                      )}
+                      <span style={{ flex: 1, minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+                        {it.label}
+                        {it.sublabel && (
+                          <span style={{ color: "var(--ck-text-tertiary)", marginLeft: 6, fontSize: 12 }}>
+                            {it.sublabel}
+                          </span>
+                        )}
+                      </span>
+                      {it.hint && (
+                        <span style={{ color: "var(--ck-text-tertiary)", fontSize: 12 }}>
+                          {it.hint}
+                        </span>
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
+            ))
+          )}
+        </div>
+        <div
+          style={{
+            padding: "8px 12px",
+            borderTop: "1px solid var(--ck-border-subtle)",
+            display: "flex",
+            alignItems: "center",
+            gap: 12,
+            color: "var(--ck-text-tertiary)",
+            font: "400 11px/1 var(--ck-font-mono)",
+            background: "var(--ck-bg-surface-2)",
+          }}
+        >
+          <span style={{ display: "inline-flex", alignItems: "center", gap: 4 }}>
+            <Kbd>↑</Kbd>
+            <Kbd>↓</Kbd>
+            navigate
+          </span>
+          <span style={{ display: "inline-flex", alignItems: "center", gap: 4 }}>
+            <Kbd>Enter</Kbd>
+            run
+          </span>
+          <span style={{ display: "inline-flex", alignItems: "center", gap: 4 }}>
+            <Kbd>Esc</Kbd>
+            close
+          </span>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}

package/src/command/CommandProvider.tsx

@@ -0,0 +1,57 @@
+import { useCallback, useMemo, useState, type ReactNode } from "react";
+import { CommandContext } from "./command-context";
+import { useKeyboardHotkey } from "../hooks/useKeyboardHotkey";
+import type { CommandItem } from "./types";
+
+// Hosts the command-source registry + the palette's open state.
+// Binds Cmd+K globally so any consumer page can trigger the palette
+// without wiring its own listener.
+
+export function CommandProvider({
+  children,
+  hotkey = "k",
+}: {
+  children: ReactNode;
+  // Letter for the Mod+_ shortcut. Default "k".
+  hotkey?: string;
+}) {
+  const [sources, setSources] = useState<Record<string, CommandItem[]>>({});
+  const [open, setOpen] = useState(false);
+
+  const register = useCallback((sourceKey: string, items: CommandItem[]) => {
+    setSources((prev) => {
+      const cur = prev[sourceKey];
+      if (cur && cur.length === items.length && cur.every((it, i) => it === items[i])) {
+        return prev;
+      }
+      return { ...prev, [sourceKey]: items };
+    });
+  }, []);
+
+  const unregister = useCallback((sourceKey: string) => {
+    setSources((prev) => {
+      if (!(sourceKey in prev)) return prev;
+      const next = { ...prev };
+      delete next[sourceKey];
+      return next;
+    });
+  }, []);
+
+  const items = useMemo(() => Object.values(sources).flat(), [sources]);
+
+  useKeyboardHotkey(
+    hotkey,
+    (e) => {
+      e.preventDefault();
+      setOpen((v) => !v);
+    },
+    { mod: true, skipWhenModalOpen: false },
+  );
+
+  const value = useMemo(
+    () => ({ register, unregister, items, open, setOpen }),
+    [register, unregister, items, open],
+  );
+
+  return <CommandContext.Provider value={value}>{children}</CommandContext.Provider>;
+}

package/src/command/command-context.ts

@@ -0,0 +1,12 @@
+import { createContext } from "react";
+import type { CommandItem } from "./types";
+
+export interface CommandContextValue {
+  register: (sourceKey: string, items: CommandItem[]) => void;
+  unregister: (sourceKey: string) => void;
+  items: CommandItem[];
+  open: boolean;
+  setOpen: (next: boolean) => void;
+}
+
+export const CommandContext = createContext<CommandContextValue | null>(null);

package/src/command/index.ts

@@ -0,0 +1,6 @@
+export { CommandProvider } from "./CommandProvider";
+export { CommandPalette } from "./CommandPalette";
+export type { CommandPaletteProps } from "./CommandPalette";
+export { useCommandSource, useCommandPalette } from "./useCommandSource";
+export { rankItems } from "./rank";
+export type { CommandItem } from "./types";

package/src/command/rank.ts

@@ -0,0 +1,45 @@
+import type { CommandItem } from "./types";
+
+// Tiny fuzzy ranker. Three signals:
+//   - label substring match  → score 100
+//   - label prefix match     → score +20
+//   - keyword substring match → score 60 (lower than label)
+// Anything that doesn't match returns null.
+//
+// Not as fancy as fzf — good enough for command palettes with
+// dozens to low hundreds of items. Swap in a fancier library if
+// you outgrow it; the call site (`useFilteredCommands`) is small.
+
+interface Ranked {
+  item: CommandItem;
+  score: number;
+}
+
+function scoreOne(item: CommandItem, q: string): number | null {
+  if (!q) return 1; // empty query — everyone passes, sorted by registration order
+  const ql = q.toLowerCase();
+  const lab = item.label.toLowerCase();
+  let s = 0;
+  if (lab.includes(ql)) {
+    s = 100;
+    if (lab.startsWith(ql)) s += 20;
+  } else if (item.keywords?.some((k) => k.toLowerCase().includes(ql))) {
+    s = 60;
+  } else if (item.sublabel?.toLowerCase().includes(ql)) {
+    s = 40;
+  } else {
+    return null;
+  }
+  return s;
+}
+
+export function rankItems(items: CommandItem[], query: string): CommandItem[] {
+  const ranked: Ranked[] = [];
+  for (const item of items) {
+    const sc = scoreOne(item, query);
+    if (sc !== null) ranked.push({ item, score: sc });
+  }
+  // Stable sort by score descending.
+  ranked.sort((a, b) => b.score - a.score);
+  return ranked.map((r) => r.item);
+}

package/src/command/types.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+
+// Single executable command. Sources register sets of these; the
+// palette flattens, filters by the user's query, groups by `group`,
+// and runs `run()` when the user picks.
+
+export interface CommandItem {
+  key: string;
+  // Visual category — items sharing a group render under a single
+  // labelled header in the palette. Use anything; the kit pins
+  // ordering via the palette's `groupOrder` prop.
+  group: string;
+  label: string;
+  // Dimmed secondary text — usually a path or short context.
+  sublabel?: string;
+  // Right-aligned hint (kbd shortcut, "→", etc.).
+  hint?: ReactNode;
+  icon?: ReactNode;
+  // Extra strings to score against (filenames, aliases). Lower
+  // weight than label so they don't drown the primary match.
+  keywords?: string[];
+  // Called when the user picks this command. `close()` shuts the
+  // palette — useful when the command opens a sub-flow that wants
+  // to keep the palette open.
+  run: (api: { close: () => void }) => void;
+}

package/src/command/useCommandSource.ts

@@ -0,0 +1,37 @@
+import { useContext, useEffect, useMemo } from "react";
+import { CommandContext } from "./command-context";
+import type { CommandItem } from "./types";
+
+// Register a set of commands. Same lifecycle pattern as
+// useActionBarItems — auto-unregister on unmount / sourceKey change.
+//
+// **Important**: same `ctx`-in-deps caveat as useActionBarItems —
+// depending on the whole ctx object would cause an infinite render
+// loop (register mutates provider state → ctx ref changes → effect
+// re-runs → loop). Destructure register/unregister out so we depend
+// on the stable useCallback'd refs instead.
+
+export function useCommandSource(sourceKey: string, items: CommandItem[]) {
+  const ctx = useContext(CommandContext);
+  if (!ctx) {
+    throw new Error("useCommandSource must be used within <CommandProvider>");
+  }
+  const { register, unregister } = ctx;
+  const memo = useMemo(
+    () => items,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [items.length, items.map((i) => i.key).join("|")],
+  );
+  useEffect(() => {
+    register(sourceKey, memo);
+    return () => unregister(sourceKey);
+  }, [register, unregister, sourceKey, memo]);
+}
+
+export function useCommandPalette() {
+  const ctx = useContext(CommandContext);
+  if (!ctx) {
+    throw new Error("Command palette context not found");
+  }
+  return { open: ctx.open, setOpen: ctx.setOpen };
+}

package/src/dialogs/DialogsProvider.tsx

@@ -0,0 +1,216 @@
+import { useCallback, useMemo, useRef, useState, type ReactNode } from "react";
+import { DialogsContext } from "./dialogs-context";
+import { Modal, ModalHeader, ModalBody, ModalFooter } from "./Modal";
+import { Button } from "../primitives/Button";
+import { Input } from "../primitives/Input";
+import { ToastStack, type ToastItem } from "./Toast";
+import type {
+  ConfirmOptions,
+  PromptOptions,
+  ToastOptions,
+  DialogsApi,
+} from "./types";
+
+// Single mount point. Hosts the imperative confirm/prompt/toast
+// API used by useDialogs(). Promise-based so call sites flow
+// naturally:
+//
+//   const ok = await dialogs.confirm({ title: "Delete?", danger: true });
+//   if (!ok) return;
+//   await api.deleteThing();
+//
+// Toast queue handles its own dismiss timer (see Toast.tsx).
+
+interface ConfirmState extends ConfirmOptions {
+  resolve: (value: boolean) => void;
+}
+interface PromptState extends PromptOptions {
+  resolve: (value: string | null) => void;
+}
+
+export function DialogsProvider({ children }: { children: ReactNode }) {
+  const [confirmState, setConfirmState] = useState<ConfirmState | null>(null);
+  const [promptState, setPromptState] = useState<PromptState | null>(null);
+  const [toasts, setToasts] = useState<ToastItem[]>([]);
+  const toastIdRef = useRef(0);
+
+  const confirm = useCallback(
+    (opts: ConfirmOptions) =>
+      new Promise<boolean>((resolve) => {
+        setConfirmState({ ...opts, resolve });
+      }),
+    [],
+  );
+
+  const prompt = useCallback(
+    (opts: PromptOptions) =>
+      new Promise<string | null>((resolve) => {
+        setPromptState({ ...opts, resolve });
+      }),
+    [],
+  );
+
+  const toast = useCallback((opts: ToastOptions) => {
+    const id = ++toastIdRef.current;
+    setToasts((t) => [...t, { ...opts, id }]);
+  }, []);
+
+  const dismissToast = useCallback((id: number) => {
+    setToasts((t) => t.filter((x) => x.id !== id));
+  }, []);
+
+  const api = useMemo<DialogsApi>(
+    () => ({ confirm, prompt, toast }),
+    [confirm, prompt, toast],
+  );
+
+  return (
+    <DialogsContext.Provider value={api}>
+      {children}
+      {confirmState && (
+        <ConfirmDialog
+          state={confirmState}
+          onDone={(v) => {
+            confirmState.resolve(v);
+            setConfirmState(null);
+          }}
+        />
+      )}
+      {promptState && (
+        <PromptDialog
+          state={promptState}
+          onDone={(v) => {
+            promptState.resolve(v);
+            setPromptState(null);
+          }}
+        />
+      )}
+      <ToastStack toasts={toasts} onDismiss={dismissToast} />
+    </DialogsContext.Provider>
+  );
+}
+
+// ---------- Confirm dialog ----------
+
+function ConfirmDialog({
+  state,
+  onDone,
+}: {
+  state: ConfirmState;
+  onDone: (value: boolean) => void;
+}) {
+  const [typed, setTyped] = useState("");
+  const needsTyped = !!state.confirmationText;
+  const canConfirm =
+    !needsTyped ||
+    typed.trim().toLowerCase() === state.confirmationText!.trim().toLowerCase();
+  return (
+    <Modal open onClose={() => onDone(false)}>
+      <ModalHeader title={state.title} onClose={() => onDone(false)} />
+      {(state.message || needsTyped) && (
+        <ModalBody>
+          {state.message && (
+            <div
+              style={{
+                font: "400 14px/1.5 var(--ck-font-sans)",
+                color: "var(--ck-text-secondary)",
+              }}
+            >
+              {state.message}
+            </div>
+          )}
+          {needsTyped && (
+            <div style={{ marginTop: 16 }}>
+              <Input
+                value={typed}
+                onChange={(e) => setTyped(e.target.value)}
+                placeholder={state.confirmationText}
+                helper={`Type "${state.confirmationText}" to confirm.`}
+              />
+            </div>
+          )}
+        </ModalBody>
+      )}
+      <ModalFooter>
+        <Button variant="ghost" onClick={() => onDone(false)}>
+          {state.cancelLabel ?? "Cancel"}
+        </Button>
+        <Button
+          variant="primary"
+          onClick={() => onDone(true)}
+          disabled={!canConfirm}
+          style={
+            state.danger
+              ? {
+                  background: "var(--ck-critical)",
+                  color: "var(--ck-text-inverse)",
+                }
+              : undefined
+          }
+        >
+          {state.confirmLabel ?? "Confirm"}
+        </Button>
+      </ModalFooter>
+    </Modal>
+  );
+}
+
+// ---------- Prompt dialog ----------
+
+function PromptDialog({
+  state,
+  onDone,
+}: {
+  state: PromptState;
+  onDone: (value: string | null) => void;
+}) {
+  const [value, setValue] = useState(state.defaultValue ?? "");
+  const [error, setError] = useState<string | null>(null);
+  const submit = () => {
+    const err = state.validate?.(value);
+    if (err) {
+      setError(err);
+      return;
+    }
+    onDone(value);
+  };
+  return (
+    <Modal open onClose={() => onDone(null)}>
+      <ModalHeader title={state.title} onClose={() => onDone(null)} />
+      <ModalBody>
+        {state.message && (
+          <div
+            style={{
+              font: "400 14px/1.5 var(--ck-font-sans)",
+              color: "var(--ck-text-secondary)",
+              marginBottom: 12,
+            }}
+          >
+            {state.message}
+          </div>
+        )}
+        <Input
+          value={value}
+          onChange={(e) => {
+            setValue(e.target.value);
+            if (error) setError(null);
+          }}
+          placeholder={state.placeholder}
+          error={error}
+          onKeyDown={(e) => {
+            if (e.key === "Enter") submit();
+          }}
+          autoFocus
+        />
+      </ModalBody>
+      <ModalFooter>
+        <Button variant="ghost" onClick={() => onDone(null)}>
+          {state.cancelLabel ?? "Cancel"}
+        </Button>
+        <Button variant="primary" onClick={submit}>
+          {state.confirmLabel ?? "OK"}
+        </Button>
+      </ModalFooter>
+    </Modal>
+  );
+}