@exegia/corpora-ui 0.19.0 → 0.21.0

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

@@ -1,9 +1,10 @@
 import { describe, expect, mock, test } from "bun:test"
-import { render, screen } from "@testing-library/react"
+import { act, 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 { SHELL_WIDTHS } from "../utils"
 import type { TPanelMap, UseShellPanelsOptions } from "../type"
 
 const PANELS: TPanelMap = {
@@ -23,6 +24,68 @@ const PANELS: TPanelMap = {
   },
 }
 
+/** The shell resolves its columns from CSS variables with hidden probe
+ * elements. happy-dom has no layout engine, so every probe measures 0 and the
+ * fit rule fails open — answer the probes with the real px behind each
+ * variable so the rule works on the numbers it ships with:
+ *
+ *   rail 256 (56 folded) + body 360 + panel 320
+ *
+ * Only probes are intercepted; every other box keeps happy-dom's answer. */
+function stubShellWidths() {
+  const px = Object.fromEntries(
+    Object.entries(SHELL_WIDTHS).map(([name, value]) => [
+      name,
+      Number.parseFloat(value),
+    ])
+  )
+  const original = HTMLElement.prototype.getBoundingClientRect
+  HTMLElement.prototype.getBoundingClientRect = function (this: HTMLElement) {
+    const isProbe =
+      this.style.visibility === "hidden" && this.style.position === "absolute"
+    if (!isProbe) return original.call(this)
+
+    const variable = /var\((--[a-z-]+)\)/.exec(this.style.width)?.[1]
+    return { width: (variable && px[variable]) || 0 } as DOMRect
+  }
+  return () => {
+    HTMLElement.prototype.getBoundingClientRect = original
+  }
+}
+
+interface HappyDOMWindow {
+  happyDOM?: { setViewport: (viewport: { width: number }) => void }
+}
+
+/** Resize the viewport the way the shell hears it: happy-dom's own viewport
+ * plus the `resize` event, inside `act` so the remeasure lands in this tick. */
+function resizeViewport(width: number) {
+  act(() => {
+    ;(globalThis as HappyDOMWindow).happyDOM?.setViewport({ width })
+    window.dispatchEvent(new Event("resize"))
+  })
+}
+
+/** happy-dom's default, restored between viewport tests. */
+const WIDE_VIEWPORT = 1024
+
+/** Mount the shell at `width` px of viewport with real column widths in play.
+ * The returned function puts both back — inside `act`, because happy-dom
+ * fires `resize` on `setViewport` and the shell (still mounted until
+ * cleanup) remeasures on it. */
+function shellViewport(width: number) {
+  const restoreWidths = stubShellWidths()
+  ;(globalThis as HappyDOMWindow).happyDOM?.setViewport({ width })
+  return () => {
+    restoreWidths()
+    act(() => {
+      ;(globalThis as HappyDOMWindow).happyDOM?.setViewport({
+        width: WIDE_VIEWPORT,
+      })
+    })
+  }
+}
+
 /** The desktop rail / drawer elements, queried by their landmark roles. */
 function leftRail() {
   return screen.getByRole("navigation", { name: "Primary navigation" })
@@ -73,7 +136,7 @@ describe("ShellLayout", () => {
     expect(leftRail().getAttribute("data-state")).toBe("collapsed")
   })
 
-  test("a panel's trigger node replaces the default icon, keeping the toggle", async () => {
+  test("the shell owns the trigger icon, ignoring a panel's trigger node", async () => {
     const user = userEvent.setup()
     render(
       <ShellLayout
@@ -86,12 +149,19 @@ describe("ShellLayout", () => {
     )
 
     const rightTrigger = screen.getByRole("button", { name: "Toggle panel" })
-    expect(rightTrigger.textContent).toContain("Custom trigger")
+    expect(rightTrigger.textContent).not.toContain("Custom trigger")
 
     await user.click(rightTrigger)
     expect(rightDrawer().getAttribute("data-state")).toBe("expanded")
   })
 
+  test("a side with no panel gets no header trigger", () => {
+    render(<ShellLayout panels={{ left: PANELS.left! }} variant="web" />)
+
+    expect(screen.getByRole("button", { name: "Toggle sidebar" })).toBeDefined()
+    expect(screen.queryByRole("button", { name: "Toggle panel" })).toBeNull()
+  })
+
   test("a panel's own defaultOpen flag seeds its side's initial state", () => {
     render(
       <ShellLayout
@@ -122,6 +192,56 @@ describe("ShellLayout", () => {
     expect(rightDrawer().getAttribute("data-state")).toBe("collapsed")
   })
 
+  test("keeps the right panel while every column fits", () => {
+    // 256 + 360 + 320 = 936, inside happy-dom's 1024px viewport.
+    const restore = shellViewport(WIDE_VIEWPORT)
+    try {
+      render(<ShellLayout panels={PANELS} variant="web" />)
+
+      expect(rightDrawer()).toBeDefined()
+      expect(screen.getByRole("button", { name: "Toggle panel" })).toBeDefined()
+    } finally {
+      restore()
+    }
+  })
+
+  test("drops the right panel when the columns no longer fit", () => {
+    // 936 needed, 800 available.
+    const restore = shellViewport(800)
+    try {
+      render(<ShellLayout panels={PANELS} variant="web" />)
+
+      expect(screen.queryByRole("complementary")).toBeNull()
+      // Its trigger goes with it rather than driving nothing.
+      expect(screen.queryByRole("button", { name: "Toggle panel" })).toBeNull()
+      // The rail and the body are untouched — they are never the ones to go.
+      expect(leftRail()).toBeDefined()
+      expect(screen.getByRole("main")).toBeDefined()
+    } finally {
+      restore()
+    }
+  })
+
+  test("folding the left rail hands its column to the right panel", async () => {
+    const user = userEvent.setup()
+    // Expanded: 256 + 360 + 320 = 936 > 800. Folded: 56 + 360 + 320 = 736.
+    const restore = shellViewport(800)
+    try {
+      render(<ShellLayout panels={PANELS} variant="web" />)
+
+      expect(leftRail().getAttribute("data-state")).toBe("expanded")
+      expect(screen.queryByRole("complementary")).toBeNull()
+
+      await user.click(screen.getByRole("button", { name: "Toggle sidebar" }))
+
+      expect(leftRail().getAttribute("data-state")).toBe("collapsed")
+      expect(rightDrawer()).toBeDefined()
+      expect(screen.getByRole("button", { name: "Toggle panel" })).toBeDefined()
+    } finally {
+      restore()
+    }
+  })
+
   test("⌘B toggles the left rail", async () => {
     const user = userEvent.setup()
     render(<ShellLayout panels={PANELS} variant="web" />)
@@ -148,6 +268,7 @@ function HookedShell({
       <button onClick={() => panels.toggle("right")} type="button">
         External toggle
       </button>
+      {panels.isNarrow && <p>No room for the inspector</p>}
     </ShellLayout>
   )
 }
@@ -180,6 +301,74 @@ describe("useShellPanels", () => {
     expect(rightDrawer().getAttribute("data-state")).toBe("collapsed")
   })
 
+  test("mirrors the shell's too-narrow verdict back into the hook", () => {
+    const restore = shellViewport(800)
+    try {
+      render(<HookedShell />)
+
+      // The shell measures, the hook hears about it, and outside UI stands
+      // down with the panel it would have driven.
+      expect(screen.getByText("No room for the inspector")).toBeDefined()
+      expect(screen.queryByRole("complementary")).toBeNull()
+    } finally {
+      restore()
+    }
+  })
+
+  test("leaves the hook's verdict alone while the panel fits", () => {
+    const restore = shellViewport(WIDE_VIEWPORT)
+    try {
+      render(<HookedShell />)
+
+      expect(screen.queryByText("No room for the inspector")).toBeNull()
+      expect(rightDrawer()).toBeDefined()
+    } finally {
+      restore()
+    }
+  })
+
+  test("refuses to open the right panel while the shell is too narrow", async () => {
+    const user = userEvent.setup()
+    const onPanelChange = mock(() => {})
+    const restore = shellViewport(800)
+    try {
+      render(<HookedShell onPanelChange={onPanelChange} />)
+
+      await user.click(screen.getByRole("button", { name: "External toggle" }))
+
+      // Nothing opened, and nothing was reported — the write never happened,
+      // so widening the viewport later cannot surface a stale panel.
+      expect(screen.queryByRole("complementary")).toBeNull()
+      expect(onPanelChange).not.toHaveBeenCalled()
+    } finally {
+      restore()
+    }
+  })
+
+  test("retires the right panel's state when the shell goes too narrow", async () => {
+    const user = userEvent.setup()
+    const onPanelChange = mock(() => {})
+    const restore = shellViewport(WIDE_VIEWPORT)
+    try {
+      render(<HookedShell onPanelChange={onPanelChange} />)
+
+      await user.click(screen.getByRole("button", { name: "External toggle" }))
+      expect(rightDrawer().getAttribute("data-state")).toBe("expanded")
+
+      resizeViewport(800)
+
+      expect(screen.queryByRole("complementary")).toBeNull()
+      expect(onPanelChange).toHaveBeenLastCalledWith(false, "right")
+
+      // The state went with the panel: coming back does not spring it open.
+      resizeViewport(WIDE_VIEWPORT)
+
+      expect(rightDrawer().getAttribute("data-state")).toBe("collapsed")
+    } finally {
+      restore()
+    }
+  })
+
   test("the shell's own triggers round-trip through the hook's state", async () => {
     const user = userEvent.setup()
     render(<HookedShell />)

package/src/components/blocks/shell/__tests__/shell-metrics.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "bun:test"
+
+import {
+  clampPanelWidth,
+  fitsPanel,
+  metricsEqual,
+  panelBounds,
+  requiredWidth,
+  type ShellMetrics,
+} from "../shell-metrics"
+
+/** The columns the shell ships with: rail 256 (56 folded), body floor 360,
+ * secondary panel floor 320 — 936px before a panel can exist — plus the 32px
+ * of shell padding and column gaps that only the ceiling pays for. */
+function shell(over: Partial<ShellMetrics> = {}): ShellMetrics {
+  return {
+    rail: 256,
+    insetMin: 360,
+    panelMin: 320,
+    viewport: 1024,
+    chrome: 32,
+    ...over,
+  }
+}
+
+describe("fitsPanel", () => {
+  test("wants the rail plus both floors to clear the viewport", () => {
+    expect(requiredWidth(shell())).toBe(936)
+    expect(fitsPanel(shell())).toBe(true)
+    expect(fitsPanel(shell({ viewport: 800 }))).toBe(false)
+  })
+
+  test("is strict — a viewport that fits exactly has nothing left to give", () => {
+    expect(fitsPanel(shell({ viewport: 936 }))).toBe(false)
+    expect(fitsPanel(shell({ viewport: 937 }))).toBe(true)
+  })
+
+  test("a folded rail hands its column back", () => {
+    expect(fitsPanel(shell({ rail: 56, viewport: 800 }))).toBe(true)
+  })
+
+  test("a shell with no rail spends nothing on one", () => {
+    expect(fitsPanel(shell({ rail: 0, viewport: 700 }))).toBe(true)
+  })
+
+  test("an unmeasurable shell fails open rather than hiding the panel", () => {
+    expect(
+      fitsPanel({
+        rail: 0,
+        insetMin: 0,
+        panelMin: 0,
+        viewport: 0,
+        chrome: 0,
+      })
+    ).toBe(true)
+    expect(fitsPanel(shell({ panelMin: 0 }))).toBe(true)
+  })
+
+  test("ignores the shell's own frame — the rule is stated on the viewport", () => {
+    expect(fitsPanel(shell({ chrome: 0 }))).toBe(
+      fitsPanel(shell({ chrome: 300 }))
+    )
+  })
+})
+
+describe("panelBounds", () => {
+  test("the panel may take every px the body holds above its floor", () => {
+    // 1024 - 32 frame - 256 rail - 360 body floor.
+    expect(panelBounds(shell())).toEqual({ min: 320, max: 376 })
+    expect(panelBounds(shell({ rail: 56 })).max).toBe(576)
+  })
+
+  test("the shell's frame comes out of the ceiling, not the floor", () => {
+    expect(panelBounds(shell({ chrome: 0 })).max).toBe(408)
+    expect(panelBounds(shell({ chrome: 0 })).min).toBe(320)
+  })
+
+  test("never inverts — a shell with no room reports its floor twice", () => {
+    expect(panelBounds(shell({ viewport: 800 }))).toEqual({
+      min: 320,
+      max: 320,
+    })
+  })
+})
+
+describe("clampPanelWidth", () => {
+  test("holds a drag inside the bounds and leaves the middle alone", () => {
+    expect(clampPanelWidth(600, shell())).toBe(376)
+    expect(clampPanelWidth(100, shell())).toBe(320)
+    expect(clampPanelWidth(360, shell())).toBe(360)
+  })
+
+  test("a narrowing viewport pulls a resized panel back down", () => {
+    const resized = clampPanelWidth(500, shell({ rail: 56 }))
+    expect(resized).toBe(500)
+    expect(clampPanelWidth(resized, shell({ rail: 56, viewport: 900 }))).toBe(
+      452
+    )
+  })
+})
+
+describe("metricsEqual", () => {
+  test("compares fields, so a fresh object off the same layout is quiet", () => {
+    expect(metricsEqual(shell(), shell())).toBe(true)
+    expect(metricsEqual(shell(), shell({ viewport: 1025 }))).toBe(false)
+    expect(metricsEqual(shell(), shell({ rail: 56 }))).toBe(false)
+  })
+})

package/src/components/blocks/shell/animated-panel-inset.tsx

@@ -13,7 +13,11 @@ export const AnimatedPanelInset = forwardRef<
       ref={forwardedRef}
       data-slot="sidebar-inset"
       className={cn(
-        "relative flex min-w-0 flex-1 flex-col bg-neutral-50 dark:bg-neutral-900",
+        // The body takes every column the panels leave (flex-1 = width 100%)
+        // but never yields past its own floor: a resized panel may only take
+        // the slack above --inset-min-width, and the shell drops the secondary
+        // panel entirely once even that no longer fits.
+        "relative flex min-w-(--inset-min-width) flex-1 flex-col bg-neutral-50 dark:bg-neutral-900",
         "outline-offset-0.5 overflow-hidden border-t-3 border-white outline-neutral-100 dark:border-neutral-800 dark:inset-ring-black",
         "rounded-lg shadow-md shadow-neutral-200 dark:shadow-neutral-950",
         className

package/src/components/blocks/shell/animated-panel-provider.tsx

@@ -1,24 +1,26 @@
 import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react"
-import { useReducedMotion } from "motion/react"
+import { useIsomorphicLayoutEffect, useReducedMotion } from "motion/react"
 import { cn } from "@/lib/utils.ts"
-import type {
-  AnimatedSidebarProviderProps,
-  SidebarSide,
-} from "./type"
+import type { AnimatedSidebarProviderProps, SidebarSide } from "./type"
+import { useShellFit } from "./use-shell-fit"
 import {
   AnimatedSidebarContext,
+  SHELL_WIDTHS,
   SIDEBAR_KEYBOARD_SHORTCUT,
   useIsMobile,
 } from "./utils"
 
 export function AnimatedPanelProvider({
   children,
+  shellId,
+  defaultPanelWidth,
   open,
   defaultOpen,
   onOpenChange,
   openMobile,
   defaultOpenMobile,
   onOpenMobileChange,
+  onNarrowChange,
   className,
   style,
   ...props
@@ -40,6 +42,12 @@ export function AnimatedPanelProvider({
   const generatedId = useId()
   const leftTriggerRef = useRef<HTMLButtonElement>(null)
   const rightTriggerRef = useRef<HTMLButtonElement>(null)
+  const wrapperRef = useRef<HTMLDivElement>(null)
+  // The narrow gate below is consulted by the setters, but the verdict comes
+  // from `useShellFit` further down — which needs those very setters to retire
+  // the panel. A ref unwinds the cycle: a setter only ever runs from an event,
+  // by which time the layout effect has published the current verdict.
+  const fitsRef = useRef(true)
 
   // Per-side controlled/uncontrolled merge — a side is controlled exactly
   // when its key is present on the controlled record.
@@ -63,8 +71,14 @@ export function AnimatedPanelProvider({
     [controlledMobileLeft, controlledMobileRight, internalOpenMobile]
   )
 
+  // The right panel is not on screen while the shell is too narrow to hold
+  // it, so opening it would only ever surface later as a panel nobody asked
+  // for. Closing always goes through — that is how state left over from a
+  // wider viewport clears.
   const setOpen = useCallback(
     (nextOpen: boolean, side: SidebarSide) => {
+      if (nextOpen && side === "right" && !fitsRef.current) return
+
       const controlled = side === "left" ? controlledLeft : controlledRight
       if (controlled === undefined) {
         setInternalOpen((prev) =>
@@ -78,6 +92,8 @@ export function AnimatedPanelProvider({
 
   const setOpenMobile = useCallback(
     (nextOpen: boolean, side: SidebarSide) => {
+      if (nextOpen && side === "right" && !fitsRef.current) return
+
       const controlled =
         side === "left" ? controlledMobileLeft : controlledMobileRight
       if (controlled === undefined) {
@@ -103,6 +119,58 @@ export function AnimatedPanelProvider({
     []
   )
 
+  // A measurement that lands on "no room" retires the right panel's open
+  // state instead of parking it: a panel that survived the crossing would
+  // spring back the moment the viewport widened, long after the user asked
+  // for it. Closing is the one write the narrow gate lets through, and the
+  // guards keep a repeated verdict from re-reporting a panel already shut.
+  //
+  // It rides a ref so `useShellFit` can call the latest one from a listener
+  // it bound once, and it is a layout effect declared FIRST so the ref is
+  // filled before that listener takes its opening measurement.
+  const retireRightPanelRef = useRef<() => void>(() => {})
+  useIsomorphicLayoutEffect(() => {
+    retireRightPanelRef.current = () => {
+      if (openState.right) setOpen(false, "right")
+      if (openMobileState.right) setOpenMobile(false, "right")
+    }
+  })
+  const retireRightPanel = useCallback(() => retireRightPanelRef.current(), [])
+
+  // Everything about the shell's columns — whether a secondary panel fits,
+  // how wide it is, how far it may be dragged — lives in this one hook, and
+  // in the shell-fit atoms it writes to under `shellId`. The rail's fold is an
+  // input because its column is part of the room the panel needs.
+  const fit = useShellFit({
+    shellId,
+    hostRef: wrapperRef,
+    railOpen: openState.left,
+    defaultPanelWidth,
+    onUnfit: retireRightPanel,
+  })
+  const isNarrow = !fit.fits
+  useIsomorphicLayoutEffect(() => {
+    fitsRef.current = fit.fits
+  })
+
+  // The verdict has to travel up to whoever renders the provider —
+  // useShellPanels, a title bar — since context only flows down. The
+  // listener above is bound once, so the callback rides a ref rather than
+  // rebinding it whenever a consumer passes a fresh arrow.
+  const onNarrowChangeRef = useRef(onNarrowChange)
+  useEffect(() => {
+    onNarrowChangeRef.current = onNarrowChange
+  })
+
+  // Only real crossings are news: a resize that leaves the verdict alone is
+  // silent, and so is the mount default the consumer already holds.
+  const reportedNarrowRef = useRef(false)
+  useEffect(() => {
+    if (reportedNarrowRef.current === isNarrow) return
+    reportedNarrowRef.current = isNarrow
+    onNarrowChangeRef.current?.(isNarrow)
+  }, [isNarrow])
+
   useEffect(() => {
     const handleShortcut = (event: KeyboardEvent) => {
       if (
@@ -122,6 +190,7 @@ export function AnimatedPanelProvider({
     <AnimatedSidebarContext.Provider
       value={{
         isMobile,
+        fit,
         layoutId: `${generatedId}-active`,
         open: openState,
         openMobile: openMobileState,
@@ -134,15 +203,12 @@ export function AnimatedPanelProvider({
     >
       <div
         {...props}
+        ref={wrapperRef}
         data-slot="sidebar-wrapper"
+        data-narrow={isNarrow ? "" : undefined}
         data-state-left={openState.left ? "expanded" : "collapsed"}
         data-state-right={openState.right ? "expanded" : "collapsed"}
-        style={{
-          "--sidebar-width": "19rem",
-          "--sidebar-width-icon": "4.25rem",
-          "--sidebar-width-mobile": "18rem",
-          ...style,
-        }}
+        style={{ ...SHELL_WIDTHS, ...style }}
         className={cn(
           "group/sidebar-wrapper flex w-full min-w-0 gap-x-2",
           className

package/src/components/blocks/shell/animated-panel-trigger.tsx

@@ -16,6 +16,10 @@ export const AnimatedPanelTrigger = forwardRef<
     : context.open[side]
   const triggerRef = context.triggerRefs[side]
 
+  // The right panel drops out of a viewport too narrow to hold it, so its
+  // toggle would otherwise sit in the header driving nothing.
+  if (side === "right" && !context.fit.fits) return null
+
   return (
     <Button
       {...props}