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

package/src/components/RecipientsInput.tsx

@@ -0,0 +1,252 @@
+import * as Popover from '@radix-ui/react-popover';
+import { X } from 'lucide-react';
+import { useId, useRef, useState, type KeyboardEvent, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { useField } from './Field';
+import { DEFAULT_LABELS, ListboxBody, type ListboxLabels, type ListItem } from './inputs-listbox';
+import { useDebouncedSearch } from './inputs-search';
+
+export type RecipientStatus = 'valid' | 'invalid' | 'unverified';
+export type Recipient = { email: string; name?: string | undefined; status: RecipientStatus };
+
+export type RecipientsInputProps = {
+  value?: Recipient[] | undefined;
+  defaultValue?: Recipient[] | undefined;
+  onChange?: ((recipients: Recipient[]) => void) | undefined;
+  /** People to suggest while typing (value = email). */
+  search?: ((query: string, signal: AbortSignal) => Promise<ListItem[]>) | undefined;
+  /** Status for a typed address that is well formed: valid, or unverified (dashed) when the caller can't confirm it. @default () => 'valid' */
+  verify?: ((email: string) => 'valid' | 'unverified') | undefined;
+  /** @default "Add people or paste emails" */
+  placeholder?: string | undefined;
+  labels?: Partial<ListboxLabels> & { remove?: ((r: Recipient) => string) | undefined; invalid?: string | undefined; unverified?: string | undefined };
+  disabled?: boolean | undefined;
+  /** A leading word inside the field, e.g. "To". */
+  prefix?: ReactNode | undefined;
+  id?: string | undefined;
+  'aria-label'?: string | undefined;
+  className?: string | undefined;
+};
+
+const EMAIL = /^[^\s@,;<>]+@[^\s@,;<>]+\.[^\s@,;<>]+$/;
+const SPLIT = /[\s,;]+/;
+
+/** "Anna K <anna@x.co>" → the address; anything else as typed. */
+function addressOf(token: string): string {
+  const m = token.match(/<([^>]+)>/);
+  return (m ? m[1]! : token).trim();
+}
+
+/**
+ * RecipientsInput — the "To" field. Addresses become chips as they are
+ * confirmed (Enter, comma, space or leaving the field); pasting a list
+ * splits it. A malformed address gets the red outline and opens for
+ * editing in place when clicked; one the caller can't confirm is dashed.
+ * Backspace in the empty field removes the last chip.
+ */
+export function RecipientsInput({
+  value,
+  defaultValue = [],
+  onChange,
+  search,
+  verify = () => 'valid',
+  placeholder = 'Add people or paste emails',
+  labels: labelsIn,
+  disabled,
+  prefix,
+  id,
+  className,
+  ...aria
+}: RecipientsInputProps) {
+  const field = useField();
+  const auto = useId();
+  const listId = `ri${auto}-list`;
+  const optionId = (i: number) => `ri${auto}-o${i}`;
+  const labels = { ...DEFAULT_LABELS, ...labelsIn };
+  const [own, setOwn] = useState<Recipient[]>(defaultValue);
+  const list = value ?? own;
+  const [text, setText] = useState('');
+  const [editing, setEditing] = useState<number | null>(null);
+  const [active, setActive] = useState(0);
+  const input = useRef<HTMLInputElement | null>(null);
+  const off = Boolean(disabled || field?.disabled);
+  const { status, result, retry } = useDebouncedSearch(text, search, { delay: 250 });
+  const items = (status === 'done' ? (result ?? []) : []).filter((i) => !list.some((r) => r.email.toLowerCase() === i.value.toLowerCase()));
+  // Suggestions only while there is something to suggest: a new address
+  // that matches no one is normal here, not "nothing matches".
+  const showList = Boolean(search) && text.trim().length > 0 && editing === null && (status === 'searching' || status === 'error' || items.length > 0);
+
+  const commitList = (next: Recipient[]) => {
+    if (value === undefined) setOwn(next);
+    onChange?.(next);
+  };
+  const toRecipient = (token: string, name?: string): Recipient => {
+    const email = addressOf(token);
+    return { email, ...(name ? { name } : {}), status: EMAIL.test(email) ? verify(email) : 'invalid' };
+  };
+  /** Turn typed text into chips; returns true when something was added. */
+  const commitText = (raw: string, at: number | null = null) => {
+    const tokens = raw.split(SPLIT).map((t) => t.trim()).filter(Boolean);
+    if (!tokens.length) return false;
+    const fresh = tokens.map((t) => toRecipient(t)).filter((r) => !list.some((x, i) => i !== at && x.email.toLowerCase() === r.email.toLowerCase()));
+    const next = [...list];
+    if (at === null) next.push(...fresh);
+    else next.splice(at, 1, ...fresh);
+    commitList(next);
+    setText('');
+    setEditing(null);
+    return true;
+  };
+  const choose = (i: number) => {
+    const it = items[i];
+    if (!it) return;
+    commitList([...list, { email: it.value, name: it.label, status: 'valid' }]);
+    setText('');
+  };
+
+  const onKey = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (showList && items.length && (e.key === 'ArrowDown' || e.key === 'ArrowUp')) {
+      e.preventDefault();
+      setActive((a) => (e.key === 'ArrowDown' ? Math.min(items.length - 1, a + 1) : Math.max(0, a - 1)));
+      return;
+    }
+    if (e.key === 'Enter' || e.key === ',' || e.key === ';' || (e.key === ' ' && text.trim()) || (e.key === 'Tab' && text.trim())) {
+      if (e.key === 'Enter' && showList && status === 'done' && items.length) {
+        e.preventDefault();
+        choose(active);
+        return;
+      }
+      if (commitText(text, editing)) e.preventDefault();
+      else if (e.key !== 'Tab' && e.key !== ' ') e.preventDefault();
+    } else if (e.key === 'Backspace' && !text && editing === null && list.length) {
+      e.preventDefault();
+      commitList(list.slice(0, -1));
+    } else if (e.key === 'Escape' && editing !== null) {
+      setEditing(null);
+      setText('');
+    }
+  };
+
+  const editInput = (
+    <input
+      ref={input}
+      id={editing === null ? (id ?? field?.id) : undefined}
+      value={text}
+      disabled={off}
+      placeholder={list.length || editing !== null ? undefined : placeholder}
+      aria-label={aria['aria-label'] ?? (field?.labelId ? undefined : placeholder)}
+      aria-labelledby={field?.labelId}
+      aria-describedby={field?.describedBy}
+      role={search ? 'combobox' : undefined}
+      aria-expanded={search ? showList : undefined}
+      aria-controls={search && showList ? listId : undefined}
+      aria-autocomplete={search ? 'list' : undefined}
+      aria-activedescendant={showList && status === 'done' && items.length ? optionId(active) : undefined}
+      autoComplete="off"
+      onChange={(e) => {
+        setText(e.target.value);
+        setActive(0);
+      }}
+      onPaste={(e) => {
+        const pasted = e.clipboardData.getData('text');
+        if (SPLIT.test(pasted.trim())) {
+          e.preventDefault();
+          commitText(text + pasted, editing);
+        }
+      }}
+      onBlur={() => text.trim() && commitText(text, editing)}
+      onKeyDown={onKey}
+      className={cn('min-w-[8ch] flex-1 border-none bg-transparent p-0 py-1 font-sans text-[13px] text-fg outline-none placeholder:text-fg-secondary', editing !== null && 'min-w-[16ch]')}
+    />
+  );
+
+  return (
+    <Popover.Root open={showList} onOpenChange={() => {}}>
+      <Popover.Anchor asChild>
+        <div
+          onClick={(e) => e.target === e.currentTarget && input.current?.focus()}
+          className={cn(
+            'flex min-h-[38px] w-full flex-wrap items-center gap-1.5 rounded-md border border-rule bg-sunk px-2 py-1 font-sans text-fg',
+            'transition-[border-color] duration-[120ms] ease-standard focus-within:border-fg focus-within:shadow-(--focus-ring)',
+            off && 'cursor-not-allowed bg-well text-fg-secondary',
+            className,
+          )}
+        >
+          {prefix !== undefined && <span className="pr-0.5 pl-1 text-[12.5px] text-fg-secondary">{prefix}</span>}
+          {list.map((r, i) =>
+            editing === i ? (
+              <span key={`edit-${i}`} className="inline-flex rounded-sm border border-error bg-page px-1.5">
+                {editInput}
+              </span>
+            ) : (
+              <span
+                key={r.email + i}
+                className={cn(
+                  'inline-flex max-w-full items-center gap-1 rounded-sm border bg-page py-0.5 pr-1 pl-2 text-[12.5px] leading-[1.4]',
+                  r.status === 'invalid' ? 'border-error bg-error-wash' : r.status === 'unverified' ? 'border-dashed border-fg-secondary' : 'border-rule',
+                )}
+              >
+                {r.status === 'invalid' ? (
+                  <button
+                    type="button"
+                    disabled={off}
+                    onClick={() => {
+                      setEditing(i);
+                      setText(r.email);
+                      requestAnimationFrame(() => input.current?.focus());
+                    }}
+                    className="cursor-text truncate rounded-xs outline-none focus-visible:shadow-(--focus-ring)"
+                  >
+                    {r.email}
+                    <span className="sr-only">, {labelsIn?.invalid ?? 'not a valid address — edit'}</span>
+                  </button>
+                ) : (
+                  <span className="truncate" title={r.name ? r.email : undefined}>
+                    {r.name ?? r.email}
+                    {r.status === 'unverified' && <span className="sr-only">, {labelsIn?.unverified ?? 'unverified'}</span>}
+                  </span>
+                )}
+                {!off && (
+                  <button
+                    type="button"
+                    aria-label={labelsIn?.remove?.(r) ?? `Remove ${r.name ?? r.email}`}
+                    onClick={() => commitList(list.filter((_, k) => k !== i))}
+                    className="inline-grid cursor-pointer place-items-center rounded-xs text-fg-secondary outline-none hover:text-fg focus-visible:shadow-(--focus-ring)"
+                  >
+                    <X size={12} aria-hidden />
+                  </button>
+                )}
+              </span>
+            ),
+          )}
+          {editing === null && editInput}
+        </div>
+      </Popover.Anchor>
+      <Popover.Portal>
+        <Popover.Content
+          align="start"
+          sideOffset={6}
+          collisionPadding={12}
+          onOpenAutoFocus={(e) => 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={text.trim()}
+            canCreate={false}
+            labels={labels}
+            onActive={setActive}
+            onChoose={choose}
+            onRetry={retry}
+          />
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+}

package/src/components/SearchField.tsx

@@ -0,0 +1,137 @@
+import { Search, X } from 'lucide-react';
+import { useEffect, useRef, useState, type ComponentProps, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { useField } from './Field';
+import { controlFrame, controlInner } from './forms-control';
+import { useDebouncedSearch } from './inputs-search';
+import { Spinner } from './Spinner';
+
+export type SearchFieldProps = Omit<ComponentProps<'input'>, 'size' | 'value' | 'defaultValue' | 'onChange' | 'type'> & {
+  value?: string | undefined;
+  defaultValue?: string | undefined;
+  /** Every keystroke (the field is controlled or not). */
+  onChange?: ((value: string) => void) | undefined;
+  /**
+   * Runs after the debounce with an AbortSignal that fires when newer input
+   * arrives. Resolve with the result count to show it (14 results); a late
+   * answer to an older query is ignored.
+   */
+  onSearch?: ((query: string, signal: AbortSignal) => Promise<number | void>) | undefined;
+  /** ms. @default 250 */
+  debounce?: number | undefined;
+  /** Focus with / or ⌘K / Ctrl+K. One field per page. */
+  shortcut?: boolean | undefined;
+  /** The count line. @default (n) => `${n} results` */
+  formatCount?: ((count: number) => ReactNode) | undefined;
+  /** Accessible name of the clear button. @default "Clear search" */
+  clearLabel?: string | undefined;
+  size?: 'sm' | 'md' | 'lg' | undefined;
+};
+
+function isTyping(el: EventTarget | null): boolean {
+  const e = el as HTMLElement | null;
+  return Boolean(e && (e.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(e.tagName)));
+}
+
+/**
+ * SearchField — search with the debounce built in, so pages stop writing
+ * their own. Four states: empty (with the / hint when it has a shortcut),
+ * searching (a spinner — never "No results" before the answer), a result
+ * count, and cleared. New input cancels the request in flight.
+ */
+export function SearchField({
+  value,
+  defaultValue = '',
+  onChange,
+  onSearch,
+  debounce = 250,
+  shortcut = false,
+  formatCount = (n) => (n === 1 ? '1 result' : `${n} results`),
+  clearLabel = 'Clear search',
+  size,
+  placeholder = 'Search',
+  className,
+  id,
+  ref,
+  ...rest
+}: SearchFieldProps) {
+  const field = useField();
+  const [own, setOwn] = useState(defaultValue);
+  const text = value ?? own;
+  const inner = useRef<HTMLInputElement | null>(null);
+  const { status, result } = useDebouncedSearch(text, onSearch, { delay: debounce });
+
+  const set = (v: string) => {
+    if (value === undefined) setOwn(v);
+    onChange?.(v);
+  };
+
+  useEffect(() => {
+    if (!shortcut) return;
+    const onKey = (e: KeyboardEvent) => {
+      const k = e.key.toLowerCase();
+      if ((k === 'k' && (e.metaKey || e.ctrlKey)) || (e.key === '/' && !isTyping(e.target) && !e.metaKey && !e.ctrlKey)) {
+        e.preventDefault();
+        inner.current?.focus();
+        inner.current?.select();
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [shortcut]);
+
+  const off = Boolean(rest.disabled || field?.disabled);
+  const count = status === 'done' && typeof result === 'number' ? result : null;
+
+  return (
+    <div role="search" className={cn(controlFrame({ size, disabled: off, invalid: Boolean(field?.invalid) }), className)}>
+      <Search size={14} aria-hidden className="shrink-0 text-fg-secondary" />
+      <input
+        {...rest}
+        ref={(el) => {
+          inner.current = el;
+          if (typeof ref === 'function') ref(el);
+          else if (ref) ref.current = el;
+        }}
+        id={id ?? field?.id}
+        type="search"
+        value={text}
+        placeholder={placeholder}
+        disabled={off}
+        aria-describedby={cn(rest['aria-describedby'], field?.describedBy) || undefined}
+        onChange={(e) => set(e.target.value)}
+        onKeyDown={(e) => {
+          rest.onKeyDown?.(e);
+          if (e.key === 'Escape' && text) {
+            e.preventDefault();
+            set('');
+          }
+        }}
+        className={cn(controlInner, '[&::-webkit-search-cancel-button]:hidden')}
+      />
+      <span aria-live="polite" className="flex shrink-0 items-center gap-2 text-meta whitespace-nowrap text-fg-secondary tabular-nums">
+        {status === 'searching' ? <Spinner label="Searching" size={12} /> : count !== null ? formatCount(count) : null}
+      </span>
+      {text ? (
+        <button
+          type="button"
+          aria-label={clearLabel}
+          onClick={() => {
+            set('');
+            inner.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>
+      ) : (
+        shortcut && (
+          <kbd aria-hidden className="shrink-0 rounded-xs border border-rule px-1.5 font-sans text-[11px] leading-[18px] text-fg-secondary">
+            /
+          </kbd>
+        )
+      )}
+    </div>
+  );
+}

package/src/components/SegmentedControl.tsx

@@ -0,0 +1,95 @@
+import * as RadioPrimitive from '@radix-ui/react-radio-group';
+import { useLayoutEffect, useRef, useState, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { definedAria } from './inputs-aria';
+import { Tooltip } from './Tooltip';
+
+export type Segment = {
+  value: string;
+  label: ReactNode;
+  /** Unavailable; say why (shown on hover and focus, and read out). */
+  disabled?: boolean | undefined;
+  reason?: string | undefined;
+};
+
+export type SegmentedControlProps = {
+  segments: Segment[];
+  value?: string | undefined;
+  defaultValue?: string | undefined;
+  onChange?: ((value: string) => void) | undefined;
+  /** Accessible name when there is no visible label. */
+  'aria-label'?: string | undefined;
+  'aria-labelledby'?: string | undefined;
+  /** 32 · 38. @default "md" */
+  size?: 'sm' | 'md' | undefined;
+  className?: string | undefined;
+};
+
+/**
+ * SegmentedControl — two to five mutually exclusive views or modes, side
+ * by side. Radio semantics: one tab stop, arrows move and choose. The
+ * selected segment sits on the brand colour and the marker glides to it
+ * (still, with reduced motion). A disabled segment explains why.
+ */
+export function SegmentedControl({ segments, value, defaultValue, onChange, size = 'md', className, ...aria }: SegmentedControlProps) {
+  const [own, setOwn] = useState(defaultValue ?? segments.find((s) => !s.disabled)?.value);
+  const current = value ?? own;
+  const root = useRef<HTMLDivElement | null>(null);
+  const [marker, setMarker] = useState<{ left: number; width: number } | null>(null);
+
+  useLayoutEffect(() => {
+    const el = root.current?.querySelector<HTMLElement>('[data-state="checked"]');
+    setMarker(el ? { left: el.offsetLeft, width: el.offsetWidth } : null);
+  }, [current, segments]);
+
+  return (
+    <RadioPrimitive.Root
+      ref={root}
+      value={current ?? ''}
+      onValueChange={(v) => {
+        if (value === undefined) setOwn(v);
+        onChange?.(v);
+      }}
+      orientation="horizontal"
+      loop
+      {...definedAria(aria)}
+      className={cn('relative inline-flex rounded-md border border-rule bg-sunk p-[3px] font-sans', className)}
+    >
+      {marker && (
+        <span
+          aria-hidden
+          className="absolute top-[3px] bottom-[3px] rounded-sm bg-brand-field motion-safe:transition-[left,width] motion-safe:duration-[320ms] motion-safe:ease-out"
+          style={{ left: marker.left, width: marker.width }}
+        />
+      )}
+      {segments.map((s) => {
+        const item = (
+          <RadioPrimitive.Item
+            key={s.value}
+            value={s.value}
+            disabled={s.disabled}
+            className={cn(
+              'relative z-[1] inline-flex cursor-pointer items-center gap-1.5 rounded-sm px-3 font-medium whitespace-nowrap text-fg-secondary outline-none',
+              'transition-colors duration-[120ms] ease-standard hover:text-fg focus-visible:shadow-(--focus-ring)',
+              'data-[state=checked]:text-ink disabled:cursor-not-allowed disabled:opacity-40',
+              size === 'sm' ? 'h-[24px] text-meta' : 'h-[30px] text-[13px]',
+            )}
+          >
+            {s.label}
+            {s.disabled && s.reason && <span className="sr-only">, {s.reason}</span>}
+          </RadioPrimitive.Item>
+        );
+        return s.disabled && s.reason ? (
+          <Tooltip key={s.value} content={s.reason}>
+            <span className="relative z-[1] inline-flex" tabIndex={-1}>
+              {item}
+            </span>
+          </Tooltip>
+        ) : (
+          item
+        );
+      })}
+    </RadioPrimitive.Root>
+  );
+}

package/src/components/SidePanel.tsx

@@ -0,0 +1,130 @@
+import { X } from 'lucide-react';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useState,
+  type ComponentProps,
+  type ReactNode,
+} from 'react';
+import { createPortal } from 'react-dom';
+
+import { cn } from '../lib/cn';
+import { IconButton } from './IconButton';
+
+type SlotContext = {
+  /** The panel in the slot, if any. */
+  openId: string | null;
+  open: (id: string) => void;
+  close: (id?: string) => void;
+  slot: HTMLElement | null;
+  setSlot: (el: HTMLElement | null) => void;
+};
+
+const SidePanelContext = createContext<SlotContext | null>(null);
+
+/**
+ * SidePanelProvider — the page's one right-hand slot. Opening a panel
+ * closes whatever held the slot (Share and the Agent drawer never show
+ * together). Place <SidePanelSlot/> beside the main content.
+ */
+export function SidePanelProvider({ children }: { children: ReactNode }) {
+  const [openId, setOpenId] = useState<string | null>(null);
+  const [slot, setSlot] = useState<HTMLElement | null>(null);
+  const open = useCallback((id: string) => setOpenId(id), []);
+  const close = useCallback((id?: string) => setOpenId((cur) => (id === undefined || cur === id ? null : cur)), []);
+  const value = useMemo(() => ({ openId, open, close, slot, setSlot }), [openId, open, close, slot]);
+  return <SidePanelContext.Provider value={value}>{children}</SidePanelContext.Provider>;
+}
+
+/** The slot's state and controls. */
+export function useSidePanel() {
+  const ctx = useContext(SidePanelContext);
+  if (!ctx) throw new Error('useSidePanel needs a <SidePanelProvider>');
+  const { openId, open, close } = ctx;
+  return { openId, open, close };
+}
+
+/** Where the open panel renders: a flex sibling of the main content, so it pushes the content (no overlay). */
+export function SidePanelSlot({ className, ...rest }: ComponentProps<'div'>) {
+  const ctx = useContext(SidePanelContext);
+  const setSlot = ctx?.setSlot;
+  return <div ref={setSlot} className={cn('flex h-full shrink-0', className)} {...rest} />;
+}
+
+const WIDTH = { sm: 'sm:w-[360px]', md: 'sm:w-[480px]', lg: 'sm:w-[640px]' } as const;
+
+export type SidePanelProps = Omit<ComponentProps<'aside'>, 'title'> & {
+  /** The panel's id in the slot. */
+  id: string;
+  title: ReactNode;
+  /** A line above the title (the item it is about). */
+  eyebrow?: ReactNode;
+  /** 360 · 480 · 640. @default "sm" */
+  width?: keyof typeof WIDTH | undefined;
+  /** Pinned at the bottom (New share). */
+  footer?: ReactNode;
+  /** @default "Close" */
+  closeLabel?: string | undefined;
+  onClose?: (() => void) | undefined;
+};
+
+/**
+ * SidePanel — detail beside the page (sharing, properties, the Agent).
+ * No scrim and no focus trap: the page stays usable; it pushes the content
+ * aside. Esc closes it (unless a dialog is open above). On phones it pushes
+ * in full screen. Renders only while it holds the slot.
+ */
+export function SidePanel({ id, title, eyebrow, width = 'sm', footer, closeLabel = 'Close', onClose, className, children, ...rest }: SidePanelProps) {
+  const ctx = useContext(SidePanelContext);
+  if (!ctx) throw new Error('SidePanel needs a <SidePanelProvider>');
+  const { openId, close, slot } = ctx;
+  const isOpen = openId === id;
+  const titleId = useId();
+
+  const dismiss = useCallback(() => {
+    close(id);
+    onClose?.();
+  }, [close, id, onClose]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== 'Escape' || e.defaultPrevented) return;
+      if (document.querySelector('[role="dialog"][data-state="open"], [role="alertdialog"][data-state="open"]')) return;
+      dismiss();
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [isOpen, dismiss]);
+
+  if (!isOpen || !slot) return null;
+  return createPortal(
+    <aside
+      aria-labelledby={titleId}
+      className={cn(
+        'flex h-full flex-col border-l border-rule bg-page font-sans text-fg',
+        'max-sm:fixed max-sm:inset-0 max-sm:z-40 max-sm:w-full max-sm:border-l-0',
+        WIDTH[width],
+        className,
+      )}
+      {...rest}
+    >
+      <header className="flex items-start gap-3 border-b border-rule px-5 py-4">
+        <div className="min-w-0 flex-1">
+          {eyebrow && <div className="mb-1 text-meta font-medium text-fg-secondary">{eyebrow}</div>}
+          <h2 id={titleId} className="m-0 truncate text-[16px] leading-[1.3] font-medium">
+            {title}
+          </h2>
+        </div>
+        <IconButton icon={X} label={closeLabel} size="sm" onClick={dismiss} className="-mt-1 -mr-2" />
+      </header>
+      <div className="min-h-0 flex-1 overflow-y-auto px-5 py-4 text-ui">{children}</div>
+      {footer && <footer className="border-t border-rule px-5 py-3.5">{footer}</footer>}
+    </aside>,
+    slot,
+  );
+}

package/src/components/Skeleton.tsx

@@ -0,0 +1,73 @@
+import { useEffect, useRef, useState, type ComponentProps } from 'react';
+
+import { cn } from '../lib/cn';
+import { useLoop } from './status-motion';
+
+export type SkeletonProps = ComponentProps<'div'>;
+
+/** Skeleton — a sunk placeholder block that breathes slowly (still under reduced motion). */
+export function Skeleton({ className, ...rest }: SkeletonProps) {
+  const ref = useRef<HTMLDivElement | null>(null);
+  useLoop(ref, [{ opacity: 1 }, { opacity: 0.55 }, { opacity: 1 }], { duration: 1600, easing: 'ease-in-out' });
+  return <div ref={ref} aria-hidden className={cn('rounded-sm bg-well', className)} {...rest} />;
+}
+
+type Busy = { label?: string | undefined; className?: string | undefined };
+
+/** A list of rows loading. */
+export function SkeletonList({ rows = 6, label = 'Loading', className }: Busy & { rows?: number | undefined }) {
+  return (
+    <div role="status" aria-busy="true" aria-label={label} className={cn('flex flex-col', className)}>
+      {Array.from({ length: rows }, (_, i) => (
+        <div key={i} className="flex items-center gap-3 border-b border-rule-soft py-3">
+          <Skeleton className="size-8 rounded-md" />
+          <div className="flex flex-1 flex-col gap-2">
+            <Skeleton className="h-3 w-2/5" />
+            <Skeleton className="h-2.5 w-1/4" />
+          </div>
+          <Skeleton className="h-3 w-16" />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/** A grid of cards loading. */
+export function SkeletonCards({ count = 6, label = 'Loading', className }: Busy & { count?: number | undefined }) {
+  return (
+    <div role="status" aria-busy="true" aria-label={label} className={cn('grid grid-cols-[repeat(auto-fill,minmax(180px,1fr))] gap-4', className)}>
+      {Array.from({ length: count }, (_, i) => (
+        <div key={i} className="flex flex-col gap-3 rounded-lg border border-rule p-3">
+          <Skeleton className="aspect-[4/3] w-full rounded-md" />
+          <Skeleton className="h-3 w-3/4" />
+          <Skeleton className="h-2.5 w-1/2" />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export type SkeletonViewerProps = Busy & {
+  /** What the wait is called as it gets longer. @default Opening… then, after 3 s, Rendering page 1… */
+  messages?: { after: number; text: string }[] | undefined;
+};
+
+/** A document opening: a page placeholder whose wording changes on long waits. */
+export function SkeletonViewer({ messages = [{ after: 0, text: 'Opening…' }, { after: 3000, text: 'Rendering page 1…' }], className }: SkeletonViewerProps) {
+  const sorted = [...messages].sort((a, b) => a.after - b.after);
+  const [index, setIndex] = useState(0);
+  useEffect(() => {
+    const timers = sorted.slice(1).map((m, i) => setTimeout(() => setIndex(i + 1), m.after));
+    return () => timers.forEach(clearTimeout);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [JSON.stringify(sorted)]);
+  const text = sorted[index]?.text ?? '';
+  return (
+    <div role="status" aria-busy="true" className={cn('flex flex-col items-center gap-4 rounded-lg bg-sunk p-8', className)}>
+      <Skeleton className="aspect-[1/1.3] w-full max-w-[360px] rounded-md bg-page" />
+      <span aria-live="polite" className="text-meta font-medium text-fg-secondary">
+        {text}
+      </span>
+    </div>
+  );
+}