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

package/src/components/StageProgress.tsx

@@ -0,0 +1,51 @@
+import { Check, X } from 'lucide-react';
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { PulseDot } from './PulseDot';
+
+export type Stage = {
+  label: ReactNode;
+  state: 'done' | 'current' | 'todo' | 'failed';
+  /** Shown beside the state: "Batch 2 of 4", "Done", the failure. */
+  detail?: ReactNode;
+};
+
+export type StageProgressProps = Omit<ComponentProps<'ol'>, 'children'> & {
+  stages: Stage[];
+  /** Accessible name of the list. */
+  label?: string | undefined;
+};
+
+/**
+ * StageProgress — work that moves through named stages (Documents →
+ * People → Facts → Assessment → Report), not a percentage. Done stages are
+ * ink with a tick, the current one pulses on the brand colour, failed is red.
+ */
+export function StageProgress({ stages, label, className, ...rest }: StageProgressProps) {
+  return (
+    <ol aria-label={label} className={cn('m-0 flex list-none flex-wrap items-center gap-x-5 gap-y-2 p-0 font-sans', className)} {...rest}>
+      {stages.map((s, i) => (
+        <li key={i} aria-current={s.state === 'current' ? 'step' : undefined} data-state={s.state} className="flex items-center gap-2 text-small">
+          {s.state === 'done' ? (
+            <span className="grid size-4 place-items-center rounded-pill bg-fg text-page">
+              <Check size={10} strokeWidth={3} aria-hidden />
+            </span>
+          ) : s.state === 'failed' ? (
+            <span className="grid size-4 place-items-center rounded-pill bg-error text-white">
+              <X size={10} strokeWidth={3} aria-hidden />
+            </span>
+          ) : s.state === 'current' ? (
+            <span className="grid size-4 place-items-center">
+              <PulseDot size={9} />
+            </span>
+          ) : (
+            <span aria-hidden className="size-4 rounded-pill border border-rule" />
+          )}
+          <span className={cn(s.state === 'todo' ? 'text-fg-secondary' : 'text-fg', s.state === 'current' && 'font-medium')}>{s.label}</span>
+          {s.detail && <span className={cn('text-meta', s.state === 'failed' ? 'text-error-text' : 'text-fg-secondary')}>{s.detail}</span>}
+        </li>
+      ))}
+    </ol>
+  );
+}

package/src/components/Steps.tsx

@@ -0,0 +1,58 @@
+import { Check, Lock } from 'lucide-react';
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+export type StepState = 'done' | 'current' | 'upcoming' | 'blocked';
+
+export type Step = {
+  title: ReactNode;
+  state: StepState;
+  /** The second line: "Done 22 Sep", "Current step", "Blocked · opens at the Term sheet stage". */
+  detail?: ReactNode;
+};
+
+export type StepsProps = Omit<ComponentProps<'ol'>, 'children'> & {
+  steps: Step[];
+  /** Read out for each state (the marker shows it visually). */
+  stateLabels?: Partial<Record<StepState, string>> | undefined;
+};
+
+const STATE_LABELS: Record<StepState, string> = { done: 'Done', current: 'Current step', upcoming: 'Not started', blocked: 'Blocked' };
+
+/**
+ * Steps — a path in four states: done (ink tick), current (brand disc,
+ * aria-current="step"), upcoming (outlined number), blocked (lock, with the
+ * reason in the detail line).
+ */
+export function Steps({ steps, stateLabels, className, ...rest }: StepsProps) {
+  const said = { ...STATE_LABELS, ...stateLabels };
+  return (
+    <ol className={cn('m-0 flex list-none flex-col p-0', className)} {...rest}>
+      {steps.map((s, i) => (
+        <li key={i} aria-current={s.state === 'current' ? 'step' : undefined} className="relative flex gap-3 pb-4 last:pb-0">
+          {i < steps.length - 1 && <span aria-hidden className="absolute top-6 bottom-0 left-[11px] w-px bg-rule" />}
+          <span
+            aria-hidden
+            className={cn(
+              'relative z-[1] grid size-[22px] shrink-0 place-items-center rounded-pill text-[11px] font-semibold tabular-nums',
+              s.state === 'done' && 'bg-fg text-page',
+              s.state === 'current' && 'bg-brand-mark text-ink',
+              s.state === 'upcoming' && 'border border-rule bg-page text-fg-secondary',
+              s.state === 'blocked' && 'bg-sunk text-fg-secondary',
+            )}
+          >
+            {s.state === 'done' ? <Check size={12} strokeWidth={2.5} /> : s.state === 'blocked' ? <Lock size={11} strokeWidth={2} /> : i + 1}
+          </span>
+          <div className="flex min-w-0 flex-col pt-0.5">
+            <span className={cn('text-ui font-medium', s.state === 'upcoming' || s.state === 'blocked' ? 'text-fg-secondary' : 'text-fg')}>
+              {s.title}
+              <span className="sr-only">, {said[s.state]}</span>
+            </span>
+            {s.detail && <span className="text-meta text-fg-secondary">{s.detail}</span>}
+          </div>
+        </li>
+      ))}
+    </ol>
+  );
+}

package/src/components/SyncStatus.tsx

@@ -0,0 +1,56 @@
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { PulseDot } from './PulseDot';
+
+/** synced (quiet) · syncing (pulsing brand dot) · error (red) · paused / off (grey ring). */
+export type SyncState = 'synced' | 'syncing' | 'error' | 'paused' | 'off';
+
+function Dot({ state }: { state: SyncState }) {
+  if (state === 'syncing') return <PulseDot size={8} />;
+  return (
+    <span
+      aria-hidden
+      className={cn(
+        'inline-block size-2 shrink-0 rounded-pill',
+        state === 'error' && 'bg-error',
+        state === 'synced' && 'bg-fg-secondary',
+        (state === 'paused' || state === 'off') && 'border border-fg-secondary',
+      )}
+    />
+  );
+}
+
+export type SyncStatusProps = Omit<ComponentProps<'div'>, 'children'> & {
+  state: SyncState;
+  /** The wording, always present: "In sync", "Sync error", "Importing 2 batches". */
+  children: ReactNode;
+  /** Secondary detail: "Updated just now", "attempt 3". */
+  detail?: ReactNode;
+  /** One action, e.g. Retry. */
+  action?: ReactNode;
+  /** Dot only (the global indicator); the wording stays for screen readers and on hover. */
+  compact?: boolean | undefined;
+};
+
+/**
+ * SyncStatus — the global sync dot and the per-source sync lines ("Retrying
+ * after an error · attempt 3", "Paused by Wei Li", "Last synced 4 minutes
+ * ago"). Colour is never the only signal: the wording is always there.
+ */
+export function SyncStatus({ state, children, detail, action, compact = false, className, title, ...rest }: SyncStatusProps) {
+  return (
+    <div
+      role="status"
+      data-state={state}
+      title={compact ? (title ?? (typeof children === 'string' ? children : undefined)) : title}
+      className={cn('inline-flex items-center gap-2 font-sans text-small', state === 'error' ? 'text-error-text' : 'text-fg', className)}
+      {...rest}
+    >
+      <Dot state={state} />
+      <span className={compact ? 'sr-only' : undefined}>{children}</span>
+      {detail && <span className={cn('text-meta text-fg-secondary', compact && 'sr-only')}>{detail}</span>}
+      {action && !compact && <span className="ml-1">{action}</span>}
+    </div>
+  );
+}

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

@@ -91,6 +91,47 @@ const DEFAULT_LABELS: ToastLabels = {
   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;
@@ -120,22 +161,18 @@ export function Toaster({ labels, offset = 24 }: ToasterProps) {
             }}
             duration={t.duration ?? (t.action ? 8000 : 4000)}
             type={status === 'error' ? 'foreground' : 'background'}
-            className={cn(
-              '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',
-              'data-[swipe=move]:translate-x-(--radix-toast-swipe-move-x) data-[swipe=end]:hidden',
-            )}
+            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={cn('mb-0.5 text-meta font-medium', status === 'attention' ? 'text-yellow-accent' : 'text-grey-inverse')}>{l[status]}</div>
+              <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="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)]"
+                  className={ACTION}
                 >
                   {t.action.label}
                 </ToastPrimitive.Action>
@@ -143,7 +180,7 @@ export function Toaster({ labels, offset = 24 }: ToasterProps) {
             </div>
             <ToastPrimitive.Close
               aria-label={l.dismiss}
-              className="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)]"
+              className={CLOSE}
             >
               <X size={14} strokeWidth={2} aria-hidden />
             </ToastPrimitive.Close>

package/src/components/UploadCheck.tsx

@@ -0,0 +1,118 @@
+import { Folder } from 'lucide-react';
+import { useMemo, useState, type ComponentProps } from 'react';
+
+import { cn } from '../lib/cn';
+import { Button } from './Button';
+import { Checkbox } from './Checkbox';
+import { Icon } from './Icon';
+import { checkFiles, DEFAULT_MAX_SIZE, formatBytes, isHidden, type DroppedFile, type FileRules, type Rejected } from './status-files';
+
+type Group = { key: string; label: string; files: DroppedFile[]; hidden: boolean };
+
+const REASON: Record<Rejected['reason'], string> = { type: 'Unsupported type', size: 'Too large', depth: 'Nested too deep' };
+
+/** Groups a folder's accepted files by their first sub-folder ("" = loose files in the root). */
+export function groupByFolder(items: DroppedFile[]): Group[] {
+  const map = new Map<string, DroppedFile[]>();
+  for (const it of items) {
+    const parts = it.path.split('/');
+    const key = parts.length > 2 ? parts[1]! : '';
+    map.set(key, [...(map.get(key) ?? []), it]);
+  }
+  return [...map.entries()]
+    .map(([key, files]) => ({ key, label: key, files, hidden: key ? key.startsWith('.') : files.every((f) => isHidden(f.path)) }))
+    .sort((a, b) => Number(a.hidden) - Number(b.hidden) || a.key.localeCompare(b.key));
+}
+
+export type UploadCheckLabels = {
+  looseFiles?: string;
+  wontUpload?: (n: number) => string;
+  upload?: (n: number) => string;
+  cancel?: string;
+  of?: (included: number, total: number) => string;
+  summary?: (files: number, size: string) => string;
+  refused?: (r: Rejected) => string;
+};
+
+export type UploadCheckProps = Omit<ComponentProps<'div'>, 'children'> &
+  FileRules & {
+    /** The dropped folder's name. */
+    folder: string;
+    /** Everything read from it, with paths ("<folder>/Financials/a.pdf"). */
+    items: DroppedFile[];
+    onConfirm: (files: DroppedFile[]) => void;
+    onCancel?: (() => void) | undefined;
+    labels?: UploadCheckLabels | undefined;
+  };
+
+/**
+ * UploadCheck — before a folder uploads: what will go (by sub-folder, with
+ * counts), what is unticked by default (hidden items such as .cache), and
+ * what won't upload and why (unsupported type, too large, nested too deep).
+ */
+export function UploadCheck({ folder, items, accept, maxSize = DEFAULT_MAX_SIZE, maxDepth, onConfirm, onCancel, labels, className, ...rest }: UploadCheckProps) {
+  const { accepted, rejected } = useMemo(() => checkFiles(items, { accept, maxSize, maxDepth }), [items, accept, maxSize, maxDepth]);
+  const groups = useMemo(() => groupByFolder(accepted), [accepted]);
+  const [off, setOff] = useState<Set<string>>(() => new Set(groups.filter((g) => g.hidden).map((g) => g.key)));
+
+  const chosen = groups.filter((g) => !off.has(g.key)).flatMap((g) => g.files);
+  const bytes = chosen.reduce((n, f) => n + f.file.size, 0);
+  const toggle = (key: string, on: boolean) =>
+    setOff((s) => {
+      const next = new Set(s);
+      if (on) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  const L = {
+    looseFiles: labels?.looseFiles ?? 'Files in this folder',
+    wontUpload: labels?.wontUpload ?? ((n: number) => `${n} won’t upload`),
+    upload: labels?.upload ?? ((n: number) => `Upload ${n} ${n === 1 ? 'file' : 'files'}`),
+    of: labels?.of ?? ((a: number, b: number) => `${a} of ${b}`),
+    refused: labels?.refused ?? ((r: Rejected) => REASON[r.reason]),
+  };
+
+  return (
+    <div className={cn('flex flex-col gap-4 font-sans text-fg', className)} {...rest}>
+      <div className="flex items-center gap-2">
+        <Icon icon={Folder} size={18} />
+        <span className="flex-1 truncate text-ui font-medium">{folder}</span>
+        <span className="text-meta font-medium text-fg-secondary tabular-nums">{L.of(chosen.length, items.length)}</span>
+      </div>
+      <ul className="m-0 flex list-none flex-col rounded-md border border-rule p-0">
+        {groups.map((g) => (
+          <li key={g.key || '(root)'} className="flex items-center gap-3 border-b border-rule-soft px-3 py-2.5 last:border-b-0">
+            <Checkbox
+              checked={!off.has(g.key)}
+              onChange={(v) => toggle(g.key, v)}
+              label={g.key ? g.label : L.looseFiles}
+              rowClassName={cn('flex-1', off.has(g.key) && 'text-fg-secondary')}
+            />
+            <span className="text-meta text-fg-secondary tabular-nums">{g.files.length}</span>
+          </li>
+        ))}
+        {rejected.map((r) => (
+          <li key={r.path} data-rejected={r.reason} className="flex items-center gap-3 border-b border-rule-soft px-3 py-2.5 last:border-b-0">
+            <span className="size-4 shrink-0" />
+            <span className="flex-1 truncate text-small text-fg-secondary">{r.path.split('/').slice(1).join(' / ') || r.path}</span>
+            <span className="text-meta font-medium text-error-text">{L.refused(r)}</span>
+          </li>
+        ))}
+      </ul>
+      <div className="flex items-center gap-3">
+        <span className="flex-1 text-meta text-fg-secondary tabular-nums">
+          {(labels?.summary ?? ((n: number, s: string) => `${n} ${n === 1 ? 'file' : 'files'} · ${s}`))(chosen.length, formatBytes(bytes))}
+          {rejected.length > 0 && ` · ${L.wontUpload(rejected.length)}`}
+        </span>
+        {onCancel && (
+          <Button variant="ghost" onClick={onCancel}>
+            {labels?.cancel ?? 'Cancel'}
+          </Button>
+        )}
+        <Button disabled={chosen.length === 0} onClick={() => onConfirm(chosen)}>
+          {L.upload(chosen.length)}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/components/UploadList.tsx

@@ -0,0 +1,176 @@
+import { Check, File, Folder, X } from 'lucide-react';
+import { useEffect, useState, type ComponentProps, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { Button } from './Button';
+import { Icon } from './Icon';
+import { IconButton } from './IconButton';
+import { Progress } from './Progress';
+import { formatBytes } from './status-files';
+
+export type UploadState = 'queued' | 'uploading' | 'retrying' | 'failed' | 'done';
+
+export type UploadItem = {
+  id: string;
+  name: string;
+  state: UploadState;
+  /** 0–100 while uploading. */
+  progress?: number | undefined;
+  /** Bytes, for "1.2 of 3.4 MB". */
+  loaded?: number | undefined;
+  size?: number | undefined;
+  /** When the next attempt starts (epoch ms), while retrying. */
+  retryAt?: number | undefined;
+  /** Why it failed: "The connection dropped." */
+  error?: ReactNode;
+};
+
+export type UploadRowLabels = {
+  /** s is 0 once the retry has started. */
+  retryingIn?: (s: number) => string;
+  failed?: string;
+  retry?: string;
+  dismiss?: string;
+  cancel?: string;
+  done?: string;
+  queued?: string;
+  /** "1.2 MB of 3.4 MB" */
+  sizeOf?: (loaded: string, total: string) => string;
+};
+
+/** Seconds left until `at`, ticking once a second. */
+function useSecondsUntil(at: number | undefined): number {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    if (at === undefined) return;
+    const t = setInterval(() => setNow(Date.now()), 1000);
+    return () => clearInterval(t);
+  }, [at]);
+  return at === undefined ? 0 : Math.max(0, Math.ceil((at - now) / 1000));
+}
+
+export type UploadRowProps = Omit<ComponentProps<'li'>, 'children'> & {
+  item: UploadItem;
+  onRetry?: ((id: string) => void) | undefined;
+  onDismiss?: ((id: string) => void) | undefined;
+  onCancel?: ((id: string) => void) | undefined;
+  labels?: UploadRowLabels | undefined;
+};
+
+/**
+ * UploadRow — one file: name, progress, cancel. Retrying counts down;
+ * a failure takes a red wash with the reason and Retry while the rest keep
+ * going; done confirms until the real card takes its place.
+ */
+export function UploadRow({ item, onRetry, onDismiss, onCancel, labels, className, ...rest }: UploadRowProps) {
+  const secs = useSecondsUntil(item.state === 'retrying' ? item.retryAt : undefined);
+  const L = {
+    retryingIn: labels?.retryingIn ?? ((s: number) => (s > 0 ? `Retrying in ${s} s` : 'Retrying…')),
+    failed: labels?.failed ?? 'Upload failed.',
+    retry: labels?.retry ?? 'Retry',
+    dismiss: labels?.dismiss ?? 'Dismiss',
+    cancel: labels?.cancel ?? 'Cancel',
+    done: labels?.done ?? 'Uploaded',
+    queued: labels?.queued ?? 'Waiting',
+  };
+  const pct = Math.round(item.progress ?? 0);
+  const text =
+    item.state === 'uploading'
+      ? item.size
+        ? (labels?.sizeOf ?? ((a: string, b: string) => `${a} of ${b}`))(formatBytes(item.loaded ?? (item.size * pct) / 100), formatBytes(item.size))
+        : `${pct}%`
+      : item.state === 'retrying'
+        ? L.retryingIn(secs)
+        : undefined;
+
+  return (
+    <li
+      data-state={item.state}
+      className={cn(
+        'flex list-none items-center gap-3 rounded-md px-3 py-2.5 font-sans',
+        item.state === 'failed' ? 'bg-error-wash text-ink ink:bg-error/20 ink:text-fg' : 'text-fg',
+        className,
+      )}
+      {...rest}
+    >
+      <Icon icon={item.state === 'done' ? Check : File} size={16} className={item.state === 'done' ? 'text-fg' : 'text-fg-secondary'} />
+      <div className="flex min-w-0 flex-1 flex-col gap-1.5">
+        <div className="flex items-center gap-2">
+          <span className="min-w-0 flex-1 truncate text-small">{item.name}</span>
+          {item.state === 'uploading' && <span className="text-meta font-medium text-fg-secondary tabular-nums">{pct}%</span>}
+          {item.state === 'done' && <span className="text-meta font-medium text-fg-secondary">{L.done}</span>}
+          {item.state === 'queued' && <span className="text-meta text-fg-secondary">{L.queued}</span>}
+        </div>
+        {(item.state === 'uploading' || item.state === 'retrying') && (
+          <Progress label={item.name} value={item.state === 'uploading' ? pct : undefined} text={text} status="active" />
+        )}
+        {item.state === 'failed' && (
+          <span role="alert" className="text-meta font-medium text-error-text ink:text-fg">
+            {L.failed} {item.error}
+          </span>
+        )}
+      </div>
+      {item.state === 'failed' ? (
+        <div className="flex items-center gap-1">
+          {onRetry && (
+            <Button size="sm" variant="secondary" ground="paper" onClick={() => onRetry(item.id)} className="ink:border-inv-rule ink:text-fg">
+              {L.retry}
+            </Button>
+          )}
+          {onDismiss && (
+            <Button size="sm" variant="ghost" ground="paper" onClick={() => onDismiss(item.id)} className="ink:text-fg">
+              {L.dismiss}
+            </Button>
+          )}
+        </div>
+      ) : (
+        onCancel &&
+        item.state !== 'done' && <IconButton icon={X} label={`${L.cancel} ${item.name}`} size="sm" onClick={() => onCancel(item.id)} />
+      )}
+    </li>
+  );
+}
+
+export type UploadFolderRowProps = Omit<ComponentProps<'li'>, 'children'> & {
+  name: string;
+  done: number;
+  total: number;
+  failed?: number | undefined;
+  labels?: { failed?: (n: number) => string } | undefined;
+};
+
+/** A folder's batch: a placeholder card that tracks "28 / 41 · 1 failed". */
+export function UploadFolderRow({ name, done, total, failed = 0, labels, className, ...rest }: UploadFolderRowProps) {
+  const failedText = labels?.failed ?? ((n: number) => `${n} failed`);
+  const text = `${done} / ${total}${failed ? ` · ${failedText(failed)}` : ''}`;
+  return (
+    <li className={cn('flex list-none items-center gap-3 rounded-md px-3 py-2.5 font-sans text-fg', className)} {...rest}>
+      <Icon icon={Folder} size={16} className="text-fg-secondary" />
+      <div className="flex min-w-0 flex-1 flex-col gap-1.5">
+        <div className="flex items-center gap-2">
+          <span className="min-w-0 flex-1 truncate text-small">{name}</span>
+          <span className={cn('text-meta font-medium tabular-nums', failed ? 'text-error-text' : 'text-fg-secondary')}>{text}</span>
+        </div>
+        <Progress label={name} value={done} max={total} status={done + failed >= total ? (failed ? 'failed' : 'done') : 'active'} />
+      </div>
+    </li>
+  );
+}
+
+/** UploadList — the rows of a batch. */
+export function UploadList({ className, ...rest }: ComponentProps<'ul'>) {
+  return <ul className={cn('m-0 flex flex-col gap-1 p-0', className)} {...rest} />;
+}
+
+/** While active, closing or reloading the page asks first. */
+export function useBeforeUnloadWhile(active: boolean): void {
+  useEffect(() => {
+    if (!active) return;
+    const onBeforeUnload = (e: BeforeUnloadEvent) => {
+      e.preventDefault();
+      e.returnValue = '';
+    };
+    window.addEventListener('beforeunload', onBeforeUnload);
+    return () => window.removeEventListener('beforeunload', onBeforeUnload);
+  }, [active]);
+}