@cosxai/ui 0.23.2 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosxai/ui",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "description": "COSX design system \u2014 React 19 component primitives shared across product-meta and other consumers",
   "license": "UNLICENSED",
   "type": "module",

package/src/layout/LeftNavRail.tsx

@@ -15,6 +15,13 @@ export interface LeftNavRailProps {
   brand?: ReactNode;
   children: ReactNode;
   footer?: ReactNode;
+  /**
+   * footerTop — a block pinned BETWEEN the scrolling nav area and the
+   * footer rule: always visible, above the divider, immune to a long
+   * menu (the nav list scrolls above it). The agent drawer's trigger
+   * is the motivating case.
+   */
+  footerTop?: ReactNode;
   collapsed?: boolean;
   // Expanded / collapsed widths in px. Defaults 256 / 56.
   widthExpanded?: number;
@@ -28,6 +35,7 @@ export function LeftNavRail({
   brand,
   children,
   footer,
+  footerTop,
   collapsed = false,
   widthExpanded = 256,
   widthCollapsed = 56,
@@ -111,6 +119,11 @@ export function LeftNavRail({
       >
         {children}
       </div>
+      {footerTop && (
+        <div style={{ padding: collapsed ? "4px 4px 8px" : "4px 8px 12px", flexShrink: 0 }}>
+          {footerTop}
+        </div>
+      )}
       {footer && (
         <div
           style={{

package/src/primitives/Chip.tsx

@@ -0,0 +1,177 @@
+import { forwardRef, type CSSProperties, type HTMLAttributes, type ReactNode } from "react";
+
+import { cn } from "../lib/cn";
+
+/**
+ * Chip — a compact pill representing one selected value (a recipient,
+ * a filter, a tag the user picked). Exists so multi-value inputs
+ * (MultiCombobox) and token lists share one removable-item shape
+ * instead of each product hand-rolling a "name ×" span.
+ *
+ * Distinct from `Tag` (uppercase mono STATUS label — "PENDING",
+ * "LIVE"): a Chip is sentence-case body text (13px sans), a pill on a
+ * muted slab, and is interactive — optional `onClick` turns the label
+ * into a button (e.g. "edit this entry"), optional `onRemove` adds
+ * the × button.
+ *
+ * Tones: `neutral` (default), `accent`, `warning` (e.g. "needs a
+ * name"), `critical`. `selected` outlines the chip in the accent
+ * colour (e.g. the entry currently being edited). `disabled` dims the
+ * chip and disables both buttons.
+ *
+ * Compose with: MultiCombobox (entry row), filter bars, recipient
+ * lists on detail pages.
+ *
+ * Visual: see docs/components/multi-combobox.
+ *
+ * Forwards ref to the root <span>. Spreads `...rest` onto it so
+ * consumers can pass data-* / aria-* / title / style. Chrome presets
+ * can restyle via the `[data-ck-chip]` / `data-tone` / `data-selected`
+ * hooks — 0.24.0 ships no per-chrome CSS for it.
+ */
+
+export type ChipTone = "neutral" | "accent" | "warning" | "critical";
+
+export type ChipProps = Omit<HTMLAttributes<HTMLSpanElement>, "onClick"> & {
+  children: ReactNode;
+  tone?: ChipTone | undefined;
+  // Outline the chip in the accent colour (e.g. "being edited").
+  selected?: boolean | undefined;
+  // Dim + disable both the label button and the remove button.
+  disabled?: boolean | undefined;
+  // When set, the label renders as a <button> (e.g. click-to-edit).
+  onClick?: (() => void) | undefined;
+  // When set, a × button renders after the label.
+  onRemove?: (() => void) | undefined;
+  // aria-label for the × button. Default "Remove".
+  removeLabel?: string | undefined;
+  className?: string | undefined;
+};
+
+const TONE_FG: Record<ChipTone, string> = {
+  neutral: "var(--ck-text-primary, #111)",
+  accent: "var(--ck-accent, #4f46e5)",
+  warning: "var(--ck-warning, #D97706)",
+  critical: "var(--ck-critical, #DC2626)",
+};
+const TONE_BG: Record<ChipTone, string> = {
+  neutral: "var(--ck-bg-muted, #E5E8EE)",
+  accent: "var(--ck-accent-muted, rgba(79, 70, 229, 0.08))",
+  warning: "var(--ck-warning-muted, #FEF3E7)",
+  critical: "var(--ck-critical-muted, #FCEAEA)",
+};
+const TONE_BORDER: Record<ChipTone, string> = {
+  neutral: "var(--ck-border-subtle, #DDE0E6)",
+  accent: "var(--ck-accent-border, rgba(79, 70, 229, 0.35))",
+  warning: "color-mix(in oklab, var(--ck-warning, #D97706) 35%, transparent)",
+  critical: "color-mix(in oklab, var(--ck-critical, #DC2626) 35%, transparent)",
+};
+
+// Label text styles — shared by the <span> and <button> renderings so
+// the chip looks identical whether or not it is clickable.
+const LABEL_STYLE: CSSProperties = {
+  minWidth: 0,
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+  whiteSpace: "nowrap",
+  font: "inherit",
+  color: "inherit",
+  background: "none",
+  border: "none",
+  padding: 0,
+  margin: 0,
+  textAlign: "left",
+};
+
+export const Chip = forwardRef<HTMLSpanElement, ChipProps>(function Chip(
+  {
+    children,
+    tone = "neutral",
+    selected = false,
+    disabled = false,
+    onClick,
+    onRemove,
+    removeLabel,
+    className,
+    style,
+    ...rest
+  },
+  ref,
+) {
+  const clickable = !!onClick && !disabled;
+  return (
+    <span
+      ref={ref}
+      className={cn("ck-chip", className)}
+      data-ck-chip
+      data-tone={tone}
+      data-selected={selected ? "true" : undefined}
+      data-disabled={disabled ? "true" : undefined}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 4,
+        maxWidth: "100%",
+        boxSizing: "border-box",
+        padding: onRemove ? "3px 6px 3px 10px" : "3px 10px",
+        borderRadius: 999,
+        background: TONE_BG[tone],
+        border: `1px solid ${selected ? "var(--ck-accent, #4f46e5)" : TONE_BORDER[tone]}`,
+        boxShadow: selected ? "0 0 0 2px var(--ck-accent-muted, rgba(79, 70, 229, 0.12))" : "none",
+        font: "500 13px/1.3 var(--ck-font-sans, system-ui, sans-serif)",
+        color: TONE_FG[tone],
+        opacity: disabled ? 0.5 : 1,
+        cursor: disabled ? "default" : undefined,
+        transition: "border-color var(--ck-dur-fast, 120ms) var(--ck-ease, ease)",
+        ...style,
+      }}
+      {...rest}
+    >
+      {onClick ? (
+        <button
+          type="button"
+          className="ck-chip-label"
+          onClick={onClick}
+          disabled={disabled}
+          style={{ ...LABEL_STYLE, cursor: clickable ? "pointer" : "default" }}
+        >
+          {children}
+        </button>
+      ) : (
+        <span className="ck-chip-label" style={LABEL_STYLE}>
+          {children}
+        </span>
+      )}
+      {onRemove ? (
+        <button
+          type="button"
+          className="ck-chip-remove"
+          aria-label={removeLabel ?? "Remove"}
+          onClick={onRemove}
+          disabled={disabled}
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            justifyContent: "center",
+            width: 16,
+            height: 16,
+            flexShrink: 0,
+            padding: 0,
+            margin: 0,
+            border: "none",
+            borderRadius: 999,
+            background: "none",
+            color: "inherit",
+            opacity: 0.7,
+            font: "inherit",
+            fontSize: 14,
+            lineHeight: 1,
+            cursor: disabled ? "default" : "pointer",
+          }}
+        >
+          ×
+        </button>
+      ) : null}
+    </span>
+  );
+});

package/src/primitives/Combobox.tsx

@@ -1,6 +1,8 @@
 import {
+  forwardRef,
   useCallback,
   useEffect,
+  useImperativeHandle,
   useRef,
   useState,
   type KeyboardEvent,
@@ -96,9 +98,23 @@ export interface ComboboxProps {
   // 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;
   testid?: string | undefined;
 }
 
+// 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 {
@@ -109,7 +125,8 @@ function defaultMatch(raw: string, option: ComboboxOption): boolean {
   );
 }
 
-export function Combobox({
+export const Combobox = forwardRef<ComboboxHandle, ComboboxProps>(function Combobox(
+  {
   label,
   placeholder,
   autoFocus,
@@ -126,8 +143,11 @@ export function Combobox({
   committedExtra,
   onCommit,
   onUncommit,
+  clearOnCommit = false,
   testid = "combobox",
-}: ComboboxProps): ReactNode {
+  },
+  ref,
+) {
   const [query, setQuery] = useState("");
   const [results, setResults] = useState<ComboboxOption[]>([]);
   const [loading, setLoading] = useState(false);
@@ -141,6 +161,20 @@ export function Combobox({
 
   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
@@ -191,11 +225,13 @@ export function Combobox({
       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);
+      // 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],
+    [onCommit, clearOnCommit],
   );
 
   const commitFree = useCallback(
@@ -203,10 +239,10 @@ export function Combobox({
       setInvalid(false);
       setResults([]);
       setHighlight(0);
-      setQuery(raw);
+      setQuery(clearOnCommit ? "" : raw);
       onCommit({ kind: "free", raw });
     },
-    [onCommit],
+    [onCommit, clearOnCommit],
   );
 
   // Blur auto-commit — the fix for "typed it, tabbed on, looked
@@ -436,4 +472,4 @@ export function Combobox({
       ) : null}
     </div>
   );
-}
+});

package/src/primitives/MultiCombobox.tsx

@@ -0,0 +1,179 @@
+import { forwardRef, useRef, type KeyboardEvent, type ReactNode } from "react";
+
+import { Chip, type ChipTone } from "./Chip";
+import { Combobox, type ComboboxHandle, type ComboboxProps } from "./Combobox";
+
+/**
+ * MultiCombobox — a Combobox that collects MANY values. The embedded
+ * search input clears after every commit (`clearOnCommit`) and the
+ * parent renders what it collected as a row of removable Chips below
+ * the field. Exists so recipient lists (group share links: one URL,
+ * N emails) and similar "pick several people / things" fields share
+ * one interaction model with the single-value Combobox — same async
+ * search, same free-entry gate, same blur auto-commit.
+ *
+ * Like Combobox, the value is PARENT-OWNED: `onCommit` hands the
+ * parent each pick / free entry, the parent maps it onto its own
+ * domain state and passes back `entries` for display. Splitting a
+ * pasted "a@x.co, b@x.co" into several entries is the parent's job
+ * inside `onCommit` (`allowFreeEntry` sees the whole raw string).
+ *
+ * Per entry: `title` (chip text), `subtitle` (native tooltip),
+ * `tone` (e.g. `warning` for "still needs a name"), `editing` — the
+ * one entry currently being edited renders `selected` and, when
+ * `renderEntryEditor` is given, its editor mounts under the chip row
+ * (the parent owns the editor's state; use the forwarded handle's
+ * `focus()` to hand focus back to the search input when it closes).
+ *
+ * Keyboard: Backspace in the EMPTY search input removes the last
+ * entry (`backspaceRemovesLast`, default true). The check is scoped
+ * to the embedded Combobox's input, so Backspace inside an entry
+ * editor never removes anything.
+ *
+ * Compose with: Chip (entries), Input (inside `renderEntryEditor`),
+ * dialogs collecting recipients.
+ *
+ * Visual: see docs/components/multi-combobox.
+ *
+ * Forwards a `MultiComboboxHandle` (= `ComboboxHandle`): `focus()`
+ * the search input, `clear()` its text (e.g. after rejecting a
+ * duplicate). Testids (from `testid`, default "multi-combobox"):
+ * `${testid}` wrapper, `${testid}-combobox-input` / `-dropdown` /
+ * `-free-entry` (the embedded Combobox), `${testid}-entries` (the
+ * list), `${testid}-entry-${key}` (each chip), `${testid}-editor`.
+ */
+
+export type MultiComboboxEntry = {
+  // Stable identity — list key, testid suffix, and the argument to
+  // `onRemoveEntry` / `onEntryClick`.
+  key: string;
+  // Chip text.
+  title: ReactNode;
+  // Native tooltip on the chip (e.g. the email behind a name).
+  subtitle?: string | undefined;
+  tone?: ChipTone | undefined;
+  // Marks the entry being edited: chip renders `selected`, and
+  // `renderEntryEditor(entry)` mounts below the chip row.
+  editing?: boolean | undefined;
+};
+
+export type MultiComboboxHandle = ComboboxHandle;
+
+export type MultiComboboxProps = Omit<
+  ComboboxProps,
+  "committed" | "committedExtra" | "onUncommit" | "clearOnCommit"
+> & {
+  entries: MultiComboboxEntry[];
+  onRemoveEntry: (key: string) => void;
+  // When set, chip labels become buttons (e.g. click-to-edit).
+  onEntryClick?: ((key: string) => void) | undefined;
+  // Inline editor for the entry with `editing: true`.
+  renderEntryEditor?: ((entry: MultiComboboxEntry) => ReactNode) | undefined;
+  // aria-label of the entries list. Default "Selected items".
+  entriesLabel?: string | undefined;
+  // Per-entry aria-label for the chip's × button. Default "Remove".
+  removeLabel?: ((entry: MultiComboboxEntry) => string) | undefined;
+  // Backspace in the empty search input removes the last entry.
+  // Default true.
+  backspaceRemovesLast?: boolean | undefined;
+  // Small tertiary line under the entries (counts, duplicate notices).
+  hint?: ReactNode | undefined;
+};
+
+export const MultiCombobox = forwardRef<MultiComboboxHandle, MultiComboboxProps>(
+  function MultiCombobox(
+    {
+      entries,
+      onRemoveEntry,
+      onEntryClick,
+      renderEntryEditor,
+      entriesLabel,
+      removeLabel,
+      backspaceRemovesLast = true,
+      hint,
+      testid = "multi-combobox",
+      ...comboboxProps
+    },
+    ref,
+  ) {
+    // Wraps ONLY the embedded Combobox so the Backspace handler can
+    // tell its input apart from any input inside `renderEntryEditor`.
+    const comboboxWrapRef = useRef<HTMLDivElement | null>(null);
+    const editing = entries.find((entry) => entry.editing);
+
+    const handleKeyDownCapture = (e: KeyboardEvent<HTMLDivElement>): void => {
+      if (!backspaceRemovesLast || e.key !== "Backspace") return;
+      const target = e.target;
+      if (!(target instanceof HTMLInputElement)) return;
+      if (!comboboxWrapRef.current?.contains(target)) return;
+      if (target.value !== "") return;
+      const last = entries[entries.length - 1];
+      if (!last) return;
+      onRemoveEntry(last.key);
+    };
+
+    return (
+      <div data-testid={testid} onKeyDownCapture={handleKeyDownCapture}>
+        <div ref={comboboxWrapRef}>
+          <Combobox
+            ref={ref}
+            {...comboboxProps}
+            clearOnCommit
+            committed={null}
+            testid={`${testid}-combobox`}
+          />
+        </div>
+
+        <ul
+          role="list"
+          aria-label={entriesLabel ?? "Selected items"}
+          data-testid={`${testid}-entries`}
+          style={{
+            listStyle: "none",
+            margin: entries.length > 0 ? "8px 0 0" : 0,
+            padding: 0,
+            display: "flex",
+            flexWrap: "wrap",
+            gap: 6,
+          }}
+        >
+          {entries.map((entry) => (
+            <li key={entry.key} style={{ minWidth: 0, maxWidth: "100%" }}>
+              <Chip
+                data-testid={`${testid}-entry-${entry.key}`}
+                title={entry.subtitle}
+                tone={entry.tone}
+                selected={entry.editing}
+                disabled={comboboxProps.disabled}
+                onClick={onEntryClick ? () => onEntryClick(entry.key) : undefined}
+                onRemove={() => onRemoveEntry(entry.key)}
+                removeLabel={removeLabel?.(entry)}
+              >
+                {entry.title}
+              </Chip>
+            </li>
+          ))}
+        </ul>
+
+        {editing && renderEntryEditor ? (
+          <div data-testid={`${testid}-editor`} style={{ marginTop: 8 }}>
+            {renderEntryEditor(editing)}
+          </div>
+        ) : null}
+
+        {hint ? (
+          <div
+            style={{
+              marginTop: 6,
+              fontSize: 11,
+              lineHeight: 1.4,
+              color: "var(--ck-text-tertiary, #8B92A3)",
+            }}
+          >
+            {hint}
+          </div>
+        ) : null}
+      </div>
+    );
+  },
+);

package/src/primitives/Select.tsx

@@ -122,6 +122,10 @@ interface PopoverRect {
   top: number;
   left: number;
   width: number;
+  /** Set when the menu opens UPWARD (trigger near the viewport
+   *  bottom): `top` is then the popover's bottom edge expressed as
+   *  a CSS `bottom` inset. */
+  openUp: boolean;
 }
 
 export const Select = forwardRef<HTMLButtonElement, SelectProps>(function Select(
@@ -192,12 +196,20 @@ export const Select = forwardRef<HTMLButtonElement, SelectProps>(function Select
     const el = triggerRef.current;
     if (!el) return null;
     const r = el.getBoundingClientRect();
+    // Flip upward when the space below can't fit the menu but the
+    // space above can (QA 2026-08-20: the last options of a Select
+    // at the bottom of a drawer sat under the fixed action bar).
+    // Worst-case menu height; the listbox scrolls inside either way.
+    const needed = maxOptionsHeight + (searchable ? 48 : 0) + POPOVER_GAP;
+    const below = window.innerHeight - r.bottom;
+    const openUp = below < needed && r.top > below;
     return {
-      top: r.bottom + POPOVER_GAP,
+      top: openUp ? window.innerHeight - r.top + POPOVER_GAP : r.bottom + POPOVER_GAP,
       left: r.left,
       width: r.width,
+      openUp,
     };
-  }, []);
+  }, [maxOptionsHeight, searchable]);
 
   // Position the popover on open + on window resize. Close on
   // page scroll — keeps the popover from drifting off the trigger
@@ -487,7 +499,7 @@ export const Select = forwardRef<HTMLButtonElement, SelectProps>(function Select
       className="ck-select-popover"
       style={{
         position: "fixed",
-        top: rect.top,
+        ...(rect.openUp ? { bottom: rect.top } : { top: rect.top }),
         left: rect.left,
         width: rect.width,
         zIndex: 1000,

package/src/primitives/index.ts

@@ -20,7 +20,12 @@ export type {
   ComboboxOption,
   ComboboxCommit,
   ComboboxCommitted,
+  ComboboxHandle,
 } from "./Combobox";
+export { Chip } from "./Chip";
+export type { ChipProps, ChipTone } from "./Chip";
+export { MultiCombobox } from "./MultiCombobox";
+export type { MultiComboboxProps, MultiComboboxEntry, MultiComboboxHandle } from "./MultiCombobox";
 export { Textarea } from "./Textarea";
 export type { TextareaProps } from "./Textarea";
 export { Checkbox } from "./Checkbox";