@cosxai/ui 1.0.0-alpha.0 → 1.0.0-alpha.10

package/src/components/AsyncSelect.tsx

@@ -0,0 +1,205 @@
+import * as Popover from '@radix-ui/react-popover';
+import { Search, X } from 'lucide-react';
+import { useId, useRef, useState, type KeyboardEvent } from 'react';
+
+import { cn } from '../lib/cn';
+import { useField } from './Field';
+import { controlFrame, controlInner } from './forms-control';
+import { Avatar, DEFAULT_LABELS, ListboxBody, type ListboxLabels, type ListItem } from './inputs-listbox';
+import { useDebouncedSearch } from './inputs-search';
+import { Spinner } from './Spinner';
+
+export type AsyncSelectProps = {
+  /** Look up matches; the signal aborts when newer input arrives. */
+  search: (query: string, signal: AbortSignal) => Promise<ListItem[]>;
+  value?: ListItem | null | undefined;
+  onChange?: ((item: ListItem | null) => void) | undefined;
+  /** Offer “Create …” for text that matches nothing exactly. */
+  onCreate?: ((query: string) => void | ListItem | Promise<ListItem | void>) | undefined;
+  /** @default "Search" */
+  placeholder?: string | undefined;
+  /** ms. @default 250 */
+  debounce?: number | undefined;
+  labels?: Partial<ListboxLabels> & { clear?: string | undefined };
+  invalid?: boolean | undefined;
+  disabled?: boolean | undefined;
+  /** Start with this search typed and its results open. */
+  defaultQuery?: string | undefined;
+  size?: 'sm' | 'md' | 'lg' | undefined;
+  id?: string | undefined;
+  'aria-label'?: string | undefined;
+  className?: string | undefined;
+};
+
+/**
+ * AsyncSelect — choose one from a large or remote set (a customer, a
+ * project). Typing searches after a short pause and drops stale answers;
+ * a spinner shows until the answer comes, then results with their meta, a
+ * Create row, “nothing matches”, or an error with Retry. The choice
+ * becomes a card that clears with ×.
+ */
+export function AsyncSelect({
+  search,
+  value,
+  onChange,
+  onCreate,
+  placeholder = 'Search',
+  debounce = 250,
+  labels: labelsIn,
+  invalid,
+  disabled,
+  defaultQuery = '',
+  size,
+  id,
+  className,
+  ...aria
+}: AsyncSelectProps) {
+  const field = useField();
+  const auto = useId();
+  const listId = `as${auto}-list`;
+  const optionId = (i: number) => `as${auto}-o${i}`;
+  const labels = { ...DEFAULT_LABELS, ...labelsIn };
+  const [own, setOwn] = useState<ListItem | null>(null);
+  const chosen = value === undefined ? own : value;
+  const [query, setQuery] = useState(defaultQuery);
+  const [open, setOpen] = useState(defaultQuery !== '');
+  const [active, setActive] = useState(0);
+  const input = useRef<HTMLInputElement | null>(null);
+  const { status, result, retry } = useDebouncedSearch(query, search, { delay: debounce });
+  const items = status === 'done' ? (result ?? []) : [];
+  const q = query.trim();
+  const canCreate = Boolean(onCreate) && q.length > 0 && !items.some((i) => i.label.toLowerCase() === q.toLowerCase());
+  const count = items.length + (canCreate ? 1 : 0);
+  const bad = Boolean(invalid || field?.invalid);
+  const off = Boolean(disabled || field?.disabled);
+
+  const pick = (item: ListItem | null) => {
+    if (value === undefined) setOwn(item);
+    onChange?.(item);
+    setQuery('');
+    setOpen(false);
+  };
+  const choose = async (i: number) => {
+    if (i < items.length) return pick(items[i]!);
+    if (i === items.length && canCreate) {
+      const made = await onCreate!(q);
+      if (made && typeof made === 'object') pick(made);
+      else {
+        setQuery('');
+        setOpen(false);
+      }
+    }
+  };
+  const onKey = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setOpen(true);
+      setActive((a) => Math.min(count - 1, a + 1));
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setActive((a) => Math.max(0, a - 1));
+    } else if (e.key === 'Enter' && open && count > 0) {
+      e.preventDefault();
+      void choose(active);
+    } else if (e.key === 'Escape') {
+      setOpen(false);
+    }
+  };
+
+  if (chosen) {
+    return (
+      <div
+        className={cn(
+          'flex min-h-[38px] items-center gap-2.5 rounded-md border bg-sunk px-2 py-1.5 font-sans text-ui text-fg',
+          bad ? 'border-error' : 'border-rule-soft',
+          off && 'bg-well text-fg-secondary',
+          className,
+        )}
+      >
+        <Avatar item={chosen} className="size-8 rounded-sm bg-ink text-linen ink:bg-yellow-accent ink:text-ink" />
+        <span className="flex min-w-0 flex-1 flex-col">
+          <span id={id ?? field?.id} className="truncate font-medium">
+            {chosen.label}
+          </span>
+          {chosen.meta && <span className="truncate text-meta text-fg-secondary">{chosen.meta}</span>}
+        </span>
+        {!off && (
+          <button
+            type="button"
+            aria-label={`${labelsIn?.clear ?? 'Clear'} ${chosen.label}`}
+            onClick={() => {
+              pick(null);
+              requestAnimationFrame(() => input.current?.focus());
+            }}
+            className="inline-grid shrink-0 cursor-pointer place-items-center rounded-xs p-0.5 text-fg-secondary outline-none hover:text-fg focus-visible:shadow-(--focus-ring)"
+          >
+            <X size={13} aria-hidden />
+          </button>
+        )}
+      </div>
+    );
+  }
+
+  const showList = open && q.length > 0;
+  return (
+    <Popover.Root open={showList} onOpenChange={setOpen}>
+      <Popover.Anchor asChild>
+        <div className={cn(controlFrame({ size, invalid: bad, disabled: off }), className)}>
+          <Search size={14} aria-hidden className="shrink-0 text-fg-secondary" />
+          <input
+            ref={input}
+            id={id ?? field?.id}
+            role="combobox"
+            aria-expanded={showList}
+            aria-controls={showList ? listId : undefined}
+            aria-autocomplete="list"
+            aria-activedescendant={showList && status === 'done' && count > 0 ? optionId(active) : undefined}
+            aria-invalid={bad || undefined}
+            aria-describedby={field?.describedBy}
+            aria-label={aria['aria-label']}
+            disabled={off}
+            value={query}
+            placeholder={placeholder}
+            autoComplete="off"
+            onChange={(e) => {
+              setQuery(e.target.value);
+              setActive(0);
+              setOpen(true);
+            }}
+            onFocus={() => q && setOpen(true)}
+            onKeyDown={onKey}
+            className={controlInner}
+          />
+          {status === 'searching' && <Spinner size={12} className="text-fg-secondary" />}
+        </div>
+      </Popover.Anchor>
+      <Popover.Portal>
+        <Popover.Content
+          align="start"
+          sideOffset={6}
+          collisionPadding={12}
+          onOpenAutoFocus={(e) => e.preventDefault()}
+          onInteractOutside={(e) => {
+            if (e.target instanceof Node && input.current?.parentElement?.contains(e.target)) e.preventDefault();
+          }}
+          className="rise z-60 rounded-lg border border-rule bg-page p-1 font-sans [--motion-reveal:200ms]"
+          style={{ width: 'var(--radix-popover-trigger-width)' }}
+        >
+          <ListboxBody
+            id={listId}
+            optionId={optionId}
+            items={items}
+            active={active}
+            status={status}
+            query={q}
+            canCreate={canCreate}
+            labels={labels}
+            onActive={setActive}
+            onChoose={(i) => void choose(i)}
+            onRetry={retry}
+          />
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+}

package/src/components/AuthLayout.tsx

@@ -0,0 +1,127 @@
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { Logo } from './Logo';
+
+export type AuthLayoutProps = Omit<ComponentProps<'div'>, 'children'> & {
+  /** Top left: the product lockup (a Logo tile and the product name). */
+  brand: ReactNode;
+  /** Top right: usually a ThemeSwitch. */
+  headerEnd?: ReactNode;
+  /** The step, centred in a 400px column. */
+  children: ReactNode;
+  /** One line under the step: who to ask when stuck. */
+  help?: ReactNode;
+  /** The foot: links on the left, the language on the right. */
+  footer?: ReactNode;
+  /** The yellow panel's text (an AuthPanel). Dropped below 900px. */
+  panel?: ReactNode;
+};
+
+/**
+ * AuthLayout — the sign-in page (Metaroom sign-in, design.cosx.co): the step
+ * on the left under the product lockup, the yellow panel on the right saying
+ * what this step is for. The panel drops when the layout is narrower than
+ * 900px (a container query, so a narrow window or pane works too).
+ */
+export function AuthLayout({ brand, headerEnd, children, help, footer, panel, className, ...rest }: AuthLayoutProps) {
+  return (
+    <div className={cn('@container flex h-full w-full font-sans text-fg', className)} {...rest}>
+      <div className="flex min-w-0 flex-1 flex-col px-12 pt-12 pb-8">
+        <div className="flex items-center justify-between gap-4">
+          <div className="flex items-center gap-3 text-[15px] font-medium">{brand}</div>
+          {headerEnd}
+        </div>
+        <main className="flex flex-1 items-center py-8">
+          <div className="mx-auto flex w-full max-w-[400px] flex-col gap-8">
+            {children}
+            {help && <p className="m-0 text-[12px] leading-[1.6] text-fg-secondary">{help}</p>}
+          </div>
+        </main>
+        {footer && <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2 text-[12px] text-fg-secondary">{footer}</div>}
+      </div>
+      {panel && (
+        <aside className="hidden w-[min(560px,45%)] shrink-0 p-6 @min-[900px]:flex">
+          <div className="flex flex-1 flex-col justify-between gap-8 overflow-hidden rounded-[24px] bg-brand-field p-14 text-ink">{panel}</div>
+        </aside>
+      )}
+    </div>
+  );
+}
+
+export type AuthPanelProps = {
+  /** Small line above: "Your workspaces", "Security". */
+  eyebrow: ReactNode;
+  /** The statement's plain start: "Every workspace you belong to, ". */
+  lead: ReactNode;
+  /** Its highlighted end: "under one sign-in." */
+  mark: ReactNode;
+  /** One sentence under it. */
+  sub?: ReactNode;
+  /** Top of the panel. @default the COSX wordmark */
+  logo?: ReactNode;
+};
+
+/** AuthPanel — the yellow panel's text: wordmark on top, the statement at the foot. */
+export function AuthPanel({ eyebrow, lead, mark, sub, logo }: AuthPanelProps) {
+  return (
+    <>
+      {logo ?? <Logo height={22} tone="ink" />}
+      <div className="flex flex-col gap-4">
+        <span className="text-[13px] font-medium text-[rgba(17,17,17,.7)]">{eyebrow}</span>
+        {/* Chinese sets at 1.35, untracked, its band starting lower (design: Patterns · Sign-in).
+            Important: typography-cjk.css sets every :lang(zh) line-height outside the layers. */}
+        <p className="m-0 text-[34px] leading-[1.22] font-medium tracking-[-.02em] text-pretty [&:lang(zh)]:leading-[1.35]! [&:lang(zh)]:tracking-normal!">
+          {lead}
+          <span className="mx-[-.08em] box-decoration-clone px-[.08em] bg-[linear-gradient(transparent_40%,var(--brand-mark)_40%,var(--brand-mark)_94%,transparent_94%)] [&:lang(zh)]:bg-[linear-gradient(transparent_50%,var(--brand-mark)_50%,var(--brand-mark)_94%,transparent_94%)]">
+            {mark}
+          </span>
+        </p>
+        {sub && <p className="m-0 text-[15px] leading-[1.6] text-[rgba(17,17,17,.7)]">{sub}</p>}
+      </div>
+    </>
+  );
+}
+
+export type AuthStepHeadProps = {
+  /** An AuthIconTile, a Spinner, a workspace mark. */
+  icon?: ReactNode;
+  title: ReactNode;
+  children?: ReactNode;
+};
+
+/** AuthStepHead — a step's icon, title and one explanation. */
+export function AuthStepHead({ icon, title, children }: AuthStepHeadProps) {
+  return (
+    <div className="flex flex-col gap-5">
+      {icon}
+      <div className="flex flex-col gap-2">
+        <h1 className="m-0 text-[30px] leading-[1.2] font-medium tracking-[-.015em]">{title}</h1>
+        {children && <p className="m-0 text-[15px] leading-[1.6] text-fg-secondary">{children}</p>}
+      </div>
+    </div>
+  );
+}
+
+export type AuthIconTileProps = {
+  children: ReactNode;
+  /** plain: a step; yellow: done; error: it didn't work. @default "plain" */
+  tone?: 'plain' | 'yellow' | 'error' | undefined;
+};
+
+/** AuthIconTile — the 56px tile holding a step's icon. */
+export function AuthIconTile({ children, tone = 'plain' }: AuthIconTileProps) {
+  return (
+    <span
+      aria-hidden
+      className={cn(
+        'grid size-14 place-items-center rounded-[14px]',
+        tone === 'plain' && 'bg-sunk text-fg',
+        tone === 'yellow' && 'bg-brand-field text-ink',
+        tone === 'error' && 'bg-error-wash text-error-text',
+      )}
+    >
+      {children}
+    </span>
+  );
+}

package/src/components/Badge.tsx

@@ -0,0 +1,68 @@
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+export type BadgeStatus = 'neutral' | 'attention' | 'error' | 'progress' | 'complete';
+export type BadgeAppearance = 'fill' | 'outline' | 'dot';
+
+const DEFAULT_APPEARANCE: Record<BadgeStatus, BadgeAppearance> = {
+  attention: 'fill',
+  error: 'fill',
+  progress: 'outline',
+  complete: 'dot',
+  neutral: 'dot',
+};
+const STATUSES = new Set<string>(Object.keys(DEFAULT_APPEARANCE));
+
+export type BadgeProps = Omit<ComponentProps<'span'>, 'children'> & {
+  /** The state. Unknown values fall back to neutral. @default "neutral" */
+  status?: BadgeStatus | (string & {}) | undefined;
+  /** fill · outline · dot. Defaults by status; change it only to match density in a column. */
+  appearance?: BadgeAppearance | undefined;
+  /** Dot density for rows: only the dot shows; the wording stays for screen readers and appears on hover. */
+  compact?: boolean | undefined;
+  /** The wording — always present: name the state (Awaiting you), not the action. */
+  children: ReactNode;
+};
+
+/**
+ * Badge — product status in yellow, ink and one red. Shape carries urgency:
+ * a fill needs a person (attention: brand fill, ink text; error: the red),
+ * an outline is under way (progress), a dot is a known state (complete:
+ * ink dot, neutral: grey dot). Colour is never the only signal.
+ * Product UI only — never on brand, marketing or decks.
+ */
+export function Badge({ status = 'neutral', appearance, compact = false, className, children, title, ...rest }: BadgeProps) {
+  const s = (STATUSES.has(status) ? status : 'neutral') as BadgeStatus;
+  const mode = compact ? 'dot' : (appearance ?? DEFAULT_APPEARANCE[s]);
+  const base = 'inline-flex items-center gap-[7px] whitespace-nowrap rounded-sm text-meta leading-none font-semibold';
+
+  if (mode === 'fill') {
+    const fill = s === 'error' ? 'bg-error text-white' : s === 'attention' ? 'bg-brand-mark text-ink' : 'bg-fg text-page';
+    return (
+      <span data-status={s} className={cn(base, 'px-2 py-[5px]', fill, className)} title={title} {...rest}>
+        {children}
+      </span>
+    );
+  }
+  if (mode === 'outline') {
+    return (
+      <span data-status={s} className={cn(base, 'border border-fg px-[7px] py-1 text-fg', className)} title={title} {...rest}>
+        {children}
+      </span>
+    );
+  }
+  const dot =
+    s === 'error' ? 'bg-error' : s === 'attention' ? 'bg-brand-mark' : s === 'complete' || s === 'progress' ? 'bg-fg' : 'bg-fg-secondary';
+  return (
+    <span
+      data-status={s}
+      className={cn(base, 'text-fg-secondary', className)}
+      title={compact ? (title ?? (typeof children === 'string' ? children : undefined)) : title}
+      {...rest}
+    >
+      <span aria-hidden className={cn('size-[9px] shrink-0 rounded-pill', dot)} />
+      <span className={compact ? 'sr-only' : undefined}>{children}</span>
+    </span>
+  );
+}

package/src/components/BrandLoader.tsx

@@ -0,0 +1,122 @@
+import { useEffect, useId, useRef } from 'react';
+
+import { LOOP } from './logo-art';
+
+/**
+ * BrandLoader — the COSX loop as a loading indicator (Claude Design, COSX
+ * Loader). A short stroke runs along the loop, blooms into the full mark,
+ * holds 0.6 s, gathers back and runs again: 3.4 s a round, the head's
+ * speed continuous. At rest it is the logo itself — the fill is the logo
+ * path, the stroke only a mask over it.
+ *
+ * For whole-page and start-up waits, where the brand belongs. Buttons,
+ * rows, inputs and anything under 24 px wide keep Spinner or a skeleton.
+ * Reduced motion: the full mark, still.
+ */
+export type BrandLoaderProps = {
+  /** Width in px (height follows the mark: 106 / 202). Default 48; 24 at least. */
+  size?: number | undefined;
+  /**
+   * ink on paper and yellow; linen or accent on ink; current follows the
+   * text colour (light and dark themes alike). The mark is never yellow on paper.
+   */
+  tone?: 'ink' | 'linen' | 'accent' | 'current' | undefined;
+  /** The faint full mark under the stroke (default on), so it always reads as COSX. */
+  track?: boolean | undefined;
+  /** 1 = a 3.4 s round. */
+  speed?: number | undefined;
+  /** What is loading, for assistive tech. Default "Loading". */
+  label?: string | undefined;
+  className?: string | undefined;
+};
+
+const TONES = {
+  ink: ['#111111', 'rgba(17,17,17,.12)'],
+  linen: ['#F5F2EC', 'rgba(245,242,236,.16)'],
+  accent: ['#FFD166', 'rgba(255,209,102,.18)'],
+  current: ['currentColor', 'currentColor'],
+} as const;
+
+// The stroke's centre line: the C counter-clockwise, the diagonal, the O
+// clockwise, then back across the open gap.
+const R = 38.3;
+const LC = [96.12, 144.62] as const;
+const RC = [193.32, 144.62] as const;
+const pt = (c: readonly [number, number], deg: number) => {
+  const a = (deg * Math.PI) / 180;
+  return `${(c[0] + R * Math.cos(a)).toFixed(2)},${(c[1] + R * Math.sin(a)).toFixed(2)}`;
+};
+const CENTRE = `M${pt(LC, -42)} A${R},${R} 0 1,0 ${pt(LC, 48)} L${pt(RC, 214)} A${R},${R} 0 0,1 ${pt(RC, 34)} A${R},${R} 0 0,1 ${pt(RC, 214)} L${pt(LC, -42)} Z`;
+
+// Seconds: run, bloom, hold, gather; SEG = the running stroke's share of the loop.
+const RUN = 1.5;
+const GROW = 0.7;
+const HOLD = 0.6;
+const SHRINK = 0.6;
+const T = RUN + GROW + HOLD + SHRINK;
+const SEG = 0.14;
+const easeOut = (x: number) => 1 - (1 - x) ** 3;
+const easeInOut = (x: number) => (x < 0.5 ? 4 * x ** 3 : 1 - (-2 * x + 2) ** 3 / 2);
+
+/** Head position h (in loop lengths) and visible share s (0..1) at t seconds. */
+export function loaderState(t: number): { h: number; s: number } {
+  const c = Math.floor(t / T);
+  let u = t - c * T;
+  const base = c * (RUN + GROW / 2 + SHRINK / 2);
+  if (u < RUN) return { h: base + u, s: SEG };
+  u -= RUN;
+  if (u < GROW) {
+    const g = u / GROW;
+    return { h: base + RUN + GROW * (g - (g * g) / 2), s: SEG + (1 - SEG) * easeOut(g) };
+  }
+  u -= GROW;
+  if (u < HOLD) return { h: base + RUN + GROW / 2, s: 1 };
+  u -= HOLD;
+  const k = u / SHRINK;
+  return { h: base + RUN + GROW / 2 + (SHRINK * k * k) / 2, s: 1 - (1 - SEG) * easeInOut(k) };
+}
+
+export function BrandLoader({ size = 48, tone = 'ink', track = true, speed = 1, label = 'Loading', className }: BrandLoaderProps) {
+  const maskId = `cosx-loader-${useId().replace(/[^a-zA-Z0-9-]/g, '')}`;
+  const stroke = useRef<SVGPathElement>(null);
+  const [fill, faint] = TONES[tone];
+
+  useEffect(() => {
+    const c = stroke.current;
+    if (!c || typeof c.getTotalLength !== 'function') return undefined;
+    const L = c.getTotalLength();
+    const still = window.matchMedia?.('(prefers-reduced-motion: reduce)');
+    const t0 = performance.now();
+    let raf = 0;
+    const frame = (now: number) => {
+      const st = still?.matches ? { h: 0, s: 1 } : loaderState(((now - t0) / 1000) * speed);
+      const s = Math.min(1, st.s);
+      const tail = (((st.h - s) % 1) + 1) % 1;
+      c.setAttribute('stroke-dasharray', s >= 0.999 ? `${L} 0` : `${(s * L).toFixed(2)} ${((1 - s) * L).toFixed(2)}`);
+      c.setAttribute('stroke-dashoffset', (-tail * L).toFixed(2));
+      raf = requestAnimationFrame(frame);
+    };
+    raf = requestAnimationFrame(frame);
+    return () => cancelAnimationFrame(raf);
+  }, [speed]);
+
+  return (
+    <svg
+      role="img"
+      aria-label={label}
+      viewBox="44 92 202 106"
+      width={size}
+      height={Number(((size * 106) / 202).toFixed(1))}
+      className={className}
+      style={{ display: 'block', overflow: 'visible' }}
+    >
+      <defs>
+        <mask id={maskId} maskUnits="userSpaceOnUse" x="30" y="80" width="230" height="130">
+          <path ref={stroke} d={CENTRE} fill="none" stroke="#fff" strokeWidth="21" strokeLinecap="round" strokeLinejoin="round" />
+        </mask>
+      </defs>
+      {track && <path d={LOOP.paths[0]} fill={faint} fillOpacity={tone === 'current' ? 0.12 : undefined} />}
+      <path d={LOOP.paths[0]} fill={fill} mask={`url(#${maskId})`} />
+    </svg>
+  );
+}

package/src/components/Breadcrumb.tsx

@@ -0,0 +1,129 @@
+import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+export type BreadcrumbItem = {
+  label: ReactNode;
+  /** A link; or use onSelect for in-app navigation. */
+  href?: string | undefined;
+  onSelect?: (() => void) | undefined;
+  /** A trailing tag on the current page: its format (PDF). */
+  tag?: ReactNode;
+};
+
+export type BreadcrumbProps = Omit<ComponentProps<'nav'>, 'children'> & {
+  items: BreadcrumbItem[];
+  /** What starts the trail — the workspace brand (on a customer domain it replaces the platform name). */
+  root?: ReactNode;
+  /** Beyond this many segments the middle folds into a menu. @default 4 */
+  max?: number | undefined;
+  /** @default "Breadcrumb" */
+  label?: string | undefined;
+  /** Accessible name of the fold button. @default "Show hidden folders" */
+  foldLabel?: string | undefined;
+  /** A line under the trail: the current item's status. */
+  status?: ReactNode;
+};
+
+const linkClass = 'cursor-pointer text-fg-secondary outline-none hover:text-fg hover:underline underline-offset-2 focus-visible:shadow-(--focus-ring) rounded-xs';
+
+function Crumb({ item }: { item: BreadcrumbItem }) {
+  if (item.href)
+    return (
+      <a href={item.href} onClick={item.onSelect} className={linkClass}>
+        {item.label}
+      </a>
+    );
+  if (item.onSelect)
+    return (
+      <button type="button" onClick={item.onSelect} className={linkClass}>
+        {item.label}
+      </button>
+    );
+  return <span className="text-fg-secondary">{item.label}</span>;
+}
+
+const Sep = () => (
+  <span aria-hidden className="text-fg-secondary">
+    /
+  </span>
+);
+
+/**
+ * Breadcrumb — where this page sits. The current page is the last segment
+ * and not a link; beyond four segments the middle folds into a menu. On a
+ * customer domain the trail starts at the workspace brand (root).
+ */
+export function Breadcrumb({ items, root, max = 4, label = 'Breadcrumb', foldLabel = 'Show hidden folders', status, className, ...rest }: BreadcrumbProps) {
+  const last = items[items.length - 1];
+  const before = items.slice(0, -1);
+  const total = items.length + (root ? 1 : 0);
+  const fold = total > max && before.length > 1;
+  // Folded: [root or the first ancestor] / … / parent / current.
+  const head = fold ? (root ? [] : before.slice(0, 1)) : before;
+  const folded = fold ? before.slice(root ? 0 : 1, -1) : [];
+  const tail = fold ? before.slice(-1) : [];
+  const segment = 'flex items-center gap-2';
+
+  return (
+    <nav aria-label={label} className={cn('flex flex-col gap-1.5', className)} {...rest}>
+      <ol className="m-0 flex list-none flex-wrap items-center gap-x-2 gap-y-1 p-0 text-ui">
+        {root && (
+          <li className={segment}>
+            {root}
+            {items.length > 0 && <Sep />}
+          </li>
+        )}
+        {head.map((it, i) => (
+          <li key={`h${i}`} className={segment}>
+            <Crumb item={it} />
+            <Sep />
+          </li>
+        ))}
+        {folded.length > 0 && (
+          <li className={segment}>
+            <DropdownMenu.Root>
+              <DropdownMenu.Trigger
+                aria-label={foldLabel}
+                className="inline-grid h-6 min-w-6 cursor-pointer place-items-center rounded-sm bg-sunk px-1.5 text-meta font-semibold text-fg outline-none hover:bg-well focus-visible:shadow-(--focus-ring)"
+              >
+                …
+              </DropdownMenu.Trigger>
+              <DropdownMenu.Portal>
+                <DropdownMenu.Content align="start" sideOffset={6} className="z-50 min-w-[180px] rounded-lg border border-rule bg-page p-1.5 text-ui text-fg">
+                  {folded.map((it, i) => (
+                    <DropdownMenu.Item
+                      key={i}
+                      onSelect={() => {
+                        if (it.href) window.location.assign(it.href);
+                        else it.onSelect?.();
+                      }}
+                      className="flex h-8 cursor-pointer items-center rounded-md px-2.5 outline-none data-[highlighted]:bg-hover"
+                    >
+                      {it.label}
+                    </DropdownMenu.Item>
+                  ))}
+                </DropdownMenu.Content>
+              </DropdownMenu.Portal>
+            </DropdownMenu.Root>
+            <Sep />
+          </li>
+        )}
+        {tail.map((it, i) => (
+          <li key={`t${i}`} className={segment}>
+            <Crumb item={it} />
+            <Sep />
+          </li>
+        ))}
+        {last && (
+          <li aria-current="page" className="flex items-center gap-2 font-medium text-fg">
+            {last.label}
+            {last.tag && <span className="rounded-sm bg-sunk px-1.5 py-0.5 text-[11px] font-semibold text-fg">{last.tag}</span>}
+          </li>
+        )}
+      </ol>
+      {status && <div className="text-meta text-fg-secondary">{status}</div>}
+    </nav>
+  );
+}