@exegia/corpora-ui 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exegia/corpora-ui",
-  "version": "0.14.0",
+  "version": "0.16.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/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,197 @@
+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 trigger node replaces the default icon, keeping the toggle", async () => {
+    const user = userEvent.setup()
+    render(
+      <ShellLayout
+        panels={{
+          ...PANELS,
+          right: { ...PANELS.right!, trigger: <span>Custom trigger</span> },
+        }}
+        variant="web"
+      />
+    )
+
+    const rightTrigger = screen.getByRole("button", { name: "Toggle panel" })
+    expect(rightTrigger.textContent).toContain("Custom trigger")
+
+    await user.click(rightTrigger)
+    expect(rightDrawer().getAttribute("data-state")).toBe("expanded")
+  })
+
+  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,6 +1,7 @@
 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,16 @@ 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" />
+              {panels?.left?.trigger ?? (
+                <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" />
+              {panels?.right?.trigger ?? (
+                <MotionIcon name="PanelRight" size={24} animation="press" />
+              )}
             </AnimatedSidebarTrigger>
           </div>
         </header>
@@ -72,10 +83,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 +101,7 @@ export function ShellLayout({
         side="right"
         variant="inset"
       >
-        {rightDrawer}
+        {panels?.right?.component}
       </AnimatedSidebar>
     </AnimatedSidebarProvider>
   )

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

@@ -1,30 +1,96 @@
-import React from "react"
+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
-  open?: boolean
+export interface IPanel {
+  id: string
+  name: string
+  component: ReactNode
+  /** Replaces the default icon inside the panel's header trigger. The shell
+   * keeps the trigger button itself (toggle wiring, aria-label) — this only
+   * swaps what renders inside it. */
+  trigger?: 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
+  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'
+  variant?: "web" | "desktop"
 }

package/src/components/blocks/shell/use-shell-panels.ts

@@ -0,0 +1,78 @@
+"use client"
+
+import { useCallback, useMemo, useState } from "react"
+
+import type { SidebarSide } from "@/components/motion/animated-sidebar"
+import type {
+  ShellPanelControlProps,
+  ShellPanelControls,
+  UseShellPanelsOptions,
+} from "./type"
+
+/**
+ * Owns the open/close state of the shell's panels, keyed by side, and
+ * reports every change through a single `onPanelChange(open, side)`
+ * callback. Spread the returned `providerProps` onto ShellLayout; the
+ * setters and `toggle` are for UI that lives outside the shell (title-bar
+ * buttons, command palette, shortcuts).
+ */
+export function useShellPanels({
+  defaultOpen,
+  defaultOpenMobile,
+  onPanelChange,
+}: UseShellPanelsOptions = {}): ShellPanelControls {
+  const [open, setOpenState] = useState<Record<SidebarSide, boolean>>(() => ({
+    left: defaultOpen?.left ?? true,
+    right: defaultOpen?.right ?? false,
+  }))
+  const [openMobile, setOpenMobileState] = useState<
+    Record<SidebarSide, boolean>
+  >(() => ({
+    left: defaultOpenMobile?.left ?? false,
+    right: defaultOpenMobile?.right ?? false,
+  }))
+
+  const setOpen = useCallback(
+    (nextOpen: boolean, side: SidebarSide) => {
+      setOpenState((prev) =>
+        prev[side] === nextOpen ? prev : { ...prev, [side]: nextOpen }
+      )
+      onPanelChange?.(nextOpen, side)
+    },
+    [onPanelChange]
+  )
+
+  const setOpenMobile = useCallback(
+    (nextOpen: boolean, side: SidebarSide) => {
+      setOpenMobileState((prev) =>
+        prev[side] === nextOpen ? prev : { ...prev, [side]: nextOpen }
+      )
+      onPanelChange?.(nextOpen, side)
+    },
+    [onPanelChange]
+  )
+
+  const toggle = useCallback(
+    (side: SidebarSide) => setOpen(!open[side], side),
+    [open, setOpen]
+  )
+
+  const providerProps = useMemo<ShellPanelControlProps>(
+    () => ({
+      open,
+      onOpenChange: setOpen,
+      openMobile,
+      onOpenMobileChange: setOpenMobile,
+    }),
+    [open, openMobile, setOpen, setOpenMobile]
+  )
+
+  return {
+    open,
+    openMobile,
+    setOpen,
+    setOpenMobile,
+    toggle,
+    providerProps,
+  }
+}