@exegia/corpora-ui 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exegia/corpora-ui",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "shadcn-ready React UI library for the corpora manuscript-research apps.",
   "license": "MIT",
   "repository": {
@@ -46,8 +46,9 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cuelume": "^0.2.1",
-    "lucide-react": "^1.27.0",
+    "lucide-react": "^1.31.0",
     "motion": "^12.43.0",
+    "motion-icons-react": "^1.1.0",
     "tailwind-merge": "^3.6.0"
   },
   "devDependencies": {

package/src/components/blocks/layout.ts

@@ -0,0 +1,7 @@
+import ShellLayout from "@/components/blocks/shell"
+
+const Layout = {
+  Main: ShellLayout
+}
+
+export default Layout

package/src/components/{agents → blocks/nav/sidebar}/ai-sidebar.tsx

@@ -2,9 +2,9 @@
 
 import { AnimatePresence } from "motion/react";
 import { cn } from "@/lib/utils";
-import type { AISidebarProps } from "@/components/agents/type.ts"
-import { useAISidebar } from "@/components/agents/use-ai-sidebar.ts"
-import { ResourceRow } from "@/components/agents/sidebar-row.tsx"
+import type { AISidebarProps, FlatResource } from "./type"
+import { useAISidebar, type UseAISidebarOptions } from "./use-ai-sidebar"
+import { ResourceRow } from "./sidebar-row"
 
 export function AISidebar({
   renderIcon,
@@ -41,7 +41,7 @@ export function AISidebar({
     commitRename,
     handleMenuOpenChange,
     setRowRef,
-  } = useAISidebar(options);
+  } = useAISidebar(options as UseAISidebarOptions);
 
   return (
     <>
@@ -53,13 +53,13 @@ export function AISidebar({
         onDrop={handleDrop}
         onMouseLeave={clearHover}
         className={cn(
-          "relative flex min-w-0 flex-col gap-0.5 [overflow-anchor:none] group-data-[state=collapsed]/sidebar:hidden",
-          draggingId && "select-none pb-9",
-          className,
+          "relative min-w-0 flex-col gap-0.5 [overflow-anchor:none] group-data-[state=collapsed]/sidebar:hidden",
+          draggingId && "pb-9 select-none",
+          className
         )}
       >
         <AnimatePresence initial={false}>
-          {flat.map((row) => (
+          {flat.map((row: FlatResource) => (
             <ResourceRow
               key={row.item.id}
               row={row}
@@ -72,14 +72,10 @@ export function AISidebar({
               renaming={renamingId === row.item.id}
               hoverActive={hoveredId !== null && !draggingId}
               hoverPill={
-                hoveredId === row.item.id &&
-                !draggingId &&
-                !row.item.disabled
+                hoveredId === row.item.id && !draggingId && !row.item.disabled
               }
               hoverLayoutId={hoverLayoutId}
-              onHoverChange={(hovered) =>
-                handleRowHover(row.item.id, hovered)
-              }
+              onHoverChange={(hovered) => handleRowHover(row.item.id, hovered)}
               onFocus={() => setFocusedId(row.item.id)}
               onSelect={() => select(row.item.id)}
               onToggle={() => toggle(row.item.id)}
@@ -100,7 +96,7 @@ export function AISidebar({
           ))}
         </AnimatePresence>
 
-        {draggingId ? (
+        {draggingId && (
           <div
             aria-hidden="true"
             data-active={dropTarget?.id === null || undefined}
@@ -108,11 +104,11 @@ export function AISidebar({
           >
             Move to top level
           </div>
-        ) : null}
+        )}
       </div>
       <span className="sr-only" aria-live="polite">
         {announcement}
       </span>
     </>
-  );
+  )
 }

package/src/components/{agents → blocks/nav/sidebar}/marquee-label.tsx

@@ -1,6 +1,6 @@
 import { motion, useReducedMotion } from "motion/react"
 import { useEffect, useRef, useState } from "react"
-import { ROW_REVEAL } from "@/components/agents/utils.ts"
+import { ROW_REVEAL } from "./utils.ts"
 
 export function MarqueeLabel({
   active,

package/src/components/{agents → blocks/nav/sidebar}/sidebar-icon.tsx

@@ -1,4 +1,4 @@
-import type { SidebarResource } from "@/components/agents/type.ts"
+import type { SidebarResource } from "./type.ts"
 import { Bookmark, FileText, Folder, FolderOpen } from "lucide-react"
 
 export function SidebarIcon(item: SidebarResource, expanded: boolean) {

package/src/components/{agents → blocks/nav/sidebar}/sidebar-row.tsx

@@ -5,7 +5,7 @@ import {
   useState,
   type MouseEvent,
 } from "react"
-import type { ResourceRowProps } from "@/components/agents/type.ts"
+import type { ResourceRowProps } from "./type"
 import {
   AnimatePresence,
   motion,
@@ -15,9 +15,9 @@ import {
 import { ChevronRight, MoreHorizontal, Pencil } from "lucide-react"
 import { SPRING_LAYOUT } from "@/lib/ease.ts"
 import { cn } from "@/lib/utils.ts"
-import { canContain } from "@/components/agents/utils.ts"
-import { SidebarIcon } from "@/components/agents/sidebar-icon.tsx"
-import { MarqueeLabel } from "@/components/agents/marquee-label.tsx"
+import { canContain } from "./utils"
+import { SidebarIcon } from "./sidebar-icon"
+import { MarqueeLabel } from "./marquee-label"
 import {
   MorphPopover,
   MorphPopoverContent,

package/src/components/{agents → blocks/nav/sidebar}/use-ai-sidebar.ts

@@ -16,7 +16,7 @@ import type {
   FlatResource,
   SidebarResource,
   SidebarResourceMove,
-} from "@/components/agents/type.ts"
+} from "./type.ts"
 import {
   canContain,
   containsResource,
@@ -24,7 +24,7 @@ import {
   flattenResources,
   moveResource,
   renameResource,
-} from "@/components/agents/utils.ts"
+} from "./utils.ts"
 
 export type UseAISidebarOptions = Pick<
   AISidebarProps,

package/src/components/{agents → blocks/nav/sidebar}/utils.ts

@@ -1,5 +1,5 @@
 import { EASE_OUT } from "@/lib/ease.ts"
-import type { FlatResource, SidebarResource, SidebarResourceDropPosition, SidebarResourceMove } from "@/components/agents/type.ts"
+import type { FlatResource, SidebarResource, SidebarResourceDropPosition, SidebarResourceMove } from "./type.ts"
 
 export const ROW_REVEAL = {
   duration: 0.16,

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

@@ -62,14 +62,22 @@ export function SidebarBlock({
   return (
     <AnimatedSidebarProvider
       // The provider ships a full-page flex shell; this block is just the
-      // panel, so the shell is flattened back to the panel's own box.
+      // panel, so the shell is flattened back to the panel's own box. The
+      // block is a single panel, so its scalar open props map onto the
+      // provider's side-keyed records under the block's own `side`.
       className="h-full min-h-0 w-auto"
-      defaultOpen={defaultOpen}
-      defaultOpenMobile={defaultOpenMobile}
-      onOpenChange={onOpenChange}
-      onOpenMobileChange={onOpenMobileChange}
-      open={open}
-      openMobile={openMobile}
+      defaultOpen={{ [side]: defaultOpen ?? true }}
+      defaultOpenMobile={
+        defaultOpenMobile === undefined ? undefined : { [side]: defaultOpenMobile }
+      }
+      onOpenChange={(nextOpen, changedSide) => {
+        if (changedSide === side) onOpenChange?.(nextOpen)
+      }}
+      onOpenMobileChange={(nextOpen, changedSide) => {
+        if (changedSide === side) onOpenMobileChange?.(nextOpen)
+      }}
+      open={open === undefined ? undefined : { [side]: open }}
+      openMobile={openMobile === undefined ? undefined : { [side]: openMobile }}
       style={{
         ...(width ? { "--sidebar-width": width } : null),
         ...(iconWidth ? { "--sidebar-width-icon": iconWidth } : null),

package/src/components/blocks/shell/__tests__/shell-layout.test.tsx

@@ -0,0 +1,178 @@
+import { describe, expect, mock, test } from "bun:test"
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+
+import { ShellLayout } from "../shell-layout"
+import { useShellPanels } from "../use-shell-panels"
+import type { TPanelMap, UseShellPanelsOptions } from "../type"
+
+const PANELS: TPanelMap = {
+  left: {
+    id: "nav",
+    name: "Navigation",
+    component: <div>Nav body</div>,
+    open: true,
+    side: "left",
+  },
+  right: {
+    id: "inspector",
+    name: "Inspector",
+    component: <div>Inspector body</div>,
+    open: false,
+    side: "right",
+  },
+}
+
+/** The desktop rail / drawer elements, queried by their landmark roles. */
+function leftRail() {
+  return screen.getByRole("navigation", { name: "Primary navigation" })
+}
+
+function rightDrawer(name = "Inspector") {
+  return screen.getByRole("complementary", { name })
+}
+
+describe("ShellLayout", () => {
+  test("renders panel content by side and children in the inset", () => {
+    render(
+      <ShellLayout panels={PANELS} variant="web">
+        <div>Main content</div>
+      </ShellLayout>
+    )
+
+    expect(leftRail().textContent).toContain("Nav body")
+    expect(rightDrawer().textContent).toContain("Inspector body")
+    expect(screen.getByRole("main").textContent).toContain("Main content")
+  })
+
+  test("names the right drawer after its panel", () => {
+    render(<ShellLayout panels={PANELS} variant="web" />)
+
+    expect(rightDrawer("Inspector")).toBeDefined()
+  })
+
+  test("the header triggers toggle their own side", async () => {
+    const user = userEvent.setup()
+    render(<ShellLayout panels={PANELS} variant="web" />)
+
+    const leftTrigger = screen.getByRole("button", { name: "Toggle sidebar" })
+    const rightTrigger = screen.getByRole("button", { name: "Toggle panel" })
+
+    expect(leftRail().getAttribute("data-state")).toBe("expanded")
+    expect(rightDrawer().getAttribute("data-state")).toBe("collapsed")
+
+    await user.click(leftTrigger)
+    expect(leftRail().getAttribute("data-state")).toBe("collapsed")
+    expect(leftTrigger.getAttribute("aria-expanded")).toBe("false")
+    // The other side is untouched.
+    expect(rightDrawer().getAttribute("data-state")).toBe("collapsed")
+
+    await user.click(rightTrigger)
+    expect(rightDrawer().getAttribute("data-state")).toBe("expanded")
+    expect(rightTrigger.getAttribute("aria-expanded")).toBe("true")
+    expect(leftRail().getAttribute("data-state")).toBe("collapsed")
+  })
+
+  test("a panel's own open flag seeds its side's initial state", () => {
+    render(
+      <ShellLayout
+        panels={{
+          ...PANELS,
+          right: { ...PANELS.right!, open: true },
+        }}
+        variant="web"
+      />
+    )
+
+    expect(rightDrawer().getAttribute("data-state")).toBe("expanded")
+  })
+
+  test("an explicit defaultOpen record wins over the panel's flag", () => {
+    render(
+      <ShellLayout
+        defaultOpen={{ left: false, right: false }}
+        panels={{
+          ...PANELS,
+          right: { ...PANELS.right!, open: true },
+        }}
+        variant="web"
+      />
+    )
+
+    expect(leftRail().getAttribute("data-state")).toBe("collapsed")
+    expect(rightDrawer().getAttribute("data-state")).toBe("collapsed")
+  })
+
+  test("⌘B toggles the left rail", async () => {
+    const user = userEvent.setup()
+    render(<ShellLayout panels={PANELS} variant="web" />)
+
+    expect(leftRail().getAttribute("data-state")).toBe("expanded")
+
+    await user.keyboard("{Meta>}b{/Meta}")
+    expect(leftRail().getAttribute("data-state")).toBe("collapsed")
+
+    await user.keyboard("{Meta>}b{/Meta}")
+    expect(leftRail().getAttribute("data-state")).toBe("expanded")
+  })
+})
+
+function HookedShell({
+  onPanelChange,
+}: {
+  onPanelChange?: UseShellPanelsOptions["onPanelChange"]
+}) {
+  const panels = useShellPanels({ onPanelChange })
+
+  return (
+    <ShellLayout {...panels.providerProps} panels={PANELS} variant="web">
+      <button onClick={() => panels.toggle("right")} type="button">
+        External toggle
+      </button>
+    </ShellLayout>
+  )
+}
+
+describe("useShellPanels", () => {
+  test("reports every change as (open, side)", async () => {
+    const user = userEvent.setup()
+    const onPanelChange = mock(() => {})
+    render(<HookedShell onPanelChange={onPanelChange} />)
+
+    await user.click(screen.getByRole("button", { name: "Toggle panel" }))
+    expect(onPanelChange).toHaveBeenLastCalledWith(true, "right")
+
+    await user.click(screen.getByRole("button", { name: "Toggle sidebar" }))
+    expect(onPanelChange).toHaveBeenLastCalledWith(false, "left")
+
+    expect(onPanelChange).toHaveBeenCalledTimes(2)
+  })
+
+  test("controls the shell from outside it", async () => {
+    const user = userEvent.setup()
+    render(<HookedShell />)
+
+    expect(rightDrawer().getAttribute("data-state")).toBe("collapsed")
+
+    await user.click(screen.getByRole("button", { name: "External toggle" }))
+    expect(rightDrawer().getAttribute("data-state")).toBe("expanded")
+
+    await user.click(screen.getByRole("button", { name: "External toggle" }))
+    expect(rightDrawer().getAttribute("data-state")).toBe("collapsed")
+  })
+
+  test("the shell's own triggers round-trip through the hook's state", async () => {
+    const user = userEvent.setup()
+    render(<HookedShell />)
+
+    // Trigger click flows through providerProps into hook state and back —
+    // the drawer only opens because the hook re-rendered the controlled
+    // provider.
+    await user.click(screen.getByRole("button", { name: "Toggle panel" }))
+    expect(rightDrawer().getAttribute("data-state")).toBe("expanded")
+
+    // The external toggle sees that state, so it closes rather than opens.
+    await user.click(screen.getByRole("button", { name: "External toggle" }))
+    expect(rightDrawer().getAttribute("data-state")).toBe("collapsed")
+  })
+})

package/src/components/blocks/shell/index.ts

@@ -1,3 +1,7 @@
-export * from "./shell-layout"
+import { ShellLayout } from "./shell-layout"
+
 export type * from "./type"
+export * from "./use-shell-panels"
 export * from "./utils"
+
+export { ShellLayout as default }

package/src/components/blocks/shell/shell-layout.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import { MenuIcon, PanelRightIcon } from "lucide-react"
+import { MotionIcon } from "motion-icons-react"
 import * as React from "react"
 
 import {
@@ -10,44 +10,51 @@ import {
   AnimatedSidebarTrigger,
 } from "@/components/motion/animated-sidebar"
 import { cn } from "@/lib/utils"
-import type { ShellLayoutProps } from "./type"
+import type { ShellLayoutProps, ShellPanelControlProps } from "./type"
 import { TITLE_BAR_HEIGHT } from "./utils"
 import type { ClassNameValue } from "tailwind-merge"
 
 export function ShellLayout({
   children,
-  open,
-  defaultOpen,
-  onOpenChange,
-  rightDrawer,
-  rightOpen,
-  defaultRightOpen,
-  onRightOpenChange,
   variant = "desktop",
+  panels,
   className,
+  defaultOpen,
+  ...panelControlProps
 }: ShellLayoutProps): React.ReactElement {
 
   const background: ClassNameValue = `bg-linear-to-tr/increasing from-neutral-200 via-neutral-100 to-stone-200 dark:from-neutral-900 dark:via-neutral-950 dark:to-stone-950`
+
+  // Each panel seeds its own side's initial state (`defaultOpen ?? open`);
+  // an explicit `defaultOpen` record — usually from useShellPanels — wins
+  // per side.
+  const initialOpen: ShellPanelControlProps["defaultOpen"] = {
+    ...(panels?.left && {
+      left: panels.left.defaultOpen ?? panels.left.open,
+    }),
+    ...(panels?.right && {
+      right: panels.right.defaultOpen ?? panels.right.open,
+    }),
+    ...(defaultOpen)
+  }
+
   return (
     <AnimatedSidebarProvider
-      className={cn("block-full", className, background, 'relative pr-2')}
-      defaultOpen={defaultOpen}
-      defaultOpenRight={defaultRightOpen}
-      onOpenChange={onOpenChange}
-      onOpenRightChange={onRightOpenChange}
-      open={open}
-      openRight={rightOpen}
+      {...panelControlProps}
+      defaultOpen={initialOpen}
+      className={cn("block-full", className, background, "relative pr-2")}
       style={{
         paddingTop: variant === "desktop" ? TITLE_BAR_HEIGHT : 0
       }}
     >
       <AnimatedSidebar
         ariaLabel="Primary navigation"
-        className={cn("")}
         collapsible="icon"
         role="navigation"
         variant="inset"
-      ></AnimatedSidebar>
+      >
+        {panels?.left?.component}
+      </AnimatedSidebar>
 
       <AnimatedSidebarInset
         className={cn(
@@ -58,12 +65,12 @@ export function ShellLayout({
         <header className="flex h-16 items-center justify-between gap-3 px-4 sm:px-6">
           <div className="flex min-w-0 items-center gap-3">
             <AnimatedSidebarTrigger>
-              <MenuIcon className="size-5" />
+              <MotionIcon name="PanelLeft" size={24} animation="press" />
             </AnimatedSidebarTrigger>
           </div>
           <div className="flex shrink-0 items-center gap-3">
             <AnimatedSidebarTrigger aria-label="Toggle panel" side="right">
-              <PanelRightIcon className="size-5" />
+              <MotionIcon name="PanelRight" size={24} animation="press" />
             </AnimatedSidebarTrigger>
           </div>
         </header>
@@ -72,10 +79,8 @@ export function ShellLayout({
         </div>
       </AnimatedSidebarInset>
 
-
-
       <AnimatedSidebar
-        ariaLabel="Secondary panel"
+        ariaLabel={panels?.right?.name ?? "Secondary panel"}
         // Below md the panel is portal led over the page, so it carries the
         // surface itself; the desktop rail keeps it on the inner panel.
         className={cn("max-md:border-l max-md:border-neutral-200 max-md:bg-white dark:max-md:border-neutral-700 dark:max-md:bg-card")}
@@ -92,7 +97,7 @@ export function ShellLayout({
         side="right"
         variant="inset"
       >
-        {rightDrawer}
+        {panels?.right?.component}
       </AnimatedSidebar>
     </AnimatedSidebarProvider>
   )

package/src/components/blocks/shell/type.ts

@@ -1,50 +1,92 @@
-// import type {
-//   ISidebarNavItem,
-//   ISidebarNavSection,
-//   ISidebarNavSubItem,
-// } from "@/components/blocks/nav/types"
+import type { ReactNode } from "react"
 
+import type {
+  AnimatedSidebarProviderProps,
+  SidebarSide,
+} from "@/components/motion/animated-sidebar"
 
 export interface ShellAction {
   id: string
   label: string
-  icon: React.ReactNode
-  badge?: React.ReactNode
+  icon: ReactNode
+  badge?: ReactNode
   onSelect?: () => void
 }
 
 export interface ShellWorkspace {
   name: string
-  logo?: React.ReactNode
-  meta?: React.ReactNode
+  logo?: ReactNode
+  meta?: ReactNode
 }
 
-export interface ShellLayoutProps {
-  children?: React.ReactNode
- // sections?: ISidebarNavSection[]
-  //activeId?: string
-//  onNavigate?: (item: ISidebarNavItem | ISidebarNavSubItem) => void
-//  workspace?: ShellWorkspace
-  //sidebarFooter?: React.ReactNode
- // topActions?: ShellAction[]
-  //title?: React.ReactNode
-  //eyebrow?: React.ReactNode
-  //searchPlaceholder?: string
-  //searchShortcut?: React.ReactNode
-  open?: boolean
+export interface IPanel {
+  id: string
+  name: string
+  component: ReactNode
+  open: boolean
   defaultOpen?: boolean
-  onOpenChange?: (open: boolean) => void
-  /** Content of the right drawer. It has no icon rail — it is either fully
-   * shown or fully hidden. */
-  rightDrawer?: React.ReactNode
-  rightOpen?: boolean
-  defaultRightOpen?: boolean
-  onRightOpenChange?: (open: boolean) => void
- // openMobile?: boolean
-  //defaultOpenMobile?: boolean
-  //onOpenMobileChange?: (open: boolean) => void
+  side: "left" | "bottom" | "right" | "sidebar"
+}
+
+/** The side a panel docks to, as a value union (`IPanel["side"]`).
+ * `Pick<IPanel, "side">` would be the object type `{ side: ... }`, which can
+ * neither key a Record nor travel as a plain callback argument. */
+export type TPanelSide = IPanel["side"]
+
+/** Panel content keyed by the side it docks to. `Side` narrows the map to
+ * the sides a surface actually renders (the shell renders left and right).
+ * Entries are optional — a shell with no bottom dock simply has no `bottom`
+ * key. Where an entry's own `side` field disagrees with its key, the key
+ * wins. */
+export type TPanelMap<Side extends TPanelSide = TPanelSide> = Partial<
+  Record<Side, IPanel>
+>
+
+/** The open/close surface of the shell's panels, lifted straight from
+ * AnimatedSidebarProvider — every prop is keyed by side, there are no
+ * explicit per-side props. `useShellPanels` produces the controlled subset
+ * of these as `providerProps`. */
+export type ShellPanelControlProps = Pick<
+  AnimatedSidebarProviderProps,
+  | "open"
+  | "defaultOpen"
+  | "onOpenChange"
+  | "openMobile"
+  | "defaultOpenMobile"
+  | "onOpenMobileChange"
+>
+
+export interface UseShellPanelsOptions {
+  /** Initial desktop open state per side, merged over
+   * `{ left: true, right: false }`. */
+  defaultOpen?: AnimatedSidebarProviderProps["defaultOpen"]
+  /** Initial mobile overlay state per side — every side starts closed. */
+  defaultOpenMobile?: AnimatedSidebarProviderProps["defaultOpenMobile"]
+  /** Panel change event returning both the next open state and the side of
+   * the panel the change comes from. Mobile overlay changes report the same
+   * side as their desktop counterpart. */
+  onPanelChange?: (open: boolean, side: TPanelSide) => void
+}
+
+export interface ShellPanelControls {
+  /** Live desktop open state, keyed by side. */
+  open: Record<SidebarSide, boolean>
+  /** Live mobile overlay state, keyed by side. */
+  openMobile: Record<SidebarSide, boolean>
+  setOpen: (open: boolean, side: SidebarSide) => void
+  setOpenMobile: (open: boolean, side: SidebarSide) => void
+  /** Desktop-only convenience — the in-shell triggers already pick the
+   * mobile state themselves when the viewport is narrow. */
+  toggle: (side: SidebarSide) => void
+  /** Spread onto ShellLayout (or AnimatedSidebarProvider directly). */
+  providerProps: ShellPanelControlProps
+}
+
+export interface ShellLayoutProps extends ShellPanelControlProps {
+  children?: ReactNode
+  /** Content for the shell's panels, keyed by the side. The shell renders
+   * the `left` rail and the `right` drawer; other sides are reserved. */
+  panels?: TPanelMap
   className?: string
-   variant: 'web' | 'desktop'
-  //sidebarClassName?: string
-  //contentClassName?: string
+  variant?: "web" | "desktop"
 }