@elabs-ai/components-ui 4.2.0 → 5.0.0

package/src/components/schema-form/schema-form.tsx

@@ -84,6 +84,9 @@ import {
 } from "../file-upload";
 import { AdvancedGroup } from "../advanced-group";
 import { Tabs, TabsList, TabsTrigger, TabsContent } from "../tabs";
+import { ChevronRight } from "lucide-react";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../collapsible";
+import { Descriptions, DescriptionsItem } from "../descriptions";
 
 import {
   checkFileIssue,
@@ -745,6 +748,32 @@ export const SchemaFormField = memo(
       setValue: store.setValue,
     };
 
+    if (field.type !== "group" && field.readOnly) {
+      return (
+        <div
+          ref={ref}
+          data-slot="schema-form-field"
+          data-readonly=""
+          className={cn("flex flex-col gap-1.5", className)}
+          {...props}
+        >
+          <Descriptions layout="vertical">
+            <DescriptionsItem
+              label={fieldLabel(field)}
+              numeric={field.type === "number" || field.type === "integer"}
+            >
+              {readOnlyText(snapshot.value)}
+            </DescriptionsItem>
+          </Descriptions>
+          {hasDesc && (
+            <p id={descId(meta.formId, name)} className="text-caption text-muted-foreground">
+              {description}
+            </p>
+          )}
+        </div>
+      );
+    }
+
     const isBoolean = field.type === "boolean";
     const isGroup = field.type === "group";
     // A multi-value control renders a labelled REGION, not one focusable
@@ -852,14 +881,92 @@ export const SchemaFormFields = forwardRef<HTMLDivElement, SchemaFormFieldsProps
         className={cn("flex flex-col gap-4", className)}
         {...props}
       >
-        {visibleNames.map((name) => (
-          <SchemaFormField key={name} name={name} />
-        ))}
+        {spec.sections
+          ? (() => {
+              const grouped = new Set(spec.sections.flatMap((section) => section.fields));
+              const visible = new Set(visibleNames);
+              return (
+                <>
+                  {visibleNames
+                    .filter((name) => !grouped.has(name))
+                    .map((name) => (
+                      <SchemaFormField key={name} name={name} />
+                    ))}
+                  {spec.sections.map((section) => {
+                    const names = section.fields.filter((name) => visible.has(name));
+                    if (names.length === 0) return null;
+                    return (
+                      <SchemaFormSection
+                        key={section.id}
+                        label={section.label}
+                        collapsed={section.collapsed}
+                      >
+                        {names.map((name) => (
+                          <SchemaFormField key={name} name={name} />
+                        ))}
+                      </SchemaFormSection>
+                    );
+                  })}
+                </>
+              );
+            })()
+          : visibleNames.map((name) => <SchemaFormField key={name} name={name} />)}
       </div>
     );
   },
 );
 
+/** A read-only field's value as text; an empty value renders an em dash. */
+function readOnlyText(value: FormValue): string {
+  if (value === undefined || value === "") return "—";
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "—";
+    return value
+      .map((item) =>
+        typeof item === "string"
+          ? item
+          : item instanceof File
+            ? item.name
+            : `${item.key}: ${item.value}`,
+      )
+      .join(", ");
+  }
+  return String(value);
+}
+
+/** One `FormSpec.sections` entry: a disclosure over its fields. */
+function SchemaFormSection({
+  label,
+  collapsed,
+  children,
+}: {
+  label: string;
+  collapsed?: boolean;
+  children: ReactNode;
+}) {
+  return (
+    <Collapsible
+      defaultOpen={!collapsed}
+      data-slot="schema-form-section"
+      className="group/section flex flex-col gap-3 border-t border-border-strong pt-3"
+    >
+      <CollapsibleTrigger
+        data-slot="schema-form-section-trigger"
+        className="focus-ring flex w-full items-center gap-1 rounded-sm text-start text-subtitle text-foreground"
+      >
+        <ChevronRight
+          aria-hidden="true"
+          className="size-4 shrink-0 transition-transform group-data-[state=open]/section:rotate-90 motion-reduce:transition-none"
+        />
+        {label}
+      </CollapsibleTrigger>
+      <CollapsibleContent data-slot="schema-form-section-content" className="flex flex-col gap-4">
+        {children}
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}
+
 function SchemaFormSkeletonAnnouncement() {
   const { t } = useLocale();
   return (
@@ -1209,7 +1316,7 @@ export const SchemaFormTitle = forwardRef<HTMLParagraphElement, SchemaFormTitleP
       <p
         ref={ref}
         id={headingId}
-        className={cn("text-subtitle font-semibold text-foreground text-balance", className)}
+        className={cn("text-subtitle text-foreground text-balance", className)}
         {...props}
       >
         {content}

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,9 +34,7 @@ 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-meta 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-body text-muted-foreground">{description}</p> : null}

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

@@ -125,7 +125,7 @@ export const SelectTrigger = forwardRef<
       className={cn(
         "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",
+        "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).
@@ -156,7 +156,7 @@ export const SelectContent = forwardRef<
         ref={ref}
         position={position}
         className={cn(
-          "relative z-50 max-h-96 min-w-[12rem] 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" &&
@@ -207,7 +207,7 @@ export const SelectItem = forwardRef<
       ref={ref}
       className={cn(
         "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",
+        "focus:bg-accent focus:text-accent-foreground focus-ring-inset data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
         className,
       )}
       {...props}

package/src/components/sheet/sheet.tsx

@@ -38,7 +38,7 @@ const sheetVariants = cva(
   // `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)]",
+  "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: {

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.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,10 +226,12 @@ 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(() => {
+    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.
@@ -410,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">
@@ -452,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}
     >
@@ -475,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
@@ -506,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}

package/src/components/sidebar/sidebar.stories.tsx

@@ -68,7 +68,7 @@ export const Default: Story = {
           </SidebarContent>
         </Sidebar>
         <SidebarInset>
-          <header className="flex h-14 items-center gap-2 border-b px-4">
+          <header className="flex h-header items-center gap-2 border-b px-4">
             <SidebarTrigger />
             <span className="text-body font-medium">Dashboard</span>
           </header>
@@ -357,7 +357,7 @@ export const NestedFrameProvider: Story = {
           </SidebarContent>
         </Sidebar>
         <SidebarInset>
-          <header className="flex h-14 items-center gap-2 border-b px-4">
+          <header className="flex h-header items-center gap-2 border-b px-4">
             <SidebarTrigger />
             <span className="text-body font-medium">Dashboard</span>
           </header>
@@ -435,7 +435,7 @@ export const Mobile: Story = {
         </SidebarContent>
       </Sidebar>
       <SidebarInset>
-        <header className="flex h-14 items-center gap-2 border-b px-4">
+        <header className="flex h-header items-center gap-2 border-b px-4">
           <SidebarTrigger />
         </header>
       </SidebarInset>

package/src/components/sidebar/sidebar.test.tsx

@@ -73,7 +73,7 @@ describe("SidebarProvider", () => {
     // Asserting the two class strings merely DIFFER passes on colour-only code and
     // is not sufficient (.claude/rules/accessibility.md §1.4.1). Assert the cues
     // that survive greyscale: a drawn bar, and a heavier weight.
-    expect(active.className).toContain("data-[active=true]:before:w-1");
+    expect(active.className).toContain("data-[active=true]:before:w-(--sidebar-indicator-width)");
     expect(active.className).toContain("data-[active=true]:font-semibold");
     expect(resting).toHaveAttribute("data-active", "false");
   });
@@ -110,3 +110,33 @@ describe("SidebarProvider", () => {
     removeSpy.mockRestore();
   });
 });
+
+describe("Sidebar containerPosition", () => {
+  const frame = (position?: "viewport" | "inset") =>
+    render(
+      <SidebarProvider>
+        <Sidebar containerPosition={position}>
+          <span>chrome</span>
+        </Sidebar>
+        <SidebarInset>
+          <p>canvas</p>
+        </SidebarInset>
+      </SidebarProvider>,
+    ).container;
+
+  it("pins the rail to the window by default — today's behaviour, unchanged", () => {
+    const container = frame().querySelector('[data-slot="sidebar-container"]');
+    expect(container?.className).toContain("fixed");
+    expect(container?.className).not.toContain("absolute");
+    expect(frame().querySelector('[data-slot="sidebar"]')?.className).not.toContain("relative");
+  });
+
+  it('pins the rail to its own place in the layout with containerPosition="inset"', () => {
+    const root = frame("inset");
+    const container = root.querySelector('[data-slot="sidebar-container"]');
+    expect(container?.className).toContain("absolute");
+    expect(container?.className).not.toContain("fixed");
+    // The absolute container needs a positioned ancestor of the rail's own height.
+    expect(root.querySelector('[data-slot="sidebar"]')?.className).toContain("relative");
+  });
+});