@exegia/corpora-ui 0.19.0 → 0.20.0

package/src/components/blocks/scaffold/use-panel-visibility.ts

@@ -0,0 +1,180 @@
+"use client"
+
+import * as React from "react"
+
+import { SCAFFOLD_PANEL_CAPACITY } from "./constants"
+import { getPanelCapacity } from "./utils"
+
+/**
+ * Internal bookkeeping for responsive panel hiding.
+ *
+ * - `visibleOrder`: visible panel ids, least-recently-activated first — the
+ *   front is what capacity pressure evicts next.
+ * - `autoHidden`: panels the scaffold hid because the canvas shrank, most
+ *   recent last. They return on their own when room comes back.
+ * - `userHidden`: panels hidden by a tab press. They stay hidden until the
+ *   tab is pressed again, however wide the canvas grows.
+ */
+interface PanelVisibilityState {
+  visibleOrder: string[]
+  autoHidden: string[]
+  userHidden: string[]
+}
+
+const EMPTY_STATE: PanelVisibilityState = {
+  visibleOrder: [],
+  autoHidden: [],
+  userHidden: [],
+}
+
+/** Fold the registered ids and current capacity into a settled state:
+ * prune departed panels, admit new ones, evict the least-recently-activated
+ * visible panels past capacity, and restore auto-hidden ones when room
+ * returns. Returns `prev` untouched when nothing changes. */
+function reconcile(
+  prev: PanelVisibilityState,
+  ids: readonly string[],
+  capacity: number
+): PanelVisibilityState {
+  const known = new Set(ids)
+  const visibleOrder = prev.visibleOrder.filter((id) => known.has(id))
+  const autoHidden = prev.autoHidden.filter((id) => known.has(id))
+  const userHidden = prev.userHidden.filter((id) => known.has(id))
+
+  const tracked = new Set([...visibleOrder, ...autoHidden, ...userHidden])
+  for (const id of ids) if (!tracked.has(id)) visibleOrder.push(id)
+
+  while (visibleOrder.length > capacity && visibleOrder.length > 1) {
+    autoHidden.push(visibleOrder.shift() as string)
+  }
+  while (visibleOrder.length < capacity && autoHidden.length > 0) {
+    visibleOrder.push(autoHidden.pop() as string)
+  }
+
+  const unchanged =
+    visibleOrder.join(" ") === prev.visibleOrder.join(" ") &&
+    autoHidden.join(" ") === prev.autoHidden.join(" ") &&
+    userHidden.join(" ") === prev.userHidden.join(" ")
+  return unchanged ? prev : { visibleOrder, autoHidden, userHidden }
+}
+
+export interface PanelVisibility {
+  /** How many panels currently fit side by side (1..capacity cap). */
+  panelCapacity: number
+  /** Ids of panels currently hidden (auto + user), for tabs to reflect. */
+  hiddenPanelIds: readonly string[]
+  isPanelHidden: (id: string) => boolean
+  togglePanelVisibility: (id: string) => void
+  /** Id of the panel whose tab is hovered — the canvas spotlights it. */
+  hoveredPanelId: string | null
+  /** @internal Tabs report pointer enter/leave on their label. */
+  setPanelHovered: (id: string, hovered: boolean) => void
+  /** @internal Canvas reports its ordered panel ids each render. */
+  registerPanelIds: (ids: readonly string[]) => void
+  /** @internal Canvas reports its measured width. */
+  setCanvasWidth: (width: number) => void
+}
+
+/** Owns which panels are hidden as the canvas gains and loses room.
+ * Lives in `Scaffold.Root`; Canvas and Tab reach it through context. */
+export function usePanelVisibility(): PanelVisibility {
+  const [panelIds, setPanelIds] = React.useState<readonly string[]>([])
+  const [measuredCapacity, setMeasuredCapacity] = React.useState<number | null>(
+    null
+  )
+  const [state, setState] = React.useState<PanelVisibilityState>(EMPTY_STATE)
+  const [hoveredPanelId, setHoveredPanelId] = React.useState<string | null>(
+    null
+  )
+
+  const panelCapacity = measuredCapacity ?? SCAFFOLD_PANEL_CAPACITY
+
+  const registerPanelIds = React.useCallback((ids: readonly string[]) => {
+    setPanelIds((prev) =>
+      prev.length === ids.length && prev.every((id, i) => id === ids[i])
+        ? prev
+        : [...ids]
+    )
+  }, [])
+
+  // Store the derived capacity, not the raw width — resize storms only
+  // re-render the tree when a panel actually gains or loses room.
+  const setCanvasWidth = React.useCallback((width: number) => {
+    setMeasuredCapacity(getPanelCapacity(width))
+  }, [])
+
+  // Settle during render (the derive-state-while-rendering pattern): ids
+  // and capacity arrive as state, so an effect here would only add a
+  // cascading render after each change.
+  const settled = reconcile(state, panelIds, panelCapacity)
+  if (settled !== state) setState(settled)
+
+  const togglePanelVisibility = React.useCallback(
+    (id: string) => {
+      setState((prev) => {
+        if (!panelIds.includes(id)) return prev
+        const hidden =
+          prev.autoHidden.includes(id) || prev.userHidden.includes(id)
+        if (!hidden && prev.visibleOrder.length <= 1) return prev
+
+        const next: PanelVisibilityState = hidden
+          ? {
+              // Showing: newest activation — reconcile evicts the oldest
+              // visible panel if the canvas can't fit one more.
+              visibleOrder: [...prev.visibleOrder, id],
+              autoHidden: prev.autoHidden.filter((other) => other !== id),
+              userHidden: prev.userHidden.filter((other) => other !== id),
+            }
+          : {
+              visibleOrder: prev.visibleOrder.filter((other) => other !== id),
+              autoHidden: prev.autoHidden,
+              userHidden: [...prev.userHidden, id],
+            }
+        return reconcile(next, panelIds, panelCapacity)
+      })
+    },
+    [panelIds, panelCapacity]
+  )
+
+  // Leaving clears only its own id — a tab that unmounts mid-hover must
+  // not wipe out a hover the pointer has already moved on to.
+  const setPanelHovered = React.useCallback((id: string, hovered: boolean) => {
+    setHoveredPanelId((prev) => {
+      if (hovered) return id
+      return prev === id ? null : prev
+    })
+  }, [])
+
+  const hiddenPanelIds = React.useMemo(
+    () => [...settled.autoHidden, ...settled.userHidden],
+    [settled]
+  )
+
+  const isPanelHidden = React.useCallback(
+    (id: string) => hiddenPanelIds.includes(id),
+    [hiddenPanelIds]
+  )
+
+  return React.useMemo(
+    () => ({
+      panelCapacity,
+      hiddenPanelIds,
+      isPanelHidden,
+      togglePanelVisibility,
+      hoveredPanelId,
+      setPanelHovered,
+      registerPanelIds,
+      setCanvasWidth,
+    }),
+    [
+      panelCapacity,
+      hiddenPanelIds,
+      isPanelHidden,
+      togglePanelVisibility,
+      hoveredPanelId,
+      setPanelHovered,
+      registerPanelIds,
+      setCanvasWidth,
+    ]
+  )
+}

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

@@ -2,6 +2,25 @@ import type { Variants } from "motion/react"
 import type { ClassNameValue } from "tailwind-merge"
 import type { TSubPanelVariant } from "@/components/blocks/scaffold/type.ts"
 import { EASE_OUT } from "@/lib/ease.ts"
+import {
+  SCAFFOLD_CANVAS_GAP,
+  SCAFFOLD_PANEL_CAPACITY,
+  SCAFFOLD_PANEL_MIN_WIDTH,
+} from "./constants"
+
+/**
+ * How many panels fit on a canvas of `width` px, granting each
+ * `SCAFFOLD_PANEL_MIN_WIDTH` plus the gaps between them. Clamped to
+ * [1, SCAFFOLD_PANEL_CAPACITY]; an unmeasured canvas (`null`) fits the cap.
+ */
+export function getPanelCapacity(width: number | null): number {
+  if (width === null) return SCAFFOLD_PANEL_CAPACITY
+  const fits = Math.floor(
+    (width + SCAFFOLD_CANVAS_GAP) /
+      (SCAFFOLD_PANEL_MIN_WIDTH + SCAFFOLD_CANVAS_GAP)
+  )
+  return Math.max(1, Math.min(SCAFFOLD_PANEL_CAPACITY, fits))
+}
 
 /** Desktop backdrop the whole scaffold sits on — a soft warm-gray wash. */
 export const scaffoldBackgroundClass: ClassNameValue =

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

@@ -0,0 +1,400 @@
+import { describe, expect, mock, test } from "bun:test"
+import { fireEvent, render, screen, waitFor } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { FileTextIcon, FolderIcon, SearchIcon } from "lucide-react"
+
+import { Tree } from "../index"
+import type { TreeNode } from "../type"
+import { moveNode } from "../utils"
+
+/** 3-level data — `navigation` promotes the top level to section names. */
+const SECTIONED: TreeNode[] = [
+  {
+    id: "research",
+    label: "Research",
+    children: [
+      { id: "search", label: "Search", icon: <SearchIcon />, href: "/search" },
+      {
+        id: "library",
+        label: "Library",
+        children: [
+          { id: "manuscripts", label: "Manuscripts", href: "/m" },
+          { id: "codices", label: "Codices", href: "/c" },
+        ],
+      },
+    ],
+  },
+  {
+    id: "workspace",
+    label: "Workspace",
+    children: [{ id: "notes", label: "Notes", href: "/notes" }],
+  },
+]
+
+/** 2-level data — the top level stays plain link rows. */
+const FLAT_NAV: TreeNode[] = [
+  { id: "search", label: "Search", href: "/search" },
+  {
+    id: "library",
+    label: "Library",
+    children: [{ id: "manuscripts", label: "Manuscripts", href: "/m" }],
+  },
+]
+
+const TOC: TreeNode[] = [
+  {
+    id: "guide",
+    label: "Guide",
+    href: "/guide",
+    children: [
+      {
+        id: "setup",
+        label: "Setup",
+        children: [{ id: "install", label: "Install" }],
+      },
+    ],
+  },
+  { id: "api", label: "API", href: "/api" },
+]
+
+const RAIL: TreeNode[] = [
+  { id: "search", label: "Search", icon: <SearchIcon />, href: "/search" },
+  { id: "notes", label: "Notes", icon: <FileTextIcon />, href: "/notes" },
+]
+
+const FILES: TreeNode[] = [
+  {
+    id: "src",
+    label: "src",
+    icon: <FolderIcon />,
+    defaultOpen: true,
+    children: [
+      { id: "index-ts", label: "index.ts" },
+      { id: "utils-ts", label: "utils.ts" },
+    ],
+  },
+  { id: "readme", label: "README.md" },
+]
+
+/** Branch exits run through AnimatePresence — let them settle on real
+ * timers, then query once (happy-dom serves stale waitFor queries while
+ * an exit is in flight). */
+const settleExit = () => new Promise((resolve) => setTimeout(resolve, 400))
+
+describe("Tree · navigation", () => {
+  test("3-level data renders top level as collapsible sections, not links", async () => {
+    const user = userEvent.setup()
+    render(<Tree items={SECTIONED} variant="navigation" />)
+
+    const section = screen.getByRole("button", { name: "Research" })
+    expect(section.getAttribute("aria-expanded")).toBe("true")
+    // Sections are buttons — no anchor wraps them.
+    expect(section.closest("a")).toBeNull()
+    expect(screen.getByRole("link", { name: "Search" })).toBeDefined()
+
+    // Collapsing the section folds its items away.
+    await user.click(section)
+    await settleExit()
+    expect(screen.queryByRole("link", { name: "Search" })).toBeNull()
+  })
+
+  test("2-level data keeps top level as links and parents as toggles", async () => {
+    const user = userEvent.setup()
+    render(<Tree items={FLAT_NAV} variant="navigation" />)
+
+    expect(screen.getByRole("link", { name: "Search" })).toBeDefined()
+    const parent = screen.getByRole("button", { name: "Library" })
+    expect(parent.getAttribute("aria-expanded")).toBe("false")
+
+    await user.click(parent)
+    expect(await screen.findByRole("link", { name: "Manuscripts" })).toBeDefined()
+  })
+
+  test("read-only variants render no drag or rename affordances", () => {
+    render(<Tree items={SECTIONED} variant="navigation" />)
+    const rows = document.querySelectorAll('[data-slot="tree-row"]')
+    expect(rows.length).toBeGreaterThan(0)
+    for (const row of rows) expect(row.getAttribute("draggable")).toBeNull()
+  })
+
+  test("activeId marks the row current and expands collapsed ancestors", async () => {
+    const { rerender } = render(
+      <Tree items={SECTIONED} variant="navigation" />
+    )
+    // Library starts collapsed — its children are absent.
+    expect(screen.queryByRole("link", { name: "Codices" })).toBeNull()
+
+    rerender(<Tree activeId="codices" items={SECTIONED} variant="navigation" />)
+    const active = await screen.findByRole("link", { name: "Codices" })
+    expect(active.getAttribute("aria-current")).toBe("page")
+  })
+
+  test("onNavigate fires for link rows after the node's own onSelect", async () => {
+    const user = userEvent.setup()
+    const order: string[] = []
+    const items: TreeNode[] = [
+      {
+        id: "a",
+        label: "Alpha",
+        href: "/a",
+        onSelect: () => order.push("onSelect"),
+      },
+    ]
+    render(
+      <Tree
+        items={items}
+        onNavigate={() => order.push("onNavigate")}
+        variant="navigation"
+      />
+    )
+    await user.click(screen.getByRole("link", { name: "Alpha" }))
+    expect(order).toEqual(["onSelect", "onNavigate"])
+  })
+})
+
+describe("Tree · toc", () => {
+  test("leaves anchor to #{id}; explicit hrefs win; parents keep their route", async () => {
+    const user = userEvent.setup()
+    render(<Tree items={TOC} variant="toc" />)
+
+    const guide = screen.getByRole("link", { name: "Guide" })
+    expect(guide.getAttribute("href")).toBe("/guide")
+
+    // Guide navigates on the row; its expansion is the overlay toggle.
+    await user.click(screen.getByRole("button", { name: "Expand Guide" }))
+    // Below the route level every node is an in-page anchor, parents
+    // included — only depth 0 carries routes.
+    const setup = await screen.findByRole("link", { name: "Setup" })
+    expect(setup.getAttribute("href")).toBe("#setup")
+
+    await user.click(screen.getByRole("button", { name: "Expand Setup" }))
+    const install = await screen.findByRole("link", { name: "Install" })
+    expect(install.getAttribute("href")).toBe("#install")
+  })
+})
+
+describe("Tree · sidebar", () => {
+  test("the rail's width class tracks collapsed in both directions", async () => {
+    // Locks the resting widths to the class, so the rail is right even when
+    // the animation never applies. NB this does NOT reproduce the bug it was
+    // written alongside — that was an inline width pinned at 44px by a
+    // px-against-"100%" motion target, and motion sets no inline styles
+    // under happy-dom. Only a real browser catches that one.
+    const { rerender } = render(<Tree items={RAIL} variant="sidebar" />)
+    const rail = () => document.querySelector('[data-slot="tree"]')
+
+    expect(rail()?.className).toContain("w-full")
+    expect(rail()?.getAttribute("data-collapsed")).toBeNull()
+
+    rerender(<Tree collapsed items={RAIL} variant="sidebar" />)
+    await settleExit()
+    expect(rail()?.className).toContain("w-11")
+    expect(rail()?.getAttribute("data-collapsed")).toBe("")
+
+    // Back open — the direction that was broken.
+    rerender(<Tree items={RAIL} variant="sidebar" />)
+    await settleExit()
+    expect(rail()?.className).toContain("w-full")
+    expect(rail()?.className).not.toContain("w-11")
+    expect(rail()?.getAttribute("data-collapsed")).toBeNull()
+  })
+
+  test("collapsed shows icon-only rows that keep an accessible name", async () => {
+    const { rerender } = render(<Tree items={RAIL} variant="sidebar" />)
+    expect(screen.getByRole("link", { name: "Search" }).textContent).toContain(
+      "Search"
+    )
+
+    rerender(<Tree collapsed items={RAIL} variant="sidebar" />)
+    await settleExit()
+    const row = screen.getByRole("link", { name: "Search" })
+    // The label folds to nothing rather than unmounting — keeping it in the
+    // DOM is what lets the fold animate — so assert the fold, not absence.
+    const label = row.querySelector('[data-slot="tree-row-label"]')
+    expect(label?.textContent).toBe("Search")
+    expect(label?.getAttribute("style")).toContain("display: none")
+    // With the label hidden, aria-label is what names the row.
+    expect(row.getAttribute("aria-label")).toBe("Search")
+  })
+
+  test("rail rows are tooltip triggers and keep identity across collapse", async () => {
+    // happy-dom can't drive Base UI's hover/focus-visible open logic, so
+    // assert the wiring: Base UI stamps its trigger attribute on the row.
+    const { rerender } = render(<Tree collapsed items={RAIL} variant="sidebar" />)
+    const collapsedRow = screen.getByRole("link", { name: "Search" })
+    expect(collapsedRow.hasAttribute("data-base-ui-tooltip-trigger")).toBe(true)
+
+    // The tooltip wrapper stays mounted when the rail expands (it is only
+    // disabled) — a remounted row would cut the label fold animation short.
+    // Let the label unfold before querying: mid-animation it is still
+    // display:none, and the row has no aria-label once expanded, so it has
+    // no accessible name to match on until the fold-out finishes.
+    // NB this asserts identity, not the fold-out itself — motion settles
+    // instantly under happy-dom, while in a real browser the rail currently
+    // does not reanimate back open. That defect is tracked separately; do
+    // not read this test as covering it.
+    rerender(<Tree items={RAIL} variant="sidebar" />)
+    await settleExit()
+    expect(screen.getByRole("link", { name: "Search" })).toBe(collapsedRow)
+  })
+
+  test("nested children are ignored — the rail is single-level", () => {
+    const items: TreeNode[] = [
+      {
+        id: "top",
+        label: "Top",
+        icon: <SearchIcon />,
+        children: [{ id: "nested", label: "Nested" }],
+      },
+    ]
+    render(<Tree items={items} variant="sidebar" />)
+    expect(screen.queryByText("Nested")).toBeNull()
+    // No chevron either — the row is a plain button.
+    expect(
+      screen.getByRole("button", { name: "Top" }).getAttribute("aria-expanded")
+    ).toBeNull()
+  })
+})
+
+describe("Tree · files", () => {
+  test("folders toggle on row press; only leaves navigate", async () => {
+    const user = userEvent.setup()
+    const onNavigate = mock(() => {})
+    render(<Tree items={FILES} onNavigate={onNavigate} variant="files" />)
+
+    await user.click(screen.getByText("index.ts"))
+    expect(onNavigate).toHaveBeenCalledTimes(1)
+
+    const folder = screen.getByRole("button", { name: /^src/ })
+    await user.click(folder)
+    expect(onNavigate).toHaveBeenCalledTimes(1)
+    await settleExit()
+    expect(screen.queryByText("index.ts")).toBeNull()
+  })
+
+  test("trailing actions sit beside the row, not inside it", async () => {
+    const user = userEvent.setup()
+    const onDelete = mock(() => {})
+    render(
+      <Tree
+        items={FILES}
+        renderTrailing={(node) => (
+          <button onClick={onDelete} type="button">
+            {`Delete ${node.label}`}
+          </button>
+        )}
+        variant="files"
+      />
+    )
+
+    // A folder row is a <button> and a leaf row an <a> — either one nesting
+    // the trailing button would be invalid markup React warns about.
+    for (const row of document.querySelectorAll('[data-slot="tree-row"]')) {
+      expect(row.querySelector("button, a")).toBeNull()
+    }
+
+    // Still wired: pressing it does not also toggle or navigate the row.
+    const folder = screen.getByRole("button", { name: /^src/ })
+    await user.click(screen.getByRole("button", { name: "Delete src" }))
+    expect(onDelete).toHaveBeenCalledTimes(1)
+    expect(folder.getAttribute("aria-expanded")).toBe("true")
+  })
+
+  test("double-click renames inline; Enter commits, Escape cancels", async () => {
+    const user = userEvent.setup()
+    const onRename = mock(() => {})
+    render(<Tree items={FILES} onRename={onRename} variant="files" />)
+
+    await user.dblClick(screen.getByText("README.md"))
+    const input = document.querySelector<HTMLInputElement>(
+      '[data-slot="tree-rename-input"]'
+    )
+    expect(input).not.toBeNull()
+    await user.clear(input as HTMLInputElement)
+    await user.type(input as HTMLInputElement, "NOTES.md{Enter}")
+    expect(onRename).toHaveBeenCalledWith("readme", "NOTES.md")
+
+    // Escape leaves the label untouched.
+    await user.dblClick(screen.getByText("README.md"))
+    await user.keyboard("{Escape}")
+    expect(onRename).toHaveBeenCalledTimes(1)
+  })
+
+  test("drag reorders around a row and drops into a folder", () => {
+    const onMove = mock(() => {})
+    render(<Tree items={FILES} onMove={onMove} variant="files" />)
+    const rows = Array.from(
+      document.querySelectorAll<HTMLElement>('[data-slot="tree-row"]')
+    )
+    const src = rows.find((row) => row.dataset.id === "src") as HTMLElement
+    const readme = rows.find(
+      (row) => row.dataset.id === "readme"
+    ) as HTMLElement
+    expect(src.getAttribute("draggable")).toBe("true")
+
+    // happy-dom rects are zero-height, so the hook falls back to the
+    // 0.5 midpoint → "inside" for folders, "after" for leaves.
+    fireEvent.dragStart(readme)
+    fireEvent.dragOver(src)
+    fireEvent.drop(src)
+    expect(onMove).toHaveBeenCalledWith("readme", "src", 2)
+
+    // A folder never drops into its own subtree.
+    onMove.mockClear()
+    fireEvent.dragStart(src)
+    const indexRow = rows.find(
+      (row) => row.dataset.id === "index-ts"
+    ) as HTMLElement
+    fireEvent.dragOver(indexRow)
+    fireEvent.drop(indexRow)
+    expect(onMove).not.toHaveBeenCalled()
+  })
+
+  test("moveNode reducer lifts and reinserts immutably", () => {
+    const next = moveNode(FILES, "readme", "src", 2)
+    const src = next.find((node) => node.id === "src")
+    expect(src?.children?.map((child) => child.id)).toEqual([
+      "index-ts",
+      "utils-ts",
+      "readme",
+    ])
+    // Refuses a drop into the moved node's own subtree.
+    expect(moveNode(FILES, "src", "index-ts", 0)).toEqual(FILES)
+    // The input is untouched.
+    expect(FILES.find((node) => node.id === "src")?.children?.length).toBe(2)
+  })
+})
+
+describe("Tree · keyboard", () => {
+  test("arrows walk visible rows; right expands, left collapses", async () => {
+    const user = userEvent.setup()
+    render(<Tree items={FLAT_NAV} variant="navigation" />)
+
+    const search = screen.getByRole("link", { name: "Search" })
+    search.focus()
+    await user.keyboard("{ArrowDown}")
+    const library = screen.getByRole("button", { name: "Library" })
+    expect(document.activeElement).toBe(library)
+
+    await user.keyboard("{ArrowRight}")
+    expect(await screen.findByRole("link", { name: "Manuscripts" })).toBeDefined()
+    await waitFor(() =>
+      expect(library.getAttribute("aria-expanded")).toBe("true")
+    )
+
+    await user.keyboard("{ArrowLeft}")
+    await settleExit()
+    expect(screen.queryByRole("link", { name: "Manuscripts" })).toBeNull()
+    expect(document.activeElement).toBe(library)
+  })
+
+  test("F2 starts a rename on the focused files row", async () => {
+    const user = userEvent.setup()
+    render(<Tree items={FILES} onRename={() => {}} variant="files" />)
+    screen.getByText("README.md").closest("button")?.focus()
+    await user.keyboard("{F2}")
+    expect(
+      document.querySelector('[data-slot="tree-rename-input"]')
+    ).not.toBeNull()
+  })
+})