feat: SW-2096 add AssistantLayout composed component (dockable AI assistant panel) (#167)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Author: 3 people

src/components/composed/AssistantLayout/AssistantLayout.stories.tsx

@@ -0,0 +1,164 @@
+import { SparklesIcon } from "lucide-react"
+import { expect, userEvent, waitFor } from "storybook/test"
+
+import {
+  AssistantDockControls,
+  AssistantLayout,
+  AssistantLayoutProvider,
+} from "./AssistantLayout"
+
+import type { AssistantDock } from "./dockLayout"
+import type { Meta, StoryObj } from "@storybook/react-vite"
+
+const meta: Meta<typeof AssistantLayout> = {
+  title: "AI Elements/Layout Manager",
+  component: AssistantLayout,
+  parameters: { layout: "fullscreen" },
+  tags: ["autodocs"],
+}
+
+export default meta
+type Story = StoryObj<typeof AssistantLayout>
+
+function MockAssistant() {
+  return (
+    <>
+      <div className="flex shrink-0 items-center gap-2 border-b border-border px-3 py-2">
+        <SparklesIcon className="size-4 text-primary" />
+        <span className="text-sm font-medium">AI Assistant</span>
+      </div>
+      <div className="flex-1 space-y-3 overflow-auto p-3 text-sm">
+        <div className="ml-auto w-fit max-w-[80%] rounded-lg bg-primary px-3 py-2 text-primary-foreground">
+          Which leads have the best developability?
+        </div>
+        <div className="w-fit max-w-[85%] rounded-lg bg-muted px-3 py-2">
+          Leads 3, 7 and 12 score highest on aggregation and thermostability. Want me to filter the table to those?
+        </div>
+      </div>
+      <div className="shrink-0 border-t border-border p-3">
+        <div className="flex h-9 items-center rounded-lg border border-input px-3 text-sm text-muted-foreground">
+          Ask anything…
+        </div>
+      </div>
+    </>
+  )
+}
+
+function MockContent() {
+  return (
+    <div className="flex-1 overflow-auto p-5">
+      <h2 className="text-lg font-semibold">Antibody Lead Selection</h2>
+      <p className="mt-1 text-sm text-muted-foreground">
+        Main content area. Use the dock controls in the top bar to move the AI Assistant left, bottom, or right —
+        or click the active icon again to hide it and reclaim the full width.
+      </p>
+      <div className="mt-4 grid grid-cols-3 gap-3">
+        {Array.from({ length: 9 }).map((_, i) => (
+          <div key={i} className="rounded-lg border border-border bg-background p-4 text-sm">
+            Lead {i + 1}
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+function Demo({ defaultDock }: { defaultDock?: AssistantDock }) {
+  return (
+    <AssistantLayoutProvider defaultDock={defaultDock} persist={false}>
+      <div className="flex h-screen w-full flex-col gap-2 p-3">
+        <div className="flex shrink-0 items-center justify-between">
+          <span className="text-sm font-semibold">Workspace</span>
+          <AssistantDockControls />
+        </div>
+        <AssistantLayout assistant={<MockAssistant />}>
+          <MockContent />
+        </AssistantLayout>
+      </div>
+    </AssistantLayoutProvider>
+  )
+}
+
+export const DockedLeft: Story = {
+  render: () => <Demo defaultDock="left" />,
+  play: async ({ canvasElement, step }) => {
+    const body = () => canvasElement.querySelector('[data-slot="assistant-layout"]') as HTMLElement
+    const assistant = () =>
+      canvasElement.querySelector('[data-slot="assistant-layout-assistant"]') as HTMLElement
+    const content = () =>
+      canvasElement.querySelector('[data-slot="assistant-layout-content"]') as HTMLElement
+    // The three dock buttons are the only elements with aria-pressed.
+    const dockButtons = () => [...canvasElement.querySelectorAll<HTMLElement>("[aria-pressed]")]
+    // True when `a` appears before `b` in document order.
+    const precedes = (a: HTMLElement, b: HTMLElement) =>
+      Boolean(a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING)
+
+    await step("Starts docked left (horizontal, assistant before content)", async () => {
+      expect(getComputedStyle(body()).flexDirection).toBe("row")
+      expect(assistant()).toBeVisible()
+      expect(precedes(assistant(), content())).toBe(true)
+      // The resizable handle is present while the assistant is visible.
+      expect(canvasElement.querySelector('[role="separator"]')).not.toBeNull()
+    })
+
+    await step("Dock bottom → vertical", async () => {
+      await userEvent.click(dockButtons()[1]) // [left, bottom, right]
+      expect(getComputedStyle(body()).flexDirection).toBe("column")
+      expect(precedes(content(), assistant())).toBe(true)
+    })
+
+    await step("Click the active dock again → hidden, no handle, none pressed", async () => {
+      await userEvent.click(dockButtons()[1]) // now active → hides
+      expect(canvasElement.querySelector('[role="separator"]')).toBeNull()
+      expect(dockButtons().some((b) => b.getAttribute("aria-pressed") === "true")).toBe(false)
+      expect(canvasElement.querySelector('[data-slot="assistant-layout-assistant"]')).toBeNull()
+    })
+
+    await step("Re-dock right → visible again, content before assistant", async () => {
+      await userEvent.click(dockButtons()[2])
+      expect(assistant()).toBeVisible()
+      expect(getComputedStyle(body()).flexDirection).toBe("row")
+      expect(precedes(content(), assistant())).toBe(true)
+    })
+  },
+  parameters: {
+    zephyr: { testCaseId: "SW-T5497" },
+  },
+}
+export const DockedRight: Story = { render: () => <Demo defaultDock="right" />,
+    parameters: {
+            // Auto-generated by sync-storybook-zephyr - do not add manually
+            zephyr: { testCaseId: "SW-T5498" },
+          }
+}
+export const DockedBottom: Story = { render: () => <Demo defaultDock="bottom" />,
+    parameters: {
+            // Auto-generated by sync-storybook-zephyr - do not add manually
+            zephyr: { testCaseId: "SW-T5499" },
+          }
+}
+
+// testCaseId intentionally left blank — the zephyr_sync workflow backfills it.
+export const ResizeByKeyboard: Story = {
+  parameters: { zephyr: { testCaseId: "SW-T5500" } },
+  render: () => <Demo defaultDock="right" />,
+  play: async ({ canvasElement, step }) => {
+    const separator = () => canvasElement.querySelector('[role="separator"]') as HTMLElement
+    const assistant = () =>
+      canvasElement.querySelector('[data-slot="assistant-layout-assistant"]') as HTMLElement
+
+    await step("Resize handle is present and keyboard-focusable", async () => {
+      expect(separator()).not.toBeNull()
+      expect(assistant()).toBeVisible()
+    })
+
+    await step("Arrow keys resize the panels via the Resizable handle", async () => {
+      const widthBefore = assistant().getBoundingClientRect().width
+      separator().focus()
+      await userEvent.keyboard("{ArrowLeft}{ArrowLeft}{ArrowLeft}{ArrowLeft}")
+      await waitFor(() =>
+        expect(assistant().getBoundingClientRect().width).not.toBe(widthBefore)
+      )
+    })
+  },
+}

src/components/composed/AssistantLayout/AssistantLayout.test.tsx

@@ -0,0 +1,173 @@
+import * as React from "react"
+import { act } from "react"
+import { createRoot } from "react-dom/client"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+
+import {
+  AssistantDockControls,
+  AssistantLayoutProvider,
+  useAssistantLayout,
+} from "./AssistantLayout"
+
+;(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: ReturnType<typeof createRoot>
+
+/** jsdom's bundled `localStorage` is a non-functional stub here, so use our own. */
+function installLocalStorage() {
+  const store = new Map<string, string>()
+  const storage: Storage = {
+    getItem: (k) => (store.has(k) ? store.get(k)! : null),
+    setItem: (k, v) => {
+      store.set(k, String(v))
+    },
+    removeItem: (k) => {
+      store.delete(k)
+    },
+    clear: () => {
+      store.clear()
+    },
+    key: (i) => [...store.keys()][i] ?? null,
+    get length() {
+      return store.size
+    },
+  }
+  Object.defineProperty(window, "localStorage", { configurable: true, value: storage })
+}
+
+beforeEach(() => {
+  container = document.createElement("div")
+  document.body.appendChild(container)
+  root = createRoot(container)
+  installLocalStorage()
+})
+
+afterEach(() => {
+  act(() => {
+    root.unmount()
+  })
+  container.remove()
+})
+
+function render(ui: React.ReactElement) {
+  act(() => {
+    root.render(ui)
+  })
+}
+
+function q<T extends Element = HTMLElement>(selector: string) {
+  return container.querySelector(selector) as T | null
+}
+
+function click(selector: string) {
+  const el = q<HTMLElement>(selector)
+  expect(el).not.toBeNull()
+  act(() => {
+    el!.click()
+  })
+}
+
+/** Surfaces the context values so assertions don't depend on the resizable layout. */
+function Probe() {
+  const { dock, size, visible } = useAssistantLayout()
+  return (
+    <span data-testid="probe" data-dock={dock} data-size={String(size)} data-visible={String(visible)} />
+  )
+}
+
+function probe() {
+  const el = q('[data-testid="probe"]')
+  return {
+    dock: el?.getAttribute("data-dock"),
+    size: Number(el?.getAttribute("data-size")),
+    visible: el?.getAttribute("data-visible") === "true",
+  }
+}
+
+function Harness({
+  dock = "left",
+  size,
+  persist = true,
+  showLabel = true,
+}: {
+  dock?: "left" | "right" | "bottom"
+  size?: number
+  persist?: boolean
+  showLabel?: boolean
+}) {
+  return (
+    <AssistantLayoutProvider
+      storageKey="spec.assistant"
+      defaultDock={dock}
+      defaultSize={size}
+      persist={persist}
+    >
+      <AssistantDockControls label={showLabel ? undefined : null} />
+      <Probe />
+    </AssistantLayoutProvider>
+  )
+}
+
+describe("AssistantLayout", () => {
+  it("throws when useAssistantLayout is used outside the provider", () => {
+    function Consumer() {
+      useAssistantLayout()
+      return null
+    }
+
+    expect(() => {
+      render(<Consumer />)
+    }).toThrow("useAssistantLayout must be used within an AssistantLayoutProvider")
+  })
+
+  it("reads persisted dock and size", () => {
+    window.localStorage.setItem("spec.assistant.dock", "right")
+    window.localStorage.setItem("spec.assistant.size", "45")
+
+    render(<Harness dock="left" size={32} />)
+
+    expect(probe().dock).toBe("right")
+    expect(probe().size).toBe(45)
+  })
+
+  it("falls back to the default when the persisted size is out of the (0,100) range", () => {
+    window.localStorage.setItem("spec.assistant.size", "150")
+
+    render(<Harness dock="left" size={32} />)
+
+    expect(probe().size).toBe(32)
+  })
+
+  it("ignores persisted values when persist is false", () => {
+    window.localStorage.setItem("spec.assistant.dock", "bottom")
+
+    render(<Harness dock="left" size={32} persist={false} />)
+
+    expect(probe().dock).toBe("left")
+  })
+
+  it("shows the label by default and hides it when label is null", () => {
+    render(<Harness dock="left" />)
+    expect(container.textContent).toContain("AI Assistant")
+
+    act(() => root.unmount())
+    root = createRoot(container)
+    render(<Harness dock="left" showLabel={false} />)
+    expect(container.textContent).not.toContain("AI Assistant")
+  })
+
+  it("hides on active dock click and redocks (persisting the dock) on another icon", () => {
+    render(<Harness dock="left" />)
+    expect(probe().visible).toBe(true)
+    expect(probe().dock).toBe("left")
+
+    click('button[aria-label="Hide AI Assistant"]')
+    expect(probe().visible).toBe(false)
+
+    click('button[aria-label="Dock assistant right"]')
+    expect(probe().visible).toBe(true)
+    expect(probe().dock).toBe("right")
+    expect(window.localStorage.getItem("spec.assistant.dock")).toBe("right")
+  })
+})