@exegia/corpora-ui 0.19.0 → 0.21.0

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"

package/src/components/blocks/shell/shell-fit-atom.ts

@@ -0,0 +1,243 @@
+/**
+ * Per-instance Jotai state for the shell's layout fit.
+ *
+ * Every atom is a module-level family keyed by a shell id, so one
+ * `ExegiaProvider` at the app root is enough: several shells coexist in one
+ * store without a provider each, and a title bar, a command palette or a
+ * layout test can drive one by id without holding its controller.
+ *
+ * Unlike the tree, this feature has no controlled props — the shell measures
+ * itself, nobody hands it a viewport. So, like `blocks/auth`'s coordination
+ * layer, there is no config atom, no projection and no owned-* loop guard.
+ * `useShellFit` is the only writer of `metrics`, and that write is silent by
+ * design: a resize is not an event an app subscribed to.
+ *
+ * The rule itself lives in `shell-metrics.ts` and is called from here, so the
+ * arithmetic has one home whether it is read through a hook or a store.
+ */
+import { atom } from "jotai"
+import type { Getter, Setter } from "jotai"
+
+import {
+  clampPanelWidth,
+  fitsPanel,
+  metricsEqual,
+  panelBounds,
+  type ShellMetrics,
+} from "./shell-metrics"
+import type {
+  ShellFitInstanceId,
+  ShellFitPanelBounds,
+  ShellFitSeed,
+  ShellFitState,
+} from "./type"
+
+/** An unmeasured shell. Zeroes read as "no layout yet", which the rule fails
+ * open on rather than hiding a panel over a reading it never took. */
+const NO_METRICS: ShellMetrics = {
+  rail: 0,
+  insetMin: 0,
+  panelMin: 0,
+  viewport: 0,
+  chrome: 0,
+}
+
+/** A panel that mounts at `--panel-width`. */
+const DEFAULT_SHELL_FIT_SEED: ShellFitSeed = { panelWidth: null }
+
+const NO_BOUNDS: ShellFitPanelBounds = { min: 0, max: 0 }
+
+/**
+ * A string-keyed atom family.
+ *
+ * `jotai/utils`' `atomFamily` is deprecated for Jotai v3, and we need only
+ * the string-keyed case with a `remove` — so this stays in-house rather than
+ * adding `jotai-family` as a second Jotai package to keep version-aligned.
+ * Dropping a key lets the store's WeakMap release that instance's state.
+ */
+type Family<AtomType> = ((id: ShellFitInstanceId) => AtomType) & {
+  remove: (id: ShellFitInstanceId) => void
+}
+
+/** Every family, so `removeShellFitInstance` can drop an id from all of them. */
+const families: { remove: (id: ShellFitInstanceId) => void }[] = []
+
+function keyed<AtomType>(create: (id: ShellFitInstanceId) => AtomType) {
+  const cache = new Map<ShellFitInstanceId, AtomType>()
+  const family = ((id: ShellFitInstanceId) => {
+    let instance = cache.get(id)
+    if (instance === undefined) {
+      instance = create(id)
+      cache.set(id, instance)
+    }
+    return instance
+  }) as Family<AtomType>
+  family.remove = (id: ShellFitInstanceId) => {
+    cache.delete(id)
+  }
+  families.push(family)
+  return family
+}
+
+function stateFamily<Value>(name: string, initialValue: Value) {
+  return keyed((id) => {
+    const instance = atom(initialValue)
+    instance.debugLabel = `shell-fit/${id}/${name}`
+    return instance
+  })
+}
+
+function readFamily<Value>(
+  name: string,
+  read: (get: Getter, id: ShellFitInstanceId) => Value
+) {
+  return keyed((id) => {
+    const instance = atom((get) => read(get, id))
+    instance.debugLabel = `shell-fit/${id}/${name}`
+    return instance
+  })
+}
+
+function actionFamily<Args extends unknown[]>(
+  name: string,
+  write: (
+    get: Getter,
+    set: Setter,
+    id: ShellFitInstanceId,
+    ...args: Args
+  ) => void
+) {
+  return keyed((id) => {
+    const instance = atom(null, (get, set, ...args: Args) =>
+      write(get, set, id, ...args)
+    )
+    instance.debugLabel = `shell-fit/${id}/${name}`
+    return instance
+  })
+}
+
+/** The shell's own measurement of its columns. `useShellFit` is the only
+ * writer; read `shellFitMeasuredAtom` to get it with the "no layout yet" case
+ * already resolved. */
+export const shellFitMetricsAtom = stateFamily<ShellMetrics>(
+  "metrics",
+  NO_METRICS
+)
+
+/** The width the user dragged to, before clamping — null while the panel sits
+ * at `--panel-width`. Read `shellFitPanelWidthAtom` for the width the panel
+ * actually renders at: clamping on read is what lets a narrowing viewport
+ * pull the panel down without forgetting the width they asked for. */
+export const shellFitRequestedWidthAtom = stateFamily<number | null>(
+  "requestedWidth",
+  null
+)
+
+const shellFitSeedAtom = stateFamily<ShellFitSeed>(
+  "seed",
+  DEFAULT_SHELL_FIT_SEED
+)
+const shellFitInitializedAtom = stateFamily<boolean>("initialized", false)
+
+/** The metrics, or null when the shell has no layout to report — a server
+ * render, a `display: none` host, a test with no layout engine. A zero is not
+ * a width, and treating it as one would pin the panel to nothing. */
+export const shellFitMeasuredAtom = readFamily<ShellMetrics | null>(
+  "measured",
+  (get, id) => {
+    const metrics = get(shellFitMetricsAtom(id))
+    return metrics.panelMin > 0 ? metrics : null
+  }
+)
+
+/** Whether the shell can hold a secondary panel at all. */
+export const shellFitFitsAtom = readFamily("fits", (get, id) =>
+  fitsPanel(get(shellFitMetricsAtom(id)))
+)
+
+/** The range a resize may land in. */
+export const shellFitPanelBoundsAtom = readFamily<ShellFitPanelBounds>(
+  "panelBounds",
+  (get, id) => {
+    const measured = get(shellFitMeasuredAtom(id))
+    return measured ? panelBounds(measured) : NO_BOUNDS
+  }
+)
+
+/** The width the secondary panel renders at, or null before the first
+ * measurement, where the caller falls back to `--panel-width`. */
+export const shellFitPanelWidthAtom = readFamily<number | null>(
+  "panelWidth",
+  (get, id) => {
+    const measured = get(shellFitMeasuredAtom(id))
+    if (!measured) return null
+    const requested = get(shellFitRequestedWidthAtom(id))
+    return clampPanelWidth(requested ?? measured.panelMin, measured)
+  }
+)
+
+/** The whole fit of one shell. This changes on every measurement, so a
+ * component that reads one field should subscribe to that field's atom
+ * instead: `useAtomValue(shellFitFitsAtom("app-shell"))`. */
+export const shellFitStateAtom = readFamily<ShellFitState>(
+  "state",
+  (get, id) => ({
+    metrics: get(shellFitMeasuredAtom(id)),
+    fits: get(shellFitFitsAtom(id)),
+    panelWidth: get(shellFitPanelWidthAtom(id)),
+    bounds: get(shellFitPanelBoundsAtom(id)),
+  })
+)
+
+/** @internal The measurement's way in. Silent, and inert when the numbers did
+ * not move — a resize event that changes nothing must not re-render a shell. */
+export const measureShellFitAtom = actionFamily<[metrics: ShellMetrics]>(
+  "measure",
+  (get, set, id, metrics) => {
+    if (metricsEqual(get(shellFitMetricsAtom(id)), metrics)) return
+    set(shellFitMetricsAtom(id), metrics)
+  }
+)
+
+/** Resize the secondary panel. Clamped on the way in, so a drag past the
+ * gutter parks at the bound instead of banking travel it has to give back —
+ * and a caller with no idea how wide the shell is can still ask for 900. */
+export const resizeShellPanelAtom = actionFamily<[width: number]>(
+  "resizePanel",
+  (get, set, id, width) => {
+    const measured = get(shellFitMeasuredAtom(id))
+    set(
+      shellFitRequestedWidthAtom(id),
+      measured ? clampPanelWidth(width, measured) : width
+    )
+  }
+)
+
+/** Back to the width the shell mounted with — `defaultPanelWidth`, or
+ * `--panel-width` when there was none. */
+export const resetShellPanelWidthAtom = actionFamily<[]>(
+  "resetPanelWidth",
+  (get, set, id) => {
+    set(shellFitRequestedWidthAtom(id), get(shellFitSeedAtom(id)).panelWidth)
+  }
+)
+
+/** @internal Seed the instance once. A seed describes the mount, not every
+ * render, so a `defaultPanelWidth` that arrives later never overwrites a
+ * width the user dragged to. */
+export const mountShellFitAtom = actionFamily<[seed: ShellFitSeed]>(
+  "mount",
+  (get, set, id, seed) => {
+    if (get(shellFitInitializedAtom(id))) return
+    set(shellFitInitializedAtom(id), true)
+    set(shellFitSeedAtom(id), seed)
+    set(shellFitRequestedWidthAtom(id), seed.panelWidth)
+  }
+)
+
+/** Drop every atom for `id`. `useShellFit` calls this on unmount for shells it
+ * keyed itself; an explicit `shellId` is the app's key and outlives its
+ * component, so a resized panel survives a route change. */
+export function removeShellFitInstance(id: ShellFitInstanceId): void {
+  for (const family of families) family.remove(id)
+}

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

@@ -3,9 +3,7 @@
 import { MotionIcon } from "motion-icons-react"
 import * as React from "react"
 
-import {
-  AnimatedPanel
-} from "./animated-panel.tsx"
+import { AnimatedPanel } from "./animated-panel.tsx"
 import { cn } from "@/lib/utils"
 import type { ShellLayoutProps, ShellPanelControlProps } from "./type"
 import { TITLE_BAR_HEIGHT } from "./utils"
@@ -23,82 +21,86 @@ export function ShellLayout({
   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 ?? true,
-      }),
-      ...(panels?.right && {
-        right: panels.right.defaultOpen ?? false,
-      }),
-      ...defaultOpen,
-    }
-
+    ...(panels?.left && {
+      left: panels.left.defaultOpen ?? true,
+    }),
+    ...(panels?.right && {
+      right: panels.right.defaultOpen ?? false,
+    }),
+    ...defaultOpen,
+  }
 
   return (
     <AnimatedPanelProvider
       {...panelControlProps}
       defaultOpen={initialOpen}
-      className={cn("relative h-full min-h-0 pb-2", className, background)}
+      className={cn("relative h-full min-h-0 px-2 pb-2", className, background)}
       style={{
         paddingTop: variant === "desktop" ? TITLE_BAR_HEIGHT : 0,
       }}
     >
-      <AnimatedPanel
-        ariaLabel="Primary navigation"
-        collapsible="icon"
-        role="navigation"
-        variant="inset"
-      >
-        {panels?.left?.component}
-      </AnimatedPanel>
+      {panels?.left?.component && (
+        <AnimatedPanel
+          ariaLabel="Primary navigation"
+          collapsible="icon"
+          role="navigation"
+          variant="inset"
+        >
+          {panels?.left?.component}
+        </AnimatedPanel>
+      )}
 
-      <AnimatedPanelInset className="min-w-24">
-        <header className="flex h-12 items-center justify-between gap-2 border-b px-2">
-          <div className="flex min-w-0 items-center gap-2">
-            <AnimatedPanelTrigger>
-              {panels?.left?.trigger ?? (
+      <AnimatedPanelInset>
+        <header className="flex h-12 flex-row! items-center justify-between gap-2 border-b px-2">
+          {panels?.left?.component && (
+            <div className="flex min-w-0 flex-1 items-center gap-2">
+              <AnimatedPanelTrigger side="left">
                 <MotionIcon name="PanelLeft" size={24} animation="press" />
-              )}
-            </AnimatedPanelTrigger>
-          </div>
-          {header && <div className="flex flex-1 items-center">{header}</div>}
-          <div className="flex shrink-0 items-center gap-2">
-            <AnimatedPanelTrigger aria-label="Toggle panel" side="right">
-              {panels?.right?.trigger ?? (
+              </AnimatedPanelTrigger>
+            </div>
+          )}
+          {header && (
+            <div className="flex w-full flex-1 items-center">{header}</div>
+          )}
+          {panels?.right?.component && (
+            <div className="flex flex-1 items-center justify-end gap-2">
+              <AnimatedPanelTrigger aria-label="Toggle panel" side="right">
                 <MotionIcon
                   className="opacity-70"
                   name="PanelRight"
                   size={24}
                 />
-              )}
-            </AnimatedPanelTrigger>
-          </div>
+              </AnimatedPanelTrigger>
+            </div>
+          )}
         </header>
         <div className="min-h-24 flex-1 overflow-auto">{children}</div>
       </AnimatedPanelInset>
 
-      <AnimatedPanel
-        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(
-          "mr-2 bg-neutral-50 dark:border-neutral-800 dark:bg-neutral-900",
-          "outline-offset-0.5 border-t-3 border-white outline-neutral-100 dark:inset-ring-black",
-          "rounded-lg shadow-md shadow-neutral-200 dark:shadow-neutral-950"
-        )}
-        collapsible="offcanvas"
-        role="complementary"
-        side="right"
-        variant="inset"
-      >
-        {panels?.right?.component}
-      </AnimatedPanel>
+      {panels?.right?.component && (
+        <AnimatedPanel
+          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(
+            "bg-neutral-50 dark:border-neutral-800 dark:bg-neutral-900",
+            "outline-offset-0.5 border-t-3 border-white outline-neutral-100 dark:inset-ring-black",
+            "rounded-lg shadow-md shadow-neutral-200 dark:shadow-neutral-950"
+          )}
+          collapsible="offcanvas"
+          role="complementary"
+          side="right"
+          variant="inset"
+        >
+          {panels.right.component}
+        </AnimatedPanel>
+      )}
     </AnimatedPanelProvider>
   )
 }