@cosxai/ui 0.25.0 → 1.0.0-alpha.0

package/src/primitives/Combobox.tsx

@@ -1,507 +0,0 @@
-import {
-  forwardRef,
-  useCallback,
-  useEffect,
-  useImperativeHandle,
-  useRef,
-  useState,
-  type KeyboardEvent,
-  type ReactNode,
-} from "react";
-
-import { Input } from "./Input";
-
-// Combobox — async-search commit picker (recipient fields, entity
-// lookups). Extracted from product-meta's CustomerPicker so every
-// product surface shares one commit model (QA 2026-07-21: typed-but-
-// uncommitted text was visually identical to a committed pick, and on
-// slow networks the dropdown never even appeared before the user
-// moved on).
-//
-// The model has exactly two visible states, both always unambiguous:
-//
-//   · The INPUT is always rendered and always editable — it carries
-//     the "in progress" state (typing / searching). Editing it after
-//     a commit clears the commit (via onUncommit) and resumes search.
-//   · The COMMITTED CARD below the input carries the "confirmed"
-//     state — title + subtitle + × to clear + an optional extra slot
-//     (e.g. a display-name input for brand-new entities).
-//
-// Commit paths:
-//   · click / Enter on a dropdown row            → onCommit(option)
-//   · click / Enter on the free-entry row        → onCommit(free)
-//   · BLUR with committable text (auto-commit)   → exact option match
-//     when the search already returned one, else free entry when
-//     `allowFreeEntry(raw)` passes. Deliberately independent of the
-//     dropdown having rendered — on a slow network the free-entry
-//     path still commits from the local validity check alone.
-//   · blur with non-committable text             → invalid state
-//     (error border + `invalidHint`), never a silent look-alike.
-//
-// The committed value is PARENT-OWNED (controlled): the parent maps
-// options / free entries onto its own domain state and passes back
-// `committed` for display. This keeps the primitive product-agnostic.
-
-export interface ComboboxOption {
-  // Stable identity for list keys + commit payloads.
-  key: string;
-  // Primary row line (e.g. a person's name).
-  title: string;
-  // Secondary row line (e.g. their email). Also used by the default
-  // auto-commit matcher, so put the canonical typed value here.
-  subtitle?: string | undefined;
-}
-
-export type ComboboxCommit =
-  | { kind: "option"; option: ComboboxOption }
-  | { kind: "free"; raw: string };
-
-export interface ComboboxCommitted {
-  title: ReactNode;
-  subtitle?: ReactNode | undefined;
-}
-
-export interface ComboboxProps {
-  label?: ReactNode | undefined;
-  placeholder?: string | undefined;
-  autoFocus?: boolean | undefined;
-  disabled?: boolean | undefined;
-  // Async search. Called after `debounceMs` of quiet with a non-empty
-  // trimmed query; the AbortSignal cancels superseded requests.
-  search: (query: string, signal: AbortSignal) => Promise<ComboboxOption[]>;
-  // Select-with-search mode: run `search("")` the moment the input
-  // focuses, so clicking the field presents the option list before
-  // any typing — the picker pattern for small, known sets. Off by
-  // default (async person/document searches would fire on every
-  // focus for no gain).
-  searchOnFocus?: boolean | undefined;
-  debounceMs?: number | undefined;
-  // Free-entry gate: return true when the raw text is committable on
-  // its own (e.g. a syntactically valid email). Omit to disable free
-  // entry entirely (only listed options commit).
-  allowFreeEntry?: ((raw: string) => boolean) | undefined;
-  // Dropdown row copy for the free-entry affordance.
-  freeEntryLabel?: ((raw: string) => ReactNode) | undefined;
-  // Rendered in the dropdown when a search returned nothing and free
-  // entry doesn't apply.
-  emptyHint?: ReactNode | undefined;
-  // Error copy for "blurred with text that can't commit".
-  invalidHint?: string | undefined;
-  // Matcher backing blur auto-commit against loaded options. Default:
-  // case-insensitive equality on subtitle, then title.
-  matchOption?: ((raw: string, option: ComboboxOption) => boolean) | undefined;
-  // Parent-owned committed state; null/undefined = nothing committed.
-  committed?: ComboboxCommitted | null | undefined;
-  // Extra content inside the committed card (below subtitle).
-  committedExtra?: ReactNode | undefined;
-  onCommit: (commit: ComboboxCommit) => void;
-  // Fired when the user edits the input after a commit, or clicks the
-  // card's ×. Parent clears its committed state.
-  onUncommit?: (() => void) | undefined;
-  // Multi-value mode: after `onCommit` fires, reset the input to ""
-  // and close the dropdown instead of echoing the committed text. The
-  // parent renders the committed values itself (see MultiCombobox)
-  // and typically passes `committed={null}`. Default false — the
-  // single-value echo-into-input behaviour is unchanged.
-  clearOnCommit?: boolean | undefined;
-  // Bare mode: the input renders without its own field chrome (see
-  // Input `bare`) and the root wrapper is `position: static` +
-  // `flex: 1 1 140px`, so a host that draws the field (MultiCombobox
-  // inline layout) can place this after its chips and the dropdown
-  // anchors to the host's `position: relative` container. `label`
-  // and the inline error text are not rendered (the host draws them;
-  // `aria-invalid` is still set on the input). Default false.
-  bare?: boolean | undefined;
-  // id for the <input>, so a host-drawn <label htmlFor> can target it.
-  inputId?: string | undefined;
-  // Extra aria-describedby id(s) for the <input> (e.g. a host-drawn
-  // invalid hint in bare mode). Merged with Input's own error/helper
-  // association, never replacing it.
-  inputDescribedBy?: string | undefined;
-  testid?: string | undefined;
-}
-
-export const COMBOBOX_DEFAULT_INVALID_HINT = "Pick from the list to continue.";
-
-// Imperative handle — `focus()` returns focus to the input (e.g. after
-// an inline editor closes); `clear()` wipes the typed text + dropdown
-// (e.g. a parent rejecting a duplicate commit).
-export type ComboboxHandle = {
-  focus: () => void;
-  clear: () => void;
-};
-
-const DEFAULT_DEBOUNCE_MS = 250;
-
-function defaultMatch(raw: string, option: ComboboxOption): boolean {
-  const norm = raw.trim().toLowerCase();
-  return (
-    (option.subtitle ?? "").trim().toLowerCase() === norm ||
-    option.title.trim().toLowerCase() === norm
-  );
-}
-
-export const Combobox = forwardRef<ComboboxHandle, ComboboxProps>(function Combobox(
-  {
-  label,
-  placeholder,
-  autoFocus,
-  disabled,
-  search,
-  searchOnFocus,
-  debounceMs = DEFAULT_DEBOUNCE_MS,
-  allowFreeEntry,
-  freeEntryLabel,
-  emptyHint,
-  invalidHint,
-  matchOption = defaultMatch,
-  committed,
-  committedExtra,
-  onCommit,
-  onUncommit,
-  clearOnCommit = false,
-  bare = false,
-  inputId,
-  inputDescribedBy,
-  testid = "combobox",
-  },
-  ref,
-) {
-  const [query, setQuery] = useState("");
-  const [results, setResults] = useState<ComboboxOption[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [focused, setFocused] = useState(false);
-  const [highlight, setHighlight] = useState(0);
-  const [invalid, setInvalid] = useState(false);
-
-  const abortRef = useRef<AbortController | null>(null);
-  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const inputRef = useRef<HTMLInputElement | null>(null);
-
-  const isCommitted = !!committed;
-
-  useImperativeHandle(
-    ref,
-    () => ({
-      focus: () => inputRef.current?.focus(),
-      clear: () => {
-        setQuery("");
-        setResults([]);
-        setHighlight(0);
-        setInvalid(false);
-      },
-    }),
-    [],
-  );
-
-  useEffect(() => {
-    if (debounceRef.current) clearTimeout(debounceRef.current);
-    // Search is suspended while a commit is displayed — the input
-    // still holds the committed text but shouldn't re-open the list.
-    // searchOnFocus lifts the non-empty-query requirement while the
-    // field is focused: clicking presents the list, typing narrows.
-    if (isCommitted || (!query.trim() && !(searchOnFocus && focused))) {
-      setResults([]);
-      setLoading(false);
-      return;
-    }
-    debounceRef.current = setTimeout(() => {
-      abortRef.current?.abort();
-      const ac = new AbortController();
-      abortRef.current = ac;
-      setLoading(true);
-      search(query.trim(), ac.signal)
-        .then((rows) => {
-          if (ac.signal.aborted) return;
-          setResults(rows);
-          setHighlight(0);
-          setLoading(false);
-        })
-        .catch(() => {
-          if (ac.signal.aborted) return;
-          // Search failure degrades to "no suggestions" — free-entry
-          // auto-commit still works, which is the whole point on a
-          // flaky network.
-          setResults([]);
-          setLoading(false);
-        });
-    }, debounceMs);
-    return () => {
-      if (debounceRef.current) clearTimeout(debounceRef.current);
-      abortRef.current?.abort();
-    };
-  }, [query, isCommitted, search, debounceMs, searchOnFocus, focused]);
-
-  const trimmed = query.trim();
-  const freeEntryOk = !!allowFreeEntry && trimmed.length > 0 && allowFreeEntry(trimmed);
-  const hasNoResults = !loading && trimmed.length > 0 && results.length === 0;
-  const offerFree = !isCommitted && freeEntryOk && !results.some((r) => matchOption(trimmed, r));
-  const totalEntries = results.length + (offerFree ? 1 : 0);
-
-  const commitOption = useCallback(
-    (option: ComboboxOption) => {
-      setInvalid(false);
-      setResults([]);
-      setHighlight(0);
-      // Reflect the commit in the input so a half-typed query never
-      // sits next to a card naming someone else — unless the parent
-      // collects values (clearOnCommit), where the input resets for
-      // the next entry.
-      setQuery(clearOnCommit ? "" : (option.subtitle ?? option.title));
-      onCommit({ kind: "option", option });
-    },
-    [onCommit, clearOnCommit],
-  );
-
-  const commitFree = useCallback(
-    (raw: string) => {
-      setInvalid(false);
-      setResults([]);
-      setHighlight(0);
-      setQuery(clearOnCommit ? "" : raw);
-      onCommit({ kind: "free", raw });
-    },
-    [onCommit, clearOnCommit],
-  );
-
-  // Blur auto-commit — the fix for "typed it, tabbed on, looked
-  // committed but wasn't". Exact option match wins (brings the
-  // entity's identity along); otherwise free entry; otherwise flag
-  // invalid. Runs on a short delay so a dropdown row click (which
-  // blurs first) still lands on the row handler.
-  const handleBlur = useCallback(() => {
-    setTimeout(() => {
-      // Re-focused within the delay (e.g. a host frame click handing
-      // focus straight back, MultiCombobox inline): still editing —
-      // neither close the list nor auto-commit.
-      if (inputRef.current && document.activeElement === inputRef.current) return;
-      setFocused(false);
-      if (isCommitted) return;
-      const raw = trimmed;
-      if (!raw) {
-        setInvalid(false);
-        return;
-      }
-      const exact = results.find((r) => matchOption(raw, r));
-      if (exact) {
-        commitOption(exact);
-        return;
-      }
-      if (allowFreeEntry?.(raw)) {
-        commitFree(raw);
-        return;
-      }
-      setInvalid(true);
-    }, 150);
-  }, [isCommitted, trimmed, results, matchOption, allowFreeEntry, commitOption, commitFree]);
-
-  const handleQueryChange = useCallback(
-    (next: string) => {
-      setQuery(next);
-      setInvalid(false);
-      if (isCommitted) onUncommit?.();
-    },
-    [isCommitted, onUncommit],
-  );
-
-  const clearCommitted = useCallback(() => {
-    onUncommit?.();
-    // Keep the committed text in the input for editing; focus so the
-    // user can immediately type.
-    inputRef.current?.focus();
-  }, [onUncommit]);
-
-  const handleKeyDown = (e: KeyboardEvent<HTMLInputElement>): void => {
-    if (isCommitted) return;
-    if (e.key === "ArrowDown") {
-      e.preventDefault();
-      setHighlight((h) => Math.min(h + 1, Math.max(totalEntries - 1, 0)));
-    } else if (e.key === "ArrowUp") {
-      e.preventDefault();
-      setHighlight((h) => Math.max(h - 1, 0));
-    } else if (e.key === "Enter") {
-      if (totalEntries > 0) {
-        e.preventDefault();
-        if (highlight < results.length) {
-          const chosen = results[highlight];
-          if (chosen) commitOption(chosen);
-        } else if (offerFree) {
-          commitFree(trimmed);
-        }
-      } else if (freeEntryOk) {
-        // No dropdown (e.g. search still in flight on a slow
-        // network) — Enter on a valid free entry commits directly.
-        e.preventDefault();
-        commitFree(trimmed);
-      }
-    } else if (e.key === "Escape") {
-      setQuery("");
-      setResults([]);
-      setInvalid(false);
-    }
-  };
-
-  const showDropdown =
-    focused && !isCommitted && (results.length > 0 || offerFree || (hasNoResults && !!emptyHint));
-
-  return (
-    <div
-      style={
-        bare
-          ? { position: "static", flex: "1 1 140px", minWidth: 140 }
-          : { position: "relative" }
-      }
-    >
-      <Input
-        ref={inputRef}
-        id={inputId}
-        aria-describedby={inputDescribedBy}
-        bare={bare}
-        label={label}
-        data-testid={`${testid}-input`}
-        value={query}
-        disabled={disabled}
-        onChange={(e) => handleQueryChange(e.target.value)}
-        onFocus={() => {
-          setFocused(true);
-          setInvalid(false);
-        }}
-        onBlur={handleBlur}
-        onKeyDown={handleKeyDown}
-        placeholder={placeholder}
-        autoFocus={autoFocus}
-        autoComplete="off"
-        error={invalid ? (invalidHint ?? COMBOBOX_DEFAULT_INVALID_HINT) : null}
-      />
-
-      {showDropdown ? (
-        <div
-          data-testid={`${testid}-dropdown`}
-          style={{
-            position: "absolute",
-            top: "100%",
-            marginTop: 4,
-            left: 0,
-            right: 0,
-            background: "var(--ck-bg-surface)",
-            border: "1px solid var(--ck-border-strong)",
-            borderRadius: "var(--ck-radius-sm)",
-            boxShadow: "var(--ck-shadow-menu, 0 4px 12px rgba(0,0,0,0.08))",
-            zIndex: 10,
-            overflow: "hidden",
-          }}
-        >
-          {results.map((row, i) => (
-            <button
-              key={row.key}
-              type="button"
-              onMouseDown={(e) => {
-                e.preventDefault();
-                commitOption(row);
-              }}
-              onMouseEnter={() => setHighlight(i)}
-              style={{
-                display: "block",
-                width: "100%",
-                textAlign: "left",
-                padding: "8px 12px",
-                border: "none",
-                background: i === highlight ? "var(--ck-bg-muted)" : "transparent",
-                cursor: "pointer",
-                font: "inherit",
-                fontSize: 13,
-                color: "var(--ck-text-primary)",
-              }}
-            >
-              <div style={{ fontWeight: 500 }}>{row.title}</div>
-              {row.subtitle ? (
-                <div style={{ fontSize: 12, color: "var(--ck-text-secondary)" }}>
-                  {row.subtitle}
-                </div>
-              ) : null}
-            </button>
-          ))}
-          {offerFree ? (
-            <button
-              type="button"
-              data-testid={`${testid}-free-entry`}
-              onMouseDown={(e) => {
-                e.preventDefault();
-                commitFree(trimmed);
-              }}
-              onMouseEnter={() => setHighlight(results.length)}
-              style={{
-                display: "block",
-                width: "100%",
-                textAlign: "left",
-                padding: "8px 12px",
-                border: "none",
-                background:
-                  highlight === results.length ? "var(--ck-bg-muted)" : "transparent",
-                borderTop: results.length > 0 ? "1px solid var(--ck-border-subtle)" : "none",
-                cursor: "pointer",
-                font: "inherit",
-                fontSize: 13,
-                color: "var(--ck-accent)",
-              }}
-            >
-              {freeEntryLabel ? freeEntryLabel(trimmed) : <>Use “{trimmed}”</>}
-            </button>
-          ) : hasNoResults && emptyHint ? (
-            <div style={{ padding: "8px 12px", fontSize: 12, color: "var(--ck-text-secondary)" }}>
-              {emptyHint}
-            </div>
-          ) : null}
-        </div>
-      ) : null}
-
-      {committed ? (
-        <div
-          data-testid={`${testid}-committed`}
-          style={{
-            marginTop: 8,
-            padding: "10px 12px",
-            background: "var(--ck-bg-muted)",
-            border: "1px solid var(--ck-border-subtle)",
-            borderRadius: "var(--ck-radius-sm)",
-            display: "flex",
-            alignItems: "flex-start",
-            gap: 8,
-          }}
-        >
-          <div style={{ flex: 1, minWidth: 0, display: "flex", flexDirection: "column", gap: 2 }}>
-            <div style={{ fontSize: 14, fontWeight: 500, color: "var(--ck-text-primary)" }}>
-              {committed.title}
-            </div>
-            {committed.subtitle ? (
-              <div style={{ fontSize: 12, color: "var(--ck-text-secondary)" }}>
-                {committed.subtitle}
-              </div>
-            ) : null}
-            {committedExtra ? <div style={{ marginTop: 6 }}>{committedExtra}</div> : null}
-          </div>
-          {onUncommit ? (
-            <button
-              type="button"
-              aria-label="Clear selection"
-              data-testid={`${testid}-clear`}
-              onClick={clearCommitted}
-              style={{
-                border: "none",
-                background: "none",
-                cursor: "pointer",
-                color: "var(--ck-text-secondary)",
-                fontSize: 14,
-                lineHeight: 1,
-                padding: 2,
-                flexShrink: 0,
-              }}
-            >
-              ×
-            </button>
-          ) : null}
-        </div>
-      ) : null}
-    </div>
-  );
-});

package/src/primitives/CopyField.tsx

@@ -1,139 +0,0 @@
-import { forwardRef, useCallback, useRef, useState, type HTMLAttributes, type ReactNode } from "react";
-import { cn } from "../lib/cn";
-
-// CopyField — read-only value field with an embedded Copy button.
-//
-// One bordered frame (same 36px field chrome as Input-with-addon):
-// the value renders mono + ellipsized on the left, the Copy button
-// sits INSIDE the frame flush right on a muted slab (mirrors Input's
-// suffix addon). Clicking copies to the clipboard and flips the
-// label to "Copied ✓" for a beat; clicking the value text selects it
-// (manual-copy fallback for non-secure origins where the Clipboard
-// API is unavailable).
-//
-// Use for share links, signing URLs, tokens, API keys — anywhere the
-// user's next action is overwhelmingly "copy this". Compose with:
-// dialog bodies (share link rows), sidebar token reveals, settings
-// pages (API-key display).
-//
-// Forwards ref to the copy <button>. Spreads `...rest` on the frame
-// so consumers can pass data-* / aria-* / style / className.
-
-export interface CopyFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, "onCopy"> {
-  // The string shown + copied. Rendered mono, single-line, ellipsized.
-  value: string;
-  // Copy-button label; flips to `copiedLabel` after a click.
-  copyLabel?: ReactNode;
-  copiedLabel?: ReactNode;
-  // How long the copied state lingers before flipping back (ms).
-  copiedForMs?: number;
-  // Notified after a successful clipboard write. Clipboard failures
-  // are silent by design — the value stays selectable in the field.
-  onCopied?: (value: string) => void;
-}
-
-export const CopyField = forwardRef<HTMLButtonElement, CopyFieldProps>(function CopyField(
-  {
-    value,
-    copyLabel = "Copy",
-    copiedLabel = "Copied ✓",
-    copiedForMs = 1500,
-    onCopied,
-    className,
-    style,
-    ...rest
-  },
-  ref,
-) {
-  const [copied, setCopied] = useState(false);
-  const valueRef = useRef<HTMLElement | null>(null);
-
-  const handleCopy = useCallback(() => {
-    void navigator.clipboard
-      ?.writeText(value)
-      .then(() => onCopied?.(value))
-      .catch(() => {
-        // Clipboard rejected (permissions / non-secure origin). The
-        // value stays visible + selectable in the field — no error UI.
-      });
-    setCopied(true);
-    window.setTimeout(() => setCopied(false), copiedForMs);
-  }, [value, copiedForMs, onCopied]);
-
-  // Click-to-select on the value — the manual-copy fallback.
-  const handleSelectAll = useCallback(() => {
-    const node = valueRef.current;
-    if (!node) return;
-    const range = document.createRange();
-    range.selectNodeContents(node);
-    const sel = window.getSelection();
-    sel?.removeAllRanges();
-    sel?.addRange(range);
-  }, []);
-
-  return (
-    <div
-      {...rest}
-      className={cn("ck-copy-field", className)}
-      style={{
-        display: "flex",
-        alignItems: "stretch",
-        height: 36,
-        background: "var(--ck-bg-surface)",
-        border: "1px solid var(--ck-border-strong)",
-        borderRadius: "var(--ck-radius-sm)",
-        overflow: "hidden",
-        minWidth: 0,
-        ...(style ?? {}),
-      }}
-    >
-      <code
-        ref={valueRef}
-        title={value}
-        onClick={handleSelectAll}
-        style={{
-          flex: 1,
-          minWidth: 0,
-          alignSelf: "center",
-          padding: "0 12px",
-          font: "400 12px/1.5 var(--ck-font-mono, ui-monospace, monospace)",
-          color: "var(--ck-text-primary)",
-          whiteSpace: "nowrap",
-          overflow: "hidden",
-          textOverflow: "ellipsis",
-          cursor: "text",
-        }}
-      >
-        {value}
-      </code>
-      <button
-        ref={ref}
-        type="button"
-        onClick={handleCopy}
-        disabled={copied}
-        className="ck-copy-field-btn"
-        style={{
-          flex: "0 0 auto",
-          display: "inline-flex",
-          alignItems: "center",
-          justifyContent: "center",
-          padding: "0 14px",
-          // Reserve the wider copied-label footprint so the value
-          // column doesn't shift mid-flash.
-          minWidth: 84,
-          border: "none",
-          borderLeft: "1px solid var(--ck-border-strong)",
-          background: "var(--ck-bg-muted)",
-          color: copied ? "var(--ck-text-secondary)" : "var(--ck-text-primary)",
-          font: "500 11px/1 var(--ck-font-sans)",
-          letterSpacing: "0.04em",
-          textTransform: "uppercase",
-          cursor: copied ? "default" : "pointer",
-          transition: "color var(--ck-dur-fast) var(--ck-ease)",
-        }}
-      >
-        {copied ? copiedLabel : copyLabel}
-      </button>
-    </div>
-  );
-});

package/src/primitives/CountBadge.tsx

@@ -1,50 +0,0 @@
-import { cn } from "../lib/cn";
-
-// Small filled pill showing an integer count. Caps at 99+ to keep
-// the visual mass tight. Returns null at 0 — call sites can
-// unconditionally render it inside a label without an `if (n > 0)`.
-
-export interface CountBadgeProps {
-  count: number;
-  size?: "sm" | "md";
-  // Tone — default accent. Use "critical" for notifications.
-  tone?: "accent" | "critical" | "neutral";
-  className?: string;
-}
-
-const TONE_BG: Record<NonNullable<CountBadgeProps["tone"]>, string> = {
-  accent: "var(--ck-accent)",
-  critical: "var(--ck-critical)",
-  neutral: "var(--ck-text-tertiary)",
-};
-
-export function CountBadge({
-  count,
-  size = "md",
-  tone = "accent",
-  className,
-}: CountBadgeProps) {
-  if (count <= 0) return null;
-  const display = count > 99 ? "99+" : String(count);
-  const isSm = size === "sm";
-  return (
-    <span
-      className={cn("ck-count-badge", className)}
-      style={{
-        display: "inline-flex",
-        alignItems: "center",
-        justifyContent: "center",
-        minWidth: isSm ? 14 : 18,
-        height: isSm ? 14 : 18,
-        padding: "0 5px",
-        background: TONE_BG[tone],
-        color: "var(--ck-text-inverse)",
-        font: `500 ${isSm ? 10 : 11}px/1 var(--ck-font-mono)`,
-        borderRadius: 999,
-        fontVariantNumeric: "tabular-nums",
-      }}
-    >
-      {display}
-    </span>
-  );
-}