@elabs-ai/components-ui 4.0.0 → 4.2.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,18 +27,19 @@ export function SectionHeader({
   description,
   actions,
   eyebrow,
+  as: TitleTag = "h2",
   className,
 }: SectionHeaderProps) {
   return (
     <div className={cn("flex flex-wrap items-end justify-between gap-4", className)}>
       <div className="space-y-1">
         {eyebrow ? (
-          <div className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+          <div className="text-meta font-medium uppercase tracking-wide text-muted-foreground">
             {eyebrow}
           </div>
         ) : null}
-        <h2 className="text-title text-foreground">{title}</h2>
-        {description ? <p className="text-sm text-muted-foreground">{description}</p> : null}
+        <TitleTag className="text-title text-foreground">{title}</TitleTag>
+        {description ? <p className="text-body text-muted-foreground">{description}</p> : null}
       </div>
       {actions ? <div className="flex items-center gap-2">{actions}</div> : null}
     </div>

package/src/components/select/select.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   forwardRef,
   useEffect,
@@ -121,13 +123,17 @@ export const SelectTrigger = forwardRef<
       data-size={size}
       title={title}
       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",
+        "flex w-full items-center justify-between gap-2 rounded-control border border-input bg-input-background px-3 py-2 text-body shadow-input",
+        size === "sm" ? "h-control-sm" : "h-control",
+        "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}
@@ -150,7 +156,7 @@ export const SelectContent = forwardRef<
         ref={ref}
         position={position}
         className={cn(
-          "relative z-50 max-h-96 min-w-[8rem] overflow-hidden rounded-md bg-popover text-popover-foreground shadow-ring-md",
+          "relative z-50 max-h-96 min-w-[12rem] overflow-hidden rounded-md bg-popover text-popover-foreground shadow-ring-md",
           "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95",
           "data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2",
           position === "popper" &&
@@ -186,7 +192,7 @@ export const SelectLabel = forwardRef<
   return (
     <SelectPrimitive.Label
       ref={ref}
-      className={cn("px-2 py-1.5 text-xs font-semibold text-muted-foreground", className)}
+      className={cn("px-2 py-1.5 text-meta font-semibold text-muted-foreground", className)}
       {...props}
     />
   );
@@ -200,7 +206,7 @@ export const SelectItem = forwardRef<
     <SelectPrimitive.Item
       ref={ref}
       className={cn(
-        "relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 ps-2 pe-8 text-sm outline-none transition-colors duration-fast",
+        "relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 ps-2 pe-8 text-body outline-none transition-colors duration-fast",
         "focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
         className,
       )}

package/src/components/separator/separator.tsx

@@ -37,6 +37,7 @@ export const Separator = forwardRef<ElementRef<typeof SeparatorPrimitive.Root>,
     return (
       <SeparatorPrimitive.Root
         ref={ref}
+        data-slot="separator"
         decorative={decorative}
         orientation={orientation}
         className={cn(

package/src/components/sheet/sheet.test.tsx

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from "./sheet";
+
+describe("SheetContent overflow", () => {
+  it("scrolls tall content instead of overflowing the fixed panel", () => {
+    render(
+      <Sheet open>
+        <SheetContent>
+          <SheetHeader>
+            <SheetTitle>Title</SheetTitle>
+            <SheetDescription>Description</SheetDescription>
+          </SheetHeader>
+          Body
+        </SheetContent>
+      </Sheet>,
+    );
+    const content = screen.getByRole("dialog");
+    // Without `overflow-y-auto`, content taller than the panel overflows the
+    // fixed-position box and its bottom half is unreachable.
+    expect(content.className).toContain("overflow-y-auto");
+  });
+
+  it("caps top/bottom sheets at a viewport-relative height so the scroll rule engages", () => {
+    render(
+      <Sheet open>
+        <SheetContent side="bottom">
+          <SheetHeader>
+            <SheetTitle>Title</SheetTitle>
+            <SheetDescription>Description</SheetDescription>
+          </SheetHeader>
+          Body
+        </SheetContent>
+      </Sheet>,
+    );
+    const content = screen.getByRole("dialog");
+    expect(content.className).toContain("max-h-[90dvh]");
+  });
+});

package/src/components/sheet/sheet.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   forwardRef,
   type ComponentPropsWithoutRef,
@@ -8,6 +10,7 @@ import * as SheetPrimitive from "@radix-ui/react-dialog";
 import { cva, type VariantProps } from "class-variance-authority";
 import { X } from "lucide-react";
 import { cn } from "../../lib/cn";
+import { useLocale } from "../locale-provider";
 
 export const Sheet = SheetPrimitive.Root;
 export const SheetTrigger = SheetPrimitive.Trigger;
@@ -21,8 +24,9 @@ const SheetOverlay = forwardRef<
   return (
     <SheetPrimitive.Overlay
       ref={ref}
+      data-slot="sheet-overlay"
       className={cn(
-        "fixed inset-0 z-50 bg-foreground/50 backdrop-blur-sm data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+        "fixed inset-0 z-50 bg-overlay backdrop-blur-overlay data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
         className,
       )}
       {...props}
@@ -31,13 +35,23 @@ const SheetOverlay = forwardRef<
 });
 
 const sheetVariants = cva(
-  "fixed z-50 gap-4 overscroll-contain bg-card p-6 text-card-foreground shadow-ring-lg transition duration-slow ease-standard data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=open]:[--tw-ease:var(--ease-entrance)] data-[state=closed]:[--tw-ease:var(--ease-exit)]",
+  // `overflow-y-auto` so content taller than the sheet scrolls INSIDE it
+  // instead of overflowing the fixed-position box (unreachable below the
+  // viewport edge).
+  "fixed z-50 gap-4 overflow-y-auto overscroll-contain bg-card p-6 text-card-foreground shadow-ring-lg transition duration-slow ease-standard data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=open]:[--tw-ease:var(--ease-entrance)] data-[state=closed]:[--tw-ease:var(--ease-exit)]",
   {
     variants: {
       side: {
-        top: "inset-x-0 top-0 border-b data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top",
+        // `top`/`bottom` have no inherent height ceiling, so long content grows
+        // past the viewport; cap it at 90dvh (matching Dialog's dvh unit — ADR
+        // on mobile browser chrome) so the scroll rule above actually engages.
+        top: "inset-x-0 top-0 max-h-[90dvh] border-b data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top",
         bottom:
-          "inset-x-0 bottom-0 border-t data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom",
+          "inset-x-0 bottom-0 max-h-[90dvh] border-t data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom",
+        // `side` is an explicit physical edge of the screen (like Radix's own
+        // Popper `side`), not a logical start/end — a caller who picks `"left"`
+        // wants the panel on the physical left even in an RTL layout, so these
+        // stay physical `left-0`/`right-0` and `border-r`/`border-l` on purpose.
         left: "inset-y-0 left-0 h-full w-3/4 max-w-sm border-r data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left",
         right:
           "inset-y-0 right-0 h-full w-3/4 max-w-sm border-l data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right",
@@ -56,18 +70,24 @@ export const SheetContent = forwardRef<
   ElementRef<typeof SheetPrimitive.Content>,
   SheetContentProps
 >(function SheetContent({ side = "right", className, children, ...props }, ref) {
+  const { t } = useLocale();
   return (
     <SheetPortal>
       <SheetOverlay />
       <SheetPrimitive.Content
         ref={ref}
+        data-slot="sheet-content"
         className={cn(sheetVariants({ side }), className)}
         {...props}
       >
         {children}
+        {/* Matches Dialog's close button exactly (radius, padding, ink,
+            opacity choreography) — a 24px target (`p-1` + the 16px glyph)
+            instead of the previous bare 16px hit area (#286). */}
         <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"
-          aria-label="Close"
+          data-slot="sheet-close"
+          className="absolute end-4 top-4 rounded-md p-1 text-muted-foreground opacity-70 transition-opacity hover:opacity-100 focus-ring"
+          aria-label={t("close")}
         >
           <X className="size-4" />
         </SheetPrimitive.Close>
@@ -77,11 +97,14 @@ export const SheetContent = forwardRef<
 });
 
 export function SheetHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn("flex flex-col gap-1.5", className)} {...props} />;
+  return (
+    <div data-slot="sheet-header" className={cn("flex flex-col gap-1.5", className)} {...props} />
+  );
 }
 export function SheetFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
   return (
     <div
+      data-slot="sheet-footer"
       className={cn("mt-auto flex flex-col-reverse gap-2 sm:flex-row sm:justify-end", className)}
       {...props}
     />
@@ -92,7 +115,14 @@ export const SheetTitle = forwardRef<
   ComponentPropsWithoutRef<typeof SheetPrimitive.Title>
 >(function SheetTitle({ className, ...props }, ref) {
   return (
-    <SheetPrimitive.Title ref={ref} className={cn("text-lg font-semibold", className)} {...props} />
+    // `text-title`, matching `DialogTitle` (#286) — was `text-lg font-semibold`,
+    // one rung below Dialog's for the same anatomical role (a modal title).
+    <SheetPrimitive.Title
+      ref={ref}
+      data-slot="sheet-title"
+      className={cn("text-title leading-none", className)}
+      {...props}
+    />
   );
 });
 export const SheetDescription = forwardRef<
@@ -102,7 +132,8 @@ export const SheetDescription = forwardRef<
   return (
     <SheetPrimitive.Description
       ref={ref}
-      className={cn("text-sm text-muted-foreground", className)}
+      data-slot="sheet-description"
+      className={cn("text-body text-muted-foreground", className)}
       {...props}
     />
   );

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();
+  },
+};