@cosxai/ui 0.23.3 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosxai/ui",
-  "version": "0.23.3",
+  "version": "0.25.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,191 @@
+import {
+  forwardRef,
+  type CSSProperties,
+  type HTMLAttributes,
+  type MouseEvent,
+  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;
+  // Chip buttons act on click but must NOT take focus on mousedown:
+  // when a host has an inline editor open for another chip, the
+  // editor's blur (commit + unmount) would otherwise run before this
+  // click lands and the click is lost. Keyboard focus via Tab is
+  // unaffected.
+  const keepFocus = (e: MouseEvent<HTMLButtonElement>): void => e.preventDefault();
+  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"
+          onMouseDown={keepFocus}
+          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"}
+          onMouseDown={keepFocus}
+          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,39 @@ 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;
+  // 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 {
@@ -109,7 +141,8 @@ function defaultMatch(raw: string, option: ComboboxOption): boolean {
   );
 }
 
-export function Combobox({
+export const Combobox = forwardRef<ComboboxHandle, ComboboxProps>(function Combobox(
+  {
   label,
   placeholder,
   autoFocus,
@@ -126,8 +159,14 @@ export function Combobox({
   committedExtra,
   onCommit,
   onUncommit,
+  clearOnCommit = false,
+  bare = false,
+  inputId,
+  inputDescribedBy,
   testid = "combobox",
-}: ComboboxProps): ReactNode {
+  },
+  ref,
+) {
   const [query, setQuery] = useState("");
   const [results, setResults] = useState<ComboboxOption[]>([]);
   const [loading, setLoading] = useState(false);
@@ -141,6 +180,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 +244,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 +258,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
@@ -216,6 +271,10 @@ export function Combobox({
   // 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;
@@ -286,9 +345,18 @@ export function Combobox({
     focused && !isCommitted && (results.length > 0 || offerFree || (hasNoResults && !!emptyHint));
 
   return (
-    <div style={{ position: "relative" }}>
+    <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}
@@ -303,7 +371,7 @@ export function Combobox({
         placeholder={placeholder}
         autoFocus={autoFocus}
         autoComplete="off"
-        error={invalid ? (invalidHint ?? "Pick from the list to continue.") : null}
+        error={invalid ? (invalidHint ?? COMBOBOX_DEFAULT_INVALID_HINT) : null}
       />
 
       {showDropdown ? (
@@ -436,4 +504,4 @@ export function Combobox({
       ) : null}
     </div>
   );
-}
+});

package/src/primitives/Input.tsx

@@ -33,6 +33,14 @@ export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
   // currency symbols, unit labels, search icons, etc.
   prefix?: ReactNode;
   suffix?: ReactNode;
+  // Bare mode: render ONLY the <input> — no wrapper, label, helper,
+  // error text, or field chrome (border / background / height). For
+  // hosts that draw the field themselves (MultiCombobox's inline
+  // layout, where chips and the input share one frame). `label`,
+  // `helper`, `error` text, `prefix`, `suffix` and `fit` are ignored;
+  // `aria-invalid` is still set from `error` so the host can react.
+  // Default false.
+  bare?: boolean;
 }
 
 const ADDON_STYLE = {
@@ -52,12 +60,47 @@ const ADDON_STYLE = {
 };
 
 export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
-  { label, helper, error, fit = "full", prefix, suffix, className, id, style, ...rest },
+  { label, helper, error, fit = "full", prefix, suffix, bare = false, className, id, style, ...rest },
   ref,
 ) {
   const autoId = useId();
   const inputId = id ?? autoId;
-  const hasAddon = prefix != null || suffix != null;
+  const hasAddon = !bare && (prefix != null || suffix != null);
+  // `...rest` is spread FIRST so the `error`-derived aria-invalid (and,
+  // non-bare, the helper/error text association) stays authoritative;
+  // a consumer aria-describedby is merged with ours, not replaced.
+  const ownDescribedBy = !bare && (helper || error) ? `${inputId}-helper` : undefined;
+  const describedBy =
+    [rest["aria-describedby"], ownDescribedBy].filter(Boolean).join(" ") || undefined;
+
+  if (bare) {
+    // Chrome presets restyle .ck-input with !important; the matching
+    // .ck-input--bare rule in styles/index.css strips that again.
+    return (
+      <input
+        ref={ref}
+        id={inputId}
+        {...rest}
+        aria-invalid={error ? true : undefined}
+        aria-describedby={describedBy}
+        className={cn("ck-input", "ck-input--bare", className)}
+        style={{
+          minWidth: 0,
+          width: "100%",
+          height: 28,
+          padding: "0 4px",
+          font: "400 13px/1 var(--ck-font-sans)",
+          background: "transparent",
+          color: "var(--ck-text-primary)",
+          border: "none",
+          borderRadius: 0,
+          boxShadow: "none",
+          outline: "none",
+          ...(style ?? {}),
+        }}
+      />
+    );
+  }
 
   // Border / radius live on the WRAPPER when there's an addon so the
   // addon + input share one continuous frame. Otherwise the input
@@ -69,9 +112,9 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
     <input
       ref={ref}
       id={inputId}
-      aria-invalid={error ? true : undefined}
-      aria-describedby={(helper || error) ? `${inputId}-helper` : undefined}
       {...rest}
+      aria-invalid={error ? true : undefined}
+      aria-describedby={describedBy}
       className={cn("ck-input", hasAddon ? "ck-input--with-addon" : undefined)}
       style={{
         flex: hasAddon ? "1 1 auto" : undefined,

package/src/primitives/MultiCombobox.tsx

@@ -0,0 +1,327 @@
+import {
+  forwardRef,
+  useId,
+  useImperativeHandle,
+  useRef,
+  type CSSProperties,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+
+import { Chip, type ChipTone } from "./Chip";
+import {
+  COMBOBOX_DEFAULT_INVALID_HINT,
+  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.
+ *
+ * Layouts (`layout`): `stacked` (default) — the search field, then
+ * the chip row underneath. `inline` — a mail-client "To" field: one
+ * Input-like frame (`.ck-multi-combobox-field`) whose `<ul>` is the
+ * flex-wrap row: chips as `<li>`s and the bare search input in a last
+ * presentational `<li>`, so typing continues after the last chip and
+ * wraps with it. The label renders above as an eyebrow; the invalid
+ * hint (aria-describedby on the input), editor and hint stay below.
+ *
+ * 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 MultiComboboxLayout = "stacked" | "inline";
+
+export type MultiComboboxProps = Omit<
+  ComboboxProps,
+  | "committed"
+  | "committedExtra"
+  | "onUncommit"
+  | "clearOnCommit"
+  | "bare"
+  | "inputId"
+  | "inputDescribedBy"
+> & {
+  entries: MultiComboboxEntry[];
+  // `stacked` (default): field, then chips underneath. `inline`:
+  // chips inside the field, input after the last chip.
+  layout?: MultiComboboxLayout | undefined;
+  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;
+};
+
+// Inline layout: the host-drawn field mirrors Input's chrome. Focus
+// ring / invalid border / disabled dim come from styles/index.css
+// (`.ck-multi-combobox-field`).
+const INLINE_FIELD_STYLE: CSSProperties = {
+  position: "relative",
+  display: "flex",
+  flexWrap: "wrap",
+  alignItems: "center",
+  gap: 6,
+  minHeight: 36,
+  padding: "4px 8px",
+  boxSizing: "border-box",
+  background: "var(--ck-bg-surface, #fff)",
+  border: "1px solid var(--ck-border-strong, #C5C9D2)",
+  borderRadius: "var(--ck-radius-sm, 6px)",
+  transition: "border-color var(--ck-dur-fast, 120ms) var(--ck-ease, ease)",
+};
+// The `<ul>` inside the frame is the actual flex-wrap row.
+const INLINE_LIST_STYLE: CSSProperties = {
+  listStyle: "none",
+  margin: 0,
+  padding: 0,
+  width: "100%",
+  display: "flex",
+  flexWrap: "wrap",
+  alignItems: "center",
+  gap: 6,
+};
+// Last <li>: holds the bare Combobox (its root is `position: static`,
+// so the dropdown anchors to the frame) and takes the remaining width.
+const INLINE_COMBOBOX_ITEM: CSSProperties = {
+  flex: "1 1 140px",
+  minWidth: 140,
+  display: "flex",
+};
+
+export const MultiCombobox = forwardRef<MultiComboboxHandle, MultiComboboxProps>(
+  function MultiCombobox(
+    {
+      entries,
+      onRemoveEntry,
+      onEntryClick,
+      renderEntryEditor,
+      entriesLabel,
+      removeLabel,
+      backspaceRemovesLast = true,
+      hint,
+      layout = "stacked",
+      testid = "multi-combobox",
+      label,
+      ...comboboxProps
+    },
+    ref,
+  ) {
+    // Wraps ONLY the embedded Combobox so the Backspace handler can
+    // tell its input apart from any input inside `renderEntryEditor`.
+    // A <div> in stacked mode, the last <li> in inline mode.
+    const comboboxWrapRef = useRef<HTMLElement | null>(null);
+    const setComboboxWrap = (el: HTMLElement | null): void => {
+      comboboxWrapRef.current = el;
+    };
+    const listRef = useRef<HTMLUListElement | null>(null);
+    const handleRef = useRef<ComboboxHandle | null>(null);
+    useImperativeHandle(ref, () => ({
+      focus: () => handleRef.current?.focus(),
+      clear: () => handleRef.current?.clear(),
+    }));
+    const inputId = useId();
+    const hintId = useId();
+    const inline = layout === "inline";
+    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);
+    };
+
+    // Clicking the field's empty area (inline) focuses the input, like
+    // a mail client's To field. Chip / input clicks handle themselves.
+    const handleFieldMouseDown = (e: MouseEvent<HTMLDivElement>): void => {
+      if (e.target !== e.currentTarget && e.target !== listRef.current) return;
+      e.preventDefault();
+      handleRef.current?.focus();
+    };
+
+    const comboboxEl = (
+      <Combobox
+        ref={handleRef}
+        {...comboboxProps}
+        label={inline ? undefined : label}
+        bare={inline}
+        inputId={inline ? inputId : undefined}
+        inputDescribedBy={inline ? hintId : undefined}
+        clearOnCommit
+        committed={null}
+        testid={`${testid}-combobox`}
+      />
+    );
+
+    const entriesList = (
+      <ul
+        ref={listRef}
+        role="list"
+        aria-label={entriesLabel ?? "Selected items"}
+        data-testid={`${testid}-entries`}
+        style={
+          inline
+            ? INLINE_LIST_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>
+        ))}
+        {inline ? (
+          // Not an entry: presentational so the list still counts N
+          // chips for assistive tech.
+          <li ref={setComboboxWrap} role="presentation" style={INLINE_COMBOBOX_ITEM}>
+            {comboboxEl}
+          </li>
+        ) : null}
+      </ul>
+    );
+
+    return (
+      <div data-testid={testid} onKeyDownCapture={handleKeyDownCapture}>
+        {inline ? (
+          <>
+            {label ? (
+              <label
+                htmlFor={inputId}
+                className="ck-eyebrow"
+                style={{ color: "var(--ck-text-secondary)", display: "block", marginBottom: 6 }}
+              >
+                {label}
+              </label>
+            ) : null}
+            <div
+              className="ck-multi-combobox-field"
+              data-testid={`${testid}-field`}
+              style={INLINE_FIELD_STYLE}
+              onMouseDown={handleFieldMouseDown}
+            >
+              {entriesList}
+            </div>
+            <div
+              id={hintId}
+              className="ck-multi-combobox-invalid-hint"
+              style={{
+                marginTop: 6,
+                font: "400 11px/1.4 var(--ck-font-sans)",
+                color: "var(--ck-critical)",
+              }}
+            >
+              {comboboxProps.invalidHint ?? COMBOBOX_DEFAULT_INVALID_HINT}
+            </div>
+          </>
+        ) : (
+          <>
+            <div ref={setComboboxWrap}>{comboboxEl}</div>
+            {entriesList}
+          </>
+        )}
+
+        {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/index.ts

@@ -20,7 +20,17 @@ 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,
+  MultiComboboxLayout,
+} from "./MultiCombobox";
 export { Textarea } from "./Textarea";
 export type { TextareaProps } from "./Textarea";
 export { Checkbox } from "./Checkbox";

package/src/styles/index.css

@@ -304,3 +304,40 @@ html[data-ck-chrome="seamless"] .ck-card__foot {
     animation: none;
   }
 }
+
+/* ---------- Input bare mode + MultiCombobox inline field ----------
+   `.ck-input--bare` is an <input> whose FIELD is drawn by its host
+   (MultiCombobox inline layout: chips + input in one frame). Chrome
+   presets restyle `.ck-input` with !important at up to (0,5,1)
+   specificity, so this rule uses `:not(#\#)` to out-rank them and
+   strip every trace of field chrome back off. */
+.ck-input.ck-input--bare:not(#\#) {
+  background: transparent !important;
+  border: none !important;
+  border-radius: 0 !important;
+  box-shadow: none !important;
+  outline: none !important;
+  height: 28px !important;
+  padding: 0 4px !important;
+}
+
+/* The host-drawn field: looks like .ck-input, carries the focus ring
+   via :focus-within, the invalid border via :has([aria-invalid]) and
+   the disabled dim via :has(:disabled). */
+.ck-multi-combobox-field:focus-within {
+  border-color: var(--ck-accent) !important;
+  box-shadow: 0 0 0 3px var(--ck-accent-muted);
+}
+.ck-multi-combobox-field:has(.ck-input[aria-invalid="true"]) {
+  border-color: var(--ck-critical) !important;
+}
+.ck-multi-combobox-field:has(.ck-input:disabled) {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+.ck-multi-combobox-invalid-hint {
+  display: none;
+}
+.ck-multi-combobox-field:has(.ck-input[aria-invalid="true"]) + .ck-multi-combobox-invalid-hint {
+  display: block;
+}