@robr0/design-system 0.15.0 → 0.16.0

package/README.md

@@ -153,17 +153,17 @@ The same generated data is served as files too: every component's prop contract
 - **Vite 7**: dev server and library build
 - **Next.js 16**: portfolio site and design system documentation
 - **Storybook 10**: component explorer
-- **Vitest + Playwright + axe**: every Storybook story runs as a render test in headless Chromium, with an accessibility audit on each
+- **Vitest + Playwright + axe**: every Storybook story runs as a render test in headless Chromium, with an accessibility audit on each and interaction assertions where a story carries a play function
 - **CSS custom properties**: all theming via semantic tokens, no CSS-in-JS
 
 ---
 
 ## Quality & CI
 
-Every push and pull request runs a GitHub Actions pipeline ([`ci.yml`](.github/workflows/ci.yml)) with four jobs: lint + library build, story tests, Storybook build, and website lint + build followed by the two built-HTML checks (rendered spacing, chat-corpus coverage). The story tests render every Storybook story in headless Chromium via Vitest and run an axe accessibility audit on each, so a violation fails the build exactly like a render error. The same checklist runs locally with one command:
+Every push and pull request runs a GitHub Actions pipeline ([`ci.yml`](.github/workflows/ci.yml)) with four jobs: lint + library build + the package-publish lint, story tests, Storybook build, and website lint + build followed by the built-HTML checks (rendered spacing, chat-corpus coverage, internal links) and the served-site checks: a hydration smoke that loads the built site in a real browser, and a page-level axe pass over the served pages in both themes. The story tests render every Storybook story in headless Chromium via Vitest and run an axe accessibility audit on each, so a violation fails the build exactly like a render error; the overlay stories also assert their keyboard and focus behaviour with play functions, enforced the same way. A scheduled workflow ([`uptime.yml`](.github/workflows/uptime.yml)) re-runs the hydration smoke against production every four hours, because incremental regeneration means the served site can change with no deploy. The same checklist runs locally with one command:
 
 ```bash
-npm run verify   # lint + library type-check + package build + story tests + Storybook build + website lint + build + built-HTML checks
+npm run verify   # lint + library type-check + package build + publish lint + story tests + Storybook build + website lint + build + the built-HTML and served-site checks
 ```
 
 CI also guards against documentation drift: every generated surface (the `validate-registry` entry in the root `package.json` is the authoritative list, from this README's component count to the per-component markdown and the consumer agent skill) is rebuilt from its source registries on every build, and CI fails if the committed copies are stale. The numbers on the site are never hand-written.

package/behaviors/focusable.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared focusability queries for the overlay behavior layer.
+ *
+ * One home for the selector the modal components previously each carried a
+ * copy of. Plain DOM utilities — no React, safe to import anywhere.
+ */
+/** Everything a focus trap must cycle through. */
+export declare const FOCUSABLE = "button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";
+/**
+ * The subset worth landing initial focus on: real controls, not arbitrary
+ * tabindex carriers (a scrollable body region is tabbable but focusing it on
+ * open would strand a keyboard user on a non-control).
+ */
+export declare const INITIAL_FOCUS = "button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled])";
+/**
+ * The focusable elements inside a container, in DOM order, excluding
+ * invisible ones — a control hidden by `display: none` must not count as the
+ * trap's first or last stop.
+ */
+export declare function getFocusable(container: HTMLElement): HTMLElement[];
+/**
+ * Where initial focus should land when a scope activates: the first visible
+ * real control, then the first visible focusable of any kind, else null (the
+ * caller falls back to the container itself).
+ */
+export declare function getInitialFocus(container: HTMLElement): HTMLElement | null;

package/behaviors/focusable.js

@@ -0,0 +1,18 @@
+const FOCUSABLE = 'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+const INITIAL_FOCUS = "button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled])";
+const isVisible = (el) => typeof el.checkVisibility === "function" ? el.checkVisibility() : el.offsetParent !== null;
+function getFocusable(container) {
+  return Array.from(container.querySelectorAll(FOCUSABLE)).filter(isVisible);
+}
+function getInitialFocus(container) {
+  const preferred = Array.from(container.querySelectorAll(INITIAL_FOCUS)).find(
+    isVisible
+  );
+  return preferred ?? getFocusable(container)[0] ?? null;
+}
+export {
+  FOCUSABLE,
+  INITIAL_FOCUS,
+  getFocusable,
+  getInitialFocus
+};

package/behaviors/useFocusScope.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Focus containment for modal overlays: initial focus, Tab wrapping, focus
+ * restore, and background isolation.
+ *
+ * Restore is guarded by `document.contains` — the element that opened a
+ * dialog can be gone by the time it closes (a row the dialog itself deleted),
+ * and restoring into a detached node silently drops focus to `<body>`. It
+ * also runs when the component unmounts while open, which the per-component
+ * implementations this replaces never handled.
+ *
+ * Background isolation uses `inert`, not `aria-hidden`: a JS focus trap only
+ * fences the Tab key, while a screen reader's virtual cursor walks the page
+ * behind the dialog freely. `inert` closes all three doors at once —
+ * assistive-tech traversal, focusability, and pointer events. Scopes stack:
+ * only the topmost active scope's overlay is interactive, and closing it
+ * hands the page back to the scope below, not to the whole document. The
+ * inert set is recomputed only when a scope activates or deactivates, so a
+ * portal that mounts *while* a modal is open (a toast, say) is not inerted
+ * until the stack next changes — under `aria-modal` that content is outside
+ * the dialog's world anyway.
+ */
+type FocusScopeOptions = {
+    /** Whether the scope is active — the overlay's open state. */
+    active: boolean;
+    /** Wrap Tab / Shift+Tab within the scope. Default true. */
+    trap?: boolean;
+    /** Restore focus to the previously focused element on deactivate. Default true. */
+    restoreFocus?: boolean;
+    /**
+     * Where initial focus lands. Defaults to the first visible real control,
+     * then the first focusable of any kind, then the container itself.
+     */
+    initialFocus?: () => HTMLElement | null;
+    /** Make everything outside the scope inert while active. Default true. */
+    inertOutside?: boolean;
+};
+export declare function useFocusScope(ref: React.RefObject<HTMLElement | null>, options: FocusScopeOptions): void;
+export {};

package/behaviors/useFocusScope.js

@@ -0,0 +1,82 @@
+"use client";
+import { useRef, useEffect } from "react";
+import { getInitialFocus, getFocusable } from "./focusable.js";
+const inertScopes = [];
+const inerted = /* @__PURE__ */ new Set();
+const applyInert = () => {
+  const top = inertScopes[inertScopes.length - 1];
+  for (const child of Array.from(document.body.children)) {
+    if (!(child instanceof HTMLElement)) continue;
+    if (child.tagName === "SCRIPT" || child.tagName === "STYLE") continue;
+    const shouldBeInert = top !== void 0 && !child.contains(top.panel);
+    if (shouldBeInert && !child.inert) {
+      child.inert = true;
+      inerted.add(child);
+    } else if (!shouldBeInert && inerted.has(child)) {
+      child.inert = false;
+      inerted.delete(child);
+    }
+  }
+  if (top === void 0 && inerted.size > 0) {
+    for (const el of inerted) el.inert = false;
+    inerted.clear();
+  }
+};
+function useFocusScope(ref, options) {
+  const optionsRef = useRef(options);
+  useEffect(() => {
+    optionsRef.current = options;
+  });
+  const { active } = options;
+  useEffect(() => {
+    if (!active) return;
+    const panel = ref.current;
+    if (!panel) return;
+    const previousFocus = document.activeElement;
+    let focusRaf = 0;
+    let focusAttempts = 0;
+    const tryInitialFocus = () => {
+      const initial = optionsRef.current.initialFocus?.() ?? getInitialFocus(panel) ?? panel;
+      initial.focus();
+      if (document.activeElement === initial) return;
+      focusAttempts += 1;
+      if (focusAttempts < 5) focusRaf = requestAnimationFrame(tryInitialFocus);
+    };
+    tryInitialFocus();
+    const scope = { panel };
+    if (optionsRef.current.inertOutside !== false) {
+      inertScopes.push(scope);
+      applyInert();
+    }
+    const handleKeyDown = (event) => {
+      if (event.key !== "Tab" || optionsRef.current.trap === false) return;
+      const focusable = getFocusable(panel);
+      if (focusable.length === 0) return;
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      cancelAnimationFrame(focusRaf);
+      document.removeEventListener("keydown", handleKeyDown);
+      const index = inertScopes.indexOf(scope);
+      if (index !== -1) {
+        inertScopes.splice(index, 1);
+        applyInert();
+      }
+      if (optionsRef.current.restoreFocus !== false && previousFocus && document.contains(previousFocus)) {
+        previousFocus.focus();
+      }
+    };
+  }, [active, ref]);
+}
+export {
+  useFocusScope
+};

package/behaviors/useLayer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The dismissal layer stack — the single owner of the document-level Escape
+ * and outside-press listeners for every overlay in the library.
+ *
+ * Before this existed, each open overlay registered its own document keydown,
+ * so Escape over a stacked Dialog-in-Drawer closed both at once. The stack
+ * routes each interaction to the **topmost** open layer only: Escape
+ * dismisses it (or is swallowed when it is not Escape-dismissible — a lower
+ * layer must never close through a blocking one), and an outside press
+ * dismisses it only when the press lands outside every element the layer
+ * claims. Layers below are untouched; one press, one layer.
+ *
+ * Exactly two document listeners exist while any layer is open, and none
+ * while the stack is empty. Registration order is stack order — overlays
+ * portal into `document.body` in the order they open, so stack order and
+ * paint order agree without reading z-index.
+ */
+type LayerOptions = {
+    /** The overlay's open state — the layer registers while true. */
+    open: boolean;
+    /** Called when the stack decides this layer should dismiss. */
+    onDismiss?: () => void;
+    /** Whether Escape dismisses this layer. Default true. */
+    dismissOnEscape?: boolean;
+    /**
+     * Whether a pointerdown outside `getElements()` dismisses this layer.
+     * Default false — modal components keep their own backdrop click handler,
+     * which is part of their DOM and needs no document listener.
+     */
+    dismissOnOutsidePress?: boolean;
+    /**
+     * The elements that count as "inside" for outside-press checks — typically
+     * the panel and its trigger. Only read when `dismissOnOutsidePress` is on.
+     */
+    getElements?: () => (HTMLElement | null | undefined)[];
+};
+/**
+ * Register an overlay on the dismissal stack while `open` is true. Options
+ * are read at event time, so a `dismissOnEscape` toggle takes effect without
+ * re-registering (which would wrongly move the layer to the top).
+ */
+export declare function useLayer(options: LayerOptions): void;
+export {};

package/behaviors/useLayer.js

@@ -0,0 +1,55 @@
+"use client";
+import { useRef, useEffect } from "react";
+const layers = [];
+let listenersInstalled = false;
+const handleKeyDown = (event) => {
+  if (event.key !== "Escape") return;
+  const top = layers[layers.length - 1];
+  if (!top) return;
+  const options = top.optionsRef.current;
+  if (options.dismissOnEscape === false) return;
+  event.preventDefault();
+  options.onDismiss?.();
+};
+const handlePointerDown = (event) => {
+  const top = layers[layers.length - 1];
+  if (!top) return;
+  const options = top.optionsRef.current;
+  if (!options.dismissOnOutsidePress) return;
+  const target = event.target instanceof Node ? event.target : null;
+  if (!target) return;
+  const inside = (options.getElements?.() ?? []).some((el) => el?.contains(target));
+  if (!inside) options.onDismiss?.();
+};
+const syncListeners = () => {
+  if (layers.length > 0 && !listenersInstalled) {
+    document.addEventListener("keydown", handleKeyDown);
+    document.addEventListener("pointerdown", handlePointerDown);
+    listenersInstalled = true;
+  } else if (layers.length === 0 && listenersInstalled) {
+    document.removeEventListener("keydown", handleKeyDown);
+    document.removeEventListener("pointerdown", handlePointerDown);
+    listenersInstalled = false;
+  }
+};
+function useLayer(options) {
+  const optionsRef = useRef(options);
+  useEffect(() => {
+    optionsRef.current = options;
+  });
+  const { open } = options;
+  useEffect(() => {
+    if (!open) return;
+    const layer = { optionsRef };
+    layers.push(layer);
+    syncListeners();
+    return () => {
+      const index = layers.indexOf(layer);
+      if (index !== -1) layers.splice(index, 1);
+      syncListeners();
+    };
+  }, [open]);
+}
+export {
+  useLayer
+};

package/behaviors/useMounted.d.ts

@@ -0,0 +1,7 @@
+/**
+ * False during SSR and the hydration render, true afterwards — the guard a
+ * portal component needs before touching `document.body`. Uses
+ * `useSyncExternalStore` rather than a mount effect so the client's first
+ * render matches the server HTML without an extra render pass.
+ */
+export declare function useMounted(): boolean;

package/behaviors/useMounted.js

@@ -0,0 +1,14 @@
+"use client";
+import { useSyncExternalStore } from "react";
+const emptySubscribe = () => () => {
+};
+function useMounted() {
+  return useSyncExternalStore(
+    emptySubscribe,
+    () => true,
+    () => false
+  );
+}
+export {
+  useMounted
+};

package/behaviors/useScrollLock.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Page scroll locking for modal overlays, with two strategies and one owner.
+ *
+ * `pin` (the default) fixes the body in place rather than hiding its
+ * overflow. iOS Safari ignores `overflow: hidden` on the body: a touch still
+ * scrolls the document, and focusing a field scrolls it programmatically to
+ * bring the field above the keyboard — which slides the page out from under
+ * the overlay. A fixed body has no scrollable overflow at all, so neither can
+ * move it. The body is pinned at its current scroll offset so the page behind
+ * the overlay does not visibly jump, and the offset is restored when the last
+ * holder releases. `overflow: hidden` rides along so the pinned body cannot
+ * grow scrollbars of its own.
+ *
+ * The pin is **counted**, and the counter is the whole point: closing a
+ * Dialog opened over a Drawer must not unlock the Drawer's scroll. The
+ * imperative pair (`acquireScrollLock` / `releaseScrollLock`) exposes the
+ * same counter to host chrome — a site's nav drawer, a bespoke chat panel —
+ * because two locks that cannot see each other each believe they own
+ * `document.body`, and whichever releases first unlocks the page under the
+ * overlay the other still holds (or restores styles the other already
+ * changed). One counter means the first acquire captures and pins, only the
+ * last release restores, whichever module it belongs to. The captured inline
+ * styles are restored verbatim, never blanked, so a host's own body styling
+ * survives a lock cycle.
+ *
+ * `cancel-events` keeps the document scrollbar rendered and cancels scroll
+ * *input* instead — wheel and touch gestures work only inside `allowWithin`.
+ * This is CommandPalette's documented design decision (unscrollable-body
+ * treatments blink the scrollbar rail out, which reads as a layout jump on
+ * classic-scrollbar platforms); it is deliberately not the default because
+ * swapping the modals onto it would change their scrollbar rendering.
+ * Instances are independent — overlapping cancel-events locks stack
+ * harmlessly.
+ */
+type ScrollLockOptions = {
+    /** Which locking strategy to use. Default `'pin'`. */
+    strategy?: 'pin' | 'cancel-events';
+    /** For `cancel-events`: the scrollable region that keeps receiving input. */
+    allowWithin?: React.RefObject<HTMLElement | null>;
+};
+/**
+ * Take one hold on the shared page scroll lock — the counter behind the
+ * hook's `pin` strategy. For overlays outside this library (host chrome)
+ * that must not fight the modal components over `document.body`. Every
+ * acquire needs exactly one matching release.
+ */
+export declare function acquireScrollLock(): void;
+/**
+ * Release one hold on the shared page scroll lock. The body styles and the
+ * scroll offset are restored only when the last hold anywhere releases; an
+ * unbalanced release never touches the page.
+ */
+export declare function releaseScrollLock(): void;
+export declare function useScrollLock(active: boolean, options?: ScrollLockOptions): void;
+export {};

package/behaviors/useScrollLock.js

@@ -0,0 +1,59 @@
+"use client";
+import { useRef, useEffect } from "react";
+const PINNED_PROPS = ["position", "top", "left", "right", "overflow"];
+let pinCount = 0;
+let pinnedScrollY = 0;
+let previousBodyStyle = {};
+function acquireScrollLock() {
+  if (pinCount === 0) {
+    const { style } = document.body;
+    pinnedScrollY = window.scrollY;
+    previousBodyStyle = {};
+    for (const prop of PINNED_PROPS) previousBodyStyle[prop] = style[prop];
+    style.position = "fixed";
+    style.top = `-${pinnedScrollY}px`;
+    style.left = "0";
+    style.right = "0";
+    style.overflow = "hidden";
+  }
+  pinCount += 1;
+}
+function releaseScrollLock() {
+  if (pinCount === 0) return;
+  pinCount -= 1;
+  if (pinCount > 0) return;
+  const { style } = document.body;
+  for (const prop of PINNED_PROPS) style[prop] = previousBodyStyle[prop] ?? "";
+  window.scrollTo({ top: pinnedScrollY, behavior: "instant" });
+}
+function useScrollLock(active, options) {
+  const optionsRef = useRef(options);
+  useEffect(() => {
+    optionsRef.current = options;
+  });
+  const strategy = options?.strategy ?? "pin";
+  useEffect(() => {
+    if (!active) return;
+    if (strategy === "pin") {
+      acquireScrollLock();
+      return releaseScrollLock;
+    }
+    const block = (event) => {
+      const allow = optionsRef.current?.allowWithin?.current;
+      const target = event.target instanceof Node ? event.target : null;
+      if (allow && target && allow.contains(target)) return;
+      event.preventDefault();
+    };
+    document.addEventListener("wheel", block, { passive: false });
+    document.addEventListener("touchmove", block, { passive: false });
+    return () => {
+      document.removeEventListener("wheel", block);
+      document.removeEventListener("touchmove", block);
+    };
+  }, [active, strategy]);
+}
+export {
+  acquireScrollLock,
+  releaseScrollLock,
+  useScrollLock
+};

package/components/AgentPlan/AgentPlan.css

@@ -151,6 +151,11 @@
   align-items: center;
   justify-content: center;
   flex: none;
+  /* Fixed box: the active step's spinner (16px) is smaller than the step
+     icons (20px), so without this the column narrows and the spinner drifts
+     off the connector's centre line. */
+  width: var(--icon-size-sm);
+  height: var(--icon-size-sm);
   color: var(--color-icon-secondary);
 }
 
@@ -188,8 +193,12 @@
    STEP STATES
    ============================================ */
 
+.ds-agent-plan__step--pending .ds-agent-plan__indicator {
+  color: var(--color-status-neutral-icon);
+}
+
 .ds-agent-plan__step--completed .ds-agent-plan__indicator {
-  color: var(--color-status-positive-text);
+  color: var(--color-status-positive-icon);
 }
 
 .ds-agent-plan__step--completed .ds-agent-plan__label {
@@ -197,7 +206,7 @@
 }
 
 .ds-agent-plan__step--active .ds-agent-plan__indicator {
-  color: var(--color-status-info-text);
+  color: var(--color-status-info-icon);
 }
 
 .ds-agent-plan__step--active .ds-agent-plan__label {
@@ -207,7 +216,7 @@
 }
 
 .ds-agent-plan__step--failed .ds-agent-plan__indicator {
-  color: var(--color-status-error-text);
+  color: var(--color-status-error-icon);
 }
 
 .ds-agent-plan__step--failed .ds-agent-plan__label {