@exegia/corpora-ui 0.20.0 → 0.21.0

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}

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

@@ -1,18 +1,30 @@
 "use client"
 // beui.dev/components/motion/animated-sidebar
 
-import { motion } from "motion/react"
+import { motion, type PanInfo } from "motion/react"
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type KeyboardEvent,
+} from "react"
 import { EASE_OUT } from "@/lib/ease.ts"
 import { cn } from "@/lib/utils"
 import type { AnimatedSidebarProps } from "./type"
 import {
   AnimatedSidebarPanelContext,
+  expandedWidthVar,
   SIDEBAR_MORPH_TRANSITION,
   PANEL_TRANSITION,
   REDUCED_TRANSITION,
-  useAnimatedSidebar
+  useAnimatedSidebar,
 } from "./utils"
 
+/** How far one arrow key moves the panel edge (shift = coarse step). */
+const RESIZE_STEP = 16
+const RESIZE_STEP_COARSE = 64
+
 export function AnimatedPanel({
   side = "left",
   variant = "sidebar",
@@ -26,21 +38,97 @@ export function AnimatedPanel({
   ...props
 }: AnimatedSidebarProps) {
   const context = useAnimatedSidebar()
+  const { bounds, panelWidth, resetPanelWidth, resizePanel } = context.fit
   const sideOpen = context.open[side]
   const collapsed = collapsible !== "none" && !sideOpen
   const offcanvas = collapsed && collapsible === "offcanvas"
-  const width = offcanvas
-    ? "0px"
+
+  // Only the expanded secondary panel is resizable: the rail is pinned to its
+  // own columns, and a collapsed panel has no edge left to grab.
+  const resizable =
+    side === "right" && collapsible === "offcanvas" && !collapsed
+
+  const resizeStartRef = useRef(0)
+  const [resizing, setResizing] = useState(false)
+
+  const baseWidth = offcanvas
+    ? 0
     : collapsed
       ? "var(--sidebar-width-icon)"
-      : "var(--sidebar-width)"
+      : expandedWidthVar(side)
+  // The secondary panel's width is shell state, not panel state: the shell
+  // measured it, re-clamps it when the room changes, and hands back the same
+  // width after a collapse. Everything else rides the CSS variables, which
+  // also covers the server render, where nothing has been measured yet.
+  const width = resizable && panelWidth !== null ? panelWidth : baseWidth
+
+  const setPanelRef = useCallback(
+    (node: HTMLElement | null) => {
+      if (typeof ref === "function") ref(node)
+      else if (ref) ref.current = node
+    },
+    [ref]
+  )
+
+  const handleResizeStart = useCallback(() => {
+    resizeStartRef.current = panelWidth ?? bounds.min
+    setResizing(true)
+  }, [bounds.min, panelWidth])
+
+  const handleResize = useCallback(
+    (_event: PointerEvent, info: PanInfo) => {
+      // The handle rides the panel's inner edge, so the panel grows as the
+      // pointer travels left. `offset` is measured from the pointer-down
+      // point, so the edge tracks it 1:1 instead of accumulating rounding.
+      resizePanel(resizeStartRef.current - info.offset.x)
+    },
+    [resizePanel]
+  )
+
+  const handleResizeEnd = useCallback(() => setResizing(false), [])
+
+  const handleResizeKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLDivElement>) => {
+      const direction =
+        event.key === "ArrowLeft" ? 1 : event.key === "ArrowRight" ? -1 : 0
+      if (!direction) return
+
+      event.preventDefault()
+      const step = event.shiftKey ? RESIZE_STEP_COARSE : RESIZE_STEP
+      resizePanel((panelWidth ?? bounds.min) + direction * step)
+    },
+    [bounds.min, panelWidth, resizePanel]
+  )
+
+  // The pointer leaves the 2px handle the moment the drag starts, so the
+  // cursor and the text selection have to be held on the document instead.
+  useEffect(() => {
+    if (!resizing) return
+
+    const { body } = document
+    const previousCursor = body.style.cursor
+    const previousUserSelect = body.style.userSelect
+    body.style.cursor = "col-resize"
+    body.style.userSelect = "none"
+
+    return () => {
+      body.style.cursor = previousCursor
+      body.style.userSelect = previousUserSelect
+    }
+  }, [resizing])
+
+  // A secondary panel exists only while the viewport can carry it beside the
+  // rail and the body at their own floors. Below that there is nothing to dock
+  // into, so the panel stands down rather than squeezing the content column —
+  // and its trigger stands down with it.
+  if (side === "right" && !context.fit.fits) return null
 
   if (context.isMobile) return <div>TODO: Create Mobile nav experience</div>
 
   return (
     <motion.aside
       {...props}
-      ref={ref}
+      ref={setPanelRef}
       initial={false}
       aria-label={ariaLabel}
       data-slot="sidebar"
@@ -48,6 +136,7 @@ export function AnimatedPanel({
       data-collapsible={collapsible}
       data-variant={variant}
       data-side={side}
+      data-resizing={resizing ? "" : undefined}
       animate={{
         width,
         // Swallow the shell's gap-x-2 column gap while off canvas so the
@@ -57,7 +146,11 @@ export function AnimatedPanel({
           ? { marginLeft: offcanvas ? "-0.5rem" : "0rem" }
           : { marginRight: offcanvas ? "-0.5rem" : "0rem" }),
       }}
-      transition={context.reduce ? { duration: 0 } : SIDEBAR_MORPH_TRANSITION}
+      // A drag has to land on the frame it happened — the morph spring would
+      // trail the pointer and keep settling after the handle is released.
+      transition={
+        resizing || context.reduce ? { duration: 0 } : SIDEBAR_MORPH_TRANSITION
+      }
       style={style}
       className={cn(
         "group/sidebar relative hidden h-full shrink-0 will-change-[width] md:block",
@@ -66,14 +159,28 @@ export function AnimatedPanel({
         className
       )}
     >
-      {side === "right" && !collapsed && (
+      {resizable && (
         // The handle occupies the shell's gap-x-2 column gap. It must stay
         // outside the clipping mask below or the gap would never receive
         // hover — clipping cuts hit-testing, not just painting.
         <motion.div
-          className="absolute inset-y-0 -left-2 z-10 w-2 cursor-col-resize"
+          role="separator"
+          aria-label={`Resize ${ariaLabel}`}
+          aria-orientation="vertical"
+          tabIndex={0}
+          className="absolute inset-y-0 -left-2 z-10 w-2 cursor-col-resize touch-none"
           initial="idle"
+          // Hover alone would drop the glow the instant the drag leaves the
+          // handle, so the gesture pins it open for the whole drag.
+          animate={resizing ? "hover" : "idle"}
           whileHover="hover"
+          whileFocus="hover"
+          onPanStart={handleResizeStart}
+          onPan={handleResize}
+          onPanEnd={handleResizeEnd}
+          onKeyDown={handleResizeKeyDown}
+          // The usual escape hatch out of a width you dragged to.
+          onDoubleClick={resetPanelWidth}
         >
           <motion.div
             variants={{ idle: { scaleY: 0 }, hover: { scaleY: 1 } }}
@@ -86,30 +193,20 @@ export function AnimatedPanel({
           />
         </motion.div>
       )}
-      {/* The off canvas panel keeps its full width and slides out of the
-          zero-width rail, so mask it to the aside's box here instead of
-          clipping the aside itself — the aside must stay unclipped for the
-          gap handle above to be hoverable. */}
-      <div
-        className={
-          collapsible === "offcanvas"
-            ? "absolute inset-0 overflow-hidden rounded-[inherit]"
-            : "contents"
-        }
-      >
+      {/* The aside's own width animation is the whole layout story: the
+          inner panel just fills it and fades, so it is masked to the aside's
+          box here instead of clipping the aside itself — the aside must stay
+          unclipped for the gap handle above to be hoverable. */}
+      <div className={"contents"}>
         <motion.div
           initial={false}
-          animate={{
-            opacity: offcanvas ? 0 : 1,
-            x: offcanvas ? (side === "left" ? "-100%" : "100%") : "0%",
-          }}
+          animate={{ opacity: offcanvas ? 0 : 1 }}
           transition={context.reduce ? REDUCED_TRANSITION : PANEL_TRANSITION}
           className={cn(
-            "sticky top-0 flex flex-col overflow-hidden",
-         //   collapsible === "offcanvas" && "w-(--sidebar-width)",
-            // Pin the right panel to the aside's trailing edge so the width
-            // animation expands the panel out of it instead of revealing a
-            // detached strip.
+            "sticky top-0 flex w-full flex-col overflow-hidden",
+            // Pin the right panel to the aside's trailing edge so the aside's
+            // width animation expands the panel out of it instead of
+            // revealing a detached strip.
             side === "right" && "ml-auto",
 
             // Panels fill the shell's container, not the viewport — the shell

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

@@ -1,7 +1,25 @@
 import { ShellLayout } from "./shell-layout"
 
 export type * from "./type"
+export * from "./shell-metrics"
 export * from "./use-shell-panels"
+export { useShellFit } from "./use-shell-fit"
+export { useShellFitActions, useShellFitState } from "./use-shell-fit-state"
+// The public atom surface. `@internal` atoms (measure, mount) stay unexported
+// on purpose — `export *` would make every internal a breaking-change surface
+// for consumer apps.
+export {
+  removeShellFitInstance,
+  resetShellPanelWidthAtom,
+  resizeShellPanelAtom,
+  shellFitFitsAtom,
+  shellFitMeasuredAtom,
+  shellFitMetricsAtom,
+  shellFitPanelBoundsAtom,
+  shellFitPanelWidthAtom,
+  shellFitRequestedWidthAtom,
+  shellFitStateAtom,
+} from "./shell-fit-atom"
 export * from "./utils"
 
 export * from "./animated-panel"