@exegia/corpora-ui 0.17.0 → 0.19.0

package/dist-lib/lib/ease.d.ts

@@ -1,3 +1,4 @@
+import { Transition, Variants } from 'motion/react';
 export declare const EASE_OUT: readonly [0.16, 1, 0.3, 1];
 export declare const EASE_IN_OUT: readonly [0.77, 0, 0.175, 1];
 export declare const EASE_DRAWER: readonly [0.32, 0.72, 0, 1];
@@ -44,3 +45,5 @@ export declare const SPRING_GLIDE: {
     readonly damping: 50;
     readonly mass: 0.5;
 };
+export declare const SHELL_TRANSITION: Transition;
+export declare const ICON_VARIANTS: Variants;

package/dist-lib/lib/hooks/use-hover-capable.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns true only on devices that have a true hover (mouse / trackpad).
+ * Touch devices fire phantom `:hover` on tap that sticks until tap-elsewhere
+ * — gate hover-only effects (scale lifts, magnetic pulls) behind this.
+ */
+export declare function useHoverCapable(): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exegia/corpora-ui",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "shadcn-ready React UI library for the corpora manuscript-research apps.",
   "license": "MIT",
   "repository": {
@@ -46,6 +46,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cuelume": "^0.2.1",
+    "iconsax-reactjs": "^0.0.8",
     "lucide-react": "^1.31.0",
     "motion": "^12.43.0",
     "motion-icons-react": "^1.1.0",

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

@@ -22,7 +22,7 @@ export function BrowserFrame({
         className
       )}
     >
-      <div className="flex min-h-96 w-full flex-col overflow-hidden rounded-lg border border-border bg-neutral-50 shadow-lg dark:bg-neutral-900 relative">
+      <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="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" />
@@ -46,7 +46,7 @@ export function BrowserFrame({
             </div>
           )}
         </div>
-        <div className={cn("flex flex-1 ", titleBarStyle(titleStyle, "frame"))}>
+        <div className={cn("flex flex-1", titleBarStyle(titleStyle, "frame"))}>
           {children}
         </div>
       </div>

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

@@ -4,7 +4,9 @@ import { PanelLeftIcon } from "lucide-react"
 import * as React from "react"
 
 import {
-  AnimatedSidebar,
+  AnimatedPanel as AnimatedSidebar,
+  AnimatedPanelProvider as AnimatedSidebarProvider,
+  AnimatedPanelTrigger as AnimatedSidebarTrigger,
   AnimatedSidebarContent,
   AnimatedSidebarFooter,
   AnimatedSidebarGroup,
@@ -12,9 +14,7 @@ import {
   AnimatedSidebarGroupLabel,
   AnimatedSidebarHeader,
   AnimatedSidebarMenu,
-  AnimatedSidebarProvider,
-  AnimatedSidebarTrigger,
-} from "@/components/motion/animated-sidebar"
+} from "@/components/blocks/shell"
 import { cn } from "@/lib/utils"
 import { SidebarNavRow } from "@/components/blocks/nav/sidebar-nav-row"
 
@@ -34,7 +34,7 @@ export type {
  * beside your own content. It owns its own sidebar context (⌘B toggles it);
  * pass `open`/`onOpenChange` to drive the rail, and `openMobile`/
  * `onOpenMobileChange` to open the drawer from a header button of your own.
- * Compose the underlying `AnimatedSidebar*` parts directly when a screen
+ * Compose the underlying `AnimatedPanel*` parts directly when a screen
  * needs something this API does not cover.
  */
 export function SidebarBlock({

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

@@ -2,16 +2,15 @@
 
 import * as React from "react"
 
+import type { IRowProps, ISidebarNavItem, ISidebarNavSubItem } from "@/components/blocks/nav/types"
+import { isActive } from "@/components/blocks/nav/utils"
 import {
   AnimatedSidebarMenuButton,
   AnimatedSidebarMenuItem,
   AnimatedSidebarMenuSub,
   AnimatedSidebarMenuSubButton,
   AnimatedSidebarMenuSubItem,
-} from "@/components/motion/animated-sidebar"
-
-import type { IRowProps, ISidebarNavItem, ISidebarNavSubItem } from "@/components/blocks/nav/types"
-import { isActive } from "@/components/blocks/nav/utils"
+} from "@/components/blocks/shell"
 
 export function SidebarNavRow({ item, activeId, onNavigate }: IRowProps) {
   const children = item.items ?? []
@@ -76,4 +75,4 @@ export function SidebarNavRow({ item, activeId, onNavigate }: IRowProps) {
       ) : null}
     </AnimatedSidebarMenuItem>
   )
-}
+}

package/src/components/blocks/scaffold/__tests__/scaffold.test.tsx

@@ -0,0 +1,286 @@
+import { describe, expect, mock, test } from "bun:test"
+import { render, screen, waitFor } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import type { ReactNode } from "react"
+
+import { Scaffold, useScaffold } from "../index"
+import type { TScaffoldPanelChild } from "../type"
+
+function Strip() {
+  return <span>Strip</span>
+}
+
+function Workspace({
+  onSwap,
+  onCloseSecondary,
+  onAdd,
+  tabs,
+  SecondaryPanel = <Strip />,
+}: {
+  onSwap?: () => void
+  onCloseSecondary?: () => void
+  onAdd?: () => void
+  /** Rendered as Actions children — the panel tabs. */
+  tabs?: ReactNode
+  /** Pass null to render the panel without a secondary strip. */
+  SecondaryPanel?: TScaffoldPanelChild | null
+}) {
+  const scaffold = useScaffold()
+
+  return (
+    <Scaffold.Root {...scaffold.providerProps}>
+      <Scaffold.Sidebar>
+        <button onClick={scaffold.toggleInspector} type="button">
+          Toggle inspector
+        </button>
+      </Scaffold.Sidebar>
+      <Scaffold.Main>
+        <Scaffold.Actions onAdd={onAdd}>{tabs}</Scaffold.Actions>
+        <Scaffold.Canvas>
+          <Scaffold.Panel
+            key="alpha"
+            name="Alpha"
+            onCloseSecondary={onCloseSecondary}
+            onSwap={onSwap}
+            SecondaryPanel={SecondaryPanel ?? undefined}
+          >
+            <span>Primary body</span>
+          </Scaffold.Panel>
+        </Scaffold.Canvas>
+        <Scaffold.Inspector>
+          <span>Inspector body</span>
+        </Scaffold.Inspector>
+      </Scaffold.Main>
+    </Scaffold.Root>
+  )
+}
+
+/** The seam menu's compact toggle (icon-only, named by `swapLabel`). */
+const menuToggle = () =>
+  screen.queryByRole("button", { name: "Swap panel content" })
+
+/** Under the id'd `#scaffold-actions` ancestor, happy-dom serves stale
+ * selector-cache results to `waitFor` queries that start while an
+ * AnimatePresence exit is still running — let the exit settle on real
+ * timers, then query once. */
+const settleExit = () => new Promise((resolve) => setTimeout(resolve, 400))
+
+describe("Scaffold", () => {
+  test("renders rail, panel surfaces and secondary strip", () => {
+    render(<Workspace />)
+
+    expect(screen.getByRole("navigation", { name: "Primary" })).toBeDefined()
+    const panel = screen.getByRole("region", { name: "Alpha" })
+    expect(panel.textContent).toContain("Primary body")
+    expect(panel.textContent).toContain("Strip")
+  })
+
+  test("seam menu renders only with a callback; actions stay hidden until opened", () => {
+    const { rerender } = render(<Workspace />)
+    expect(menuToggle()).toBeNull()
+
+    rerender(<Workspace onSwap={() => {}} />)
+    expect(menuToggle()).toBeDefined()
+    // Collapsed: the action segment is aria-hidden and inert.
+    expect(screen.queryByRole("button", { name: "Swap" })).toBeNull()
+
+    // The Close action alone also earns the menu.
+    rerender(<Workspace onCloseSecondary={() => {}} />)
+    expect(menuToggle()).toBeDefined()
+  })
+
+  test("seam menu Close renders only with onCloseSecondary, fires and collapses", async () => {
+    const user = userEvent.setup()
+    const onCloseSecondary = mock(() => {})
+
+    const { rerender } = render(<Workspace onSwap={() => {}} />)
+    await user.click(menuToggle() as HTMLElement)
+    expect(await screen.findByRole("button", { name: "Swap" })).toBeDefined()
+    expect(screen.queryByRole("button", { name: "Close" })).toBeNull()
+
+    rerender(
+      <Workspace onCloseSecondary={onCloseSecondary} onSwap={() => {}} />
+    )
+    await user.click(screen.getByRole("button", { name: "Close" }))
+    expect(onCloseSecondary).toHaveBeenCalledTimes(1)
+
+    // Acting collapses the menu back to the compact toggle.
+    expect(menuToggle()).toBeDefined()
+    expect(screen.queryByRole("button", { name: "Close" })).toBeNull()
+  })
+
+  test("seam menu opens; Swap fires onSwap, flips the panel and collapses the menu", async () => {
+    const user = userEvent.setup()
+    const onSwap = mock(() => {})
+    render(<Workspace onSwap={onSwap} />)
+
+    const panel = screen.getByRole("region", { name: "Alpha" })
+    expect(panel.getAttribute("data-swapped")).toBeNull()
+
+    // The compact toggle trades places with the Expand | Swap actions.
+    await user.click(menuToggle() as HTMLElement)
+    await user.click(await screen.findByRole("button", { name: "Swap" }))
+
+    expect(onSwap).toHaveBeenCalledTimes(1)
+    expect(panel.getAttribute("data-swapped")).toBe("")
+
+    // Acting collapses the menu back to the compact toggle; the actions
+    // leave with their exit animation.
+    expect(
+      await screen.findByRole("button", { name: "Swap panel content" })
+    ).toBeDefined()
+    await waitFor(() =>
+      expect(screen.queryByRole("button", { name: "Swap" })).toBeNull()
+    )
+  })
+
+  test("expand trades the flexible slot and flips the chevron", async () => {
+    const user = userEvent.setup()
+    render(<Workspace onSwap={() => {}} />)
+
+    const panel = screen.getByRole("region", { name: "Alpha" })
+    const [top, bottom] = Array.from(
+      panel.querySelectorAll('[data-slot^="scaffold-sub-panel"]')
+    )
+    expect(top.getAttribute("data-expanded")).toBe("")
+    expect(bottom.getAttribute("data-expanded")).toBeNull()
+
+    await user.click(menuToggle() as HTMLElement)
+    await user.click(await screen.findByRole("button", { name: "Expand" }))
+
+    expect(top.getAttribute("data-expanded")).toBeNull()
+    expect(bottom.getAttribute("data-expanded")).toBe("")
+
+    // Reopen: the chevron reflects the flipped state.
+    await user.click(
+      await screen.findByRole("button", { name: "Swap panel content" })
+    )
+    const expandButton = await screen.findByRole("button", { name: "Expand" })
+    expect(
+      expandButton
+        .querySelector("svg.lucide-chevron-down")
+        ?.classList.contains("rotate-180")
+    ).toBe(true)
+
+    // Expanding again restores the primary slot.
+    await user.click(expandButton)
+    expect(top.getAttribute("data-expanded")).toBe("")
+    expect(bottom.getAttribute("data-expanded")).toBeNull()
+  })
+
+  test("expand chevron mirrors when the panel is swapped", async () => {
+    const user = userEvent.setup()
+    render(<Workspace onSwap={() => {}} />)
+
+    // Swap first — column-reverse puts the strip visually on top.
+    await user.click(menuToggle() as HTMLElement)
+    await user.click(await screen.findByRole("button", { name: "Swap" }))
+
+    // Primary still holds the flexible slot, but the strip that grows
+    // next now sits on top — the chevron points up.
+    await user.click(
+      await screen.findByRole("button", { name: "Swap panel content" })
+    )
+    const expandButton = await screen.findByRole("button", { name: "Expand" })
+    const chevron = () => expandButton.querySelector("svg.lucide-chevron-down")
+    expect(chevron()?.classList.contains("rotate-180")).toBe(true)
+
+    // After expanding, the primary — now visually at the bottom — grows
+    // next: the chevron points down again.
+    await user.click(expandButton)
+    await user.click(
+      await screen.findByRole("button", { name: "Swap panel content" })
+    )
+    expect(chevron()?.classList.contains("rotate-180")).toBe(false)
+  })
+
+  test("seam menu needs a secondary strip", () => {
+    render(<Workspace onSwap={() => {}} SecondaryPanel={null} />)
+
+    expect(menuToggle()).toBeNull()
+  })
+
+  test("actions cluster: Add renders only with onAdd and fires", async () => {
+    const user = userEvent.setup()
+    const onAdd = mock(() => {})
+
+    // Consumers omit onAdd at SCAFFOLD_PANEL_CAPACITY — the segment hides.
+    const { rerender } = render(<Workspace />)
+    expect(screen.queryByRole("button", { name: "Panel" })).toBeNull()
+
+    rerender(<Workspace onAdd={onAdd} />)
+    await user.click(screen.getByRole("button", { name: "Panel" }))
+    expect(onAdd).toHaveBeenCalledTimes(1)
+
+    rerender(<Workspace />)
+    await settleExit()
+    expect(screen.queryByRole("button", { name: "Panel" })).toBeNull()
+  })
+
+  test("panel tabs show their label; close renders only with onClose and fires", async () => {
+    const user = userEvent.setup()
+    const onCloseTab = mock(() => {})
+
+    // Consumers omit onClose on the last remaining panel's tab.
+    const { rerender } = render(
+      <Workspace tabs={<Scaffold.Tab key="alpha">Alpha</Scaffold.Tab>} />
+    )
+    expect(screen.getByText("Alpha")).toBeDefined()
+    expect(screen.queryByRole("button", { name: "Close Alpha" })).toBeNull()
+
+    rerender(
+      <Workspace
+        tabs={
+          <Scaffold.Tab
+            key="alpha"
+            closeLabel="Close Alpha"
+            onClose={onCloseTab}
+          >
+            Alpha
+          </Scaffold.Tab>
+        }
+      />
+    )
+    await user.click(screen.getByRole("button", { name: "Close Alpha" }))
+    expect(onCloseTab).toHaveBeenCalledTimes(1)
+
+    // Closing removes the tab — it animates out of the pill.
+    rerender(<Workspace tabs={null} />)
+    await settleExit()
+    expect(screen.queryByText("Alpha")).toBeNull()
+  })
+
+  test("inspector opens from outside state and hides again", async () => {
+    const user = userEvent.setup()
+    render(<Workspace />)
+
+    const inspector = () =>
+      screen.getByText("Inspector body").closest("aside") as HTMLElement
+    expect(inspector().getAttribute("aria-hidden")).toBe("true")
+
+    await user.click(screen.getByRole("button", { name: "Toggle inspector" }))
+    expect(inspector().getAttribute("aria-hidden")).toBeNull()
+    expect(
+      screen.getByRole("complementary", { name: "Inspector" })
+    ).toBeDefined()
+
+    await user.click(screen.getByRole("button", { name: "Toggle inspector" }))
+    expect(inspector().getAttribute("aria-hidden")).toBe("true")
+  })
+
+  test("root manages inspector state itself when uncontrolled", () => {
+    render(
+      <Scaffold.Root defaultInspectorOpen>
+        <Scaffold.Main>
+          <Scaffold.Inspector>
+            <span>Drawer</span>
+          </Scaffold.Inspector>
+        </Scaffold.Main>
+      </Scaffold.Root>
+    )
+
+    expect(
+      screen.getByRole("complementary", { name: "Inspector" })
+    ).toBeDefined()
+  })
+})

package/src/components/blocks/scaffold/constants.ts

@@ -0,0 +1,32 @@
+/** Icon-rail width in px (the rail sits directly on the desktop backdrop). */
+export const SCAFFOLD_SIDEBAR_WIDTH = 64
+
+/** Inspector drawer width in px. */
+export const SCAFFOLD_INSPECTOR_WIDTH = 272
+
+/** Most panels the canvas holds at once — omit Actions' `onAdd` when the
+ * count reaches it so the Add segment hides. */
+export const SCAFFOLD_PANEL_CAPACITY = 3
+
+/** Gap in px between the drawer/actions and the viewport edges. */
+export const SCAFFOLD_EDGE_GUTTER = 10
+
+/** Vertical room in px reserved above the canvas for the actions cluster. */
+export const SCAFFOLD_HEADER_HEIGHT = 52
+
+/** Height in px of a panel's secondary strip. */
+export const SCAFFOLD_SECONDARY_HEIGHT = 52
+
+/** Gap in px between a panel's primary surface and its secondary strip. */
+export const SCAFFOLD_PANEL_GAP = 10
+
+/** How long the seam menu lingers expanded after the pointer leaves it (ms)
+ * before it collapses back to the compact toggle. The timer keeps counting
+ * even when the pointer leaves the window entirely. */
+export const SCAFFOLD_MENU_COLLAPSE_DELAY = 4000
+
+/** Morph duration in seconds for drawer slides and panel layout shifts. */
+export const SCAFFOLD_MORPH_DURATION = 0.3
+
+/** `--ease-smooth-out` as a motion/react easing tuple. */
+export const SCAFFOLD_EASE = [0.22, 1, 0.36, 1] as const

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

@@ -0,0 +1,41 @@
+import { PanelCloseButton } from "./panel-close-button"
+import { PanelMenuButton } from "./panel-menu-button.tsx"
+import { ScaffoldActions } from "./scaffold-actions"
+import { ScaffoldCanvas } from "./scaffold-canvas"
+import { ScaffoldInspector } from "./scaffold-inspector"
+import { ScaffoldMain } from "./scaffold-main"
+import { ScaffoldPanel } from "./scaffold-panel"
+import { ScaffoldRoot } from "./scaffold-root"
+import { ScaffoldSidebar } from "./scaffold-sidebar"
+import { ScaffoldTab } from "./scaffold-tab"
+import { ScaffoldSubPanel } from "@/components/blocks/scaffold/scaffold-sub-panel.tsx"
+
+export { useScaffoldContext } from "./scaffold-context"
+export { useScaffold } from "./use-scaffold"
+export type * from "./type"
+export * from "./constants"
+
+export {
+  PanelCloseButton,
+  PanelMenuButton,
+  ScaffoldActions,
+  ScaffoldCanvas,
+  ScaffoldInspector,
+  ScaffoldMain,
+  ScaffoldPanel,
+  ScaffoldRoot,
+  ScaffoldSidebar,
+  ScaffoldTab,
+}
+
+export const Scaffold = {
+  Root: ScaffoldRoot,
+  Sidebar: ScaffoldSidebar,
+  Main: ScaffoldMain,
+  Actions: ScaffoldActions,
+  Canvas: ScaffoldCanvas,
+  Panel: ScaffoldPanel,
+  Tab: ScaffoldTab,
+  Inspector: ScaffoldInspector,
+  SubPanel: ScaffoldSubPanel,
+}

package/src/components/blocks/scaffold/panel-close-button.tsx

@@ -0,0 +1,36 @@
+"use client"
+
+import { RiCloseLine } from "@remixicon/react"
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+import type { PanelFloatingButtonProps } from "./type"
+import { floatingButtonClass, revealOnPanelHoverClass } from "./utils"
+
+/** Floating close affordance in a panel's top-right corner. */
+export function PanelCloseButton({
+  onClick,
+  label,
+  sound = true,
+  className,
+}: PanelFloatingButtonProps): React.ReactElement {
+  return (
+    <button
+      id="scaffold-panel-close-button"
+      aria-label={label}
+      className={cn(
+        floatingButtonClass,
+        revealOnPanelHoverClass,
+        "absolute top-4 right-3.5 z-10",
+        className
+      )}
+      data-cuelume-press={sound ? "" : undefined}
+      data-cuelume-release={sound ? "" : undefined}
+      data-slot="scaffold-panel-close"
+      onClick={onClick}
+      type="button"
+    >
+      <RiCloseLine aria-hidden className="size-4" />
+    </button>
+  )
+}