@cosxai/ui 1.0.0-alpha.1 → 1.0.0-alpha.2

package/src/components/MentionInput.tsx

@@ -0,0 +1,233 @@
+import * as Popover from '@radix-ui/react-popover';
+import { useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { Button } from './Button';
+import { useField } from './Field';
+import { DEFAULT_LABELS, ListboxBody, type ListboxLabels, type ListItem } from './inputs-listbox';
+import type { SearchStatus } from './inputs-search';
+
+export type Mention = { value: string; label: string };
+
+export type MentionInputProps = {
+  value?: string | undefined;
+  defaultValue?: string | undefined;
+  /** The text and the people mentioned in it (those whose @Name is still there). */
+  onChange?: ((text: string, mentions: Mention[]) => void) | undefined;
+  /** ⌘Enter / Ctrl+Enter, or the send button. */
+  onSubmit?: ((text: string, mentions: Mention[]) => void) | undefined;
+  /** People who can be mentioned; meta is their role (Member, Customer). */
+  people: ListItem[];
+  placeholder?: string | undefined;
+  /** @default "Send" — null hides the button (⌘Enter still sends). */
+  submitLabel?: ReactNode;
+  /** @default "⌘Enter to send" (Ctrl+Enter off the Mac) */
+  submitHint?: ReactNode;
+  labels?: Partial<ListboxLabels> | undefined;
+  disabled?: boolean | undefined;
+  /** Rows before it scrolls. @default 3 */
+  rows?: number | undefined;
+  /** Focus on mount, caret at the end (an @ being typed there opens the list). */
+  autoFocus?: boolean | undefined;
+  id?: string | undefined;
+  'aria-label'?: string | undefined;
+  className?: string | undefined;
+};
+
+const isMac = () => typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent);
+
+/** The @query being typed at the caret: "@" at a word start, no spaces since. */
+export function mentionAt(text: string, caret: number): { start: number; query: string } | null {
+  const before = text.slice(0, caret);
+  const at = before.lastIndexOf('@');
+  if (at < 0) return null;
+  if (at > 0 && !/\s/.test(before[at - 1]!)) return null;
+  const query = before.slice(at + 1);
+  if (/\s/.test(query) || query.length > 30) return null;
+  return { start: at, query };
+}
+
+/**
+ * MentionInput — the comment box: @ opens the people who can be mentioned
+ * (arrows, Enter or Tab to insert, Esc to close); the mention goes in as
+ * @Name. ⌘Enter sends. Mentions are reported with the text, and only while
+ * their @Name is still in it.
+ */
+export function MentionInput({
+  value,
+  defaultValue = '',
+  onChange,
+  onSubmit,
+  people,
+  placeholder,
+  submitLabel = 'Send',
+  submitHint,
+  labels: labelsIn,
+  disabled,
+  rows = 3,
+  autoFocus = false,
+  id,
+  className,
+  ...aria
+}: MentionInputProps) {
+  const field = useField();
+  const auto = useId();
+  const listId = `mi${auto}-list`;
+  const optionId = (i: number) => `mi${auto}-o${i}`;
+  const labels = { ...DEFAULT_LABELS, ...labelsIn, empty: labelsIn?.empty ?? ((q: string) => `No one matches “${q}”.`) };
+  const [own, setOwn] = useState(defaultValue);
+  const text = value ?? own;
+  const [picked, setPicked] = useState<Mention[]>([]);
+  const [at, setAt] = useState<{ start: number; query: string } | null>(null);
+  const [active, setActive] = useState(0);
+  const area = useRef<HTMLTextAreaElement | null>(null);
+  // After a token goes in, put the caret after it once the new text is on screen.
+  const caretTo = useRef<number | null>(null);
+  useLayoutEffect(() => {
+    const pos = caretTo.current;
+    if (pos === null || !area.current) return;
+    caretTo.current = null;
+    area.current.focus();
+    area.current.setSelectionRange(pos, pos);
+  }, [text]);
+  const off = Boolean(disabled || field?.disabled);
+
+  const matches = useMemo(() => {
+    if (!at) return [];
+    const q = at.query.toLowerCase();
+    return people.filter((p) => p.label.toLowerCase().includes(q) || (p.meta ?? '').toLowerCase().startsWith(q)).slice(0, 8);
+  }, [at, people]);
+  const status: SearchStatus = 'done';
+  const open = at !== null && !off;
+
+  const live = (t: string) => picked.filter((m, i, all) => t.includes(`@${m.label}`) && all.findIndex((x) => x.value === m.value) === i);
+  const set = (t: string, list = picked) => {
+    if (value === undefined) setOwn(t);
+    onChange?.(t, list.filter((m) => t.includes(`@${m.label}`)));
+  };
+  const track = (t: string, caret: number) => {
+    const next = mentionAt(t, caret);
+    setAt(next);
+    if (next && (!at || next.query !== at.query)) setActive(0);
+  };
+  // autoFocus: caret at the end, and an @ being typed there opens the list.
+  useEffect(() => {
+    const el = area.current;
+    if (!autoFocus || !el) return;
+    el.focus();
+    el.setSelectionRange(el.value.length, el.value.length);
+    track(el.value, el.value.length);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- on mount only
+  }, []);
+  const insert = (i: number) => {
+    const p = matches[i];
+    if (!p || !at) return;
+    const token = `@${p.label} `;
+    const caret = at.start + 1 + at.query.length;
+    const next = text.slice(0, at.start) + token + text.slice(caret);
+    const list = [...picked, { value: p.value, label: p.label }];
+    setPicked(list);
+    set(next, list);
+    setAt(null);
+    const pos = at.start + token.length;
+    caretTo.current = pos;
+  };
+  const submit = () => {
+    if (!text.trim()) return;
+    onSubmit?.(text, live(text));
+  };
+
+  const onKey = (e: KeyboardEvent<HTMLTextAreaElement>) => {
+    if (open && matches.length) {
+      if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+        e.preventDefault();
+        setActive((a) => (e.key === 'ArrowDown' ? (a + 1) % matches.length : (a - 1 + matches.length) % matches.length));
+        return;
+      }
+      if ((e.key === 'Enter' && !e.metaKey && !e.ctrlKey) || e.key === 'Tab') {
+        e.preventDefault();
+        insert(active);
+        return;
+      }
+    }
+    if (open && e.key === 'Escape') {
+      e.preventDefault();
+      setAt(null);
+      return;
+    }
+    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+      e.preventDefault();
+      submit();
+    }
+  };
+
+  return (
+    <div
+      className={cn(
+        'flex w-full flex-col rounded-md border border-rule bg-sunk font-sans text-fg',
+        'transition-[border-color] duration-[120ms] ease-standard focus-within:border-fg focus-within:shadow-(--focus-ring)',
+        field?.invalid && 'border-error focus-within:border-error',
+        off && 'cursor-not-allowed bg-well text-fg-secondary',
+        className,
+      )}
+    >
+      <Popover.Root open={open} onOpenChange={(o) => !o && setAt(null)}>
+        <Popover.Anchor asChild>
+          <textarea
+            ref={area}
+            id={id ?? field?.id}
+            rows={rows}
+            value={text}
+            placeholder={placeholder}
+            disabled={off}
+            aria-controls={open ? listId : undefined}
+            aria-autocomplete="list"
+            aria-activedescendant={open && matches.length ? optionId(active) : undefined}
+            aria-label={aria['aria-label']}
+            aria-describedby={field?.describedBy}
+            onChange={(e) => {
+              set(e.target.value);
+              track(e.target.value, e.target.selectionStart ?? e.target.value.length);
+            }}
+            onSelect={(e) => track(e.currentTarget.value, e.currentTarget.selectionStart ?? 0)}
+            onKeyDown={onKey}
+            onBlur={() => setAt(null)}
+            className="min-h-0 w-full resize-none border-none bg-transparent px-2.5 pt-2 pb-1 font-sans text-[13px] leading-normal text-inherit outline-none placeholder:text-fg-secondary"
+          />
+        </Popover.Anchor>
+        <Popover.Portal>
+          <Popover.Content
+            align="start"
+            side="bottom"
+            sideOffset={4}
+            collisionPadding={12}
+            onOpenAutoFocus={(e) => e.preventDefault()}
+            className="rise z-60 w-[260px] rounded-lg border border-rule bg-page p-1 font-sans [--motion-reveal:200ms]"
+          >
+            <ListboxBody
+              id={listId}
+              optionId={optionId}
+              items={matches}
+              active={active}
+              status={status}
+              query={at?.query ?? ''}
+              canCreate={false}
+              labels={labels}
+              onActive={setActive}
+              onChoose={insert}
+              onRetry={() => {}}
+            />
+          </Popover.Content>
+        </Popover.Portal>
+      </Popover.Root>
+      <div className="flex items-center justify-end gap-3 px-2 pb-2">
+        <span className="text-meta text-fg-secondary">{submitHint ?? (isMac() ? '⌘Enter to send' : 'Ctrl+Enter to send')}</span>
+        {submitLabel !== null && (
+          <Button size="sm" disabled={off || !text.trim()} onClick={submit}>
+            {submitLabel}
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/Menu.tsx

@@ -0,0 +1,109 @@
+import * as MenuPrimitive from '@radix-ui/react-dropdown-menu';
+import { Check, ChevronRight } from 'lucide-react';
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+/** Menu root: open / onOpenChange, or uncontrolled with MenuTrigger. */
+export const Menu = MenuPrimitive.Root;
+/** The element that opens it (asChild onto a Button or IconButton). */
+export const MenuTrigger = MenuPrimitive.Trigger;
+export const MenuSub = MenuPrimitive.Sub;
+
+const surface = cn(
+  'z-[60] min-w-[200px] overflow-hidden rounded-lg border border-rule bg-page p-1.5 font-sans text-ui text-fg outline-none',
+  'max-h-(--radix-dropdown-menu-content-available-height)',
+);
+
+export type MenuContentProps = ComponentProps<typeof MenuPrimitive.Content>;
+
+/** MenuContent — renders in a portal (never clipped), flips to fit. No shadow: a hairline on the page colour. */
+export function MenuContent({ className, sideOffset = 6, collisionPadding = 8, align = 'start', ...rest }: MenuContentProps) {
+  return (
+    <MenuPrimitive.Portal>
+      <MenuPrimitive.Content sideOffset={sideOffset} collisionPadding={collisionPadding} align={align} className={cn(surface, className)} {...rest} />
+    </MenuPrimitive.Portal>
+  );
+}
+
+const itemBase = cn(
+  'relative flex min-h-8 cursor-pointer items-center gap-2.5 rounded-md px-2.5 py-1.5 outline-none select-none',
+  'data-highlighted:bg-hover data-disabled:cursor-not-allowed data-disabled:opacity-40',
+);
+
+export type MenuItemProps = Omit<ComponentProps<typeof MenuPrimitive.Item>, 'children'> & {
+  children: ReactNode;
+  icon?: ReactNode;
+  /** Shortcut hint, right-aligned (⌘,). */
+  shortcut?: string | undefined;
+  /** Red text: sign out, delete. Place it last, after a separator. */
+  destructive?: boolean | undefined;
+  /** Why it is unavailable: shown under the label (disables the item). */
+  disabledReason?: ReactNode;
+  /** A second line (a workspace's role). */
+  description?: ReactNode;
+};
+
+/** MenuItem — one action. Keyboard: arrows, Home/End, typeahead, Enter (Radix). */
+export function MenuItem({ children, icon, shortcut, destructive, disabledReason, description, disabled, className, ...rest }: MenuItemProps) {
+  return (
+    <MenuPrimitive.Item disabled={disabled || Boolean(disabledReason)} className={cn(itemBase, destructive && 'text-error-text', className)} {...rest}>
+      {icon && <span className="grid size-4 shrink-0 place-items-center text-fg-secondary">{icon}</span>}
+      <span className="flex min-w-0 flex-1 flex-col">
+        <span className="truncate">{children}</span>
+        {(disabledReason || description) && <span className="text-meta text-fg-secondary">{disabledReason ?? description}</span>}
+      </span>
+      {shortcut && <kbd className="ml-4 font-sans text-meta font-medium text-fg-secondary">{shortcut}</kbd>}
+    </MenuPrimitive.Item>
+  );
+}
+
+export type MenuCheckboxItemProps = Omit<ComponentProps<typeof MenuPrimitive.CheckboxItem>, 'children'> & { children: ReactNode; shortcut?: string | undefined };
+
+/** A toggle in a menu; checked shows a tick. */
+export function MenuCheckboxItem({ children, shortcut, className, ...rest }: MenuCheckboxItemProps) {
+  return (
+    <MenuPrimitive.CheckboxItem className={cn(itemBase, 'pl-8', className)} {...rest}>
+      <MenuPrimitive.ItemIndicator className="absolute left-2.5 grid size-4 place-items-center">
+        <Check size={14} strokeWidth={2} aria-hidden />
+      </MenuPrimitive.ItemIndicator>
+      <span className="flex-1 truncate">{children}</span>
+      {shortcut && <kbd className="ml-4 font-sans text-meta font-medium text-fg-secondary">{shortcut}</kbd>}
+    </MenuPrimitive.CheckboxItem>
+  );
+}
+
+/** A labelled group of items (Customer / Member when switching workspaces). */
+export function MenuGroup({ label, children }: { label?: ReactNode; children: ReactNode }) {
+  return (
+    <MenuPrimitive.Group>
+      {label && <MenuPrimitive.Label className="px-2.5 pt-2 pb-1 text-meta font-medium text-fg-secondary">{label}</MenuPrimitive.Label>}
+      {children}
+    </MenuPrimitive.Group>
+  );
+}
+
+export function MenuSeparator({ className }: { className?: string | undefined }) {
+  return <MenuPrimitive.Separator className={cn('mx-1 my-1.5 h-px bg-rule', className)} />;
+}
+
+export type MenuSubTriggerProps = Omit<ComponentProps<typeof MenuPrimitive.SubTrigger>, 'children'> & { children: ReactNode; icon?: ReactNode };
+
+/** Opens a nested menu (right arrow / Enter; left arrow closes). */
+export function MenuSubTrigger({ children, icon, className, ...rest }: MenuSubTriggerProps) {
+  return (
+    <MenuPrimitive.SubTrigger className={cn(itemBase, 'data-[state=open]:bg-hover', className)} {...rest}>
+      {icon && <span className="grid size-4 shrink-0 place-items-center text-fg-secondary">{icon}</span>}
+      <span className="flex-1 truncate">{children}</span>
+      <ChevronRight size={14} aria-hidden className="text-fg-secondary" />
+    </MenuPrimitive.SubTrigger>
+  );
+}
+
+export function MenuSubContent({ className, sideOffset = 4, ...rest }: ComponentProps<typeof MenuPrimitive.SubContent>) {
+  return (
+    <MenuPrimitive.Portal>
+      <MenuPrimitive.SubContent sideOffset={sideOffset} collisionPadding={8} className={cn(surface, className)} {...rest} />
+    </MenuPrimitive.Portal>
+  );
+}

package/src/components/PageHeader.tsx

@@ -0,0 +1,62 @@
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+export type PageHeaderFigure = { value: ReactNode; label: ReactNode };
+
+export type PageHeaderProps = Omit<ComponentProps<'header'>, 'title'> & {
+  /** "Project · Series A" */
+  eyebrow?: ReactNode;
+  title: ReactNode;
+  /** Beside the title: a Badge. */
+  status?: ReactNode;
+  /** A note line under the title: sync state, counts ("Syncing · 6,831 items"). */
+  note?: ReactNode;
+  /** A brand dot before the note (background work running). */
+  noteDot?: boolean | undefined;
+  /** Stat figures; hidden on phones. */
+  figures?: PageHeaderFigure[] | undefined;
+  /** Right-hand actions. */
+  actions?: ReactNode;
+  /** Heading level of the title. @default 1 */
+  level?: 1 | 2 | 3 | undefined;
+};
+
+/**
+ * PageHeader — the "seven in one" header card: eyebrow, title, status, a
+ * note line, figures (hidden on phones) and actions. Every part is optional
+ * but the title.
+ */
+export function PageHeader({ eyebrow, title, status, note, noteDot = false, figures, actions, level = 1, className, ...rest }: PageHeaderProps) {
+  const H = `h${level}` as const;
+  return (
+    <header className={cn('flex flex-col gap-4 rounded-lg bg-sunk p-5 text-fg', className)} {...rest}>
+      <div className="flex items-start justify-between gap-4">
+        <div className="flex min-w-0 flex-col gap-1.5">
+          {eyebrow && <div className="text-meta font-medium text-fg-secondary">{eyebrow}</div>}
+          <div className="flex min-w-0 flex-wrap items-center gap-2.5">
+            <H className="m-0 truncate text-title leading-tight font-medium tracking-heading">{title}</H>
+            {status}
+          </div>
+          {note && (
+            <div className="flex items-center gap-2 text-meta text-fg-secondary">
+              {noteDot && <span aria-hidden className="size-1.5 shrink-0 rounded-pill bg-brand-mark" />}
+              <span className="truncate">{note}</span>
+            </div>
+          )}
+        </div>
+        {actions && <div className="flex shrink-0 items-center gap-2">{actions}</div>}
+      </div>
+      {figures && figures.length > 0 && (
+        <dl className="m-0 hidden flex-wrap gap-x-8 gap-y-3 sm:flex">
+          {figures.map((f, i) => (
+            <div key={i} className="flex flex-col-reverse">
+              <dt className="text-meta text-fg-secondary">{f.label}</dt>
+              <dd className="m-0 text-title leading-tight font-medium tabular-nums">{f.value}</dd>
+            </div>
+          ))}
+        </dl>
+      )}
+    </header>
+  );
+}

package/src/components/PageState.tsx

@@ -0,0 +1,84 @@
+import { CloudOff, FileQuestion, FolderOpen, Info, Lock, RefreshCw, SearchX, TriangleAlert, type LucideIcon } from 'lucide-react';
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { Icon } from './Icon';
+
+export type PageStateKind = 'empty' | 'no-results' | 'forbidden' | 'not-found' | 'error' | 'offline';
+
+const GLYPH: Record<PageStateKind, LucideIcon> = {
+  empty: FolderOpen,
+  'no-results': SearchX,
+  forbidden: Lock,
+  'not-found': FileQuestion,
+  error: TriangleAlert,
+  offline: CloudOff,
+};
+
+export type PageStateProps = Omit<ComponentProps<'div'>, 'title' | 'children'> & {
+  kind: PageStateKind;
+  /** The one sentence: "No documents yet", "Couldn't load; your work is saved". */
+  title: ReactNode;
+  /** Optional second line. */
+  description?: ReactNode;
+  /** The one action (a Button): Upload files, Try again, Go to my documents. */
+  action?: ReactNode;
+  /** Tighter, for a panel or a list rather than a page. */
+  compact?: boolean | undefined;
+};
+
+/**
+ * PageState — one sentence and one action per state: nothing yet, no
+ * results, no access, not found, error, offline. Never "No results" while a
+ * search is still running (show a Skeleton instead).
+ */
+export function PageState({ kind, title, description, action, compact = false, className, ...rest }: PageStateProps) {
+  return (
+    <div
+      role={kind === 'error' || kind === 'offline' ? 'alert' : 'status'}
+      data-kind={kind}
+      className={cn('flex flex-col items-center text-center font-sans', compact ? 'gap-2 py-8' : 'gap-3 py-16', className)}
+      {...rest}
+    >
+      <span className={cn('grid place-items-center rounded-lg bg-sunk text-fg-secondary', compact ? 'size-10' : 'size-12')}>
+        <Icon icon={GLYPH[kind]} size={compact ? 18 : 22} />
+      </span>
+      <div className="flex flex-col gap-1">
+        <p className={cn('m-0 font-medium text-fg', compact ? 'text-small' : 'text-body')}>{title}</p>
+        {description && <p className="m-0 max-w-[44ch] text-small text-fg-secondary">{description}</p>}
+      </div>
+      {action && <div className="mt-1">{action}</div>}
+    </div>
+  );
+}
+
+export type PageNoticeProps = Omit<ComponentProps<'div'>, 'children'> & {
+  /** info: a quiet sunk line (a truncated document); update: a new version is out. */
+  tone?: 'info' | 'update' | undefined;
+  children: ReactNode;
+  /** One action: Refresh. */
+  action?: ReactNode;
+};
+
+/**
+ * PageNotice — a full-width line above the content: "This document has
+ * 1,240 pages. Only the first 500 were processed…", or "MetaRoom has been
+ * updated. Refresh to load this page."
+ */
+export function PageNotice({ tone = 'info', children, action, className, ...rest }: PageNoticeProps) {
+  return (
+    <div
+      role={tone === 'update' ? 'alert' : 'status'}
+      className={cn(
+        'flex items-center gap-3 rounded-md px-4 py-2.5 font-sans text-small',
+        tone === 'update' ? 'bg-brand-field text-ink' : 'bg-sunk text-fg',
+        className,
+      )}
+      {...rest}
+    >
+      <Icon icon={tone === 'update' ? RefreshCw : Info} size={15} className={tone === 'update' ? undefined : 'text-fg-secondary'} />
+      <span className="flex-1">{children}</span>
+      {action}
+    </div>
+  );
+}

package/src/components/Progress.tsx

@@ -0,0 +1,97 @@
+import { useEffect, useRef, useState, type ComponentProps, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { useLoop } from './status-motion';
+
+export type ProgressSegment = 'done' | 'current' | 'failed' | 'todo';
+
+export type ProgressProps = Omit<ComponentProps<'div'>, 'children'> & {
+  /** Accessible name ("Uploading Cap table.xlsx"). */
+  label: string;
+  /** Determinate: how far. Leave undefined (and no segments) for indeterminate. */
+  value?: number | undefined;
+  /** @default 100 */
+  max?: number | undefined;
+  /** Segmented: one entry per step — done ink, current the brand colour, failed red. */
+  segments?: ProgressSegment[] | undefined;
+  /** Always-visible progress text: "1.2 of 3.4 MB", "Preparing download", "Batch 3 of 5". */
+  text?: ReactNode;
+  /** Announced once when it ends. */
+  status?: 'active' | 'done' | 'failed' | undefined;
+  /** Words for the announcements. */
+  labels?: { done?: string; failed?: string } | undefined;
+};
+
+/** 0, 25, 50, 75 or 100 — screen readers hear these steps, not every tick. */
+export function progressStep(value: number, max: number): number {
+  if (max <= 0) return 0;
+  const pct = Math.min(100, Math.max(0, (value / max) * 100));
+  return Math.floor(pct / 25) * 25;
+}
+
+const SEGMENT = { done: 'bg-fg', current: 'bg-brand-mark', failed: 'bg-error', todo: 'bg-well' };
+
+/**
+ * Progress — one component, three forms: determinate, indeterminate,
+ * segmented. The text is always shown; screen readers hear 25% steps and
+ * the ending (done or failed), never every tick.
+ */
+export function Progress({ label, value, max = 100, segments, text, status = 'active', labels, className, ...rest }: ProgressProps) {
+  const determinate = value !== undefined && !segments;
+  const step = determinate ? progressStep(value, max) : null;
+  const [announce, setAnnounce] = useState('');
+  const lastStep = useRef<number | null>(null);
+  const lastStatus = useRef(status);
+
+  useEffect(() => {
+    if (status !== lastStatus.current) {
+      lastStatus.current = status;
+      if (status === 'done') setAnnounce(`${label}: ${labels?.done ?? 'done'}`);
+      if (status === 'failed') setAnnounce(`${label}: ${labels?.failed ?? 'failed'}`);
+      return;
+    }
+    if (step === null || step === lastStep.current) return;
+    const first = lastStep.current === null;
+    lastStep.current = step;
+    if (!first) setAnnounce(`${label}: ${step}%`);
+  }, [step, status, label, labels?.done, labels?.failed]);
+
+  const bar = useRef<HTMLDivElement | null>(null);
+  useLoop(bar, [{ transform: 'translateX(-100%)' }, { transform: 'translateX(250%)' }], { duration: 1400, easing: 'cubic-bezier(.2,0,.2,1)' }, value === undefined && !segments);
+
+  const aria =
+    determinate
+      ? { 'aria-valuemin': 0, 'aria-valuemax': max, 'aria-valuenow': Math.min(max, Math.max(0, value)) }
+      : segments
+        ? { 'aria-valuemin': 0, 'aria-valuemax': segments.length, 'aria-valuenow': segments.filter((s) => s === 'done').length }
+        : {};
+
+  return (
+    <div className={cn('flex flex-col gap-1.5 font-sans', className)} {...rest}>
+      <div role="progressbar" aria-label={label} {...aria} aria-valuetext={typeof text === 'string' ? text : undefined} className="relative">
+        {segments ? (
+          <div className="flex gap-1">
+            {segments.map((s, i) => (
+              <span key={i} data-segment={s} className={cn('h-1 flex-1 rounded-pill', SEGMENT[s])} />
+            ))}
+          </div>
+        ) : (
+          <div className={cn('h-1 overflow-hidden rounded-pill bg-well', status === 'failed' && 'bg-error-wash')}>
+            {determinate ? (
+              <div
+                className={cn('h-full rounded-pill transition-[width] duration-[180ms] ease-standard', status === 'failed' ? 'bg-error' : 'bg-brand-mark')}
+                style={{ width: `${Math.min(100, Math.max(0, (value / max) * 100))}%` }}
+              />
+            ) : (
+              <div ref={bar} className="h-full w-2/5 rounded-pill bg-brand-mark" />
+            )}
+          </div>
+        )}
+      </div>
+      {text !== undefined && <div className="text-meta font-medium text-fg-secondary tabular-nums">{text}</div>}
+      <span className="sr-only" aria-live="polite">
+        {announce}
+      </span>
+    </div>
+  );
+}

package/src/components/PulseDot.tsx

@@ -0,0 +1,31 @@
+import { useRef, type ComponentProps } from 'react';
+
+import { cn } from '../lib/cn';
+import { useLoop } from './status-motion';
+
+export type PulseDotProps = Omit<ComponentProps<'span'>, 'children'> & {
+  /** Pulse (background work or an agent running). Off: a still dot. @default true */
+  active?: boolean | undefined;
+  /** px. @default 9 */
+  size?: number | undefined;
+  /** Accessible text ("Agent running"). Without it the dot is decorative. */
+  label?: string | undefined;
+};
+
+/** PulseDot — a slowly pulsing brand dot while work runs; a still brand
+ *  dot under reduced motion. */
+export function PulseDot({ active = true, size = 9, label, className, style, ...rest }: PulseDotProps) {
+  const ref = useRef<HTMLSpanElement | null>(null);
+  useLoop(ref, [{ opacity: 1 }, { opacity: 0.35 }, { opacity: 1 }], { duration: 2400, easing: 'ease-in-out' }, active);
+  return (
+    <span
+      ref={ref}
+      role={label ? 'img' : undefined}
+      aria-label={label}
+      aria-hidden={label ? undefined : true}
+      className={cn('inline-block shrink-0 rounded-pill bg-brand-mark', className)}
+      style={{ width: size, height: size, ...style }}
+      {...rest}
+    />
+  );
+}