@exegia/corpora-ui 0.18.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exegia/corpora-ui",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "shadcn-ready React UI library for the corpora manuscript-research apps.",
   "license": "MIT",
   "repository": {
@@ -50,6 +50,7 @@
     "lucide-react": "^1.31.0",
     "motion": "^12.43.0",
     "motion-icons-react": "^1.1.0",
+    "tailwind-animations": "^1.0.2",
     "tailwind-merge": "^3.6.0"
   },
   "devDependencies": {

package/src/components/beste/piece/browser-frame.tsx

@@ -12,9 +12,6 @@ export function BrowserFrame({
   titleStyle,
   children,
 }: IBrowserProps) {
-
-
-
   return (
     <div
       className={cn(
@@ -22,8 +19,14 @@ export function BrowserFrame({
         className
       )}
     >
-      <div className="flex min-h-32 w-full max-h-[500px] flex-col overflow-hidden rounded-lg border border-border bg-neutral-50 shadow-lg dark:bg-neutral-900 relative">
-        <div id="title-bar" className={cn("flex flex-1 w-full items-center gap-2 px-4 py-3 z-20", titleBarStyle(titleStyle, 'title'))}>
+      <div className="relative flex max-h-[500px] min-h-32 w-full flex-col overflow-hidden rounded-lg border border-border bg-neutral-50 shadow-lg dark:bg-neutral-900">
+        <div
+          id="title-bar"
+          className={cn(
+            "z-20 flex flex-1 items-center gap-2 px-4 py-3",
+            titleBarStyle(titleStyle, "title")
+          )}
+        >
           <div className="flex items-center gap-2" aria-hidden="true">
             <span className="size-3 cursor-pointer rounded-full bg-rose-500 shadow-md outline outline-rose-800" />
             <span className="size-3 cursor-pointer rounded-full bg-amber-500 shadow-md outline outline-amber-800" />
@@ -42,7 +45,7 @@ export function BrowserFrame({
           )}
           {title && !url && (
             <div className="flex w-full flex-1 justify-center select-none">
-              <span className="text-sm text-foreground ml-2">{title}</span>
+              <span className="ml-2 text-sm text-foreground">{title}</span>
             </div>
           )}
         </div>

package/src/components/blocks/nav/sidebar/__tests__/use-ai-sidebar.test.tsx

@@ -0,0 +1,310 @@
+import { describe, expect, mock, test } from "bun:test"
+import { act, render, renderHook, screen } from "@testing-library/react"
+
+import { AISidebar } from "../ai-sidebar"
+import type { AISidebarController, SidebarResource } from "../type.ts"
+import { useAISidebar } from "../use-ai-sidebar"
+
+const RESOURCES: SidebarResource[] = [
+  {
+    id: "corpora",
+    label: "Corpora",
+    kind: "project",
+    children: [
+      {
+        id: "manuscripts",
+        label: "Manuscripts",
+        kind: "folder",
+        children: [{ id: "codex-a", label: "Codex Askewianus", kind: "file" }],
+      },
+      { id: "readme", label: "Field notes", kind: "file" },
+    ],
+  },
+  { id: "reading-list", label: "Reading list", kind: "bookmark" },
+  { id: "archive", label: "Archive", kind: "folder", disabled: true },
+]
+
+const labels = (controller: AISidebarController) =>
+  controller.flat.map((row) => row.item.id)
+
+describe("useAISidebar · expansion", () => {
+  test("expand, collapse and toggle change what flattens", () => {
+    const { result } = renderHook(() =>
+      useAISidebar({ defaultItems: RESOURCES })
+    )
+    expect(labels(result.current)).toEqual(["corpora", "reading-list", "archive"])
+
+    act(() => result.current.expand("corpora"))
+    expect(result.current.isExpanded("corpora")).toBe(true)
+    expect(labels(result.current)).toContain("manuscripts")
+
+    // Expanding twice is a no-op rather than a toggle.
+    act(() => result.current.expand("corpora"))
+    expect(result.current.isExpanded("corpora")).toBe(true)
+
+    act(() => result.current.toggleExpanded("corpora"))
+    expect(result.current.isExpanded("corpora")).toBe(false)
+    act(() => result.current.collapse("corpora"))
+    expect(result.current.isExpanded("corpora")).toBe(false)
+  })
+
+  test("expandAll opens every container that has children", () => {
+    const { result } = renderHook(() =>
+      useAISidebar({ defaultItems: RESOURCES })
+    )
+    act(() => result.current.expandAll())
+    expect(labels(result.current)).toEqual([
+      "corpora",
+      "manuscripts",
+      "codex-a",
+      "readme",
+      "reading-list",
+      "archive",
+    ])
+    // A childless folder is not an expandable row.
+    expect(result.current.isExpanded("archive")).toBe(false)
+
+    act(() => result.current.collapseAll())
+    expect([...result.current.expandedIds]).toEqual([])
+  })
+
+  test("reveal opens ancestors only", () => {
+    const { result } = renderHook(() =>
+      useAISidebar({ defaultItems: RESOURCES })
+    )
+    act(() => result.current.reveal("codex-a"))
+    expect(result.current.isExpanded("corpora")).toBe(true)
+    expect(result.current.isExpanded("manuscripts")).toBe(true)
+    expect(result.current.isExpanded("codex-a")).toBe(false)
+  })
+
+  test("controlled expandedIds win and changes are only reported", () => {
+    const onExpandedChange = mock((ids: string[]) => void ids)
+    const { result } = renderHook(() =>
+      useAISidebar({
+        defaultItems: RESOURCES,
+        expandedIds: ["corpora"],
+        onExpandedChange,
+      })
+    )
+    act(() => result.current.collapse("corpora"))
+    expect(result.current.isExpanded("corpora")).toBe(true)
+    expect(onExpandedChange).toHaveBeenCalledWith([])
+  })
+})
+
+describe("useAISidebar · selection and focus", () => {
+  test("select holds the id when uncontrolled and reports either way", () => {
+    const onActiveChange = mock((id: string) => void id)
+    const { result } = renderHook(() =>
+      useAISidebar({ defaultItems: RESOURCES, onActiveChange })
+    )
+    act(() => result.current.select("reading-list"))
+    expect(result.current.selectedId).toBe("reading-list")
+    expect(onActiveChange).toHaveBeenCalledWith("reading-list")
+
+    const controlled = renderHook(() =>
+      useAISidebar({
+        defaultItems: RESOURCES,
+        activeId: "corpora",
+        onActiveChange,
+      })
+    )
+    act(() => controlled.result.current.select("reading-list"))
+    expect(controlled.result.current.selectedId).toBe("corpora")
+  })
+
+  test("focus moves the roving target, and it follows rows that fold away", () => {
+    const { result } = renderHook(() =>
+      useAISidebar({ defaultItems: RESOURCES, defaultExpandedIds: ["corpora"] })
+    )
+    act(() => result.current.focus("readme"))
+    expect(result.current.focusedId).toBe("readme")
+
+    // Collapsing the parent hides the focused row — focus falls back to the
+    // first visible row rather than pointing at nothing.
+    act(() => result.current.collapse("corpora"))
+    expect(result.current.focusedId).toBe("corpora")
+  })
+})
+
+describe("useAISidebar · rename", () => {
+  test("renames hook-owned data and leaves rename mode", () => {
+    const { result } = renderHook(() =>
+      useAISidebar({ defaultItems: RESOURCES })
+    )
+    act(() => result.current.startRename("reading-list"))
+    expect(result.current.renamingId).toBe("reading-list")
+
+    act(() => result.current.rename("reading-list", "  To read  "))
+    expect(result.current.renamingId).toBeNull()
+    expect(result.current.getItem("reading-list")?.label).toBe("To read")
+  })
+
+  test("blank, unchanged and unknown targets are dropped", () => {
+    const onRename = mock(() => {})
+    const { result } = renderHook(() =>
+      useAISidebar({ defaultItems: RESOURCES, onRename })
+    )
+    act(() => result.current.rename("reading-list", "   "))
+    act(() => result.current.rename("reading-list", "Reading list"))
+    act(() => result.current.rename("nope", "Whatever"))
+    expect(onRename).not.toHaveBeenCalled()
+
+    // Arming rename against a row that never renders is inert.
+    act(() => result.current.startRename("nope"))
+    expect(result.current.renamingId).toBeNull()
+  })
+
+  test("a rejected onRename rolls the label back and announces it", async () => {
+    const onRename = mock(() => Promise.reject(new Error("offline")))
+    const { result } = renderHook(() =>
+      useAISidebar({ defaultItems: RESOURCES, onRename })
+    )
+    await act(async () => {
+      result.current.rename("reading-list", "To read")
+      await Promise.resolve()
+    })
+    expect(result.current.getItem("reading-list")?.label).toBe("Reading list")
+    expect(result.current.announcement).toContain("Rename failed")
+  })
+})
+
+describe("useAISidebar · reorder", () => {
+  test("move reorders and announces", async () => {
+    const onMove = mock(() => {})
+    const { result } = renderHook(() =>
+      useAISidebar({ defaultItems: RESOURCES, onMove })
+    )
+    await act(async () =>
+      result.current.move({
+        itemId: "reading-list",
+        targetId: "corpora",
+        position: "before",
+      })
+    )
+    expect(result.current.items.map((item) => item.id)).toEqual([
+      "reading-list",
+      "corpora",
+      "archive",
+    ])
+    expect(onMove).toHaveBeenCalled()
+    expect(result.current.announcement).toContain("Moved Reading list before")
+  })
+
+  test("a rejected onMove restores the previous order", async () => {
+    const onMoveError = mock(() => {})
+    const { result } = renderHook(() =>
+      useAISidebar({
+        defaultItems: RESOURCES,
+        onMove: () => Promise.reject(new Error("409")),
+        onMoveError,
+      })
+    )
+    await act(async () =>
+      result.current.move({
+        itemId: "reading-list",
+        targetId: "corpora",
+        position: "before",
+      })
+    )
+    expect(result.current.items.map((item) => item.id)).toEqual([
+      "corpora",
+      "reading-list",
+      "archive",
+    ])
+    expect(result.current.announcement).toContain("Move failed")
+    expect(onMoveError).toHaveBeenCalled()
+  })
+
+  test("moves the data forbids are refused", async () => {
+    const { result } = renderHook(() =>
+      useAISidebar({ defaultItems: RESOURCES })
+    )
+    // Into its own subtree.
+    await act(async () =>
+      result.current.move({
+        itemId: "corpora",
+        targetId: "manuscripts",
+        position: "inside",
+      })
+    )
+    // Inside a row that cannot contain children.
+    await act(async () =>
+      result.current.move({
+        itemId: "corpora",
+        targetId: "reading-list",
+        position: "inside",
+      })
+    )
+    expect(result.current.items.map((item) => item.id)).toEqual([
+      "corpora",
+      "reading-list",
+      "archive",
+    ])
+  })
+})
+
+describe("useAISidebar · menu", () => {
+  test("openMenu and closeMenu track one row at a time", () => {
+    const { result } = renderHook(() =>
+      useAISidebar({ defaultItems: RESOURCES })
+    )
+    act(() => result.current.openMenu("reading-list"))
+    expect(result.current.menuOpenId).toBe("reading-list")
+
+    act(() => result.current.openMenu("nope"))
+    expect(result.current.menuOpenId).toBe("reading-list")
+
+    act(() => result.current.closeMenu())
+    expect(result.current.menuOpenId).toBeNull()
+  })
+})
+
+describe("AISidebar · controller form", () => {
+  function Harness({
+    onReady,
+  }: {
+    onReady: (controller: AISidebarController) => void
+  }) {
+    const controller = useAISidebar({ defaultItems: RESOURCES })
+    onReady(controller)
+    return <AISidebar controller={controller} />
+  }
+
+  test("renders from the controller and reacts to calls made outside it", async () => {
+    let sidebar!: AISidebarController
+    render(<Harness onReady={(next) => (sidebar = next)} />)
+    expect(screen.queryByRole("treeitem", { name: /Field notes/ })).toBeNull()
+
+    await act(async () => sidebar.expandAll())
+    expect(screen.getByRole("treeitem", { name: /Field notes/ })).toBeDefined()
+
+    await act(async () => sidebar.select("readme"))
+    expect(
+      screen.getByRole("treeitem", { name: /Field notes/ }).getAttribute("aria-selected")
+    ).toBe("true")
+  })
+
+  // Rename mode is not asserted through the rendered row here: mounting the
+  // input makes happy-dom fire focus/blur, and the row's blur handler
+  // commits and closes rename mode before an assertion can run. The hook
+  // tests above cover the state; the browser covers the rendering.
+
+  test("a move made from outside reorders the rendered rows", async () => {
+    let sidebar!: AISidebarController
+    render(<Harness onReady={(next) => (sidebar = next)} />)
+
+    await act(async () =>
+      sidebar.move({
+        itemId: "reading-list",
+        targetId: "corpora",
+        position: "before",
+      })
+    )
+    const rows = screen
+      .getAllByRole("treeitem")
+      .map((row) => row.getAttribute("aria-label") ?? row.textContent)
+    expect(rows[0]).toContain("Reading list")
+  })
+})

package/src/components/blocks/nav/sidebar/ai-sidebar.tsx

@@ -2,46 +2,72 @@
 
 import { AnimatePresence } from "motion/react";
 import { cn } from "@/lib/utils";
-import type { AISidebarProps, FlatResource } from "./type"
-import { useAISidebar, type UseAISidebarOptions } from "./use-ai-sidebar"
+import type {
+  AISidebarComponentProps,
+  AISidebarController,
+  AISidebarProps,
+  AISidebarViewProps,
+  FlatResource,
+} from "./type"
+import { useAISidebar } from "./use-ai-sidebar"
 import { ResourceRow } from "./sidebar-row"
 
-export function AISidebar({
+/**
+ * Resource tree for the app rail: nested rows with drag-and-drop reorder,
+ * inline rename, per-row action menus and full keyboard navigation.
+ *
+ * Two ways to drive it. Pass the data and handlers as props and the block
+ * owns its state, or hold a `useAISidebar` controller and pass it as
+ * `controller` — the same rendering, but select, expand, rename, reorder
+ * and menu state are then callable from anywhere in your app.
+ */
+export function AISidebar(props: AISidebarComponentProps) {
+  // Two components rather than one: hooks may not be called conditionally,
+  // and the controller form has no options to build a fallback controller
+  // from. Nobody switches a sidebar between the two forms at runtime.
+  return props.controller ? (
+    <AISidebarView {...viewProps(props)} controller={props.controller} />
+  ) : (
+    <UncontrolledAISidebar {...props} />
+  )
+}
+
+/** The props form: builds its own controller and renders through it. */
+function UncontrolledAISidebar(props: AISidebarProps) {
+  const {
+    renderIcon: _icon,
+    renderMenu: _menu,
+    renderActionsTrigger: _trigger,
+    ariaLabel: _label,
+    className: _className,
+    controller: _controller,
+    ...options
+  } = props
+  const controller = useAISidebar(options)
+  return <AISidebarView {...viewProps(props)} controller={controller} />
+}
+
+function viewProps(props: AISidebarComponentProps): AISidebarViewProps {
+  return {
+    renderIcon: props.renderIcon,
+    renderMenu: props.renderMenu,
+    renderActionsTrigger: props.renderActionsTrigger,
+    ariaLabel: props.ariaLabel,
+    className: props.className,
+  }
+}
+
+/** Rendering only — every piece of state lives on the controller. */
+function AISidebarView({
+  controller,
   renderIcon,
   renderMenu,
   renderActionsTrigger,
   ariaLabel = "Resources",
   className,
-  ...options
-}: AISidebarProps) {
-  const {
-    flat,
-    selectedId,
-    expandedIds,
-    focusedId,
-    setFocusedId,
-    draggingId,
-    dropTarget,
-    hoveredId,
-    hoverLayoutId,
-    handleRowHover,
-    clearHover,
-    menuOpenId,
-    renamingId,
-    setRenamingId,
-    announcement,
-    select,
-    toggle,
-    handleKeyDown,
-    handleRootDragOver,
-    handleDrop,
-    handleRowDragStart,
-    handleRowDragEnd,
-    handleRowDragOver,
-    commitRename,
-    handleMenuOpenChange,
-    setRowRef,
-  } = useAISidebar(options as UseAISidebarOptions);
+}: AISidebarViewProps & { controller: AISidebarController }) {
+  const { dnd, hover } = controller
+  const { draggingId, dropTarget } = dnd
 
   return (
     <>
@@ -49,9 +75,9 @@ export function AISidebar({
         role="tree"
         aria-label={ariaLabel}
         aria-multiselectable="false"
-        onDragOver={handleRootDragOver}
-        onDrop={handleDrop}
-        onMouseLeave={clearHover}
+        onDragOver={dnd.onRootDragOver}
+        onDrop={dnd.onDrop}
+        onMouseLeave={hover.clear}
         className={cn(
           "relative min-w-0 flex-col gap-0.5 [overflow-anchor:none] group-data-[state=collapsed]/sidebar:hidden",
           draggingId && "pb-9 select-none",
@@ -59,39 +85,43 @@ export function AISidebar({
         )}
       >
         <AnimatePresence initial={false}>
-          {flat.map((row: FlatResource) => (
+          {controller.flat.map((row: FlatResource) => (
             <ResourceRow
               key={row.item.id}
               row={row}
-              active={selectedId === row.item.id}
-              expanded={expandedIds.has(row.item.id)}
-              focused={focusedId === row.item.id}
+              active={controller.selectedId === row.item.id}
+              expanded={controller.isExpanded(row.item.id)}
+              focused={controller.focusedId === row.item.id}
               draggingId={draggingId}
               dropTarget={dropTarget}
-              menuOpen={menuOpenId === row.item.id}
-              renaming={renamingId === row.item.id}
-              hoverActive={hoveredId !== null && !draggingId}
+              menuOpen={controller.menuOpenId === row.item.id}
+              renaming={controller.renamingId === row.item.id}
+              hoverActive={hover.hoveredId !== null && !draggingId}
               hoverPill={
-                hoveredId === row.item.id && !draggingId && !row.item.disabled
+                hover.hoveredId === row.item.id &&
+                !draggingId &&
+                !row.item.disabled
+              }
+              hoverLayoutId={hover.layoutId}
+              onHoverChange={(hovered) => hover.onRowHover(row.item.id, hovered)}
+              onFocus={() => controller.focus(row.item.id)}
+              onSelect={() => controller.select(row.item.id)}
+              onToggle={() => controller.toggleExpanded(row.item.id)}
+              onKeyDown={(event) => controller.onRowKeyDown(event, row)}
+              onRenameStart={() => controller.startRename(row.item.id)}
+              onRenameCancel={controller.cancelRename}
+              onRenameCommit={(label) => controller.rename(row.item.id, label)}
+              onMenuOpenChange={(open) =>
+                open ? controller.openMenu(row.item.id) : controller.closeMenu()
               }
-              hoverLayoutId={hoverLayoutId}
-              onHoverChange={(hovered) => handleRowHover(row.item.id, hovered)}
-              onFocus={() => setFocusedId(row.item.id)}
-              onSelect={() => select(row.item.id)}
-              onToggle={() => toggle(row.item.id)}
-              onKeyDown={(event) => handleKeyDown(event, row)}
-              onRenameStart={() => setRenamingId(row.item.id)}
-              onRenameCancel={() => setRenamingId(null)}
-              onRenameCommit={(label) => commitRename(row, label)}
-              onMenuOpenChange={(open) => handleMenuOpenChange(row, open)}
-              onDragStart={handleRowDragStart}
-              onDragEnd={handleRowDragEnd}
-              onDragOver={handleRowDragOver}
-              onDrop={handleDrop}
+              onDragStart={dnd.onRowDragStart}
+              onDragEnd={dnd.onRowDragEnd}
+              onDragOver={dnd.onRowDragOver}
+              onDrop={dnd.onDrop}
               renderIcon={renderIcon}
               renderMenu={renderMenu}
               renderActionsTrigger={renderActionsTrigger}
-              setRef={(node) => setRowRef(row.item.id, node)}
+              setRef={(node) => controller.setRowRef(row.item.id, node)}
             />
           ))}
         </AnimatePresence>
@@ -107,7 +137,7 @@ export function AISidebar({
         )}
       </div>
       <span className="sr-only" aria-live="polite">
-        {announcement}
+        {controller.announcement}
       </span>
     </>
   )

package/src/components/blocks/nav/sidebar/type.ts

@@ -23,7 +23,10 @@ export interface SidebarResourceMenuControls {
   rename: () => void
 }
 
-export interface AISidebarProps {
+/** Options for `useAISidebar`. `items`, `activeId` and `expandedIds` are
+ * each controlled when passed and hook-owned via their `default*` twin
+ * otherwise. */
+export interface UseAISidebarOptions {
   items?: SidebarResource[]
   defaultItems?: SidebarResource[]
   onItemsChange?: (items: SidebarResource[]) => void
@@ -34,7 +37,89 @@ export interface AISidebarProps {
   activeId?: string | null
   defaultActiveId?: string | null
   onActiveChange?: (id: string) => void
+  expandedIds?: string[]
   defaultExpandedIds?: string[]
+  onExpandedChange?: (ids: string[]) => void
+}
+
+/** Everything the sidebar can do, callable from outside the block — a
+ * toolbar, a command palette, a route change. Returned by `useAISidebar`
+ * and accepted by `<AISidebar controller={…} />`. */
+export interface AISidebarController {
+  items: SidebarResource[]
+  /** Visible rows in order, each with its depth and parent id. */
+  flat: FlatResource[]
+  getItem: (id: string) => SidebarResource | undefined
+
+  selectedId: string | null
+  select: (id: string) => void
+
+  expandedIds: ReadonlySet<string>
+  isExpanded: (id: string) => boolean
+  expand: (id: string) => void
+  collapse: (id: string) => void
+  toggleExpanded: (id: string) => void
+  expandAll: () => void
+  collapseAll: () => void
+  /** Open every ancestor of `id`, leaving the rest of the tree alone. */
+  reveal: (id: string) => void
+
+  /** Roving-focus target. `focus` also moves DOM focus to the row. */
+  focusedId: string | null
+  focus: (id: string) => void
+
+  renamingId: string | null
+  startRename: (id: string) => void
+  cancelRename: () => void
+  /** Commit a rename and leave rename mode. Applied optimistically and
+   * rolled back if `onRename` rejects. Blank and unchanged labels are
+   * dropped. */
+  rename: (id: string, label: string) => void
+
+  menuOpenId: string | null
+  openMenu: (id: string) => void
+  closeMenu: () => void
+
+  /** Reorder, applied optimistically and rolled back if `onMove` rejects.
+   * Refuses moves the data forbids (into itself, into a non-container). */
+  move: (move: SidebarResourceMove) => Promise<void>
+  /** A move is in flight — further moves are refused until it settles. */
+  movePending: boolean
+
+  /** Live-region text for the last move or rename outcome. */
+  announcement: string
+
+  /** @internal Row wiring the view threads through — drag state, the
+   * hover pill and roving keyboard nav all belong to the rendering. */
+  dnd: AISidebarDndState
+  hover: AISidebarHoverState
+  onRowKeyDown: (event: KeyboardEvent<HTMLDivElement>, row: FlatResource) => void
+  setRowRef: (id: string, node: HTMLDivElement | null) => void
+}
+
+/** @internal */
+export interface AISidebarDndState {
+  draggingId: string | null
+  dropTarget: DropTarget | null
+  onRootDragOver: (event: DragEvent<HTMLDivElement>) => void
+  onDrop: (event: DragEvent<HTMLDivElement>) => void
+  onRowDragStart: (event: DragEvent<HTMLDivElement>, id: string) => void
+  onRowDragEnd: () => void
+  onRowDragOver: (event: DragEvent<HTMLDivElement>, row: FlatResource) => void
+}
+
+/** @internal */
+export interface AISidebarHoverState {
+  hoveredId: string | null
+  /** Shared motion layoutId that lets the pill travel between rows. */
+  layoutId: string
+  onRowHover: (id: string, hovered: boolean) => void
+  clear: () => void
+}
+
+export interface AISidebarProps extends UseAISidebarOptions {
+  /** Never set on the data form — `controller` selects the other one. */
+  controller?: never
   renderIcon?: (item: SidebarResource) => ReactNode
   renderMenu?: (
     item: SidebarResource,
@@ -49,6 +134,25 @@ export interface AISidebarProps {
   className?: string
 }
 
+/** Presentational props, shared by both forms of `<AISidebar>`. */
+export type AISidebarViewProps = Pick<
+  AISidebarProps,
+  | "renderIcon"
+  | "renderMenu"
+  | "renderActionsTrigger"
+  | "ariaLabel"
+  | "className"
+>
+
+/** Drive the block from a `useAISidebar` controller instead of raw props —
+ * the controller carries the data and every handler. */
+export interface AISidebarControllerProps extends AISidebarViewProps {
+  controller: AISidebarController
+}
+
+/** Either form: raw props, or a `useAISidebar` controller. */
+export type AISidebarComponentProps = AISidebarProps | AISidebarControllerProps
+
 export interface FlatResource {
   item: SidebarResource
   depth: number