@elabs-ai/components-ui 4.1.0 → 5.0.0

package/src/components/scroll-area/index.ts

@@ -1 +1 @@
-export { ScrollArea, ScrollBar } from "./scroll-area";
+export { ScrollArea, ScrollBar, type ScrollAreaProps } from "./scroll-area";

package/src/components/scroll-area/scroll-area.tsx

@@ -2,24 +2,53 @@ import { forwardRef, type ComponentPropsWithoutRef, type ElementRef } from "reac
 import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area";
 import { cn } from "../../lib/cn";
 
-export const ScrollArea = forwardRef<
-  ElementRef<typeof ScrollAreaPrimitive.Root>,
-  ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root>
->(function ScrollArea({ className, children, ...props }, ref) {
-  return (
-    <ScrollAreaPrimitive.Root
-      ref={ref}
-      className={cn("relative overflow-hidden", className)}
-      {...props}
-    >
-      <ScrollAreaPrimitive.Viewport className="size-full rounded-[inherit]">
-        {children}
-      </ScrollAreaPrimitive.Viewport>
-      <ScrollBar />
-      <ScrollAreaPrimitive.Corner />
-    </ScrollAreaPrimitive.Root>
-  );
-});
+export interface ScrollAreaProps extends ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root> {
+  /**
+   * Props for the scrolling VIEWPORT — the element that actually overflows, which is
+   * otherwise unreachable from the outside.
+   *
+   * The viewport is deliberately NOT focusable by default: when the content inside it is
+   * focusable (a list of links, rows of buttons) a keyboard user reaches the overflow by
+   * tabbing through it, and a tab stop on the viewport would be noise. When the content is
+   * plain text or non-focusable rows, that same user cannot scroll it at all — axe's
+   * `scrollable-region-focusable` is the gate that catches it. Make it a named tab stop the
+   * way `ChartFrame` does for its scrolling body:
+   *
+   * ```tsx
+   * viewportProps={{ tabIndex: 0, role: "group", "aria-label": "Scrollable list" }}
+   * ```
+   *
+   * `role="group"` rather than `"region"`: ARIA 1.2 forbids `aria-label` on a generic
+   * element, and `group` gives the name a host without adding a landmark.
+   */
+  viewportProps?: ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Viewport>;
+}
+
+export const ScrollArea = forwardRef<ElementRef<typeof ScrollAreaPrimitive.Root>, ScrollAreaProps>(
+  function ScrollArea({ className, children, viewportProps, ...props }, ref) {
+    return (
+      <ScrollAreaPrimitive.Root
+        ref={ref}
+        className={cn("relative overflow-hidden", className)}
+        {...props}
+      >
+        <ScrollAreaPrimitive.Viewport
+          {...viewportProps}
+          className={cn(
+            "size-full rounded-[inherit]",
+            // A viewport made focusable needs a visible ring, like every other tab stop.
+            viewportProps?.tabIndex !== undefined && "focus-ring-inset",
+            viewportProps?.className,
+          )}
+        >
+          {children}
+        </ScrollAreaPrimitive.Viewport>
+        <ScrollBar />
+        <ScrollAreaPrimitive.Corner />
+      </ScrollAreaPrimitive.Root>
+    );
+  },
+);
 
 export const ScrollBar = forwardRef<
   ElementRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>,

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

@@ -34,12 +34,10 @@ export function SectionHeader({
     <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">
-            {eyebrow}
-          </div>
+          <div className="text-eyebrow uppercase text-muted-foreground">{eyebrow}</div>
         ) : null}
         <TitleTag className="text-title text-foreground">{title}</TitleTag>
-        {description ? <p className="text-sm text-muted-foreground">{description}</p> : null}
+        {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.stories.tsx

@@ -36,6 +36,23 @@ export const Default: Story = {
   },
 };
 
+// WCAG 1.4.11 keyboard-focus contrast (#308) for `SelectItem` is locked in
+// `select.test.tsx`, not here: a Storybook interaction story that opens this
+// `Select` and then either closes it (any method — Escape, `{Enter}`, or a
+// click) or leaves it open trips one of two PRE-EXISTING, unrelated axe
+// violations in this test environment on any story id not already
+// grandfathered into `scripts/a11y-baseline.json` — closing hits the same
+// `button-name` false-positive `forms-select--default` is already exempted
+// for (reproduced verbatim by a throwaway story that just re-runs `Default`'s
+// own play function under a new id), and leaving it open hits
+// `aria-hidden-focus` (reproduced even with `modal={false}`). Growing the
+// a11y baseline for a new story is exactly what `pnpm check --rule
+// a11y-baseline`'s ratchet forbids (`ratchet.maxStories` only goes down), so
+// rather than force a hand-baselined exemption for a defect this change did
+// not introduce, the keyboard-focus-ring assertion for `SelectItem` lives in
+// a plain RTL unit test instead (no axe gate there), matching the existing
+// `icon-button.test.tsx` precedent of asserting the utility class directly.
+
 const LONG_LABEL = "prod-eu-west-1 · 2026-08-01 · 12 tools";
 
 /**

package/src/components/select/select.test.tsx

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it } from "vitest";
 import { render, screen, waitFor } from "@testing-library/react";
-import { Select, SelectTrigger, SelectValue } from "./select";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "./select";
 
 const LONG_LABEL = "prod-eu-west-1 · 2026-08-01 · 12 tools";
 
@@ -96,3 +96,30 @@ describe("SelectTrigger", () => {
     expect(trigger).not.toHaveAttribute("title");
   });
 });
+
+describe("SelectItem", () => {
+  // WCAG 1.4.11 (#308): a `focus:bg-accent` fill alone measures ~1.17–1.40:1
+  // against `--popover` in both themes — not a visible indicator. A real RTL
+  // unit test rather than a Storybook interaction story: opening this Select
+  // in the Storybook/vitest-browser + axe harness hits a PRE-EXISTING,
+  // unrelated `button-name`/`aria-hidden-focus` axe defect on any story id not
+  // already grandfathered into `scripts/a11y-baseline.json` (see the comment
+  // in `select.stories.tsx`), so the utility-class assertion — the same
+  // pattern `icon-button.test.tsx` already uses for its own `focus-ring` —
+  // lives here instead, with no axe gate to trip.
+  it("carries focus-ring-inset, not just the fill, on the fill-only focus state (#308)", () => {
+    render(
+      <Select defaultValue="prod" open>
+        <SelectTrigger aria-label="Environment">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="prod">Production</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+    const item = screen.getByRole("option", { name: "Production" });
+    expect(item.className).toContain("focus:bg-accent");
+    expect(item.className).toContain("focus-ring-inset");
+  });
+});

package/src/components/select/select.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   forwardRef,
   useEffect,
@@ -121,9 +123,9 @@ 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-ring focus-visible:ring-offset-1 focus-visible: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 focus-visible:border-input-focus",
         // No `disabled:cursor-*` override — disabled controls keep the arrow
         // automatically (interaction-guidelines.md), matching Combobox's
         // Button-based trigger (`disabled:pointer-events-none`) (#343).
@@ -154,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-popover",
           "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" &&
@@ -190,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}
     />
   );
@@ -204,8 +206,8 @@ 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",
-        "focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+        "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 focus-ring-inset data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
         className,
       )}
       {...props}

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-dialog 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-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/side-dock.stories.tsx

@@ -1,6 +1,15 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { expect, waitFor } from "storybook/test";
 
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarProvider,
+} from "../sidebar";
 import { SideDock } from "./side-dock";
 
 const meta = {
@@ -135,3 +144,77 @@ export const Overlay: Story = {
     await expect(canvasElement.querySelector('[data-slot="side-dock-resize-handle"]')).toBeNull();
   },
 };
+
+/**
+ * `containerPosition="inset"` (#432): nested inside a `Sidebar` + `SidebarInset`
+ * host layout — mirroring the real composition (`DashboardAssetPanel` on the
+ * left, `DashboardPropertiesPanel` on the right of a sheet inside an app
+ * `Sidebar`) — `side="left"` would otherwise race the Sidebar's own `fixed
+ * left-0` container for the SAME viewport edge — the later-mounted dock wins
+ * the paint and hides the app's own nav (`wave-4-review-visual.md` P0-1). The
+ * play function proves the fix geometrically for BOTH edges: the Sidebar's
+ * nav stays visible, and neither dock's rect ever intersects the Sidebar's or
+ * the canvas's.
+ */
+export const InSidebar: Story = {
+  render: () => (
+    <SidebarProvider>
+      <Sidebar>
+        <SidebarContent>
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <SidebarMenuButton isActive>Dashboards</SidebarMenuButton>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarContent>
+      </Sidebar>
+      <SidebarInset className="min-w-0">
+        <div className="flex h-[560px] min-w-0 flex-1">
+          <SideDock title="Assets" open side="left" containerPosition="inset">
+            {dockBody}
+          </SideDock>
+          <div
+            data-testid="canvas"
+            className="min-w-0 flex-1 bg-background p-6 text-muted-foreground"
+          >
+            Canvas content
+          </div>
+          <SideDock title="Properties" open side="right" containerPosition="inset">
+            {dockBody}
+          </SideDock>
+        </div>
+      </SidebarInset>
+    </SidebarProvider>
+  ),
+  play: async ({ canvas, canvasElement }) => {
+    const nav = await canvas.findByRole("button", { name: "Dashboards" });
+    await expect(nav).toBeVisible();
+
+    const sidebar = canvasElement.querySelector('[data-slot="sidebar-container"]') as HTMLElement;
+    const docks = canvasElement.querySelectorAll('[data-slot="side-dock-container"]');
+    const leftDock = docks[0] as HTMLElement;
+    const rightDock = docks[1] as HTMLElement;
+    const dockCanvas = canvas.getByTestId("canvas");
+
+    const sidebarRect = sidebar.getBoundingClientRect();
+    const leftDockRect = leftDock.getBoundingClientRect();
+    const rightDockRect = rightDock.getBoundingClientRect();
+    const canvasRect = dockCanvas.getBoundingClientRect();
+    const viewport = canvasElement.getBoundingClientRect();
+
+    const intersects = (a: DOMRect, b: DOMRect) =>
+      a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom;
+
+    // The Sidebar and the left dock never intersect.
+    await expect(intersects(sidebarRect, leftDockRect)).toBe(false);
+    // The left dock starts exactly where the Sidebar ends...
+    await expect(leftDockRect.left).toBeGreaterThanOrEqual(sidebarRect.right);
+    // ...and the canvas starts exactly where the left dock ends (no dead gap).
+    await expect(Math.abs(canvasRect.left - leftDockRect.right)).toBeLessThanOrEqual(1);
+
+    // The right dock never intersects the canvas, and stays inside the viewport.
+    await expect(intersects(rightDockRect, canvasRect)).toBe(false);
+    await expect(rightDockRect.right).toBeLessThanOrEqual(viewport.right + 1);
+    await expect(rightDockRect.left).toBeGreaterThanOrEqual(viewport.left - 1);
+  },
+};

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

@@ -270,4 +270,30 @@ describe("SideDock", () => {
     expect(document.activeElement).not.toBe(document.body);
     expect(document.activeElement).toBe(trigger);
   });
+
+  it("coalesces a burst of resize events into one rAF-scheduled update", () => {
+    const rafCallbacks: FrameRequestCallback[] = [];
+    const rafSpy = vi
+      .spyOn(window, "requestAnimationFrame")
+      .mockImplementation((cb: FrameRequestCallback) => {
+        rafCallbacks.push(cb);
+        return rafCallbacks.length;
+      });
+
+    render(
+      <SideDock title="Assistant" open overlayBreakpoint={COLUMN_BREAKPOINT}>
+        Body
+      </SideDock>,
+    );
+    rafCallbacks.length = 0; // clear anything scheduled at mount
+
+    // A window drag fires `resize` many times per frame — every one of these
+    // must coalesce into a SINGLE scheduled frame, not one per event.
+    fireEvent(window, new Event("resize"));
+    fireEvent(window, new Event("resize"));
+    fireEvent(window, new Event("resize"));
+    expect(rafCallbacks).toHaveLength(1);
+
+    rafSpy.mockRestore();
+  });
 });

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

@@ -31,7 +31,7 @@ import { X } from "lucide-react";
 import { cn } from "../../lib/cn";
 import { mergeRefs } from "../../lib/merge-refs";
 import { useIsMobile } from "../../lib/use-mobile";
-import { useCollapsiblePanel } from "../collapsible-panel";
+import { useCollapsiblePanel, type CollapsiblePanelContainerPosition } from "../collapsible-panel";
 import { useLocale } from "../locale-provider/locale-provider";
 import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from "../sheet";
 
@@ -44,9 +44,10 @@ export interface SideDockProps extends Omit<ComponentProps<"aside">, "title"> {
    */
   title: ReactNode;
   /**
-   * Optional longer description. Visible under the title in the column
-   * presentation; `sr-only` in the overlay presentation (the compact sheet
-   * header has no room for it, but it still reaches assistive tech).
+   * Optional longer description. Visible at the top of the body in the column
+   * presentation — never inside the header band, which is fixed at the app
+   * shell's header height; `sr-only` in the overlay presentation (the compact
+   * sheet header has no room for it, but it still reaches assistive tech).
    */
   description?: ReactNode;
   /** Optional controls placed in the header row beside the built-in close button. */
@@ -62,6 +63,18 @@ export interface SideDockProps extends Omit<ComponentProps<"aside">, "title"> {
   /** Which edge it docks to. Default `"right"`. */
   side?: "left" | "right";
 
+  /**
+   * Where the column presentation's fixed/absolute container positions
+   * itself. Default `"viewport"` (pins to the viewport edge — byte-identical
+   * pre-#432 behavior). `"inset"` pins to the dock's OWN position in the
+   * layout instead (`absolute` against a `relative` wrapper this component
+   * provides) — use this when the dock is nested inside another element that
+   * already pins itself to the same viewport edge (e.g. an app `Sidebar`),
+   * so the two never race for the same edge (#432). Has no effect on the
+   * overlay `Sheet` presentation below `overlayBreakpoint`.
+   */
+  containerPosition?: CollapsiblePanelContainerPosition;
+
   /**
    * `width`, `defaultWidth`, `minWidth`, `maxWidth`, `minContentWidth` and
    * `resizable` (below) govern the COLUMN presentation only — viewport at or
@@ -135,6 +148,7 @@ export const SideDock = forwardRef<HTMLElement, SideDockProps>(function SideDock
     defaultOpen = false,
     onOpenChange,
     side = "right",
+    containerPosition = "viewport",
     width,
     defaultWidth = DEFAULT_WIDTH,
     onWidthChange,
@@ -155,7 +169,7 @@ export const SideDock = forwardRef<HTMLElement, SideDockProps>(function SideDock
   const titleId = useId();
   const resizeLabelId = useId();
 
-  const panel = useCollapsiblePanel({ side, open, defaultOpen, onOpenChange });
+  const panel = useCollapsiblePanel({ side, open, defaultOpen, onOpenChange, containerPosition });
   const isOverlay = useIsMobile(overlayBreakpoint);
 
   // Focus restoration for the COLUMN presentation only (Finding 2,
@@ -212,13 +226,28 @@ export const SideDock = forwardRef<HTMLElement, SideDockProps>(function SideDock
 
   // The live viewport width the clamp reads — `useIsMobile` only exposes a
   // boolean threshold, not the pixel value clamping needs.
-  const [viewportWidth, setViewportWidth] = useState<number>(() =>
-    typeof window !== "undefined" ? window.innerWidth : FALLBACK_VIEWPORT_WIDTH,
-  );
+  // Starts at the fallback on the server AND on the client's first render, then reads the real
+  // width on mount: a lazy `window.innerWidth` initialiser made the first client render differ
+  // from the server HTML (`aria-valuemax`), which React reports as a hydration mismatch.
+  const [viewportWidth, setViewportWidth] = useState<number>(FALLBACK_VIEWPORT_WIDTH);
   useEffect(() => {
-    const onResize = () => setViewportWidth(window.innerWidth);
+    setViewportWidth(window.innerWidth);
+    // `resize` can fire dozens of times per second while a window is being
+    // dragged — coalesce every event inside one frame into a single state
+    // update via rAF, instead of re-rendering on each raw event.
+    let rafId: number | null = null;
+    const onResize = () => {
+      if (rafId !== null) return;
+      rafId = requestAnimationFrame(() => {
+        rafId = null;
+        setViewportWidth(window.innerWidth);
+      });
+    };
     window.addEventListener("resize", onResize);
-    return () => window.removeEventListener("resize", onResize);
+    return () => {
+      window.removeEventListener("resize", onResize);
+      if (rafId !== null) cancelAnimationFrame(rafId);
+    };
   }, []);
 
   const isWidthControlled = width !== undefined;
@@ -397,7 +426,10 @@ export const SideDock = forwardRef<HTMLElement, SideDockProps>(function SideDock
         >
           <SheetHeader
             data-slot="side-dock-header"
-            className="flex-row items-start gap-2 space-y-0 border-b border-border px-4 py-3"
+            // `h-header`, never padding: a dock's header band sits beside the app
+            // shell's top bar and MUST share its height in every theme (a theme
+            // retunes `--header-size`). See the column branch.
+            className="h-header flex-row items-center gap-2 space-y-0 border-b border-border px-4"
           >
             <div className="min-w-0 flex-1">
               <SheetTitle data-slot="side-dock-title" className="text-title">
@@ -439,7 +471,11 @@ export const SideDock = forwardRef<HTMLElement, SideDockProps>(function SideDock
       // programmatically.
       ref={groupRef}
       tabIndex={-1}
-      className="group"
+      // `relative`: only in "inset" mode, so the container's `absolute`
+      // positioning below resolves against THIS wrapper (its own slot in
+      // the layout) instead of the viewport (#432). No-op in "viewport"
+      // mode — the container stays `fixed`.
+      className={cn("group", containerPosition === "inset" && "relative")}
       {...panel.attrs}
       style={{ "--collapsible-panel-width": `${clampedWidth}px` } as CSSProperties}
     >
@@ -462,13 +498,19 @@ export const SideDock = forwardRef<HTMLElement, SideDockProps>(function SideDock
       >
         <div
           data-slot="side-dock-header"
-          className="flex items-start gap-2 border-b border-border px-4 py-3"
+          // ONE fixed band at `h-header` — the same height the app shell's top
+          // bar takes, so the two rules under them sit on one line in every
+          // theme. Never size it from padding: a padded header grows with its
+          // content (a two-line description made it 73px beside a 56px bar).
+          // The description therefore lives UNDER the band, not inside it.
+          className="flex h-header shrink-0 items-center gap-2 border-b border-border px-4"
         >
-          <div className="min-w-0 flex-1">
-            <div id={titleId} data-slot="side-dock-title" className="text-title">
-              {title}
-            </div>
-            {description && <div className="text-body text-muted-foreground">{description}</div>}
+          <div
+            id={titleId}
+            data-slot="side-dock-title"
+            className="min-w-0 flex-1 truncate text-title"
+          >
+            {title}
           </div>
           {headerActions}
           <button
@@ -493,6 +535,11 @@ export const SideDock = forwardRef<HTMLElement, SideDockProps>(function SideDock
           tabIndex={0}
           className="min-h-0 flex-1 overflow-y-auto p-4 focus-ring-inset"
         >
+          {description && (
+            <p data-slot="side-dock-description" className="mb-4 text-body text-muted-foreground">
+              {description}
+            </p>
+          )}
           {children}
         </div>
         {resizeHandle}