@exegia/corpora-ui 0.20.0 → 0.21.0

package/src/components/blocks/shell/use-shell-fit-state.ts

@@ -0,0 +1,49 @@
+"use client"
+
+import { useMemo } from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+
+import {
+  resetShellPanelWidthAtom,
+  resizeShellPanelAtom,
+  shellFitStateAtom,
+} from "./shell-fit-atom"
+import type { ShellFitActions, ShellFitInstanceId, ShellFitState } from "./type"
+
+/**
+ * Read the fit of the shell registered under `shellId` from anywhere below
+ * `ExegiaProvider` — no controller, no props, no provider of its own.
+ *
+ * ```tsx
+ * const { fits, panelWidth } = useShellFitState("app-shell")
+ * ```
+ *
+ * This returns the whole state object, so the caller re-renders on every
+ * measurement. A component that reads one field should subscribe to that
+ * field's atom instead: `useAtomValue(shellFitFitsAtom("app-shell"))`.
+ */
+export function useShellFitState(shellId: ShellFitInstanceId): ShellFitState {
+  return useAtomValue(shellFitStateAtom(shellId))
+}
+
+/**
+ * Drive the secondary panel of the shell registered under `shellId` from
+ * anywhere. Writes only — the caller never re-renders when the shell moves,
+ * so this is what a command palette or a keyboard shortcut should reach for.
+ *
+ * ```tsx
+ * const shell = useShellFitActions("app-shell")
+ * <Button onClick={() => shell.resizePanel(480)}>Wide inspector</Button>
+ * ```
+ */
+export function useShellFitActions(
+  shellId: ShellFitInstanceId
+): ShellFitActions {
+  const resizePanel = useSetAtom(resizeShellPanelAtom(shellId))
+  const resetPanelWidth = useSetAtom(resetShellPanelWidthAtom(shellId))
+
+  return useMemo(
+    () => ({ resizePanel, resetPanelWidth }),
+    [resizePanel, resetPanelWidth]
+  )
+}

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

@@ -0,0 +1,135 @@
+"use client"
+
+import { useEffect, useId, useMemo, useRef, useState } from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+import { useIsomorphicLayoutEffect } from "motion/react"
+
+import {
+  measureShellFitAtom,
+  mountShellFitAtom,
+  removeShellFitInstance,
+  resetShellPanelWidthAtom,
+  resizeShellPanelAtom,
+  shellFitStateAtom,
+} from "./shell-fit-atom"
+import { fitsPanel, type ShellMetrics } from "./shell-metrics"
+import type {
+  ShellFitController,
+  ShellFitSeed,
+  UseShellFitOptions,
+} from "./type"
+import { resolveLength } from "./utils"
+
+/** Read the shell's columns out of the DOM. The widths come from CSS
+ * variables; the rail's share comes from its own state, not its box, so a
+ * fold counts the moment React commits it rather than a frame later when the
+ * width animation has moved. */
+function readMetrics(host: HTMLElement, railOpen: boolean): ShellMetrics {
+  // Whether a shell has a rail at all is the caller's composition, so it is
+  // read off the DOM rather than tracked in state.
+  const rail = host.querySelector<HTMLElement>(
+    '[data-slot="sidebar"][data-side="left"]'
+  )
+  const collapsible = rail?.dataset.collapsible
+
+  const frame = getComputedStyle(host)
+  const gap = Number.parseFloat(frame.columnGap) || 0
+
+  return {
+    rail: !rail
+      ? 0
+      : railOpen || collapsible === "none"
+        ? resolveLength(host, "var(--sidebar-width)")
+        : collapsible === "offcanvas"
+          ? 0
+          : resolveLength(host, "var(--sidebar-width-icon)"),
+    insetMin: resolveLength(host, "var(--inset-min-width)"),
+    panelMin: resolveLength(host, "var(--panel-width)"),
+    viewport: window.innerWidth,
+    chrome:
+      (Number.parseFloat(frame.paddingLeft) || 0) +
+      (Number.parseFloat(frame.paddingRight) || 0) +
+      gap * Math.max(0, host.children.length - 1),
+  }
+}
+
+/**
+ * Measures the shell and decides what the secondary panel may do: whether it
+ * exists at all, and how wide it may be dragged.
+ *
+ * The three things that move the answer are all observed here — the viewport
+ * (`resize`), the rail's fold (`railOpen`, a render input) and the user's own
+ * drag (`resizePanel`) — so no caller has to re-derive it. The measurement is
+ * the only thing this hook keeps to itself: the numbers land in the shell-fit
+ * atoms keyed by `shellId`, so anything under `ExegiaProvider` can read the
+ * verdict (`useShellFitState`) or move the panel (`useShellFitActions`)
+ * without holding this controller.
+ */
+export function useShellFit({
+  shellId: explicitId,
+  hostRef,
+  railOpen,
+  defaultPanelWidth,
+  onUnfit,
+}: UseShellFitOptions): ShellFitController {
+  // A generated key isolates unnamed shells from each other; an explicit
+  // `shellId` is the app's handle on this one.
+  const generatedId = useId()
+  const shellId = explicitId ?? generatedId
+
+  // Read once: `defaultPanelWidth` describes the mount, not every render.
+  const [seed] = useState<ShellFitSeed>(() => ({
+    panelWidth: defaultPanelWidth ?? null,
+  }))
+
+  const mount = useSetAtom(mountShellFitAtom(shellId))
+  const measure = useSetAtom(measureShellFitAtom(shellId))
+  const resizePanel = useSetAtom(resizeShellPanelAtom(shellId))
+  const resetPanelWidth = useSetAtom(resetShellPanelWidthAtom(shellId))
+
+  // Before paint, and before the first measurement below, so a seeded width
+  // is in the store by the time the panel first reads its width.
+  useIsomorphicLayoutEffect(() => {
+    mount(seed)
+  }, [mount, seed])
+
+  // The listener below is bound once per fold, so the callback rides a ref
+  // rather than rebinding it whenever a consumer passes a fresh arrow.
+  const onUnfitRef = useRef(onUnfit)
+  useIsomorphicLayoutEffect(() => {
+    onUnfitRef.current = onUnfit
+  })
+
+  useIsomorphicLayoutEffect(() => {
+    const host = hostRef.current
+    if (!host) return
+
+    const takeMeasurement = () => {
+      const next = readMetrics(host, railOpen)
+      measure(next)
+      if (!fitsPanel(next)) onUnfitRef.current?.()
+    }
+
+    // Measured before paint so a shell that cannot hold the panel never
+    // flashes one, and re-measured on every fold because the rail's column is
+    // part of the room the panel needs.
+    takeMeasurement()
+    window.addEventListener("resize", takeMeasurement)
+    return () => window.removeEventListener("resize", takeMeasurement)
+  }, [hostRef, railOpen, measure])
+
+  // A shell the hook keyed is scrap once its component goes. An explicit
+  // `shellId` is the app's key and outlives the mount — that is what lets a
+  // dragged width survive a route change.
+  useEffect(() => {
+    if (explicitId !== undefined) return
+    return () => removeShellFitInstance(shellId)
+  }, [shellId, explicitId])
+
+  const state = useAtomValue(shellFitStateAtom(shellId))
+
+  return useMemo<ShellFitController>(
+    () => ({ shellId, ...state, resizePanel, resetPanelWidth }),
+    [shellId, state, resizePanel, resetPanelWidth]
+  )
+}

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

@@ -1,7 +1,14 @@
 "use client"
 
-import { useCallback, useMemo, useState } from "react"
+import { useCallback, useEffect, useId, useMemo, useState } from "react"
+import { useAtomValue, useSetAtom } from "jotai"
 
+import {
+  removeShellFitInstance,
+  resizeShellPanelAtom,
+  shellFitFitsAtom,
+  shellFitPanelWidthAtom,
+} from "./shell-fit-atom"
 import type {
   ShellPanelControlProps,
   ShellPanelControls,
@@ -15,12 +22,36 @@ import type {
  * 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).
+ *
+ * The way back down is the store: `providerProps` carries a `shellId`, the
+ * shell files its measurement under it, and this hook reads `isNarrow` and
+ * `panelWidth` straight out of those atoms — so outside UI stands down with
+ * the panel instead of measuring `--sidebar-width` a second time. Name the
+ * `shellId` and any component below `ExegiaProvider` can do the same with
+ * `useShellFitState(shellId)`.
+ *
+ * Call it under the same `ExegiaProvider` as the shell it drives (or under
+ * none at all, on both sides): mounted above the provider it would read
+ * Jotai's default store while the shell writes to the provider's.
  */
 export function useShellPanels({
+  shellId: explicitId,
   defaultOpen,
   defaultOpenMobile,
+  defaultPanelWidth,
   onPanelChange,
 }: UseShellPanelsOptions = {}): ShellPanelControls {
+  // The hook, not the provider, keys the shell: it renders above the provider
+  // and has to read the same atoms the provider writes. Whoever generates the
+  // key drops it — the provider treats a passed-in id as the app's and leaves
+  // it alone on unmount.
+  const generatedId = useId()
+  const shellId = explicitId ?? generatedId
+  useEffect(() => {
+    if (explicitId !== undefined) return
+    return () => removeShellFitInstance(shellId)
+  }, [shellId, explicitId])
+
   const [open, setOpenState] = useState<Record<SidebarSide, boolean>>(() => ({
     left: defaultOpen?.left ?? true,
     right: defaultOpen?.right ?? false,
@@ -32,24 +63,40 @@ export function useShellPanels({
     right: defaultOpenMobile?.right ?? false,
   }))
 
+  // Reads false until the shell has measured itself — an unmeasured shell
+  // fails open, so nothing out here stands down over a reading that has not
+  // happened yet.
+  const fits = useAtomValue(shellFitFitsAtom(shellId))
+  const isNarrow = !fits
+  const panelWidth = useAtomValue(shellFitPanelWidthAtom(shellId))
+  const resizePanel = useSetAtom(resizeShellPanelAtom(shellId))
+
+  // The shell drops the right panel when the viewport cannot hold it, so
+  // opening it from out here would only 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" && isNarrow) return
+
       setOpenState((prev) =>
         prev[side] === nextOpen ? prev : { ...prev, [side]: nextOpen }
       )
       onPanelChange?.(nextOpen, side)
     },
-    [onPanelChange]
+    [isNarrow, onPanelChange]
   )
 
   const setOpenMobile = useCallback(
     (nextOpen: boolean, side: SidebarSide) => {
+      if (nextOpen && side === "right" && isNarrow) return
+
       setOpenMobileState((prev) =>
         prev[side] === nextOpen ? prev : { ...prev, [side]: nextOpen }
       )
       onPanelChange?.(nextOpen, side)
     },
-    [onPanelChange]
+    [isNarrow, onPanelChange]
   )
 
   const toggle = useCallback(
@@ -59,15 +106,21 @@ export function useShellPanels({
 
   const providerProps = useMemo<ShellPanelControlProps>(
     () => ({
+      shellId,
+      defaultPanelWidth,
       open,
       onOpenChange: setOpen,
       openMobile,
       onOpenMobileChange: setOpenMobile,
     }),
-    [open, openMobile, setOpen, setOpenMobile]
+    [shellId, defaultPanelWidth, open, openMobile, setOpen, setOpenMobile]
   )
 
   return {
+    shellId,
+    isNarrow,
+    panelWidth,
+    resizePanel,
     open,
     openMobile,
     setOpen,

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

@@ -92,6 +92,49 @@ export const FOCUSABLE_SELECTOR = [
 export const MOBILE_QUERY = "(max-width: 767px)"
 export const SIDEBAR_KEYBOARD_SHORTCUT = "b"
 
+/**
+ * The shell's layout contract, in px. Every entry lands on the provider's
+ * wrapper as a CSS variable, so a consumer overrides a column by restyling it
+ * rather than by passing a prop:
+ *
+ * | variable               | column                                    |
+ * | ---------------------- | ----------------------------------------- |
+ * | `--sidebar-width`      | left rail, expanded                       |
+ * | `--sidebar-width-icon` | left rail, folded to icons                |
+ * | `--panel-width`        | secondary panel: its floor AND its default |
+ * | `--inset-min-width`    | the body's floor                          |
+ *
+ * These are only the defaults. Every measurement resolves the live variable,
+ * so an override wins over the value written here.
+ */
+export const SHELL_WIDTHS = {
+  "--sidebar-width": "256px",
+  "--sidebar-width-icon": "56px",
+  "--sidebar-width-mobile": "18rem",
+  "--panel-width": "320px",
+  "--inset-min-width": "360px",
+} as const
+
+/** The expanded width of a panel docked to `side`: the secondary panel opens
+ * at `--panel-width`, the primary rail at `--sidebar-width`. */
+export function expandedWidthVar(side: "left" | "right") {
+  return side === "right" ? "var(--panel-width)" : "var(--sidebar-width)"
+}
+
+/** Resolve a CSS length — `var()` included — to px inside `host`'s cascade.
+ * Custom properties inherit, so a throwaway probe mounted in `host` reads the
+ * very `--sidebar-width` the shell lays out with, including a value a
+ * consumer overrode on the provider. Returns 0 when `host` has no layout
+ * (server render, `display: none`), so callers must fail open on 0 rather
+ * than treat it as a real measurement. */
+export function resolveLength(host: HTMLElement, value: string) {
+  const probe = document.createElement("div")
+  probe.style.cssText = `position:absolute;visibility:hidden;pointer-events:none;width:${value}`
+  host.appendChild(probe)
+  const px = probe.getBoundingClientRect().width
+  probe.remove()
+  return px
+}
 
 export const AnimatedSidebarContext =
   createContext<AnimatedSidebarContextValue | null>(null)
@@ -131,13 +174,10 @@ export function useIsMobile() {
   )
 }
 
-
 export function useAnimatedSidebarPanel() {
   const context = useContext(AnimatedSidebarPanelContext)
   if (!context) {
-    throw new Error(
-      "Animated Sidebar parts must be used inside AnimatedPanel."
-    )
+    throw new Error("Animated Sidebar parts must be used inside AnimatedPanel.")
   }
   return context
 }

package/src/components/composed/tree/CLAUDE.md

@@ -0,0 +1,132 @@
+# composed/tree
+
+Nested item tree in four shapes — `navigation`, `toc`, `sidebar` (icon rail),
+`files` (explorer). It is the **reference implementation** of the Jotai
+state pattern described in `react/CLAUDE.md` ("State" section) — read that
+first; this file only holds what is specific to the tree.
+
+## File map
+
+| File                | Owns                                                                                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------------- |
+| `type.ts`           | `TreeNode`, `TreeProps` (data form × controller form), `TreeState`/`TreeActions`, `@internal` config/handlers/seed. No imports besides React types. |
+| `tree-atom.ts`      | Every atom, keyed by `treeId` (`keyed()` families) and per node (`nodeFamily`). All mutations are write-only action atoms. `debugLabel` = `tree/<id>/<name>`. |
+| `use-tree.ts`       | `useTree(options)` — mounts an instance, projects controlled props into the store, returns the `TreeController`. |
+| `use-tree-state.ts` | `useTreeState(id)` (reads, re-renders on any change) and `useTreeActions(id)` (writes only, never re-renders). |
+| `use-tree-dnd.ts`   | Stable drag handlers for `files`; they read `draggedId`/`dropTarget` out of the store at call time.       |
+| `tree-context.ts`   | Context value = `{ treeId, renderTrailing, dnd }` only. Never the controller.                            |
+| `tree.tsx`          | `Tree` (props form → `UncontrolledTree`, controller form → `TreeView`), rail width measurement, roving keyboard nav. |
+| `tree-node.tsx`     | `TreeRow` (memoized). Per-node atom subscriptions, row kind resolution, rename input, tooltip, toc overlay toggle, trailing slot, branch animation. |
+| `constants.ts`      | Durations, easings, `RAIL_COLLAPSED_WIDTH`, motion variants.                                            |
+| `utils.ts`          | Pure tree helpers (`findNode`, `moveNode`, `renameNode`, ancestor walks).                               |
+| `index.ts`          | Barrel. Public atoms are listed explicitly — never `export *`.                                          |
+| `__tests__/`        | `tree.test.tsx` (rendering per variant), `use-tree.test.tsx` (controller/hook), `tree-atom.test.tsx` (store + memo guard). |
+
+## Row anatomy (as of 2026-08-18)
+
+- **Every non-section row is the shared `ui/button` `Button`** (`variant="ghost"`,
+  or `"secondary"` for the active sidebar row). Section headings in a 3-level
+  `navigation` tree stay a plain `<button>`. **Nothing renders an `<a>` any
+  more.**
+- `TreeNode.href` / `target` are **metadata** — they ride along on the node
+  handed to `onNavigate`. Routing has exactly one path:
+  `selectTreeNodeAtom` → `node.onSelect?.()` → `handlers.onNavigate?.(node)`.
+  One native behaviour survives the anchor removal: `toc` rows below the
+  route level (depth > 0, or any toc row with a `#hash` href) set
+  `window.location.hash` **after** `select` in `handlePress` — same order the
+  old `<a>` default gave, same `:target`/history semantics. A non-hash href
+  on a toc row disables the jump (it is a route). Controller `select()` from
+  outside does NOT jump — the hash write lives in the row, not the atom,
+  because it is a DOM concern.
+- Row-level `data-*` (`data-slot="tree-row"`, `data-id`, `data-branch`,
+  `data-expanded`, `data-active`, `data-cuelume-press`) come from
+  `rowInteractionProps`, spread onto the Button; Base UI's `mergeProps` lets
+  them override Button's own `data-slot="button"`. `sound` is forwarded to the
+  Button so its press/release cues follow the tree's `sound` prop.
+- Collapsed sidebar rows are `h-10! rounded-xl! justify-center px-0` tiles;
+  the rail is `w-10` (40px). `RAIL_COLLAPSED_WIDTH` **must equal** the class
+  (a test pins it to 40) — the motion target and the resting class must agree
+  or the rail jumps on its first fold.
+- Row kinds (`rowKindOf`): `link` (selectable, `aria-expanded` absent),
+  `toggle` (parent in navigation/files, `aria-expanded` on the row),
+  `section` (top level of a 3-level navigation tree). `toc` parents are
+  `link` rows with a separate overlay `<button aria-label="Expand X">`.
+- The trailing slot (`renderTrailing`, files only) is a **sibling** of the row
+  inside `.group/row-actions`, never a child — a button inside a button is
+  invalid HTML and React warns.
+
+## Lessons learned (chronological)
+
+1. **Rows read per-node atoms, not the controller.** Reading the whole
+   controller off context re-rendered every row on every toggle.
+   `tree-atom.test.tsx` counts `renderTrailing` calls per node to guard the
+   memo + per-node subscriptions. (0021dee)
+2. **Controlled props are projected, not mirrored.** `useTree` writes
+   controlled `items`/`activeId`/`collapsed` into the store in a layout effect
+   with write gates. `treeOwnedItemsAtom` reads empty while a prop owns the
+   data — without it an inline `items={[…]}` array loops forever.
+3. **Keep the rail label mounted.** Unmounting the label on collapse killed
+   the fold animation; it animates `width/opacity/x/display` in place and the
+   test asserts `display: none`, not absence. (12b6a1f)
+4. **Both rail width endpoints must be px.** Motion cannot tween a number
+   against `"100%"`; doing so pinned the inline width at the collapsed value
+   and the rail never reopened. The expanded width is measured off the
+   container, only while expanded, with the list's inline width cleared for
+   the sample. (a69072d, 2f7539f)
+5. **Tooltip is disabled, not unmounted, when the rail expands.** Swapping the
+   wrapper remounts the row and cuts the label fold short. Test asserts row
+   identity across collapse.
+6. **Trailing actions live beside the row.** See "Row anatomy". (2c59e53)
+7. **Rows became `Button`; anchors were removed** (2026-08-18, this branch).
+   Consequences that had to follow: tests query `role: "button"` everywhere,
+   `href` documentation flipped from "renders an anchor" to "metadata for
+   `onNavigate`", `RAIL_COLLAPSED_WIDTH` 44 → 40 to match `w-10`, `sound`
+   forwarded to Button, and the toc `#{id}` anchor test was rewritten as
+   "row selects, overlay toggle expands". The native `#{id}` jump for toc
+   rows was then restored via `location.hash` in `handlePress` (see "Row
+   anatomy") — dropping it silently was a regression, not a simplification.
+8. **`settleExit()` must run inside `act`.** AnimatePresence exits finishing
+   during a bare `setTimeout` wait produce "not wrapped in act" warnings;
+   `act(() => new Promise(r => setTimeout(r, 400)))` keeps them tracked. Query
+   **once** after settling — happy-dom serves stale `waitFor` results while an
+   exit is in flight (see memory `corpora-ui-happy-dom-exit-animations`).
+
+## Testing notes
+
+- Run from `react/`: `bun test src/components/composed/tree`.
+- happy-dom cannot drive Base UI hover/focus-visible, so tooltip tests assert
+  the wiring (`data-base-ui-tooltip-trigger`) not the popup.
+- happy-dom rects are zero-height, so DnD tests hit the 0.5-midpoint fallback
+  ("inside" for folders, "after" for leaves).
+- Motion sets no inline styles under happy-dom — the rail width tests lock
+  the **class**; the px tween is only verifiable in a real browser.
+- Browser check via the docs demo (`/components/tree`, dev server config
+  `corpora-ui-docs`): the demo's Base UI `Select` only takes clicks on the
+  option's real viewport rect (screenshot frame is scaled — convert), and if
+  the Browser pane tab is hidden (`document.hidden`) both WAAPI and motion's
+  frameloop pause, so animated end-states can't be observed there — front the
+  tab or use a real browser for the fold.
+
+## Change log
+
+- **2026-08-18 — fix/tree-collapsed** (on `release/v0.21.0`)
+  - `tree-node.tsx`: link/toggle rows render the shared `Button` (ghost /
+    secondary when active on sidebar); anchor branch removed; collapsed rail
+    rows `h-10! rounded-xl!`; rename input borderless; `cursor-pointer` on
+    rows/toggles; `sound` forwarded to Button.
+  - `tree.tsx`: rail resting class `w-11` → `w-10`, `gap-y-2!` when collapsed.
+  - `constants.ts`: `RAIL_COLLAPSED_WIDTH` 44 → 40.
+  - `type.ts` / `registry/components.ts`: `href`, `onNavigate`, `navigation`
+    and `toc` docs describe button rows + `onNavigate`-only navigation.
+  - `__tests__/tree.test.tsx`: link → button queries; new tests for `href`
+    passthrough, `sound={false}`, `RAIL_COLLAPSED_WIDTH` ↔ `w-10`, collapsed
+    tile classes, active-row `secondary` variant, toc row-vs-toggle split,
+    toc `#{id}` / `#hash` jump after `onNavigate` (route rows leave the hash
+    alone).
+  - `__tests__/*.test.tsx`: `settleExit` wrapped in `act`.
+- **2026-08-17** — Jotai migration (`ExegiaProvider`, atom families,
+  `useTree`/`useTreeState`/`useTreeActions`), rail reopen + measurement fixes,
+  label kept mounted, trailing actions moved out of the row, headless
+  controller API.
+- **2026-08-16** — Initial four-variant tree, tooltip on collapsed rail rows,
+  motion + a11y pass.