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

package/src/components/Tabs.tsx

@@ -0,0 +1,124 @@
+import * as TabsPrimitive from '@radix-ui/react-tabs';
+import { createContext, useContext, type ComponentProps, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { formatCount } from './Button';
+
+export type TabsVariant = 'underline' | 'pills';
+
+export type TabItem = {
+  value: string;
+  label: ReactNode;
+  /** An attention count after the label: a small yellow badge, hidden at zero. */
+  count?: number | undefined;
+  disabled?: boolean | undefined;
+};
+
+const VariantContext = createContext<TabsVariant>('underline');
+
+export type TabsProps = Omit<ComponentProps<typeof TabsPrimitive.Root>, 'onValueChange' | 'onChange' | 'children'> & {
+  /** underline for product UI · pills for marketing sections (active one on the brand field). @default "underline" */
+  variant?: TabsVariant | undefined;
+  /** Called with the new tab's value. Keep the active tab in the URL so refresh and sharing keep it. */
+  onChange?: ((value: string) => void) | undefined;
+  /** Shorthand: renders the tab list from these. Two to seven; beyond that use More or a side menu. */
+  items?: TabItem[] | undefined;
+  /** Accessible name of the tab list (with `items`). */
+  label?: string | undefined;
+  /** TabPanels (and, without `items`, a TabList). */
+  children?: ReactNode;
+};
+
+/**
+ * Tabs — switch between views of the same object (Overview, Documents,
+ * Parties). Switching changes no data; segments change how the same
+ * content shows, tabs change the content. Arrow keys move, Home/End jump
+ * (Radix Tabs).
+ */
+export function Tabs({ variant = 'underline', onChange, items, label, className, children, ...rest }: TabsProps) {
+  return (
+    <VariantContext.Provider value={variant}>
+      <TabsPrimitive.Root {...(onChange ? { onValueChange: onChange } : {})} className={cn('flex flex-col', className)} {...rest}>
+        {items && (
+          <TabList aria-label={label}>
+            {items.map((it) => (
+              <Tab key={it.value} value={it.value} count={it.count} disabled={it.disabled}>
+                {it.label}
+              </Tab>
+            ))}
+          </TabList>
+        )}
+        {children}
+      </TabsPrimitive.Root>
+    </VariantContext.Provider>
+  );
+}
+
+export type TabListProps = ComponentProps<typeof TabsPrimitive.List>;
+
+export function TabList({ className, ...rest }: TabListProps) {
+  const variant = useContext(VariantContext);
+  return (
+    <TabsPrimitive.List
+      className={cn(variant === 'pills' ? 'flex gap-2.5 [counter-reset:cosx-tab]' : 'flex gap-0.5 border-b border-rule', className)}
+      {...rest}
+    />
+  );
+}
+
+export type TabProps = ComponentProps<typeof TabsPrimitive.Trigger> & {
+  count?: number | undefined;
+};
+
+export function Tab({ className, children, count, ...rest }: TabProps) {
+  const variant = useContext(VariantContext);
+  const shown = count === undefined ? null : formatCount(count);
+  const badge = shown && (
+    <span className="min-w-[18px] rounded-pill bg-brand-mark px-1.5 text-[11px] leading-[18px] font-semibold text-ink tabular-nums">
+      {shown}
+    </span>
+  );
+
+  if (variant === 'pills') {
+    return (
+      <TabsPrimitive.Trigger
+        className={cn(
+          'group flex flex-1 cursor-pointer items-center gap-3 rounded-md border-0 bg-sunk px-[18px] py-3.5 text-left font-sans text-ui font-medium text-fg outline-none',
+          'transition-colors duration-[120ms] ease-standard focus-visible:shadow-(--focus-ring)',
+          'data-[state=active]:bg-brand-field data-[state=active]:text-ink',
+          'disabled:cursor-not-allowed disabled:opacity-40',
+          '[counter-increment:cosx-tab] before:text-meta before:font-normal before:text-fg-secondary before:content-[counter(cosx-tab,decimal-leading-zero)] data-[state=active]:before:text-ink',
+          className,
+        )}
+        {...rest}
+      >
+        {children}
+        {badge && ' '}
+        {badge}
+      </TabsPrimitive.Trigger>
+    );
+  }
+
+  return (
+    <TabsPrimitive.Trigger
+      className={cn(
+        '-mb-px inline-flex cursor-pointer items-center gap-2 border-0 border-b-2 border-transparent bg-transparent px-3 py-2.5 font-sans text-small text-fg-secondary outline-none',
+        'transition-colors duration-[120ms] ease-standard hover:text-fg focus-visible:shadow-(--focus-ring)',
+        'data-[state=active]:border-fg data-[state=active]:font-medium data-[state=active]:text-fg',
+        'disabled:cursor-not-allowed disabled:opacity-40',
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+      {badge && ' '}
+      {badge}
+    </TabsPrimitive.Trigger>
+  );
+}
+
+export type TabPanelProps = ComponentProps<typeof TabsPrimitive.Content>;
+
+export function TabPanel({ className, ...rest }: TabPanelProps) {
+  return <TabsPrimitive.Content className={cn('pt-4 outline-none focus-visible:shadow-(--focus-ring)', className)} {...rest} />;
+}

package/src/components/Tag.tsx

@@ -0,0 +1,35 @@
+import { X } from 'lucide-react';
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+export type TagProps = Omit<ComponentProps<'span'>, 'children'> & {
+  children: ReactNode;
+  /** Shows a remove button. */
+  onRemove?: (() => void) | undefined;
+  /** Accessible name of the remove button. @default "Remove" */
+  removeLabel?: string | undefined;
+};
+
+/** Tag — quiet metadata on linen: format, origin, category, permission.
+ *  Attributes are tags, never status colours (that is Badge). */
+export function Tag({ children, onRemove, removeLabel = 'Remove', className, ...rest }: TagProps) {
+  return (
+    <span
+      className={cn('inline-flex items-center gap-1.5 rounded-md border border-rule-soft bg-sunk px-[7px] py-[3px] text-meta leading-[1.3] text-fg-secondary', className)}
+      {...rest}
+    >
+      {children}
+      {onRemove && (
+        <button
+          type="button"
+          onClick={onRemove}
+          aria-label={removeLabel}
+          className="-mr-0.5 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} strokeWidth={2} aria-hidden />
+        </button>
+      )}
+    </span>
+  );
+}

package/src/components/Textarea.tsx

@@ -0,0 +1,46 @@
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { Field, useField } from './Field';
+import { controlFrame, controlInner } from './forms-control';
+
+export type TextareaProps = ComponentProps<'textarea'> & {
+  label?: ReactNode;
+  hint?: ReactNode;
+  error?: ReactNode;
+  invalid?: boolean | undefined;
+  /** Class for the outer frame (className goes to the <textarea>). */
+  frameClassName?: string | undefined;
+};
+
+function Control({ invalid, frameClassName, className, disabled, readOnly, rows = 4, id, ...rest }: Omit<TextareaProps, 'label' | 'hint' | 'error'>) {
+  const field = useField();
+  const bad = Boolean(invalid || field?.invalid);
+  const off = Boolean(disabled || field?.disabled);
+  return (
+    <div className={cn(controlFrame({ invalid: bad, disabled: off, readOnly: Boolean(readOnly) && !off }), 'h-auto items-stretch py-2', frameClassName)}>
+      <textarea
+        {...rest}
+        id={id ?? field?.id}
+        rows={rows}
+        disabled={off}
+        readOnly={readOnly}
+        aria-invalid={bad || undefined}
+        aria-describedby={cn(rest['aria-describedby'], field?.describedBy) || undefined}
+        className={cn(controlInner, 'resize-y leading-[1.55]', className)}
+      />
+    </div>
+  );
+}
+
+/** Textarea — multi-line text in the same sunk frame as Input. */
+export function Textarea({ label, hint, error, required, ...rest }: TextareaProps) {
+  if (label !== undefined || hint !== undefined || error !== undefined) {
+    return (
+      <Field label={label} hint={hint} error={error} required={required} disabled={rest.disabled} id={rest.id}>
+        <Control {...rest} required={required} />
+      </Field>
+    );
+  }
+  return <Control {...rest} required={required} />;
+}

package/src/components/ThemeProvider.tsx

@@ -0,0 +1,80 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useState, type ReactNode } from 'react';
+
+/** system follows the OS; light is paper; ink is the dark page. */
+export type ThemeMode = 'system' | 'light' | 'ink';
+
+type ThemeContextValue = {
+  /** What the person chose. */
+  mode: ThemeMode;
+  /** What is showing now (system resolved). */
+  resolved: 'light' | 'ink';
+  setMode: (mode: ThemeMode) => void;
+};
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+const QUERY = '(prefers-color-scheme: dark)';
+
+function readStored(key: string | null): ThemeMode | null {
+  if (!key) return null;
+  try {
+    const v = localStorage.getItem(key);
+    return v === 'system' || v === 'light' || v === 'ink' ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+export type ThemeProviderProps = {
+  children: ReactNode;
+  /** @default "system" */
+  defaultMode?: ThemeMode | undefined;
+  /** localStorage key for the choice; null keeps it in memory only. @default "cosx-theme" */
+  storageKey?: string | null | undefined;
+};
+
+/**
+ * ThemeProvider — system (default) / light / ink. Sets data-mode="ink" on
+ * <html> when the ink page shows (the tokens switch on it); follows the OS
+ * live in system mode.
+ */
+export function ThemeProvider({ children, defaultMode = 'system', storageKey = 'cosx-theme' }: ThemeProviderProps) {
+  const [mode, setModeState] = useState<ThemeMode>(() => readStored(storageKey) ?? defaultMode);
+  const [systemInk, setSystemInk] = useState(() => typeof window !== 'undefined' && window.matchMedia?.(QUERY).matches === true);
+
+  useEffect(() => {
+    const mq = window.matchMedia?.(QUERY);
+    if (!mq) return;
+    const onChange = (e: MediaQueryListEvent) => setSystemInk(e.matches);
+    mq.addEventListener('change', onChange);
+    return () => mq.removeEventListener('change', onChange);
+  }, []);
+
+  const resolved: 'light' | 'ink' = mode === 'system' ? (systemInk ? 'ink' : 'light') : mode;
+
+  useEffect(() => {
+    const root = document.documentElement;
+    if (resolved === 'ink') root.setAttribute('data-mode', 'ink');
+    else root.removeAttribute('data-mode');
+  }, [resolved]);
+
+  const setMode = useCallback(
+    (next: ThemeMode) => {
+      setModeState(next);
+      if (!storageKey) return;
+      try {
+        localStorage.setItem(storageKey, next);
+      } catch {
+        /* storage unavailable: the choice lasts for this page */
+      }
+    },
+    [storageKey],
+  );
+
+  const value = useMemo(() => ({ mode, resolved, setMode }), [mode, resolved, setMode]);
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+/** The current theme and a setter. Outside a ThemeProvider: light, no-op. */
+export function useTheme(): ThemeContextValue {
+  return useContext(ThemeContext) ?? { mode: 'light', resolved: 'light', setMode: () => {} };
+}

package/src/components/ThemeSwitch.tsx

@@ -0,0 +1,99 @@
+import { Monitor, Moon, Sun, type LucideIcon } from 'lucide-react';
+import { useRef, useState, type ComponentProps } from 'react';
+
+import { cn } from '../lib/cn';
+import { useTheme, type ThemeMode } from './ThemeProvider';
+
+export type ThemeSwitchLabels = {
+  /** @default "Theme" */
+  group?: string | undefined;
+  /** @default "Theme: match system" */
+  system?: string | undefined;
+  /** @default "Theme: light" */
+  light?: string | undefined;
+  /** @default "Theme: dark" */
+  ink?: string | undefined;
+};
+
+export type ThemeSwitchProps = Omit<ComponentProps<'div'>, 'onChange' | 'children'> & {
+  /** The choice. Unset: the ThemeProvider's. */
+  value?: ThemeMode | undefined;
+  /** Unset: the ThemeProvider's setter. */
+  onChange?: ((mode: ThemeMode) => void) | undefined;
+  labels?: ThemeSwitchLabels | undefined;
+  /** Start opened (documentation specimens); it folds once the pointer leaves. */
+  defaultOpen?: boolean | undefined;
+};
+
+/** A click on an option only picks it once the switch has been open this long. */
+const PICK_AFTER_MS = 800;
+
+/**
+ * ThemeSwitch — match system · light · dark, folded to the current choice.
+ * Hovering or focusing opens all three. A click anywhere steps to the next;
+ * a click on an option picks it only once the switch has been open a moment,
+ * so the first tap on touch (which opens it) steps instead of landing on
+ * whatever slid under the finger.
+ */
+export function ThemeSwitch({ value, onChange, labels, defaultOpen = false, className, ...rest }: ThemeSwitchProps) {
+  const theme = useTheme();
+  const mode = value ?? theme.mode;
+  const setMode = onChange ?? theme.setMode;
+  const [open, setOpen] = useState(defaultOpen);
+  const openedAt = useRef(0);
+  const show = () => {
+    if (open) return;
+    openedAt.current = Date.now();
+    setOpen(true);
+  };
+  const options: Array<[ThemeMode, LucideIcon, string]> = [
+    ['system', Monitor, labels?.system ?? 'Theme: match system'],
+    ['light', Sun, labels?.light ?? 'Theme: light'],
+    ['ink', Moon, labels?.ink ?? 'Theme: dark'],
+  ];
+  const cycle = () => {
+    const i = options.findIndex(([v]) => v === mode);
+    setMode(options[(i + 1) % options.length]![0]);
+  };
+  return (
+    <div
+      role="radiogroup"
+      aria-label={labels?.group ?? 'Theme'}
+      className={cn('inline-flex cursor-pointer rounded-[10px] bg-sunk p-[3px] transition-[gap] duration-[180ms] ease-standard', open ? 'gap-0.5' : 'gap-0', className)}
+      onClick={cycle}
+      onMouseEnter={show}
+      onMouseLeave={() => setOpen(false)}
+      onFocus={show}
+      onBlur={(e) => !e.currentTarget.contains(e.relatedTarget as Node | null) && setOpen(false)}
+      {...rest}
+    >
+      {options.map(([v, Glyph, label]) => {
+        const on = mode === v;
+        const shown = open || on;
+        return (
+          <button
+            key={v}
+            type="button"
+            role="radio"
+            aria-checked={on}
+            aria-label={label}
+            title={label}
+            tabIndex={shown ? 0 : -1}
+            onClick={(e) => {
+              e.stopPropagation();
+              if (open && Date.now() - openedAt.current > PICK_AFTER_MS) setMode(v);
+              else cycle();
+            }}
+            className={cn(
+              'grid h-7 cursor-pointer place-items-center overflow-hidden rounded-[8px] border-0 p-0 outline-none transition-[width,opacity] duration-[180ms] ease-standard focus-visible:shadow-(--focus-ring)',
+              shown ? 'w-[30px] opacity-100' : 'w-0 opacity-0',
+              on ? 'bg-page text-fg' : 'bg-transparent text-fg-secondary',
+            )}
+          >
+            <Glyph size={15} strokeWidth={1.75} aria-hidden />
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/Toast.tsx

@@ -0,0 +1,196 @@
+import * as ToastPrimitive from '@radix-ui/react-toast';
+import { X } from 'lucide-react';
+import { useSyncExternalStore, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+export type ToastStatus = 'neutral' | 'complete' | 'attention' | 'error' | 'progress';
+
+export type ToastOptions = {
+  /** One sentence in the past tense: "3 files moved to Archive." Errors say why and what next. */
+  title: ReactNode;
+  description?: ReactNode;
+  /** Sets the dot and the label. @default "neutral" */
+  status?: ToastStatus | undefined;
+  /** At most one: Undo or Retry. With an action the toast stays 8s and pauses on hover. */
+  action?: { label: string; onClick: () => void; altText?: string | undefined } | undefined;
+  /** ms. @default 4000, 8000 with an action */
+  duration?: number | undefined;
+};
+
+type Entry = ToastOptions & { id: number };
+
+/** At most three at once; the oldest leaves first. */
+const MAX_VISIBLE = 3;
+/** The same error shows once per 30 seconds. */
+const REPEAT_WINDOW = 30_000;
+
+let entries: Entry[] = [];
+let nextId = 1;
+const lastShown = new Map<string, number>();
+const listeners = new Set<() => void>();
+const emit = () => listeners.forEach((l) => l());
+
+function set(next: Entry[]) {
+  entries = next;
+  emit();
+}
+
+/**
+ * toast — report a result that happened off the page (a copy, a background
+ * move, an upload finishing elsewhere). When the result can show in place
+ * (a button, a row, a field), don't toast. Needs a <Toaster/> mounted once.
+ * Returns the toast id, or null when an identical error is suppressed.
+ */
+export function toast(options: ToastOptions): number | null {
+  const status = options.status ?? 'neutral';
+  if (status === 'error' && typeof options.title === 'string') {
+    const key = `error:${options.title}`;
+    const at = lastShown.get(key);
+    const now = Date.now();
+    if (at !== undefined && now - at < REPEAT_WINDOW) return null;
+    lastShown.set(key, now);
+  }
+  const id = nextId++;
+  // The oldest leaves when a fourth arrives.
+  set([...entries, { ...options, status, id }].slice(-MAX_VISIBLE));
+  return id;
+}
+
+/** Close a toast early. */
+toast.dismiss = (id: number) => set(entries.filter((e) => e.id !== id));
+
+/** Test and story helper: forget every toast and the repeat window. */
+toast.reset = () => {
+  lastShown.clear();
+  set([]);
+};
+
+function subscribe(l: () => void) {
+  listeners.add(l);
+  return () => listeners.delete(l);
+}
+
+const DOT: Record<ToastStatus, string> = {
+  neutral: 'bg-grey-inverse',
+  progress: 'bg-grey-inverse',
+  complete: 'bg-linen',
+  attention: 'bg-yellow-accent',
+  error: 'bg-error',
+};
+
+export type ToastLabels = Record<ToastStatus, string> & { dismiss: string; region: string };
+
+const DEFAULT_LABELS: ToastLabels = {
+  neutral: 'Notice',
+  complete: 'Done',
+  attention: 'Attention',
+  error: 'Failed',
+  progress: 'In progress',
+  dismiss: 'Dismiss',
+  region: 'Notifications',
+};
+
+const CARD = 'flex w-80 max-w-full items-start gap-3 rounded-[12px] bg-ink px-4 py-3.5 font-sans text-linen ink:border ink:border-inv-rule ink:bg-ink-raised';
+const ACTION =
+  'mt-2.5 inline-flex h-8 cursor-pointer items-center rounded-md border border-inv-rule bg-transparent px-3 text-[13px] font-semibold text-linen outline-none hover:border-linen focus-visible:shadow-[0_0_0_3px_var(--ink),0_0_0_5px_var(--yellow)]';
+const CLOSE = 'flex cursor-pointer rounded-xs border-0 bg-transparent p-0.5 text-grey-inverse outline-none hover:text-linen focus-visible:shadow-[0_0_0_2px_var(--yellow)]';
+const statusLabelClass = (status: ToastStatus) => cn('mb-0.5 text-meta font-medium', status === 'attention' ? 'text-yellow-accent' : 'text-grey-inverse');
+
+export type ToastCardProps = Omit<ToastOptions, 'duration' | 'action'> & {
+  /** A label, or the full action (label + onClick). */
+  action?: string | ToastOptions['action'];
+  onClose?: (() => void) | undefined;
+  labels?: Partial<ToastLabels> | undefined;
+  className?: string | undefined;
+};
+
+/**
+ * ToastCard — one toast drawn in place, not queued: documentation
+ * specimens and previews. In the product, call toast() instead.
+ */
+export function ToastCard({ title, description, status = 'neutral', action, onClose, labels, className }: ToastCardProps) {
+  const l = { ...DEFAULT_LABELS, ...labels };
+  const act = typeof action === 'string' ? { label: action, onClick: () => {} } : action;
+  return (
+    <div className={cn(CARD, className)}>
+      <span aria-hidden className={cn('mt-[5px] size-2 shrink-0 rounded-pill', DOT[status])} />
+      <div className="min-w-0 flex-1">
+        <div className={statusLabelClass(status)}>{l[status]}</div>
+        <div className="text-ui leading-[1.4] font-medium">{title}</div>
+        {description && <div className="mt-0.5 text-[13px] leading-normal text-grey-inverse">{description}</div>}
+        {act && (
+          <button type="button" onClick={act.onClick} className={ACTION}>
+            {act.label}
+          </button>
+        )}
+      </div>
+      <button type="button" aria-label={l.dismiss} onClick={onClose} className={CLOSE}>
+        <X size={14} strokeWidth={2} aria-hidden />
+      </button>
+    </div>
+  );
+}
+
+export type ToasterProps = {
+  /** Wording of the status labels and controls (e.g. Chinese). */
+  labels?: Partial<ToastLabels> | undefined;
+  /** px from the bottom — keep clear of the action bar and the zoom pill. @default 24 */
+  offset?: number | undefined;
+};
+
+/**
+ * Toaster — mount once. Ink notices, bottom right, three at most. Polite
+ * announcements (errors assertive); a toast never takes focus, its action
+ * is reachable by keyboard (F8 jumps to the region). Radix Toast.
+ */
+export function Toaster({ labels, offset = 24 }: ToasterProps) {
+  const list = useSyncExternalStore(subscribe, () => entries, () => entries);
+  const l = { ...DEFAULT_LABELS, ...labels };
+
+  return (
+    <ToastPrimitive.Provider swipeDirection="right" label={l.region}>
+      {list.map((t) => {
+        const status = t.status ?? 'neutral';
+        return (
+          <ToastPrimitive.Root
+            key={t.id}
+            open
+            onOpenChange={(open) => {
+              if (!open) set(entries.filter((e) => e.id !== t.id));
+            }}
+            duration={t.duration ?? (t.action ? 8000 : 4000)}
+            type={status === 'error' ? 'foreground' : 'background'}
+            className={cn(CARD, 'data-[swipe=move]:translate-x-(--radix-toast-swipe-move-x) data-[swipe=end]:hidden')}
+          >
+            <span aria-hidden className={cn('mt-[5px] size-2 shrink-0 rounded-pill', DOT[status])} />
+            <div className="min-w-0 flex-1">
+              <div className={statusLabelClass(status)}>{l[status]}</div>
+              <ToastPrimitive.Title className="text-ui leading-[1.4] font-medium">{t.title}</ToastPrimitive.Title>
+              {t.description && <ToastPrimitive.Description className="mt-0.5 text-[13px] leading-normal text-grey-inverse">{t.description}</ToastPrimitive.Description>}
+              {t.action && (
+                <ToastPrimitive.Action
+                  altText={t.action.altText ?? t.action.label}
+                  onClick={t.action.onClick}
+                  className={ACTION}
+                >
+                  {t.action.label}
+                </ToastPrimitive.Action>
+              )}
+            </div>
+            <ToastPrimitive.Close
+              aria-label={l.dismiss}
+              className={CLOSE}
+            >
+              <X size={14} strokeWidth={2} aria-hidden />
+            </ToastPrimitive.Close>
+          </ToastPrimitive.Root>
+        );
+      })}
+      <ToastPrimitive.Viewport
+        className="fixed right-6 z-[60] m-0 flex max-w-[calc(100vw-48px)] list-none flex-col gap-2.5 p-0 outline-none"
+        style={{ bottom: offset }}
+      />
+    </ToastPrimitive.Provider>
+  );
+}

package/src/components/Tooltip.tsx

@@ -0,0 +1,57 @@
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+import type { ReactElement, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+/** Shares the open delay across tooltips (moving between them is instant). Optional: each Tooltip brings one. */
+export const TooltipProvider = TooltipPrimitive.Provider;
+
+export type TooltipProps = {
+  /** The hint. Never the only way to reach information — a disabled reason also goes in the page or aria. */
+  content: ReactNode;
+  /** One focusable element (a button, a link). */
+  children: ReactElement;
+  /** Preferred side; flips to fit (placement auto). @default "top" */
+  side?: 'top' | 'bottom' | 'left' | 'right' | undefined;
+  align?: 'start' | 'center' | 'end' | undefined;
+  /** ms before it opens on hover; on keyboard focus it opens at once. @default 300 */
+  delay?: number | undefined;
+  open?: boolean | undefined;
+  defaultOpen?: boolean | undefined;
+  onOpenChange?: ((open: boolean) => void) | undefined;
+  className?: string | undefined;
+};
+
+/**
+ * Tooltip — an ink chip with linen text; no shadow. Opens on hover and on
+ * keyboard focus, closes on Esc; flips to stay in view (Radix Tooltip).
+ * On an ink page it inverts to linen.
+ */
+export function Tooltip({ content, children, side = 'top', align = 'center', delay = 300, open, defaultOpen, onOpenChange, className }: TooltipProps) {
+  return (
+    <TooltipPrimitive.Provider delayDuration={delay}>
+      <TooltipPrimitive.Root
+        {...(open !== undefined ? { open } : {})}
+        {...(defaultOpen !== undefined ? { defaultOpen } : {})}
+        {...(onOpenChange ? { onOpenChange } : {})}
+      >
+        <TooltipPrimitive.Trigger asChild>{children}</TooltipPrimitive.Trigger>
+        <TooltipPrimitive.Portal>
+          <TooltipPrimitive.Content
+            side={side}
+            align={align}
+            sideOffset={6}
+            collisionPadding={8}
+            className={cn(
+              'z-[70] max-w-[260px] rounded-md bg-ink px-[9px] py-[5px] font-sans text-meta leading-[1.4] text-linen',
+              'ink:bg-linen ink:text-ink',
+              className,
+            )}
+          >
+            {content}
+          </TooltipPrimitive.Content>
+        </TooltipPrimitive.Portal>
+      </TooltipPrimitive.Root>
+    </TooltipPrimitive.Provider>
+  );
+}