@exegia/corpora-ui 0.20.0 → 0.22.0

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.

package/src/components/composed/tree/__tests__/tree-atom.test.tsx

@@ -0,0 +1,217 @@
+import { describe, expect, mock, test } from "bun:test"
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { createStore } from "jotai"
+
+import { ExegiaProvider } from "@/state"
+import { Tree, useTreeActions, useTreeState } from "../index"
+import {
+  DEFAULT_TREE_CONFIG,
+  expandTreeNodeAtom,
+  mountTreeAtom,
+  removeTreeInstance,
+  renameTreeNodeAtom,
+  resetTreeAtom,
+  treeCanRenameAtom,
+  treeCollapsedAtom,
+  treeExpandedIdsAtom,
+  treeItemsAtom,
+  treeRailCollapsedAtom,
+} from "../tree-atom"
+import type { TreeConfig, TreeNode } from "../type"
+
+type Store = ReturnType<typeof createStore>
+
+const FILES: TreeNode[] = [
+  {
+    id: "src",
+    label: "src",
+    children: [{ id: "index-ts", label: "index.ts" }],
+  },
+  { id: "readme", label: "README.md" },
+]
+
+function mount(
+  store: Store,
+  id: string,
+  config: Partial<TreeConfig>,
+  items: TreeNode[] = FILES
+) {
+  store.set(
+    mountTreeAtom(id),
+    { ...DEFAULT_TREE_CONFIG, ...config },
+    { items, collapsed: false }
+  )
+}
+
+describe("tree atoms · instance isolation", () => {
+  test("two ids never share state", () => {
+    const store = createStore()
+    mount(store, "a", { variant: "files" })
+    mount(store, "b", { variant: "files" })
+
+    store.set(expandTreeNodeAtom("a"), "src")
+    expect(store.get(treeExpandedIdsAtom("a")).has("src")).toBe(true)
+    expect(store.get(treeExpandedIdsAtom("b")).has("src")).toBe(false)
+  })
+
+  test("two stores never share state under the same id", () => {
+    const one = createStore()
+    const two = createStore()
+    mount(one, "shared", { variant: "files" })
+    mount(two, "shared", { variant: "files" })
+
+    one.set(expandTreeNodeAtom("shared"), "src")
+    expect(one.get(treeExpandedIdsAtom("shared")).has("src")).toBe(true)
+    expect(two.get(treeExpandedIdsAtom("shared")).has("src")).toBe(false)
+  })
+
+  test("removeTreeInstance drops the slice back to its defaults", () => {
+    const store = createStore()
+    mount(store, "gone", { variant: "files" })
+    store.set(expandTreeNodeAtom("gone"), "src")
+
+    removeTreeInstance("gone")
+    expect(store.get(treeExpandedIdsAtom("gone")).size).toBe(0)
+    expect(store.get(treeItemsAtom("gone"))).toEqual([])
+  })
+})
+
+describe("tree atoms · write gates", () => {
+  test("hook-owned data renames itself", () => {
+    const store = createStore()
+    mount(store, "owned", { variant: "files", managesItems: true })
+    expect(store.get(treeCanRenameAtom("owned"))).toBe(true)
+
+    store.set(renameTreeNodeAtom("owned"), "readme", "GUIDE.md")
+    expect(store.get(treeItemsAtom("owned"))[1]?.label).toBe("GUIDE.md")
+  })
+
+  test("a controlled items prop is never overwritten, only reported", () => {
+    const store = createStore()
+    const onItemsChange = mock((items: TreeNode[]) => void items)
+    mount(store, "controlled", {
+      variant: "files",
+      controlsItems: true,
+      managesItems: true,
+    })
+    store.set(
+      // Handlers ride along with the options in real use; set directly here.
+      mountTreeAtom("controlled"),
+      {
+        ...DEFAULT_TREE_CONFIG,
+        variant: "files",
+        controlsItems: true,
+        managesItems: true,
+      },
+      { items: FILES, collapsed: false }
+    )
+
+    store.set(renameTreeNodeAtom("controlled"), "readme", "GUIDE.md")
+    expect(store.get(treeItemsAtom("controlled"))[1]?.label).toBe("README.md")
+    expect(onItemsChange).not.toHaveBeenCalled()
+  })
+
+  test("the rail fold reads as false outside sidebar", () => {
+    const store = createStore()
+    mount(store, "files-rail", { variant: "files" })
+    store.set(treeRailCollapsedAtom("files-rail"), true)
+    expect(store.get(treeCollapsedAtom("files-rail")).valueOf()).toBe(false)
+
+    mount(store, "sidebar-rail", { variant: "sidebar" })
+    store.set(treeRailCollapsedAtom("sidebar-rail"), true)
+    expect(store.get(treeCollapsedAtom("sidebar-rail")).valueOf()).toBe(true)
+  })
+
+  test("reset replays the mount seed", () => {
+    const store = createStore()
+    mount(store, "replay", { variant: "files" })
+    store.set(expandTreeNodeAtom("replay"), "src")
+    store.set(renameTreeNodeAtom("replay"), "readme", "GUIDE.md")
+
+    store.set(resetTreeAtom("replay"))
+    expect(store.get(treeExpandedIdsAtom("replay")).size).toBe(0)
+    expect(store.get(treeItemsAtom("replay"))[1]?.label).toBe("README.md")
+  })
+})
+
+describe("ExegiaProvider · driving a tree by id", () => {
+  /** A component with no relationship to the Tree beyond its id. */
+  function Remote() {
+    const actions = useTreeActions("app-files")
+    const { expandedIds } = useTreeState("app-files")
+    return (
+      <button onClick={() => actions.expand("src")} type="button">
+        {`expand (${expandedIds.size})`}
+      </button>
+    )
+  }
+
+  test("a sibling component expands the tree through one provider", async () => {
+    const user = userEvent.setup()
+    render(
+      <ExegiaProvider store={createStore()}>
+        <Tree items={FILES} treeId="app-files" variant="files" />
+        <Remote />
+      </ExegiaProvider>
+    )
+
+    // src has no defaultOpen, so its child starts unmounted.
+    expect(screen.queryByText("index.ts")).toBeNull()
+
+    await user.click(screen.getByRole("button", { name: /^expand/ }))
+    expect(await screen.findByText("index.ts")).toBeDefined()
+    // The remote reader saw the change too.
+    expect(screen.getByRole("button", { name: "expand (1)" })).toBeDefined()
+  })
+})
+
+describe("Tree · render granularity", () => {
+  test("expanding one branch leaves its sibling's row untouched", async () => {
+    const user = userEvent.setup()
+    // `renderTrailing` runs inside a row's render, so counting calls per id is
+    // a proxy for counting that row's renders.
+    const renders = new Map<string, number>()
+    const items: TreeNode[] = [
+      { id: "a", label: "a", children: [{ id: "a-1", label: "a-1" }] },
+      { id: "b", label: "b", children: [{ id: "b-1", label: "b-1" }] },
+    ]
+
+    function Toggle() {
+      const actions = useTreeActions("granular")
+      return (
+        <button onClick={() => actions.expand("a")} type="button">
+          go
+        </button>
+      )
+    }
+
+    render(
+      <ExegiaProvider store={createStore()}>
+        <Tree
+          items={items}
+          renderTrailing={(node) => {
+            renders.set(node.id, (renders.get(node.id) ?? 0) + 1)
+            return null
+          }}
+          treeId="granular"
+          variant="files"
+        />
+        <Toggle />
+      </ExegiaProvider>
+    )
+
+    const beforeA = renders.get("a") ?? 0
+    const beforeB = renders.get("b") ?? 0
+    expect(beforeA).toBeGreaterThan(0)
+    expect(beforeB).toBeGreaterThan(0)
+
+    await user.click(screen.getByRole("button", { name: "go" }))
+    await screen.findByText("a-1")
+
+    // a's branch opened, so a's row re-rendered…
+    expect(renders.get("a")).toBeGreaterThan(beforeA)
+    // …and b, whose atoms did not change, did not.
+    expect(renders.get("b")).toBe(beforeB)
+  })
+})