@elabs-ai/components-editor 4.0.0 → 4.1.0

package/src/markdown-editor/markdown-editor.focus.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+// Read the stylesheet as text. The repo runs vitest per-package (turbo /
+// `--filter`), so cwd is the package root — `src/...` resolves deterministically.
+const css = readFileSync(resolve(process.cwd(), "src/markdown-editor/markdown-editor.css"), "utf8");
+
+/**
+ * #309: `.ProseMirror` used to suppress the platform focus outline
+ * (`outline: none`, repeated as a dead no-op at `:focus`) with no replacement
+ * on the element itself — the only stand-in lived on a DIFFERENT element in a
+ * different file (`markdown-editor.tsx`'s wrapper `focus-ring-within` class),
+ * an implicit, unlocked, easily-overridden dependency raw CSS can't express.
+ * jsdom doesn't apply real focus/outline rendering, so this locks the
+ * stylesheet TEXT deterministically; `markdown-editor.stories.tsx`'s
+ * `FocusIndicator` play is the rendered-surface proof (resolved computed
+ * values, real contrast, both themes).
+ */
+describe("editor focus indicator CSS (regression, #309)", () => {
+  it("gives the editable its own :focus-visible indicator with a real outline", () => {
+    const focusVisibleRule = css.match(/\.milkdown-host \.ProseMirror:focus-visible\s*\{([^}]*)\}/);
+    expect(
+      focusVisibleRule,
+      "expected a .milkdown-host .ProseMirror:focus-visible rule",
+    ).not.toBeNull();
+    const body = focusVisibleRule![1]!;
+    expect(body).toMatch(/outline:\s*(?!none\b)\S/);
+  });
+
+  it("never suppresses the outline on a :focus/:focus-visible rule with nothing else in it", () => {
+    // A rule whose ENTIRE body is `outline: none;` (whitespace only otherwise)
+    // on a focus selector is exactly the dead-suppression defect #309 found —
+    // catches a future edit re-adding `.ProseMirror:focus { outline: none; }`
+    // (or a :focus-visible equivalent) with no compensating declaration.
+    const focusRules = [...css.matchAll(/([.\w-]+:focus(?:-visible)?)\s*\{([^}]*)\}/g)];
+    for (const [, selector, body] of focusRules) {
+      const bareOutlineNone = /^\s*outline:\s*none;?\s*$/.test(body!);
+      expect(
+        bareOutlineNone,
+        `${selector} suppresses outline with no replacement in the same rule`,
+      ).toBe(false);
+    }
+  });
+
+  it("no longer contains the dead .ProseMirror:focus { outline: none; } rule", () => {
+    expect(css).not.toMatch(/\.milkdown-host \.ProseMirror:focus\s*\{\s*outline:\s*none;?\s*\}/);
+  });
+});

package/src/markdown-editor/markdown-editor.stories.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { expect, waitFor, within } from "storybook/test";
+import { expect, userEvent, waitFor, within } from "storybook/test";
 import { useRef, useState } from "react";
 import { ThemeProvider } from "@elabs-ai/components-tokens";
 import { MarkdownEditor, type MarkdownEditorHandle } from "./markdown-editor";
@@ -14,9 +14,12 @@ const meta = {
     docs: {
       description: {
         component:
+          "The WYSIWYG markdown surface; the Monaco SOURCE editor is `Editor/CodeEditor` " +
+          "and the read-only render is `Editor/MarkdownPreview` — see " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). " +
           "A headless Milkdown (ProseMirror) WYSIWYG markdown surface vendored onto " +
           "brand-ui. Companion to the Monaco `CodeEditor` (source) in the same package. " +
-          "Theming is 100% semantic tokens, so it tracks all three themes via `data-theme`. " +
+          "Theming is 100% semantic tokens, so it tracks every theme via `data-theme`. " +
           "Depends on only `@milkdown/kit` — no Vue/Crepe.",
       },
     },
@@ -138,7 +141,7 @@ Two upstream data sources are still un-mapped.
  * The brand `:::` directives render as the REAL @brand components inside the editor
  * (a live `Card`, `Alert`, `MetricBlock`), with the card/callout title and the metric
  * label/value editable inline — not the old token-styled `toDOM` chrome. Switch the
- * Storybook theme to confirm they track all three themes.
+ * Storybook theme to confirm they track every theme.
  */
 export const LiveDirectives: Story = {
   name: "Live directives (inline-editable)",
@@ -275,9 +278,9 @@ Prose continues normally after the table.
  * - Tab moves to the next cell; Shift+Tab to the previous.
  * - The serialized markdown (shown below the editor) stays lossless GFM.
  *
- * Three-theme sweep: switch the Storybook theme toolbar to verify the table
+ * Cross-theme sweep: switch the Storybook theme toolbar to verify the table
  * borders (`border-border-strong`), header tint (`bg-surface-muted`), and
- * toolbar chrome use only semantic tokens across all three themes.
+ * toolbar chrome use only semantic tokens across every theme.
  */
 export const EditableTable: Story = {
   name: "Editable table (wysiwyg-tables)",
@@ -342,7 +345,14 @@ export const FillsContainer: Story = {
     await expect(editable).toBeVisible();
     // The 1-line doc's editable fills the 700px container (well past the ~144px
     // content floor) — clickable everywhere, with room for the `/` menu.
-    expect(editable.clientHeight).toBeGreaterThan(500);
+    //
+    // Waited for, not read once: the fill chain is `.milkdown-host .ProseMirror.editor
+    // { flex: 1 1 auto }`, and Milkdown adds the `editor` class in a later commit than
+    // the one that puts `role="textbox"` in the DOM. Between the two the editable sits at
+    // its own `min-height: 9rem` (144px) inside an already-700px host — measured, not
+    // guessed. Reading `clientHeight` on the frame `findByRole` resolves therefore samples
+    // a real but transient layout; the settled condition is the one this story is about.
+    await waitFor(() => expect(editable.clientHeight).toBeGreaterThan(500), { timeout: 8000 });
   },
 };
 
@@ -504,7 +514,7 @@ export const IterationContextMenu: Story = {
 };
 
 /**
- * Three-theme sweep for the node menu (#223 round-2): both `NodeMenu` (⋯) and
+ * Cross-theme sweep for the node menu (#223 round-2): both `NodeMenu` (⋯) and
  * `IterationContextMenu` (right-click) above run only under the toolbar's
  * DEFAULT theme (`light`) — Storybook's `defaultTheme` isn't overridable
  * per-story from the global decorator alone, and toggling `preview.tsx` by hand
@@ -558,3 +568,114 @@ export const IterationContextMenuHighDecoration: Story = {
   render: IterationContextMenu.render,
   play: IterationContextMenu.play,
 };
+
+/**
+ * #309 — the editable's own compound focus indicator. Resolves the governing
+ * theme element FROM THE SUBJECT (`el.closest("[data-theme]")`, never a
+ * guessed ancestor — quality-gates.md § Theme-safe), reads RESOLVED computed
+ * values (not the class string — a class-string assertion passed on the
+ * previous, invisible wrapper ring, which is exactly how this shipped), and
+ * asserts at least one of the indicator's two layers clears 3:1 against the
+ * ground the editable sits on. `markdown-editor.focus.test.ts` locks the
+ * stylesheet TEXT; this is the rendered-surface proof.
+ */
+export const FocusIndicator: Story = {
+  name: "Focus indicator (#309)",
+  render: () => (
+    <div className="mx-auto max-w-3xl p-6">
+      <MarkdownEditor
+        defaultValue={"# Focus indicator\n\nClick or Tab into the editable below."}
+        aria-label="Markdown editor"
+      />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const editable = await canvas.findByRole(
+      "textbox",
+      { name: "Markdown editor" },
+      { timeout: 8000 },
+    );
+    await expect(editable).toBeVisible();
+    expect(editable.classList.contains("ProseMirror")).toBe(true);
+
+    const wrapper = canvasElement.querySelector<HTMLElement>('[data-testid="markdown-editor"]');
+    expect(wrapper).not.toBeNull();
+
+    // Resolve ANY CSS colour string down to sRGB so a contrast ratio is a
+    // measurement, not an assumption — same helper `FlowNode`'s
+    // `FocusIndicator` lock uses for the flow-canvas half of this same fix
+    // family (#286).
+    const toSrgb = (colour: string): [number, number, number] => {
+      const surface = document.createElement("canvas");
+      surface.width = 1;
+      surface.height = 1;
+      const ctx = surface.getContext("2d")!;
+      ctx.fillStyle = colour;
+      ctx.fillRect(0, 0, 1, 1);
+      const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+      return [r! / 255, g! / 255, b! / 255];
+    };
+    const luminance = ([r, g, b]: [number, number, number]) => {
+      const lin = (v: number) => (v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4));
+      return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+    };
+    const contrast = (a: string, b: string) => {
+      const [hi, lo] = [luminance(toSrgb(a)), luminance(toSrgb(b))].sort((x, y) => y - x);
+      return (hi! + 0.05) / (lo! + 0.05);
+    };
+
+    // Resting: no indicator on the editable, and the wrapper draws no ring of
+    // its own either (#309 — exactly one indicator, never a doubled one).
+    await expect(getComputedStyle(editable).outlineStyle).toBe("none");
+    await expect(getComputedStyle(wrapper!).boxShadow).toBe("none");
+
+    // Click into the editable. `:focus-visible` matches on pointer click for
+    // a contenteditable surface per spec (unlike a plain <input>/<button>),
+    // so this is a faithful proxy for the real "click to edit" path.
+    await userEvent.click(editable);
+    await waitFor(() => {
+      expect(getComputedStyle(editable).outlineStyle).toBe("solid");
+    });
+
+    // Exactly one indicator: the wrapper still draws nothing.
+    await expect(getComputedStyle(wrapper!).boxShadow).toBe("none");
+
+    const ground = getComputedStyle(wrapper!).backgroundColor;
+    const contourInk = getComputedStyle(editable).outlineColor;
+    const ringInk = getComputedStyle(editable).getPropertyValue("--ring").trim();
+    const contourRatio = contrast(contourInk, ground);
+    const ringRatio = contrast(ringInk, ground);
+    const bestRatio = Math.max(contourRatio, ringRatio);
+    await expect(
+      bestRatio,
+      `focus indicator vs editor ground: contour ${contourInk} = ${contourRatio.toFixed(2)}:1, ring ${ringInk} = ${ringRatio.toFixed(2)}:1`,
+    ).toBeGreaterThanOrEqual(3);
+
+    // Blur restores the resting state.
+    (editable as HTMLElement).blur();
+    await waitFor(() => {
+      expect(getComputedStyle(editable).outlineStyle).toBe("none");
+    });
+  },
+};
+
+export const FocusIndicatorDark: Story = {
+  name: "Focus indicator (#309) — dark",
+  decorators: [
+    (Story) => (
+      <ThemeProvider defaultTheme="dark" storageKey={null}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+  render: FocusIndicator.render,
+  play: FocusIndicator.play,
+};
+
+export const FocusIndicatorHighDecoration: Story = {
+  name: "Focus indicator (#309) — high decoration",
+  globals: { decoration: "10" },
+  render: FocusIndicator.render,
+  play: FocusIndicator.play,
+};

package/src/markdown-editor/markdown-editor.tsx

@@ -7,7 +7,7 @@
  *
  * - Engine dep: only `@milkdown/kit` (headless). React glue is vendored under
  *   ./milkdown-react so we never pull `@milkdown/react` → `@milkdown/crepe` → Vue.
- * - Theming: token-driven via markdown-editor.css (all three themes, no raw color).
+ * - Theming: token-driven via markdown-editor.css (every theme, no raw color).
  * - Controlled (`value` + `onChange`) or uncontrolled (`defaultValue`). Mirrors the
  *   platform: `isControlled = value !== undefined`; never flips between modes.
  * - StrictMode-safe (see markdown-editor.strictmode.test.tsx).
@@ -527,10 +527,13 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
       <div
         data-testid="markdown-editor"
         className={cn(
-          // A 1px hairline focus ring (not a heavy 2px ring) — the editable is a
-          // large surface, so a thinner edit-mode ring reads calmer while still
-          // meeting the visible-focus requirement (same `ring` token). (A7)
-          "milkdown-host overflow-auto rounded-md border border-border bg-background text-foreground focus-within:ring-1 focus-within:ring-ring",
+          // No focus-ring utility here (deliberately, #309): the editable
+          // `.ProseMirror` element owns the compound focus indicator itself
+          // (`markdown-editor.css`'s `:focus-visible` rule), so it renders
+          // even when a consumer `className` overrides this wrapper's
+          // classes (`MarkdownWorkspace` does exactly that via
+          // `className="border-0"`) and never doubles up with a wrapper ring.
+          "milkdown-host overflow-auto rounded-md border border-border bg-background text-foreground",
           className,
         )}
         // Publish the shared markdown scale as CSS vars the editor CSS reads, so the

package/src/markdown-editor/milkdown-react/use-get-editor.timer-leak.test.ts

@@ -0,0 +1,80 @@
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { createElement } from "react";
+import { afterEach, expect, test, vi } from "vitest";
+
+import { MarkdownEditor } from "../markdown-editor";
+import { waitForPendingMilkdownTeardown } from "./use-get-editor";
+
+afterEach(cleanup);
+
+// @milkdown/ctx's internal `Timer` (armed by `Ctx.wait()`, which
+// `@milkdown/core`'s `create()`/`destroy()` call internally for every
+// `createTimer(name)` — e.g. `ConfigReady`, `InitReady`, `EditorViewReady`)
+// uses `TimerType`'s default delay: `createTimer(name, timeout = 3e3)`,
+// never overridden anywhere in this repo's editor setup.
+const MILKDOWN_TIMER_DELAY_MS = 3000;
+
+/**
+ * Locks issue #84: `@milkdown/ctx`'s `Timer` class starts a 3-second
+ * `setTimeout` on every wait and never clears the handle on the resolve
+ * path — only the DOM/global event listener is removed
+ * (`lib/index.js:281-288`, vendored `@milkdown/ctx@7.21.2`). That leaves the
+ * timer armed for up to 3s after the promise it backs has already settled,
+ * and if it fires after Vitest has recycled the test file's jsdom
+ * environment, its callback's bare (unqualified) `removeEventListener` call
+ * throws `ReferenceError: removeEventListener is not defined` — the
+ * mechanism behind #65's originally-reported error.
+ *
+ * A bare "was `clearTimeout` called at some point" assertion would pass
+ * regardless of this bug, since unrelated React/ProseMirror machinery also
+ * calls `clearTimeout`. So this test tracks every `setTimeout` handle armed
+ * with Milkdown's exact 3-second delay, and every `clearTimeout` call, and
+ * asserts each such handle is cleared once Milkdown's own teardown
+ * (`waitForPendingMilkdownTeardown`, tracked in `use-get-editor.ts`) has
+ * settled. Against the unpatched `@milkdown/ctx` dependency this fails (no
+ * `clearTimeout` call in the vendored file at all — `grep -c clearTimeout`
+ * returns 0); the `patches/@milkdown__ctx@7.21.2.patch` fix (storing the
+ * handle and clearing it in `#removeListener`, which both the resolve and
+ * reject/timeout paths already call) makes it pass.
+ */
+test("clears the vendored @milkdown/ctx wait timer on teardown (#84)", async () => {
+  const originalSetTimeout = globalThis.setTimeout;
+  const originalClearTimeout = globalThis.clearTimeout;
+
+  const armedHandles = new Set<ReturnType<typeof setTimeout>>();
+  const clearedHandles = new Set<Parameters<typeof clearTimeout>[0]>();
+
+  vi.spyOn(globalThis, "setTimeout").mockImplementation(((
+    handler: TimerHandler,
+    timeout?: number,
+    ...args: unknown[]
+  ) => {
+    const handle = originalSetTimeout(handler as never, timeout, ...args);
+    if (timeout === MILKDOWN_TIMER_DELAY_MS) armedHandles.add(handle);
+    return handle;
+  }) as unknown as typeof setTimeout);
+
+  vi.spyOn(globalThis, "clearTimeout").mockImplementation(((
+    handle?: Parameters<typeof clearTimeout>[0],
+  ) => {
+    clearedHandles.add(handle);
+    return originalClearTimeout(handle as never);
+  }) as unknown as typeof clearTimeout);
+
+  const { unmount } = render(createElement(MarkdownEditor, { defaultValue: "# Hello Timer" }));
+  await waitFor(() => expect(screen.getByText("Hello Timer")).toBeInTheDocument());
+
+  unmount();
+  await waitForPendingMilkdownTeardown();
+
+  vi.restoreAllMocks();
+
+  // Sanity: the mechanism under test actually armed at least one 3-second
+  // wait timer during create()/destroy() — otherwise the loop below would
+  // trivially pass over an empty set.
+  expect(armedHandles.size).toBeGreaterThan(0);
+
+  for (const handle of armedHandles) {
+    expect(clearedHandles.has(handle)).toBe(true);
+  }
+});

package/src/markdown-editor/milkdown-react/use-get-editor.ts

@@ -9,6 +9,16 @@
  * settles), so the double-mount converges to a single editor. The co-located
  * `markdown-editor.strictmode.test.tsx` is the gate that proves that convergence
  * for our vendored copy; harden here only if that test ever shows >1 surface.
+ *
+ * DESTROY gets the same rigor (issue #65). Effect cleanup fires
+ * `editor.destroy()` but nothing awaited it, and `@milkdown/ctx` schedules its
+ * own internal async cleanup (a timer) inside that promise — so an unmount that
+ * doesn't wait can let the timer fire after Vitest has already recycled the
+ * file's jsdom environment (`ReferenceError: removeEventListener is not
+ * defined`). `pendingDestroys` tracks every in-flight `destroy()`, and
+ * `waitForPendingMilkdownTeardown()` lets a caller — a test's `afterEach`, or any
+ * consumer that cares — await "every Milkdown teardown has settled" the same way
+ * `create()` already converges before this effect resolves.
  */
 import { createContext, useContext, useEffect, useRef } from "react";
 
@@ -16,6 +26,25 @@ import type { EditorInfoCtx } from "./types";
 
 export const editorInfoContext = createContext<EditorInfoCtx>({} as EditorInfoCtx);
 
+/** Module-scoped registry of in-flight Milkdown `destroy()` promises. Not part
+ *  of the package's public API (not re-exported from `./index`) — reached by
+ *  relative import from tests/consumers that specifically need to await
+ *  teardown, mirroring how `editorInfoContext` itself stays internal. */
+const pendingDestroys = new Set<Promise<unknown>>();
+
+/** True while at least one Milkdown `destroy()` is still in flight. */
+export function hasPendingMilkdownTeardown(): boolean {
+  return pendingDestroys.size > 0;
+}
+
+/** Await every Milkdown `destroy()` currently in flight. Resolves immediately
+ *  when none are pending. Never rejects — `destroy()` already routes its own
+ *  failure through `console.error` (see the cleanup below), so a caller awaiting
+ *  teardown only needs "settled", not "succeeded". */
+export function waitForPendingMilkdownTeardown(): Promise<void> {
+  return Promise.all(pendingDestroys).then(() => undefined);
+}
+
 export function useGetEditor() {
   const {
     dom,
@@ -48,7 +77,14 @@ export function useGetEditor() {
       .catch(console.error);
 
     return () => {
-      editor.destroy().catch(console.error);
+      // `.catch(console.error)` means this promise itself never rejects, so
+      // it's safe to await via `Promise.all` in `waitForPendingMilkdownTeardown`
+      // without a stray unhandled rejection.
+      const destroyPromise = editor.destroy().catch(console.error);
+      pendingDestroys.add(destroyPromise);
+      void destroyPromise.finally(() => {
+        pendingDestroys.delete(destroyPromise);
+      });
     };
   }, [dom, editorRef, getEditor, setLoading]);
 

package/src/markdown-editor/paste-embed.ts

@@ -123,8 +123,9 @@ function makeErrorChip(message: string): HTMLElement {
   chip.setAttribute("role", "alert");
   chip.setAttribute("aria-live", "assertive");
   chip.setAttribute("title", message);
+  // #124: the chip's own "Upload failed" label is running text — ink rung.
   chip.className =
-    "inline-flex items-center gap-1 rounded px-2 py-0.5 text-caption bg-destructive/10 text-destructive " +
+    "inline-flex items-center gap-1 rounded px-2 py-0.5 text-caption bg-destructive/10 text-destructive-text " +
     "border border-destructive/30 select-none";
 
   const label = document.createElement("span");

package/src/markdown-editor/slash/slash-menu.stories.tsx

@@ -14,19 +14,22 @@ import { SlashMenu } from "./slash-menu";
  * `MarkdownWorkspace` (default `true`).
  *
  * The popup itself is rendered here standalone (the `SlashMenu` stories) so its
- * branding + a11y can be verified directly across all three themes; the in-editor
+ * branding + a11y can be verified directly across every theme; the in-editor
  * stories exercise the integration (mount + the `slashMenu={false}` no-op). The
  * live keyboard/insert UX is best verified in a real browser — ProseMirror
  * keystroke dispatch can't be fully simulated in jsdom.
  */
 const meta = {
-  title: "Editor/MarkdownEditor/Slash menu",
+  title: "Editor/MarkdownEditor/SlashMenu",
   component: SlashMenu,
   tags: ["autodocs"],
   parameters: {
     docs: {
       description: {
         component:
+          "The EDITOR slash menu, which inserts ProseMirror nodes; a chat composer uses " +
+          "`AI/Composer/PromptInputSlash` and a console composer `Terminal/TerminalSlashMenu` — see " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). " +
           "Branded `/` command menu for the WYSIWYG editor. Inserts brand `:::` " +
           "directives + basic blocks at the caret. Token-driven `listbox`/`option` " +
           "list; the editor `textbox` owns `aria-activedescendant`.",
@@ -92,7 +95,9 @@ export const Empty: Story = {
   ),
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    await expect(canvas.getByText("No matching blocks")).toBeVisible();
+    // A `role="option"` (not a bare div), so it's reachable via an
+    // assistive-tech query and stays inside the listbox contract (#157).
+    await expect(canvas.getByRole("option", { name: "No matching blocks" })).toBeVisible();
   },
 };
 

package/src/markdown-editor/slash/slash-menu.test.tsx

@@ -0,0 +1,27 @@
+/**
+ * Locking test for #157 (site 1): `SlashMenu`'s empty state used to be a bare
+ * `<div>` inside `role="listbox"` — not `option`/`group`, so a user who types
+ * a query matching nothing got silence (axe `aria-required-children`).
+ */
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+
+import { SlashMenu } from "./slash-menu";
+
+describe("SlashMenu — empty state a11y (#157)", () => {
+  it("announces the no-match message as a disabled option, not a bare div", () => {
+    render(<SlashMenu commands={[]} onSelect={() => {}} emptyLabel="No matching blocks" />);
+
+    const listbox = screen.getByRole("listbox", { name: "Insert block" });
+    // Reachable via an assistive-tech query, not only present in the DOM.
+    const empty = screen.getByRole("option", { name: "No matching blocks" });
+    expect(listbox).toContainElement(empty);
+    expect(empty).toHaveAttribute("aria-disabled", "true");
+
+    // Every direct child of the listbox is an `option` or `group` — never a
+    // bare, roleless element.
+    for (const child of Array.from(listbox.children)) {
+      expect(["option", "group"]).toContain(child.getAttribute("role"));
+    }
+  });
+});

package/src/markdown-editor/slash/slash-menu.tsx

@@ -65,7 +65,19 @@ export const SlashMenu = forwardRef<HTMLDivElement, SlashMenuProps>(function Sla
       {...props}
     >
       {commands.length === 0 ? (
-        <div className="px-2 py-6 text-center text-caption text-muted-foreground">{emptyLabel}</div>
+        // A `role="listbox"` may only own `option`/`group` children (WCAG 1.3.1,
+        // #157): a bare `<div>` here is an unannounced, dangling message — an
+        // AT user who types a query matching nothing gets silence. Shaping it
+        // as a disabled, unselectable option keeps the listbox contract AND
+        // makes the message reachable by an accessible-name query.
+        <div
+          role="option"
+          aria-disabled="true"
+          aria-selected="false"
+          className="cursor-default select-none px-2 py-6 text-center text-caption text-muted-foreground"
+        >
+          {emptyLabel}
+        </div>
       ) : (
         groups.map(({ group, commands: groupCommands }) => (
           <div key={group} role="group" aria-label={group} className="overflow-hidden p-1">

package/src/markdown-editor/table-view.tsx

@@ -109,10 +109,11 @@ function ToolbarButton({
       className={cn(
         "inline-flex h-7 items-center gap-1 rounded px-2 text-caption font-medium",
         "border border-border-strong",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        "focus-ring",
         "transition-colors duration-fast ease-standard motion-reduce:transition-none",
+        // #124: the button's LABEL text, not a mark — ink rung.
         variant === "destructive"
-          ? "bg-background text-destructive hover:bg-destructive/10"
+          ? "bg-background text-destructive-text hover:bg-destructive/10"
           : "bg-background text-foreground hover:bg-surface-muted",
       )}
     >

package/src/markdown-iteration/iteration-builder-dialog.stories.tsx

@@ -1,7 +1,7 @@
 import { Button } from "@elabs-ai/components-ui";
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { useState } from "react";
-import { expect, userEvent, within } from "storybook/test";
+import { expect, userEvent, waitFor, within } from "storybook/test";
 
 import { IterationBuilderDialog } from "./iteration-builder-dialog";
 import type { IterationBuilderValue } from "./iteration-builder";
@@ -41,6 +41,32 @@ const room = (child: HTMLElement, box: HTMLElement) => {
   };
 };
 
+/**
+ * Presence is not visibility. `findByText` resolves the instant the node lands in
+ * the DOM — which is INSIDE the dialog's enter animation (`data-[state=open]:animate-in
+ * fade-in-0 zoom-in-95` on `DialogContent`), so the query can hand back an element
+ * still holding that animation's start value, `opacity: 0`. A one-shot
+ * `toBeVisible()` on the node the query just returned then fails.
+ *
+ * Reduced motion does NOT remove that window: the token backstop in `themes.css`
+ * (`@media (prefers-reduced-motion: reduce)`) clamps every animation to `0.01ms`,
+ * it does not cancel it — and by taking the enter animation's real duration out of
+ * the way it makes the play function reach the assertion sooner. That is why these
+ * stories only started failing in CI once the browser context asked for reduced
+ * motion (`apps/docs/vitest.config.ts`); the two stories below that already waited
+ * for the settled state kept passing in the same run.
+ *
+ * (The failure PRINTS as an empty element — `<th scope="col" />`. That is jest-dom's
+ * formatting, not the DOM: `toBeVisible` reports `element.cloneNode(false)`, a
+ * shallow clone, so children are never shown. The element was populated.)
+ *
+ * So assert the SETTLED end state: re-query inside `waitFor` and re-check visibility
+ * until it holds. Not a timeout bump — a stale node can never be asserted, and the
+ * text still has to become visible for the story to pass.
+ */
+const expectVisibleText = (scope: HTMLElement, text: string) =>
+  waitFor(() => expect(within(scope).getByText(text)).toBeVisible(), { timeout: 8000 });
+
 const meta = {
   title: "Editor/Iteration/BuilderDialog",
   component: IterationBuilderDialog,
@@ -105,14 +131,12 @@ export const PivotBuilder: Story = {
     // Each value string renders TWICE — once as a TagInput chip in the left
     // column, once in the live preview — so scope queries to the preview region
     // (the confirming pattern from PivotWithCalc / WithNestedCard below).
-    const preview = within(
-      await d.findByRole("region", { name: /live preview/i }, { timeout: 8000 }),
-    );
+    const preview = await d.findByRole("region", { name: /live preview/i }, { timeout: 8000 });
     // The live preview renders a populated matrix from the embedded value lists:
     // axis headers + an interpolated cell.
-    await expect(await preview.findByText("North", {}, { timeout: 8000 })).toBeVisible();
-    await expect(preview.getByText("Q1")).toBeVisible();
-    await expect(preview.getByText("Q1 · North")).toBeVisible();
+    await expectVisibleText(preview, "North");
+    await expectVisibleText(preview, "Q1");
+    await expectVisibleText(preview, "Q1 · North");
   },
 };
 
@@ -149,13 +173,24 @@ export const IterateBuilder: Story = {
     const canvas = within(canvasElement);
     await userEvent.click(canvas.getByRole("button", { name: /Edit iteration/i }));
     const dialog = await within(document.body).findByRole("dialog", {}, { timeout: 12000 });
+    // The per-cell template field is a Monaco editor (`MarkdownWorkspace`
+    // defaultMode="source"). axe scans whatever is in the DOM the instant it
+    // runs, so a scan that races Monaco's first paint can measure a token span
+    // before its (AA-clamped) syntax color has actually been applied — wait for
+    // a real rendered token span first (#88).
+    await waitFor(
+      () => expect(dialog.querySelector('.view-line span[class*="mtk"]')).toBeTruthy(),
+      { timeout: 8000 },
+    );
     // "Alice" renders TWICE — as a TagInput chip AND in the live preview — so
     // scope to the preview region (mirrors the PivotBuilder fix above).
-    const preview = within(
-      await within(dialog).findByRole("region", { name: /live preview/i }, { timeout: 8000 }),
+    const preview = await within(dialog).findByRole(
+      "region",
+      { name: /live preview/i },
+      { timeout: 8000 },
     );
     // The live preview renders one cell per embedded value.
-    await expect(await preview.findByText("Alice", {}, { timeout: 8000 })).toBeVisible();
+    await expectVisibleText(preview, "Alice");
 
     // #425 acceptance criterion: this dialog's `Bind name` field sits directly
     // against the (now real) `DialogBody` scrollport as its first child — the
@@ -244,12 +279,13 @@ export const WithNestedCard: Story = {
     const canvas = within(canvasElement);
     await userEvent.click(canvas.getByRole("button", { name: /Edit iteration with card/i }));
     const dialog = await within(document.body).findByRole("dialog", {}, { timeout: 12000 });
-    const d = within(dialog);
-    // The nested card rendered as a real component (title + body interpolated)...
-    await expect(await d.findByText("Lead engineer for Ada", {}, { timeout: 8000 })).toBeVisible();
+    // The nested card rendered as a real component (title + body interpolated) —
+    // waited out through `expectVisibleText` (see its note: presence ≠ visibility
+    // while the dialog's enter animation is on its first frame)...
+    await expectVisibleText(dialog, "Lead engineer for Ada");
     // ...and the content AFTER it survived (dropped before the fence-collision fix).
-    await expect(d.getByText("Notes for Ada")).toBeVisible();
-    await expect(d.getByText("Notes for Grace")).toBeVisible();
+    await expectVisibleText(dialog, "Notes for Ada");
+    await expectVisibleText(dialog, "Notes for Grace");
   },
 };
 
@@ -284,10 +320,12 @@ export const BentoBuilder: Story = {
     const dialog = await within(document.body).findByRole("dialog", {}, { timeout: 12000 });
     // "Alpha"/"Epsilon" render TWICE — as TagInput chips AND in the live
     // preview's BentoGrid tiles — so scope to the preview region.
-    const preview = within(
-      await within(dialog).findByRole("region", { name: /live preview/i }, { timeout: 8000 }),
+    const preview = await within(dialog).findByRole(
+      "region",
+      { name: /live preview/i },
+      { timeout: 8000 },
     );
-    await expect(await preview.findByText("Alpha", {}, { timeout: 8000 })).toBeVisible();
-    await expect(preview.getByText("Epsilon")).toBeVisible();
+    await expectVisibleText(preview, "Alpha");
+    await expectVisibleText(preview, "Epsilon");
   },
 };

package/src/markdown-outline/document-outline.stories.tsx

@@ -60,7 +60,7 @@ function ItemActionsDemo() {
             aria-label={`Pin section “${item.text}”`}
             aria-pressed={pinned === item.id}
             onClick={() => setPinned((p) => (p === item.id ? null : item.id))}
-            className="rounded-sm p-0.5 text-muted-foreground hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            className="rounded-sm p-0.5 text-muted-foreground hover:text-foreground focus-ring"
           >
             <Pin className="size-3" aria-hidden="true" />
           </button>