@cosxai/ui 0.15.1 → 0.17.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cosxai/ui",
-  "version": "0.15.1",
-  "description": "COSX design system — React 19 component primitives shared across product-meta and other consumers",
+  "version": "0.17.0",
+  "description": "COSX design system \u2014 React 19 component primitives shared across product-meta and other consumers",
   "license": "UNLICENSED",
   "type": "module",
   "main": "./src/index.ts",

package/src/actionbar/ActionBar.tsx

@@ -1,6 +1,7 @@
 import {
   useCallback,
   useContext,
+  useLayoutEffect,
   useEffect,
   useMemo,
   useRef,
@@ -154,7 +155,7 @@ export function ActionBar({
   if (!ctx) {
     throw new Error("<ActionBar> must be inside <ActionBarProvider>");
   }
-  const { items, categories, expandedKey, setExpandedKey, statusDot } = ctx;
+  const { items, categories, expandedKey, setExpandedKey, statusDot, panel, toast } = ctx;
   const vp = useViewport();
   const isPhone = vp.isPhone;
 
@@ -382,6 +383,42 @@ export function ActionBar({
     );
   }
 
+  // ----- Panel slot (design#13): outside-click + Escape close. -----
+  const panelOpen = Boolean(panel?.open);
+  const panelClose = panel?.onOpenChange;
+  useEffect(() => {
+    if (!panelOpen || !panelClose) return;
+    const onDown = (e: MouseEvent) => {
+      const t = e.target as Node | null;
+      if (t && barRef.current?.contains(t)) return;
+      panelClose(false);
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") panelClose(false);
+    };
+    window.addEventListener("mousedown", onDown);
+    window.addEventListener("keydown", onKey);
+    return () => {
+      window.removeEventListener("mousedown", onDown);
+      window.removeEventListener("keydown", onKey);
+    };
+  }, [panelOpen, panelClose]);
+
+  // Horizontal clamp: centred on the bar unless that would push the
+  // panel past a viewport edge — then shift just enough to fit.
+  const panelRef = useRef<HTMLDivElement | null>(null);
+  useLayoutEffect(() => {
+    if (!panelOpen) return;
+    const el = panelRef.current;
+    if (!el) return;
+    el.style.marginLeft = "0px";
+    const rect = el.getBoundingClientRect();
+    let shift = 0;
+    if (rect.left < 8) shift = 8 - rect.left;
+    else if (rect.right > window.innerWidth - 8) shift = window.innerWidth - 8 - rect.right;
+    if (shift !== 0) el.style.marginLeft = `${Math.round(shift)}px`;
+  }, [panelOpen, pos]);
+
   // ----- Full bar -----
   const isDefault = pos.type === "default";
   return (
@@ -437,6 +474,44 @@ export function ActionBar({
         ...style,
       }}
     >
+      {/* Panel slot (design#13) — the bar positions + the chrome
+          themes style it (.ck-actionbar-panel); consumers own only
+          the content. Rendered inside the bar root so it follows
+          drags natively. */}
+      {panel?.open && (
+        <div
+          ref={panelRef}
+          className="ck-actionbar-panel"
+          role="region"
+          aria-label={panel.ariaLabel ?? "Panel"}
+          style={{
+            position: "absolute",
+            bottom: "calc(100% + 8px)",
+            left: "50%",
+            transform: "translateX(-50%)",
+            width: panel.width ?? 320,
+            maxWidth: "calc(100vw - 16px)",
+            cursor: "default",
+          }}
+        >
+          {panel.content}
+        </div>
+      )}
+      {toast != null && !panel?.open && (
+        <div
+          className="ck-actionbar-toast"
+          role="status"
+          style={{
+            position: "absolute",
+            bottom: "calc(100% + 8px)",
+            left: "50%",
+            transform: "translateX(-50%)",
+            whiteSpace: "nowrap",
+          }}
+        >
+          {toast}
+        </div>
+      )}
       {/* Left-edge button. Phone = collapse; desktop = drag grip. */}
       {isPhone && collapsibleOnPhone ? (
         <button

package/src/actionbar/ActionBarProvider.tsx

@@ -1,6 +1,6 @@
 import { useCallback, useMemo, useState, type ReactNode } from "react";
 import { ActionBarContext } from "./actionbar-context";
-import type { ActionBarItem, ActionBarCategories, ActionBarStatusDot } from "./types";
+import type { ActionBarItem, ActionBarCategories, ActionBarStatusDot, ActionBarPanel } from "./types";
 
 // Provider for the action-bar registry + expansion state +
 // category catalog. Mount once near the app root, inside the
@@ -24,6 +24,8 @@ export function ActionBarProvider({
   const [sources, setSources] = useState<Record<string, ActionBarItem[]>>({});
   const [expandedKey, setExpandedKey] = useState<string | null>(null);
   const [statusDot, setStatusDot] = useState<ActionBarStatusDot | null>(null);
+  const [panel, setPanel] = useState<ActionBarPanel | null>(null);
+  const [toast, setToast] = useState<ReactNode | null>(null);
 
   const register = useCallback((sourceKey: string, items: ActionBarItem[]) => {
     setSources((prev) => {
@@ -67,8 +69,12 @@ export function ActionBarProvider({
       setExpandedKey,
       statusDot,
       setStatusDot,
+      panel,
+      setPanel,
+      toast,
+      setToast,
     }),
-    [register, unregister, items, categories, expandedKey, statusDot],
+    [register, unregister, items, categories, expandedKey, statusDot, panel, toast],
   );
 
   return (

package/src/actionbar/actionbar-context.ts

@@ -1,5 +1,6 @@
 import { createContext } from "react";
-import type { ActionBarItem, ActionBarCategories, ActionBarStatusDot } from "./types";
+import type { ReactNode } from "react";
+import type { ActionBarItem, ActionBarCategories, ActionBarStatusDot, ActionBarPanel } from "./types";
 
 // Registry + expansion + category catalog + status-dot slot. Items are
 // pushed by pages through useActionBarItems(); the status dot is
@@ -23,6 +24,13 @@ export interface ActionBarContextValue {
   // has registered one. Last call to setStatusDot wins.
   statusDot: ActionBarStatusDot | null;
   setStatusDot: (dot: ActionBarStatusDot | null) => void;
+  // Bar-intrinsic popover slot (design#13). Registered by
+  // useActionBarPanel; the bar positions + themes it.
+  panel: ActionBarPanel | null;
+  setPanel: (panel: ActionBarPanel | null) => void;
+  // Transient bubble above the bar (completion toasts etc.).
+  toast: ReactNode | null;
+  setToast: (toast: ReactNode | null) => void;
 }
 
 export const ActionBarContext = createContext<ActionBarContextValue | null>(null);

package/src/actionbar/index.ts

@@ -6,6 +6,8 @@ export { ActionBarButton } from "./ActionBarButton";
 export type { ActionBarButtonProps } from "./ActionBarButton";
 export { useActionBarItems, useActionBarItemsContext } from "./useActionBarItems";
 export { useActionBarStatusDot } from "./useActionBarStatusDot";
+export { useActionBarPanel } from "./useActionBarPanel";
+export { useActionBarToast } from "./useActionBarToast";
 export { ActionBarModeHandle } from "./ActionBarModeHandle";
 export type { ActionBarModeHandleProps } from "./ActionBarModeHandle";
 export { useActionBarMode } from "./useActionBarMode";
@@ -19,6 +21,7 @@ export type {
   ActionBarItemVariant,
   ActionBarItemSlot,
   ActionBarStatusDot,
+  ActionBarPanel,
   ActionBarCategory,
   ActionBarCategories,
 } from "./types";

package/src/actionbar/types.ts

@@ -117,3 +117,22 @@ export interface ActionBarStatusDot {
   // pulsing reads as attention-grabbing.
   pulse?: boolean;
 }
+
+// Registered via `useActionBarPanel()` — the bar-intrinsic popover
+// slot (design#13). The BAR owns positioning (docked above itself,
+// following drag natively) and the chrome themes own the panel's
+// visual identity via `.ck-actionbar-panel`; the consumer owns only
+// the content subtree. One panel at a time (last call wins).
+export interface ActionBarPanel {
+  // Controlled visibility. The bar calls onOpenChange(false) on
+  // outside-click and Escape; the consumer toggles open from its
+  // own affordance (typically the status dot's onClick).
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  // Content subtree. Rendered inside the themed panel container.
+  content: ReactNode;
+  // Panel width in px. Default 320; always viewport-clamped.
+  width?: number;
+  // aria-label for the panel region. Default "Panel".
+  ariaLabel?: string;
+}

package/src/actionbar/useActionBarPanel.ts

@@ -0,0 +1,46 @@
+import { useContext, useEffect } from "react";
+import { ActionBarContext } from "./actionbar-context";
+import type { ActionBarPanel } from "./types";
+
+// Push a panel config into the action bar's popover slot (design#13).
+//
+// The BAR owns positioning: docked above itself, centered, following
+// drag natively (it renders the panel inside its own fixed-position
+// root — no polling, no rect maths in the consumer) and viewport-
+// clamped at the edges. The chrome themes own the panel's visual
+// identity via `.ck-actionbar-panel`; consumers must NOT paint their
+// own background/border/shadow. The consumer owns only the content
+// subtree and the `open` state.
+//
+// The bar calls `onOpenChange(false)` on outside-click and Escape.
+// Pass `null` to clear (also cleared automatically on unmount).
+// Last call wins — one panel at a time, same contract as the status
+// dot.
+export function useActionBarPanel(config: ActionBarPanel | null) {
+  const ctx = useContext(ActionBarContext);
+  if (!ctx) {
+    throw new Error("useActionBarPanel must be used within <ActionBarProvider>");
+  }
+  const { setPanel } = ctx;
+  const open = config?.open;
+  const onOpenChange = config?.onOpenChange;
+  const content = config?.content;
+  const width = config?.width;
+  const ariaLabel = config?.ariaLabel;
+  useEffect(() => {
+    if (open === undefined || onOpenChange === undefined) {
+      setPanel(null);
+      return;
+    }
+    setPanel({
+      open,
+      onOpenChange,
+      content,
+      ...(width !== undefined ? { width } : {}),
+      ...(ariaLabel !== undefined ? { ariaLabel } : {}),
+    });
+    return () => {
+      setPanel(null);
+    };
+  }, [setPanel, open, onOpenChange, content, width, ariaLabel]);
+}

package/src/actionbar/useActionBarToast.ts

@@ -0,0 +1,23 @@
+import { useContext, useEffect } from "react";
+import type { ReactNode } from "react";
+import { ActionBarContext } from "./actionbar-context";
+
+// Push a transient bubble into the bar's toast slot — rendered above
+// the bar (following it when dragged), themed via
+// `.ck-actionbar-toast`. The CONSUMER owns the lifetime: pass the
+// node to show, `null` to hide (typically driven by a setTimeout in
+// the consumer). Pairs with useActionBarPanel for the notification-
+// center pattern (design#13).
+export function useActionBarToast(content: ReactNode | null) {
+  const ctx = useContext(ActionBarContext);
+  if (!ctx) {
+    throw new Error("useActionBarToast must be used within <ActionBarProvider>");
+  }
+  const { setToast } = ctx;
+  useEffect(() => {
+    setToast(content ?? null);
+    return () => {
+      setToast(null);
+    };
+  }, [setToast, content]);
+}

package/src/primitives/Combobox.tsx

@@ -0,0 +1,430 @@
+import {
+  useCallback,
+  useEffect,
+  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[]>;
+  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;
+  testid?: string | undefined;
+}
+
+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 function Combobox({
+  label,
+  placeholder,
+  autoFocus,
+  disabled,
+  search,
+  debounceMs = DEFAULT_DEBOUNCE_MS,
+  allowFreeEntry,
+  freeEntryLabel,
+  emptyHint,
+  invalidHint,
+  matchOption = defaultMatch,
+  committed,
+  committedExtra,
+  onCommit,
+  onUncommit,
+  testid = "combobox",
+}: ComboboxProps): ReactNode {
+  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;
+
+  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.
+    if (!query.trim() || isCommitted) {
+      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]);
+
+  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.
+      setQuery(option.subtitle ?? option.title);
+      onCommit({ kind: "option", option });
+    },
+    [onCommit],
+  );
+
+  const commitFree = useCallback(
+    (raw: string) => {
+      setInvalid(false);
+      setResults([]);
+      setHighlight(0);
+      setQuery(raw);
+      onCommit({ kind: "free", raw });
+    },
+    [onCommit],
+  );
+
+  // 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(() => {
+      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={{ position: "relative" }}>
+      <Input
+        ref={inputRef}
+        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 ?? "Pick from the list to continue.") : 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/index.ts

@@ -14,6 +14,13 @@ export { Input } from "./Input";
 export type { InputProps } from "./Input";
 export { Select } from "./Select";
 export type { SelectProps, SelectOption } from "./Select";
+export { Combobox } from "./Combobox";
+export type {
+  ComboboxProps,
+  ComboboxOption,
+  ComboboxCommit,
+  ComboboxCommitted,
+} from "./Combobox";
 export { Textarea } from "./Textarea";
 export type { TextareaProps } from "./Textarea";
 export { Checkbox } from "./Checkbox";

package/src/styles/base.css

@@ -122,3 +122,30 @@ a:visited { color: var(--ck-accent); }
 :root {
   scrollbar-color: var(--ck-border-strong, rgba(0, 0, 0, 0.25)) transparent;
 }
+
+/* ── ActionBar panel + toast slots (design#13) ─────────────────────
+   Base chrome for the bar-intrinsic popover (useActionBarPanel) and
+   transient bubble (useActionBarToast). Token-driven so every theme
+   reads correctly by default; chrome-*.css sharpens identity themes
+   (neobrutalism ink shadows, sketch wobble, terminal flatness). */
+.ck-actionbar-panel {
+  background: var(--ck-bg-surface, #fff);
+  border: 1px solid var(--ck-border-subtle, #e5e7eb);
+  border-radius: 12px;
+  box-shadow: var(--ck-shadow-3, 0 16px 48px rgba(0, 0, 0, 0.12));
+  padding: 16px;
+  font-family: var(--ck-font-sans, system-ui, sans-serif);
+  color: var(--ck-text-primary);
+  user-select: none;
+}
+.ck-actionbar-toast {
+  background: var(--ck-bg-surface, #fff);
+  border: 1px solid var(--ck-border-subtle, #e5e7eb);
+  border-radius: 10px;
+  box-shadow: var(--ck-shadow-3, 0 16px 48px rgba(0, 0, 0, 0.12));
+  padding: 10px 14px;
+  font-size: 12px;
+  font-family: var(--ck-font-sans, system-ui, sans-serif);
+  color: var(--ck-text-primary);
+  user-select: none;
+}

package/src/styles/chrome-ambient.css

@@ -223,3 +223,13 @@ html[data-ck-chrome="ambient"] [role="dialog"] > div > div {
     transition: none !important;
   }
 }
+
+html[data-ck-chrome="ambient"] .ck-actionbar-panel,
+html[data-ck-chrome="ambient"] .ck-actionbar-toast {
+  background: var(--ck-bg-sidebar);
+  backdrop-filter: var(--ck-blur-overlay);
+  -webkit-backdrop-filter: var(--ck-blur-overlay);
+  border: 1px solid var(--ck-border-subtle);
+  border-radius: 20px;
+  box-shadow: var(--ck-shadow-2);
+}

package/src/styles/chrome-bento.css

@@ -182,3 +182,11 @@ html[data-ck-chrome="bento"] [data-ck-bento-cell][data-interactive="true"]:hover
   transform: translateY(-3px);
   box-shadow: var(--ck-shadow-3);
 }
+
+html[data-ck-chrome="bento"] .ck-actionbar-panel,
+html[data-ck-chrome="bento"] .ck-actionbar-toast {
+  background: var(--ck-bg-surface);
+  border: 1px solid var(--ck-border-subtle);
+  border-radius: 16px;
+  box-shadow: var(--ck-shadow-2);
+}

package/src/styles/chrome-editorial.css

@@ -158,3 +158,11 @@ html[data-ck-chrome="editorial"] [role="dialog"] > div:first-child {
 [data-ck-spotlight] .ck-card .ck-tag {
   color: var(--ck-text-secondary);
 }
+
+/* ActionBar panel/toast — flat paper, hairline, no drop glow. */
+html[data-ck-chrome="editorial"] .ck-actionbar-panel,
+html[data-ck-chrome="editorial"] .ck-actionbar-toast {
+  background: var(--ck-bg-surface);
+  border-color: var(--ck-border-subtle);
+  box-shadow: var(--ck-shadow-1, 0 2px 8px rgba(0, 0, 0, 0.06));
+}

package/src/styles/chrome-neobrutalism.css

@@ -316,3 +316,11 @@ html[data-ck-chrome="neobrutalism"] [role="switch"] {
     box-shadow: 4px 4px 0 0 var(--neobrut-ink);
   }
 }
+
+html[data-ck-chrome="neobrutalism"] .ck-actionbar-panel,
+html[data-ck-chrome="neobrutalism"] .ck-actionbar-toast {
+  border: 2px solid var(--neobrut-ink);
+  border-radius: 5px;
+  box-shadow: 4px 4px 0 0 var(--neobrut-ink);
+  background: var(--ck-bg-surface);
+}

package/src/styles/chrome-riso.css

@@ -329,3 +329,11 @@ html[data-ck-chrome="riso"] hr {
 }
 .ck-riso-marks::before { top: 4px; left: 8px; }
 .ck-riso-marks::after  { bottom: 4px; right: 8px; }
+
+html[data-ck-chrome="riso"] .ck-actionbar-panel,
+html[data-ck-chrome="riso"] .ck-actionbar-toast {
+  background: var(--ck-bg-surface);
+  border: 2px solid var(--ck-text-primary);
+  border-radius: 4px;
+  box-shadow: 5px 5px 0 var(--ck-riso-blue);
+}

package/src/styles/chrome-sketch.css

@@ -352,3 +352,11 @@ html[data-ck-chrome="sketch"] hr {
     stroke-dasharray: none;
   }
 }
+
+html[data-ck-chrome="sketch"] .ck-actionbar-panel,
+html[data-ck-chrome="sketch"] .ck-actionbar-toast {
+  background: var(--ck-bg-surface);
+  border: 2px solid var(--ck-text-primary);
+  border-radius: 14px 18px 16px 20px / 18px 14px 20px 16px;
+  box-shadow: 4px 5px 0 var(--ck-text-primary);
+}

package/src/styles/chrome-swiss.css

@@ -255,3 +255,11 @@ html[data-ck-chrome="swiss"] a {
   text-underline-offset: 3px;
   text-decoration-thickness: 1px;
 }
+
+html[data-ck-chrome="swiss"] .ck-actionbar-panel,
+html[data-ck-chrome="swiss"] .ck-actionbar-toast {
+  background: var(--ck-bg-canvas);
+  border: 1px solid var(--ck-border-subtle);
+  border-radius: 0;
+  box-shadow: var(--ck-shadow-1, 0 2px 8px rgba(0, 0, 0, 0.08));
+}

package/src/styles/chrome-terminal.css

@@ -261,3 +261,12 @@ html[data-ck-chrome="terminal"] [role="dialog"] > div > div {
   box-shadow: none;
   font-family: var(--ck-font-mono);
 }
+
+html[data-ck-chrome="terminal"] .ck-actionbar-panel,
+html[data-ck-chrome="terminal"] .ck-actionbar-toast {
+  background: var(--ck-bg-surface);
+  border: 1px solid var(--ck-border-subtle);
+  border-radius: 2px;
+  box-shadow: none;
+  font-family: var(--ck-font-mono);
+}