@elabs-ai/components-ui 4.0.0 → 4.1.0

package/src/components/section-header/section-header.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
 import { Button } from "../button";
 import { SectionHeader } from "./section-header";
 
@@ -18,3 +19,39 @@ export const Default: Story = {
     actions: <Button size="sm">New project</Button>,
   },
 };
+
+/**
+ * `as` picks the heading LEVEL, never the size — the title renders at
+ * `text-title` for every value. Reach for `as="h1"` when this header titles the
+ * page itself; a screen whose highest heading is an `<h2>` has no document
+ * outline root at all (WCAG 1.3.1).
+ */
+export const PageTitle: Story = {
+  args: {
+    eyebrow: "Workspace",
+    as: "h1",
+    title: "Projects",
+    description: "The page’s own title, so it owns the h1.",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // Resolve BY ROLE AND LEVEL: `getByText` would find the same node whatever
+    // tag it rendered as, so it could not tell an <h1> from the <h2> default.
+    const h1 = canvas.getByRole("heading", { level: 1, name: "Projects" });
+    await expect(h1.tagName).toBe("H1");
+    // The visual is unchanged by the level — that is the whole point of the
+    // prop, and the reason nobody should reach for it to get a bigger title.
+    await expect(h1.classList.contains("text-title")).toBe(true);
+  },
+};
+
+/** The default is still `<h2>`, so every existing caller is untouched. */
+export const DefaultLevelIsH2: Story = {
+  args: { title: "Projects" },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const heading = canvas.getByRole("heading", { name: "Projects" });
+    await expect(heading.tagName).toBe("H2");
+    await expect(canvas.queryByRole("heading", { level: 1 })).toBeNull();
+  },
+};

package/src/components/section-header/section-header.tsx

@@ -8,6 +8,16 @@ export interface SectionHeaderProps {
   actions?: ReactNode;
   /** Optional element rendered above the title (eyebrow / breadcrumbs). */
   eyebrow?: ReactNode;
+  /**
+   * The heading LEVEL the title contributes to the document outline. The
+   * visual (`text-title`) is identical for every value — pick the level the
+   * page's structure calls for, not the size you want (WCAG 1.3.1).
+   *
+   * Use `as="h1"` when this header titles the PAGE (a screen whose route it
+   * names); leave it at the default when it titles a section INSIDE a page
+   * that already has an `<h1>` elsewhere. @default "h2"
+   */
+  as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
   className?: string;
 }
 
@@ -17,6 +27,7 @@ export function SectionHeader({
   description,
   actions,
   eyebrow,
+  as: TitleTag = "h2",
   className,
 }: SectionHeaderProps) {
   return (
@@ -27,7 +38,7 @@ export function SectionHeader({
             {eyebrow}
           </div>
         ) : null}
-        <h2 className="text-title text-foreground">{title}</h2>
+        <TitleTag className="text-title text-foreground">{title}</TitleTag>
         {description ? <p className="text-sm text-muted-foreground">{description}</p> : null}
       </div>
       {actions ? <div className="flex items-center gap-2">{actions}</div> : null}

package/src/components/select/select.tsx

@@ -123,11 +123,15 @@ export const SelectTrigger = forwardRef<
       className={cn(
         "flex w-full items-center justify-between gap-2 rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm",
         size === "sm" ? "h-8" : "h-9",
-        "placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-1 focus:ring-offset-background",
+        "placeholder:text-muted-foreground focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
         // No `disabled:cursor-*` override — disabled controls keep the arrow
         // automatically (interaction-guidelines.md), matching Combobox's
         // Button-based trigger (`disabled:pointer-events-none`) (#343).
-        "disabled:opacity-50 disabled:border-border [&>span]:line-clamp-1",
+        // `truncate`, not `line-clamp-1`: a clamp only prints its ellipsis when it has
+        // dropped a LINE, so a single-line value too wide for a narrow trigger was cut
+        // mid-word with no ellipsis at all ("Occurren"). `autoTitle` above puts the full
+        // text in the tooltip, so the ellipsis is the visible half of that pair.
+        "disabled:opacity-50 disabled:border-border [&>span]:truncate",
         className,
       )}
       {...props}

package/src/components/sheet/sheet.tsx

@@ -66,7 +66,7 @@ export const SheetContent = forwardRef<
       >
         {children}
         <SheetPrimitive.Close
-          className="absolute end-4 top-4 rounded-sm opacity-70 transition-opacity hover:opacity-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          className="absolute end-4 top-4 rounded-sm opacity-70 transition-opacity hover:opacity-100 focus-ring"
           aria-label="Close"
         >
           <X className="size-4" />

package/src/components/side-dock/index.ts

@@ -0,0 +1 @@
+export { SideDock, type SideDockProps } from "./side-dock";

package/src/components/side-dock/side-dock.stories.tsx

@@ -0,0 +1,137 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
+
+import { SideDock } from "./side-dock";
+
+const meta = {
+  title: "Layout/SideDock",
+  component: SideDock,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "A summoned, resizable panel that docks to one edge of the content area — closed by default, opened by something the user does, resizable by pointer and keyboard, and rendered as an overlay `Sheet` below `overlayBreakpoint` (default 1100) instead of a fixed-width column. Unlike `ContextRail` (a persistent rail with a 48px icon collapsed state), `SideDock` has no persistent strip: closed means gone. See `docs/ADR/0035-context-rail-and-side-dock.md` §5.",
+      },
+    },
+  },
+} satisfies Meta<typeof SideDock>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const dockBody = <p className="text-body text-muted-foreground">Dock body content.</p>;
+
+/**
+ * Open, right-hand (the default `side`). The play function tabs from the
+ * close button to the resize handle, widens it twice with the keyboard
+ * (`ArrowLeft` on a right-hand dock), and asserts the CONTAINER's actual
+ * rendered width grew — a real layout measurement, not just the `aria-*`
+ * bookkeeping the unit tests already cover.
+ */
+export const Default: Story = {
+  render: () => (
+    <div className="flex h-[560px] w-full">
+      <div className="flex-1 bg-background p-6 text-muted-foreground">Canvas content</div>
+      <SideDock title="Assistant" open>
+        {dockBody}
+      </SideDock>
+    </div>
+  ),
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    const closeButton = canvas.getByRole("button", { name: "Close" });
+    const handle = canvas.getByRole("separator");
+    const container = canvasElement.querySelector(
+      '[data-slot="side-dock-container"]',
+    ) as HTMLElement;
+
+    await userEvent.tab();
+    await expect(closeButton).toHaveFocus();
+
+    /* The scroll port sits BETWEEN the two, and that is the point: a dock's
+     * children are caller-supplied and routinely have no focusable descendant,
+     * so before this stop existed a keyboard user could reach the close button
+     * and the resize handle but never the region that actually scrolls (WCAG
+     * 2.1.1, axe `scrollable-region-focusable`). `getAttribute`, not the
+     * `tabIndex` IDL getter, which reads -1 whether or not the attribute is
+     * there; and `classList`, because `toHaveClass` is a subset check that
+     * would pass with BOTH rungs applied — the inset rung is required here
+     * because the dock container clips anything drawn outside this box. */
+    const body = canvasElement.querySelector('[data-slot="side-dock-body"]') as HTMLElement;
+    await userEvent.tab();
+    await expect(body).toHaveFocus();
+    await expect(body.getAttribute("tabindex")).toBe("0");
+    await expect(body.classList.contains("focus-ring-inset")).toBe(true);
+    await expect(body.classList.contains("focus-ring")).toBe(false);
+
+    await userEvent.tab();
+    await expect(handle).toHaveFocus();
+
+    const before = container.getBoundingClientRect().width;
+    await userEvent.keyboard("{ArrowLeft}");
+    await userEvent.keyboard("{ArrowLeft}");
+
+    await waitFor(() => {
+      const after = container.getBoundingClientRect().width;
+      expect(after).toBeGreaterThan(before);
+    });
+  },
+};
+
+/** `open={false}` (the default) — collapsed, `inert`, off-screen; its body content stays mounted for the closing transition. */
+export const Closed: Story = {
+  render: () => (
+    <div className="flex h-[560px] w-full">
+      <div className="flex-1 bg-background p-6 text-muted-foreground">Canvas content</div>
+      <SideDock title="Assistant">{dockBody}</SideDock>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const root = canvasElement.querySelector('[data-slot="side-dock"]');
+    const container = canvasElement.querySelector('[data-slot="side-dock-container"]');
+    await expect(root).toHaveAttribute("data-state", "collapsed");
+    await expect(container).toHaveAttribute("inert");
+  },
+};
+
+/** `side="left"` — the handle sits on the trailing edge and the keyboard direction inverts (`ArrowRight` widens). */
+export const LeftHanded: Story = {
+  render: () => (
+    <div className="flex h-[560px] w-full">
+      <SideDock title="Assistant" open side="left">
+        {dockBody}
+      </SideDock>
+      <div className="flex-1 bg-background p-6 text-muted-foreground">Canvas content</div>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const handle = canvas.getByRole("separator");
+    await expect(handle).toHaveAttribute("aria-orientation", "vertical");
+  },
+};
+
+/**
+ * Below `overlayBreakpoint` the dock renders as an overlay `Sheet` instead of
+ * a column, with no resize handle. A very high `overlayBreakpoint` forces
+ * this branch deterministically under a headless run, mirroring
+ * `ContextRail`'s own `Narrow` story.
+ */
+export const Overlay: Story = {
+  render: () => (
+    <div className="flex h-[560px] w-full">
+      <div className="flex-1 bg-background p-6 text-muted-foreground">Canvas content</div>
+      <SideDock title="Assistant" open overlayBreakpoint={4000} description="A helper panel.">
+        {dockBody}
+      </SideDock>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const dialog = await waitFor(() => {
+      const el = document.querySelector('[role="dialog"]');
+      if (!el) throw new Error("overlay Sheet has not mounted yet");
+      return el;
+    });
+    await expect(dialog).toHaveAccessibleName("Assistant");
+    await expect(canvasElement.querySelector('[data-slot="side-dock-resize-handle"]')).toBeNull();
+  },
+};

package/src/components/side-dock/side-dock.test.tsx

@@ -0,0 +1,273 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { SideDock } from "./side-dock";
+
+/**
+ * Every test that wants the COLUMN branch passes `overlayBreakpoint={800}` —
+ * jsdom's `window.innerWidth` is 1024 and its stubbed `matchMedia` always
+ * reports `matches: false`, so the default `overlayBreakpoint` (1100) would
+ * render the OVERLAY branch in every test (see task-10-brief.md, Mechanism §2).
+ * The one test that wants the overlay branch passes `overlayBreakpoint={2000}`.
+ */
+const COLUMN_BREAKPOINT = 800;
+
+describe("SideDock", () => {
+  // 1. Names the region.
+  it("names the complementary region from `title`", () => {
+    render(
+      <SideDock title="Assistant" open overlayBreakpoint={COLUMN_BREAKPOINT}>
+        Body
+      </SideDock>,
+    );
+    expect(screen.getByRole("complementary")).toHaveAccessibleName("Assistant");
+  });
+
+  // 2. Names the handle and reports its value.
+  it("names the resize handle and reports its current value", () => {
+    render(
+      <SideDock title="Assistant" open overlayBreakpoint={COLUMN_BREAKPOINT}>
+        Body
+      </SideDock>,
+    );
+    const handle = screen.getByRole("separator");
+    expect(handle).toHaveAccessibleName("Resize Assistant");
+    expect(handle).toHaveAttribute("aria-orientation", "vertical");
+    expect(handle).toHaveAttribute("aria-valuenow", "400");
+    expect(handle).toHaveAttribute("aria-valuemin", "320");
+    expect(handle.getAttribute("aria-valuetext")).toContain("400 pixels");
+  });
+
+  // 3. Keyboard widens (right-hand dock: ArrowLeft widens).
+  it("widens on ArrowLeft and commits once on keyup", () => {
+    const onWidthChange = vi.fn();
+    const onWidthCommit = vi.fn();
+    render(
+      <SideDock
+        title="Assistant"
+        open
+        overlayBreakpoint={COLUMN_BREAKPOINT}
+        onWidthChange={onWidthChange}
+        onWidthCommit={onWidthCommit}
+      >
+        Body
+      </SideDock>,
+    );
+    const handle = screen.getByRole("separator");
+    handle.focus();
+    fireEvent.keyDown(handle, { key: "ArrowLeft" });
+    expect(onWidthChange).toHaveBeenCalledTimes(1);
+    const widened = onWidthChange.mock.calls[0]![0] as number;
+    expect(widened).toBeGreaterThan(400);
+    expect(onWidthCommit).not.toHaveBeenCalled();
+    fireEvent.keyUp(handle, { key: "ArrowLeft" });
+    expect(onWidthCommit).toHaveBeenCalledTimes(1);
+    expect(onWidthCommit).toHaveBeenCalledWith(widened);
+  });
+
+  // 4. Keyboard narrows; Home/End jump to the effective bounds.
+  // CORRECTED 2026-09-05 (Ruling 29): under these defaults (minContentWidth
+  // 480 against jsdom's 1024px viewport) the effective maximum is 544, not
+  // maxWidth (640) — see clampWidth's viewport term.
+  it("narrows on ArrowRight and End jumps to the effective maximum (544, not maxWidth)", () => {
+    render(
+      <SideDock title="Assistant" open overlayBreakpoint={COLUMN_BREAKPOINT}>
+        Body
+      </SideDock>,
+    );
+    const handle = screen.getByRole("separator");
+    handle.focus();
+    fireEvent.keyDown(handle, { key: "ArrowRight" });
+    fireEvent.keyUp(handle, { key: "ArrowRight" });
+    expect(handle).toHaveAttribute("aria-valuenow", "384");
+    fireEvent.keyDown(handle, { key: "End" });
+    fireEvent.keyUp(handle, { key: "End" });
+    expect(handle).toHaveAttribute("aria-valuenow", "544");
+  });
+
+  // 5. A no-op is silent.
+  it("fires no callback and leaves the value unchanged when the narrowing key is a no-op at minWidth", () => {
+    const onWidthChange = vi.fn();
+    const onWidthCommit = vi.fn();
+    render(
+      <SideDock
+        title="Assistant"
+        open
+        overlayBreakpoint={COLUMN_BREAKPOINT}
+        width={320}
+        minWidth={320}
+        onWidthChange={onWidthChange}
+        onWidthCommit={onWidthCommit}
+      >
+        Body
+      </SideDock>,
+    );
+    const handle = screen.getByRole("separator");
+    handle.focus();
+    fireEvent.keyDown(handle, { key: "ArrowRight" });
+    fireEvent.keyUp(handle, { key: "ArrowRight" });
+    expect(onWidthChange).not.toHaveBeenCalled();
+    expect(onWidthCommit).not.toHaveBeenCalled();
+    expect(handle).toHaveAttribute("aria-valuenow", "320");
+  });
+
+  // 6. A controlled out-of-range width converges (maxWidth as the sole
+  // upper bound — minContentWidth={0} zeroes the viewport bound, per
+  // Ruling 29; assertion 7 below is what covers the viewport bound).
+  it("converges a controlled width above maxWidth, emitting each callback once", () => {
+    const onWidthChange = vi.fn();
+    const onWidthCommit = vi.fn();
+    render(
+      <SideDock
+        title="Assistant"
+        open
+        overlayBreakpoint={COLUMN_BREAKPOINT}
+        width={9999}
+        maxWidth={640}
+        minContentWidth={0}
+        onWidthChange={onWidthChange}
+        onWidthCommit={onWidthCommit}
+      >
+        Body
+      </SideDock>,
+    );
+    expect(screen.getByRole("separator")).toHaveAttribute("aria-valuenow", "640");
+    expect(onWidthChange).toHaveBeenCalledTimes(1);
+    expect(onWidthChange).toHaveBeenCalledWith(640);
+    expect(onWidthCommit).toHaveBeenCalledTimes(1);
+    expect(onWidthCommit).toHaveBeenCalledWith(640);
+  });
+
+  // 7. minContentWidth binds against the live viewport.
+  it("binds minContentWidth against jsdom's 1024px viewport", () => {
+    render(
+      <SideDock
+        title="Assistant"
+        open
+        overlayBreakpoint={COLUMN_BREAKPOINT}
+        width={640}
+        minContentWidth={480}
+      >
+        Body
+      </SideDock>,
+    );
+    expect(screen.getByRole("separator")).toHaveAttribute("aria-valuenow", "544");
+  });
+
+  // 8. Uncontrolled default is closed.
+  // `data-state` lives on the GROUP element per task-10-brief.md Mechanism §1
+  // ("attrs ... goes on the group element that wraps both fragments" —
+  // mirrors Sidebar, which puts `data-state` on `data-slot="sidebar"`, never
+  // on `sidebar-container`); `inert` is the CONTAINER's own attribute (the
+  // fixed contract's "the collapsed container is inert").
+  it("is closed by default, inert, with its body content still mounted", () => {
+    render(
+      <SideDock title="Assistant" overlayBreakpoint={COLUMN_BREAKPOINT}>
+        Body content
+      </SideDock>,
+    );
+    const root = document.querySelector('[data-slot="side-dock"]');
+    const container = document.querySelector('[data-slot="side-dock-container"]');
+    expect(root).toHaveAttribute("data-state", "collapsed");
+    // jsdom does not implement the `.inert` IDL property (it reads back
+    // `undefined` even when the attribute is present) — assert the
+    // ATTRIBUTE, which is what React 19 actually renders for `inert={true}`.
+    expect(container).toHaveAttribute("inert");
+    expect(screen.getByText("Body content")).toBeInTheDocument();
+  });
+
+  // 9. The close control closes it.
+  it("closes on clicking the close button", () => {
+    const onOpenChange = vi.fn();
+    render(
+      <SideDock
+        title="Assistant"
+        defaultOpen
+        overlayBreakpoint={COLUMN_BREAKPOINT}
+        onOpenChange={onOpenChange}
+      >
+        Body
+      </SideDock>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Close" }));
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+    const root = document.querySelector('[data-slot="side-dock"]');
+    expect(root).toHaveAttribute("data-state", "collapsed");
+  });
+
+  // 10. The overlay branch.
+  it("renders as an overlay Sheet below overlayBreakpoint, with no resize handle", () => {
+    render(
+      <SideDock title="Assistant" open overlayBreakpoint={2000} description="A helper panel.">
+        Body
+      </SideDock>,
+    );
+    const dialog = screen.getByRole("dialog");
+    expect(dialog).toHaveAccessibleName("Assistant");
+    expect(screen.queryByRole("separator")).not.toBeInTheDocument();
+    expect(screen.getByText("A helper panel.")).toBeInTheDocument();
+  });
+
+  // 11. side="left" inverts the keyboard direction.
+  it("inverts ArrowRight to widen on a left-hand dock", () => {
+    const onWidthChange = vi.fn();
+    render(
+      <SideDock
+        title="Assistant"
+        open
+        side="left"
+        overlayBreakpoint={COLUMN_BREAKPOINT}
+        onWidthChange={onWidthChange}
+      >
+        Body
+      </SideDock>,
+    );
+    const handle = screen.getByRole("separator");
+    handle.focus();
+    fireEvent.keyDown(handle, { key: "ArrowRight" });
+    expect(onWidthChange).toHaveBeenCalledTimes(1);
+    expect(onWidthChange.mock.calls[0]![0] as number).toBeGreaterThan(400);
+  });
+
+  // 12. Finding 2 (task-11f-brief.md): `inert={!panel.open}` on the column
+  // `<aside>` means, per the HTML focus-fixup rule, that a focused
+  // descendant (the close button) loses focus the instant the close click
+  // makes the container inert — the browser's default is to drop focus to
+  // `<body>`. This asserts the repair: closing via keyboard/click restores
+  // focus to whatever opened the dock, and explicitly never to `<body>`.
+  it("restores focus to the opener when the close button closes the dock", () => {
+    function Harness() {
+      const [open, setOpen] = useState(false);
+      return (
+        <>
+          <button type="button" onClick={() => setOpen(true)}>
+            Open dock
+          </button>
+          <SideDock
+            title="Assistant"
+            open={open}
+            onOpenChange={setOpen}
+            overlayBreakpoint={COLUMN_BREAKPOINT}
+          >
+            Body
+          </SideDock>
+        </>
+      );
+    }
+    render(<Harness />);
+
+    const trigger = screen.getByRole("button", { name: "Open dock" });
+    trigger.focus();
+    expect(document.activeElement).toBe(trigger);
+
+    fireEvent.click(trigger);
+    const closeButton = screen.getByRole("button", { name: "Close" });
+    closeButton.focus();
+    expect(document.activeElement).toBe(closeButton);
+
+    fireEvent.click(closeButton);
+
+    expect(document.activeElement).not.toBe(document.body);
+    expect(document.activeElement).toBe(trigger);
+  });
+});