@elabs-ai/components-ui 4.0.0

package/src/components/theme-switcher/theme-switcher.tsx

@@ -0,0 +1,280 @@
+"use client";
+
+import { forwardRef, useCallback, useEffect, useState, type HTMLAttributes } from "react";
+import { Check, Monitor, Moon, Sun } from "lucide-react";
+import { useTheme, type ThemeDefinition, type ThemeName } from "@elabs-ai/components-tokens";
+
+import { Button } from "../button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "../dropdown-menu";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../tooltip";
+import { useThemeTransition, type ThemeTransitionEffect } from "./use-theme-transition";
+
+const SYSTEM_STORAGE_KEY = "brand-ui-theme-system";
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+
+type ButtonSize = "sm" | "default" | "lg";
+const ICON_SIZE: Record<ButtonSize, "icon-sm" | "icon" | "icon-lg"> = {
+  sm: "icon-sm",
+  default: "icon",
+  lg: "icon-lg",
+};
+
+/** A theme choice, or "system" to follow the OS color scheme. */
+export type ThemePreference = ThemeName | "system";
+
+export interface ThemeSwitcherProps extends Omit<HTMLAttributes<HTMLButtonElement>, "onChange"> {
+  /**
+   * Themes to offer, as names. ≤2 → toggle; >2 → dropdown.
+   *
+   * Defaults to the PROVIDER's registry (ADR 0029) — so an app that registers
+   * its own themes gets a working switcher with no prop at all. Pass this only
+   * to offer a subset, or to fix the order; names the provider doesn't know are
+   * dropped.
+   */
+  themes?: ThemeName[];
+  /** Force presentation; "auto" (default) picks toggle vs dropdown by theme count. */
+  mode?: "auto" | "toggle" | "dropdown";
+  /** Offer a "System" option that follows the OS color scheme. Default true. */
+  showSystem?: boolean;
+  /** Whole-screen reveal effect for the animated switch. Default "polygon". */
+  effect?: ThemeTransitionEffect;
+  /** Control size. Default "default". */
+  size?: ButtonSize;
+  /**
+   * Controlled preference (#366). When set, the switcher derives its "current"
+   * state — including "system" — from this prop instead of its own internal,
+   * `localStorage`-backed state, and reports every user pick via
+   * `onPreferenceChange` instead of writing its own storage key. Pass this pair
+   * when your app's actual source of truth is a different persisted preference
+   * (a settings API, a different storage key, a server-synced setting). Omit
+   * both for the default, uncontrolled behavior (unchanged).
+   */
+  preference?: ThemePreference;
+  /** Called with the new preference on every user pick, when `preference` is controlled. */
+  onPreferenceChange?: (preference: ThemePreference) => void;
+}
+
+function prefersDark(): boolean {
+  return typeof window !== "undefined" && window.matchMedia(DARK_QUERY).matches;
+}
+
+/** First theme in `list` matching `dark`, or the list's own first entry as a last resort. */
+function pickByDarkness(list: readonly ThemeDefinition[], dark: boolean): ThemeName | undefined {
+  return (list.find((t) => t.dark === dark) ?? list[0])?.value;
+}
+
+/**
+ * Adaptive theme control. With ≤2 themes it renders a light/dark/system toggle
+ * (a single icon button that cycles); with >2 it auto-upgrades to a dropdown
+ * over the offered themes. Every switch animates the whole screen via
+ * `useThemeTransition` (respecting reduced motion). Icons follow each theme's
+ * `dark` flag, so it works for any theme — including one you authored.
+ *
+ * Uncontrolled by default (tracks its own "system" choice via `localStorage`).
+ * Pass `preference`/`onPreferenceChange` to drive it from an external store
+ * instead (#366) — see the `Controlled` story.
+ *
+ * **It renders the PROVIDER's registry** (ADR 0029). Register your themes on
+ * `<ThemeProvider themes={…}>` and this switcher offers them with no prop —
+ * which is also why `allowedThemes` (#355) is honoured for free: the provider
+ * has already narrowed what it exposes. The `themes` prop is now purely an
+ * additional, optional narrowing on top; a name the provider does not offer is
+ * dropped rather than rendered, so a disallowed or unregistered theme is never
+ * reachable via a menu item, the toggle, "System", or the OS
+ * `prefers-color-scheme` listener.
+ *
+ * The pre-ADR-0029 hard-coded `["light","dark"]` default is gone. Behaviour for
+ * an app on the default provider is unchanged — that registry IS light + dark.
+ */
+export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
+  function ThemeSwitcher(
+    {
+      themes,
+      mode = "auto",
+      showSystem = true,
+      effect = "polygon",
+      size = "default",
+      preference,
+      onPreferenceChange,
+      className,
+      ...props
+    },
+    ref,
+  ) {
+    const { theme, themeDefinitions, setTheme } = useTheme();
+    const switchTheme = useThemeTransition(effect);
+    const isControlled = preference !== undefined;
+    const [uncontrolledIsSystem, setUncontrolledIsSystem] = useState(false);
+    const isSystem = isControlled ? preference === "system" : uncontrolledIsSystem;
+
+    // The provider's registry is the universe; the prop only narrows it, in the
+    // prop's own order. A name the provider doesn't offer is DROPPED (it has no
+    // CSS block here and no label to render), and an empty intersection falls
+    // back to the whole registry rather than to a hard-coded pair — falling back
+    // to literals is what could resurrect a theme the provider disallowed.
+    const narrowed = themes
+      ? themes
+          .map((name) => themeDefinitions.find((d) => d.value === name))
+          .filter((d): d is ThemeDefinition => d !== undefined)
+      : themeDefinitions;
+    const offered: readonly ThemeDefinition[] = narrowed.length > 0 ? narrowed : themeDefinitions;
+    const safeThemes: ThemeName[] = offered.map((d) => d.value);
+    const labelOf = (name: ThemeName) => offered.find((d) => d.value === name)?.label ?? name;
+    const isDark = (name: ThemeName) => offered.find((d) => d.value === name)?.dark ?? false;
+
+    // `?? theme` (the active theme), never a "light"/"dark" literal: with an open
+    // registry those names may not exist at all in this app.
+    const lightTheme: ThemeName = pickByDarkness(offered, false) ?? theme;
+    const darkTheme: ThemeName = pickByDarkness(offered, true) ?? theme;
+
+    // The concrete theme to DISPLAY as current: the controlled preference when
+    // it names one, otherwise the theme actually applied via the provider.
+    const resolvedTheme: ThemeName =
+      isControlled && preference !== undefined && preference !== "system" ? preference : theme;
+
+    // Hydrate the "system" choice from localStorage and apply it on mount —
+    // uncontrolled mode only. Controlled mode's "system" state comes from the
+    // `preference` prop and never touches this component's own storage key.
+    useEffect(() => {
+      if (isControlled) return;
+      if (typeof window === "undefined") return;
+      const active = window.localStorage.getItem(SYSTEM_STORAGE_KEY) === "1";
+      setUncontrolledIsSystem(active);
+      if (active) setTheme(prefersDark() ? darkTheme : lightTheme);
+      // Mount-once hydration by design (mirrors the pre-#366 behavior); a
+      // component must not flip controlled/uncontrolled mid-lifecycle
+      // (.claude/rules/component-api.md), so `isControlled` cannot change here.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    // Keep the applied theme tracking the OS scheme while "system" is active —
+    // controlled or not. Depends on every value it reads (unlike the effect
+    // above) so it never captures a stale `lightTheme`/`darkTheme` once those
+    // become provider-derived (the staleness risk #384 flags).
+    useEffect(() => {
+      if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+      const mql = window.matchMedia(DARK_QUERY);
+      const onChange = () => {
+        const active = isControlled
+          ? preference === "system"
+          : window.localStorage.getItem(SYSTEM_STORAGE_KEY) === "1";
+        if (active) setTheme(prefersDark() ? darkTheme : lightTheme);
+      };
+      mql.addEventListener("change", onChange);
+      return () => mql.removeEventListener("change", onChange);
+    }, [isControlled, preference, darkTheme, lightTheme, setTheme]);
+
+    const pickTheme = useCallback(
+      (next: ThemeName) => {
+        if (isControlled) {
+          onPreferenceChange?.(next);
+        } else {
+          setUncontrolledIsSystem(false);
+          if (typeof window !== "undefined") window.localStorage.setItem(SYSTEM_STORAGE_KEY, "0");
+        }
+        switchTheme(next);
+      },
+      [switchTheme, isControlled, onPreferenceChange],
+    );
+
+    const pickSystem = useCallback(() => {
+      if (isControlled) {
+        onPreferenceChange?.("system");
+      } else {
+        setUncontrolledIsSystem(true);
+        if (typeof window !== "undefined") window.localStorage.setItem(SYSTEM_STORAGE_KEY, "1");
+      }
+      switchTheme(prefersDark() ? darkTheme : lightTheme);
+    }, [switchTheme, darkTheme, lightTheme, isControlled, onPreferenceChange]);
+
+    const TriggerIcon = isSystem ? Monitor : isDark(resolvedTheme) ? Moon : Sun;
+    const useDropdown = mode === "dropdown" || (mode === "auto" && safeThemes.length > 2);
+
+    // ---- Dropdown mode (>2 themes) ----
+    if (useDropdown) {
+      return (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              ref={ref}
+              variant="outline"
+              size={ICON_SIZE[size]}
+              aria-label="Theme"
+              className={className}
+              {...props}
+            >
+              <TriggerIcon />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            {showSystem ? (
+              <DropdownMenuItem onSelect={() => pickSystem()}>
+                <Monitor />
+                <span>System</span>
+                {isSystem ? <Check className="ml-auto" /> : null}
+              </DropdownMenuItem>
+            ) : null}
+            {offered.map((d) => (
+              <DropdownMenuItem key={d.value} onSelect={() => pickTheme(d.value)}>
+                {d.dark ? <Moon /> : <Sun />}
+                <span>{d.label}</span>
+                {!isSystem && resolvedTheme === d.value ? <Check className="ml-auto" /> : null}
+              </DropdownMenuItem>
+            ))}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      );
+    }
+
+    // ---- Toggle mode (≤2 themes): cycle light → dark → (system) ----
+    // These three are ROLES in the cycle, not theme names — `lightTheme` and
+    // `darkTheme` resolve each role to whatever this app actually registered.
+    const order: Array<"light" | "dark" | "system"> = showSystem
+      ? ["light", "dark", "system"]
+      : ["light", "dark"];
+    const current: "light" | "dark" | "system" = isSystem
+      ? "system"
+      : resolvedTheme === darkTheme
+        ? "dark"
+        : "light";
+    const next = order[(order.indexOf(current) + 1) % order.length];
+    const apply = () => {
+      if (next === "system") pickSystem();
+      else pickTheme(next === "dark" ? darkTheme : lightTheme);
+    };
+
+    // Announce the THEME'S OWN label, not the role: an app whose themes are
+    // "Daylight"/"Midnight" would otherwise announce "Theme: light" — naming a
+    // theme that does not exist in that app.
+    // `role` is optional only because `order[i]` is an indexed read under
+    // `noUncheckedIndexedAccess`; the modulo above makes it always present.
+    const roleLabel = (role: "light" | "dark" | "system" | undefined) =>
+      role === "system" ? "System" : labelOf(role === "dark" ? darkTheme : lightTheme);
+
+    return (
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button
+              ref={ref}
+              variant="ghost"
+              size={ICON_SIZE[size]}
+              aria-label={`Theme: ${roleLabel(current)}. Activate to switch to ${roleLabel(next)}.`}
+              onClick={apply}
+              className={className}
+              {...props}
+            >
+              <TriggerIcon />
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent>{roleLabel(current)}</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    );
+  },
+);

package/src/components/theme-switcher/use-theme-transition.ts

@@ -0,0 +1,62 @@
+"use client";
+
+import { useCallback } from "react";
+import { useReducedMotion, useTheme, type ThemeName } from "@elabs-ai/components-tokens";
+
+/** Whole-screen reveal effects for the animated theme switch (View Transitions API). */
+export type ThemeTransitionEffect = "polygon" | "circle" | "circle-blur" | "triangle";
+
+type ViewTransitionDocument = Document & {
+  startViewTransition?: (callback: () => void | Promise<void>) => { finished: Promise<void> };
+};
+
+/**
+ * Returns a theme setter that animates the whole-screen switch via the View
+ * Transitions API (the chanhdai.com "theme toggle effect", adapted to brand-ui).
+ *
+ * - Direction-aware: sets `data-vt="to-dark|to-light"` on `<html>` from the
+ *   target theme's `dark` flag, so the clip-path wipes the right way for ANY of
+ *   the three themes (not just light/dark).
+ * - `data-vt-effect` selects the reveal shape (default "polygon").
+ * - Motion-aware: under `useReducedMotion()` (OS or in-app preference) — or when
+ *   the browser lacks `startViewTransition` — it falls back to an instant,
+ *   unanimated `setTheme`.
+ *
+ * The visual is pure CSS on `::view-transition-*` in `@elabs-ai/components-tokens` themes.css;
+ * this hook only orchestrates it.
+ */
+export function useThemeTransition(effect: ThemeTransitionEffect = "polygon") {
+  const { theme, setTheme, themeDefinitions } = useTheme();
+  const reduced = useReducedMotion();
+
+  return useCallback(
+    (next: ThemeName) => {
+      if (next === theme) return;
+      if (typeof document === "undefined") {
+        setTheme(next);
+        return;
+      }
+      const doc = document as ViewTransitionDocument;
+      if (reduced || typeof doc.startViewTransition !== "function") {
+        setTheme(next);
+        return;
+      }
+      const root = document.documentElement;
+      // The direction of the reveal comes from the provider's REGISTRY entry
+      // for the incoming theme (ADR 0029) — a consumer theme animates correctly
+      // without registering here. `resolveThemeIsDark` is deliberately NOT used:
+      // it reads the CURRENT computed `color-scheme`, and `next` has not been
+      // applied yet, so it would report the OUTGOING theme's direction.
+      root.dataset.vt = themeDefinitions.find((d) => d.value === next)?.dark
+        ? "to-dark"
+        : "to-light";
+      root.dataset.vtEffect = effect;
+      const transition = doc.startViewTransition(() => setTheme(next));
+      transition.finished.finally(() => {
+        delete root.dataset.vt;
+        delete root.dataset.vtEffect;
+      });
+    },
+    [theme, setTheme, reduced, effect, themeDefinitions],
+  );
+}

package/src/components/timeline/index.ts

@@ -0,0 +1,13 @@
+// NOTE: `TimelineStatus` (the editor's 3-state vocabulary) is deliberately NOT
+// re-exported here — it already reaches the @elabs-ai/components-ui barrel via
+// ./components/status-badge; exporting it twice would make the star-exports
+// ambiguous.
+export {
+  Timeline,
+  TimelineItem,
+  TimelineRoot,
+  type TimelineEntry,
+  type TimelineItemProps,
+  type TimelineProps,
+  type TimelineRootProps,
+} from "./timeline";

package/src/components/timeline/timeline.stories.tsx

@@ -0,0 +1,99 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor, within } from "storybook/test";
+import { Timeline, TimelineItem, TimelineRoot } from "./timeline";
+
+const meta = {
+  title: "Core/Timeline",
+  component: Timeline,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "Ordered steps with a vertical connector and status-colored nodes — THE shared " +
+          "rail spine (#190). Two front doors over one rail: the array `items` API (the " +
+          "editor's `:::timeline` target, `done|active|pending`) and the compound " +
+          "`TimelineRoot`/`TimelineItem` parts, whose nodes take the canonical 7-state " +
+          "`Status` (status-badge). Token-driven and motion-free.",
+      },
+    },
+  },
+  argTypes: {
+    items: {
+      description:
+        "Array of timeline entries (array-API front door; maps `done|active|pending` status).",
+      control: false,
+      table: { category: "Content" },
+    },
+    className: {
+      description: "Extra Tailwind classes merged via cn().",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof Timeline>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    items: [
+      { title: "Draft", description: "Initial scope frozen", status: "done", timestamp: "Jun 4" },
+      {
+        title: "Review",
+        description: "With the migration team",
+        status: "active",
+        timestamp: "Jun 6",
+      },
+      { title: "Publish", status: "pending" },
+    ],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await waitFor(() => expect(canvas.getByText("Review")).toBeVisible());
+    expect(canvas.getAllByRole("listitem")).toHaveLength(3);
+  },
+};
+
+export const Compound: Story = {
+  args: { items: [] },
+  render: () => (
+    <TimelineRoot aria-label="Agent run">
+      <TimelineItem status="complete" timestamp="14:02">
+        Searched financial filings
+      </TimelineItem>
+      <TimelineItem status="complete" description="8 rows reconciled · 0 variances">
+        Queried finance.revenue
+      </TimelineItem>
+      <TimelineItem status="running">Computing QoQ deltas</TimelineItem>
+      <TimelineItem status="pending">Draft the board note</TimelineItem>
+    </TimelineRoot>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await waitFor(() => expect(canvas.getByText("Computing QoQ deltas")).toBeVisible());
+    expect(canvas.getAllByRole("listitem")).toHaveLength(4);
+  },
+};
+
+export const CanonicalStatuses: Story = {
+  args: { items: [] },
+  render: () => (
+    <TimelineRoot aria-label="All canonical statuses">
+      <TimelineItem status="pending">Pending</TimelineItem>
+      <TimelineItem status="running">Running</TimelineItem>
+      <TimelineItem status="complete">Complete</TimelineItem>
+      <TimelineItem status="awaiting-approval">Awaiting approval</TimelineItem>
+      <TimelineItem status="denied">Denied</TimelineItem>
+      <TimelineItem status="failed">Failed</TimelineItem>
+      <TimelineItem status="skipped">Skipped</TimelineItem>
+    </TimelineRoot>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    expect(canvas.getAllByRole("listitem")).toHaveLength(7);
+    await waitFor(() => expect(canvas.getByText("Awaiting approval")).toBeVisible());
+  },
+};

package/src/components/timeline/timeline.test.tsx

@@ -0,0 +1,196 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { cleanup, render, screen } from "@testing-library/react";
+
+import { NODE_STYLE, Timeline, TimelineItem, TimelineRoot } from "./timeline";
+import { STATUS_ROLE, STATUSES, statusBadgeVariants, type Status } from "../status-badge";
+
+afterEach(cleanup);
+
+// #392 — one vocabulary, one colour. `NODE_STYLE` (the rail dot) is a literal
+// duplicate of the status→role mapping `STATUS_ROLE`/`statusBadgeVariants` own;
+// this block is what stops the duplicate from silently drifting again (it did,
+// for `running`: the dot rendered `--primary` while the badge rendered `--info`).
+// Only the four CHROMATIC statuses are asserted — `pending`/`skipped`/`denied`
+// are a deliberate, documented neutral divergence (a hollow dot vs a filled
+// pill), not a bug: `NODE_STYLE.pending` uses `bg-background` (hollow, "not yet")
+// where `statusBadgeVariants({status:"pending"})` uses a filled `bg-secondary`
+// pill — a legitimate design choice a dot and a pill make differently.
+describe("Timeline NODE_STYLE — one vocabulary, one colour (#392)", () => {
+  const CHROMATIC: Status[] = ["running", "complete", "awaiting-approval", "failed"];
+  const role = (classes: string) => classes.match(/\bbg-([a-z-]+?)(?:\/\d+)?\b/)?.[1];
+
+  it.each(CHROMATIC)(
+    "%s renders the same semantic role on the rail node and the badge",
+    (status) => {
+      expect(role(NODE_STYLE[status])).toBe(role(statusBadgeVariants({ status })));
+      expect(role(NODE_STYLE[status])).toBe(STATUS_ROLE[status]);
+    },
+  );
+
+  it("keeps the running ring halo on the same role as its fill", () => {
+    expect(NODE_STYLE.running).toMatch(/\bring-info\/25\b/);
+    expect(role(NODE_STYLE.running)).toBe("info");
+  });
+});
+
+// #387 — colour is never the only channel (WCAG 1.4.1). `NODE_STYLE` used to
+// encode status in fill hue alone: `denied`/`skipped` were byte-identical, and
+// `complete`/`awaiting-approval`/`failed` were shape-identical filled dots
+// differing only by hue. An earlier version of this fix reached for
+// `border-style` (dashed/dotted) on the vivid quartet too — a RENDERED check
+// caught that it is invisible there (border colour == fill colour, so a dash
+// gap reveals nothing) even though it read as "clearly different" in the
+// class string. The vivid quartet (`running`/`complete`/`awaiting-approval`/
+// `failed`) is differentiated by `ring-*` WIDTH instead (0/1/2/4 — a ring
+// contrasts against the PAGE, not the fill, which is why it actually paints).
+// `denied`/`skipped` keep `border-style` because THEIR border and fill
+// genuinely differ in colour, where it does paint. See the class-map comment
+// in `timeline.tsx` and the #387 rendered-proof zoomed/greyscale screenshots.
+describe("Timeline NODE_STYLE — colour is never the only channel (#387)", () => {
+  const signature = (status: Status) => {
+    const classes = NODE_STYLE[status];
+    const fill = classes.match(/\bbg-[a-z-]+\b/)?.[0];
+    const style = classes.match(/\bborder-(dashed|dotted|double)\b/)?.[1] ?? "solid";
+    const ringWidth = classes.match(/\bring-(\d+)\b/)?.[1] ?? "0";
+    return `${fill}|${style}|ring-${ringWidth}`;
+  };
+
+  it("gives every status a unique non-colour (fill + border-style + ring-width) signature", () => {
+    const signatures = STATUSES.map(signature);
+    expect(new Set(signatures).size).toBe(STATUSES.length);
+  });
+
+  it("distinguishes denied, skipped and pending from one another (previously denied ≡ skipped)", () => {
+    expect(NODE_STYLE.denied).not.toBe(NODE_STYLE.skipped);
+    expect(signature("denied")).not.toBe(signature("skipped"));
+    expect(signature("pending")).not.toBe(signature("denied"));
+    expect(signature("pending")).not.toBe(signature("skipped"));
+  });
+
+  it("distinguishes complete, awaiting-approval and failed from one another (previously hue-only)", () => {
+    expect(signature("complete")).not.toBe(signature("awaiting-approval"));
+    expect(signature("complete")).not.toBe(signature("failed"));
+    expect(signature("awaiting-approval")).not.toBe(signature("failed"));
+  });
+
+  it("gives the vivid quartet (running/complete/awaiting-approval/failed) four distinct ring widths", () => {
+    const widths = ["running", "complete", "awaiting-approval", "failed"].map(
+      (s) => NODE_STYLE[s as Status].match(/\bring-(\d+)\b/)?.[1] ?? "0",
+    );
+    expect(new Set(widths).size).toBe(widths.length);
+  });
+
+  it("names the status for assistive tech — data-status alone isn't AT-visible", () => {
+    render(
+      <TimelineRoot>
+        <TimelineItem status="running">Computing QoQ deltas</TimelineItem>
+        <TimelineItem status="failed">Queried finance.revenue</TimelineItem>
+        <TimelineItem status="skipped">Draft the board note</TimelineItem>
+      </TimelineRoot>,
+    );
+    const [running, failed, skipped] = screen.getAllByRole("listitem");
+    expect(running).toHaveTextContent("Running: Computing QoQ deltas");
+    expect(failed).toHaveTextContent("Failed: Queried finance.revenue");
+    expect(skipped).toHaveTextContent("Skipped: Draft the board note");
+  });
+});
+
+describe("Timeline (array API — the editor-facing surface, #190)", () => {
+  it("renders one list item per timeline step", () => {
+    render(
+      <Timeline
+        items={[
+          { title: "Draft", status: "done" },
+          { title: "Review", status: "active", description: "in progress" },
+          { title: "Publish", status: "pending" },
+        ]}
+      />,
+    );
+    expect(screen.getAllByRole("listitem")).toHaveLength(3);
+    expect(screen.getByText("Review")).toBeInTheDocument();
+    expect(screen.getByText("in progress")).toBeInTheDocument();
+  });
+
+  it("maps the editor 3-state vocabulary onto the canonical Status", () => {
+    render(
+      <Timeline
+        items={[
+          { title: "Draft", status: "done" },
+          { title: "Review", status: "active" },
+          { title: "Publish" }, // status omitted → pending
+        ]}
+      />,
+    );
+    const [done, active, pending] = screen.getAllByRole("listitem");
+    expect(done).toHaveAttribute("data-status", "complete");
+    expect(active).toHaveAttribute("data-status", "running");
+    expect(pending).toHaveAttribute("data-status", "pending");
+  });
+});
+
+describe("TimelineRoot/TimelineItem (compound API)", () => {
+  it("composes items with canonical statuses and rich children", () => {
+    render(
+      <TimelineRoot data-testid="rail">
+        <TimelineItem status="complete" timestamp="Jun 4">
+          Searched filings
+        </TimelineItem>
+        <TimelineItem status="failed" description={<em>quota exceeded</em>}>
+          Queried finance.revenue
+        </TimelineItem>
+      </TimelineRoot>,
+    );
+    expect(screen.getByTestId("rail").tagName).toBe("OL");
+    const items = screen.getAllByRole("listitem");
+    expect(items).toHaveLength(2);
+    expect(items[0]).toHaveAttribute("data-status", "complete");
+    expect(items[1]).toHaveAttribute("data-status", "failed");
+    expect(screen.getByText("Jun 4")).toBeInTheDocument();
+    expect(screen.getByText("quota exceeded")).toBeInTheDocument();
+  });
+
+  it("renders the block detail slot under the node (#192 AgentStep host)", () => {
+    render(
+      <TimelineRoot>
+        <TimelineItem
+          status="complete"
+          detail={<div data-testid="detail">8 rows · 0 variances</div>}
+        >
+          Queried finance.revenue
+        </TimelineItem>
+      </TimelineRoot>,
+    );
+    expect(screen.getByTestId("detail")).toBeInTheDocument();
+  });
+
+  // #381 — the `awaiting-approval` node is a colour-ONLY mark (a ~10px dot whose
+  // border is the same tone, so there is no rescuing hairline). It must keep
+  // reaching for the status FILL rung, which is the rung the token contract
+  // guarantees ≥3:1 on every content surface (themes-contrast.test.ts). A future
+  // edit that swaps it for a wash (`bg-warning/10`) or the plate-ink rung
+  // (`text-warning-foreground`) would silently drop it back under 1.4.11.
+  it("draws the awaiting-approval node with the warning MARK rung (1.4.11)", () => {
+    render(
+      <TimelineRoot>
+        <TimelineItem status="awaiting-approval">Awaiting sign-off</TimelineItem>
+      </TimelineRoot>,
+    );
+    const node = screen.getByRole("listitem").querySelector(".bg-warning");
+    expect(node).not.toBeNull();
+    expect(node).toHaveClass("border-warning");
+    expect(node?.className).not.toMatch(/bg-warning\//);
+  });
+
+  it("merges className and spreads props on the li", () => {
+    render(
+      <TimelineRoot>
+        <TimelineItem className="custom-item" aria-label="step">
+          Step
+        </TimelineItem>
+      </TimelineRoot>,
+    );
+    const li = screen.getByRole("listitem");
+    expect(li).toHaveClass("custom-item");
+    expect(li).toHaveAttribute("aria-label", "step");
+  });
+});