@exegia/corpora-ui 0.19.0 → 0.21.0

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

@@ -0,0 +1,286 @@
+"use client"
+
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+import { TooltipProvider } from "@/components/ui/tooltip"
+import { TreeContext } from "./tree-context"
+import { TreeRow } from "./tree-node"
+import type {
+  TreeContextValue,
+  TreeController,
+  TreeDataProps,
+  TreeNode,
+  TreeProps,
+} from "./type"
+import {
+  RAIL_COLLAPSED_WIDTH,
+  TREE_COLLAPSE_DURATION,
+  TREE_EASE,
+} from "./constants"
+import { useTree } from "./use-tree"
+import { useTreeDndHandlers } from "./use-tree-dnd"
+import { motion, useReducedMotion } from "motion/react"
+
+const DEFAULT_LABELS: Record<TreeController["variant"], string> = {
+  navigation: "Main",
+  toc: "On this page",
+  sidebar: "Main",
+  files: "Files",
+}
+
+/**
+ * A nested item tree with four shapes: `navigation` (app nav — 3-level
+ * data promotes the top level to collapsible section names), `toc`
+ * (routes on top, in-page `#` anchors at the leaves), `sidebar` (a
+ * single-level rail that collapses to icons) and `files` (a compact file
+ * explorer with rename, drag-and-drop and trailing row actions).
+ *
+ * Two ways to drive it. Data-driven like the sidebar block: pass `items`,
+ * wire `onNavigate` into your router. Or hold a `useTree` controller and
+ * pass it as `tree` — same rendering, but expand, collapse, select, rename
+ * and reorder are then callable from anywhere in your app.
+ *
+ * Branches expand with a soft height morph and row stagger; the rail's
+ * labels fold away when `collapsed` flips. Arrow keys walk visible rows,
+ * expand and collapse; F2 renames in `files`.
+ */
+export function Tree(props: TreeProps): React.ReactElement {
+  // Two components rather than one: hooks may not be called conditionally,
+  // and the controller form has no props to build a fallback controller
+  // from. Nobody switches a tree between the two forms at runtime.
+  return props.tree ? (
+    <TreeView
+      ariaLabel={props.ariaLabel}
+      className={props.className}
+      renderTrailing={props.renderTrailing}
+      tree={props.tree}
+    />
+  ) : (
+    <UncontrolledTree {...props} />
+  )
+}
+
+/** The props form: builds its own controller and renders through it. */
+function UncontrolledTree(props: TreeDataProps): React.ReactElement {
+  const {
+    variant,
+    items,
+    activeId,
+    onNavigate,
+    sound = true,
+    ariaLabel,
+    className,
+  } = props
+  const tree = useTree({
+    treeId: props.treeId,
+    variant,
+    items,
+    activeId,
+    onNavigate,
+    sound,
+    collapsed: variant === "sidebar" ? (props.collapsed ?? false) : undefined,
+    onMove: variant === "files" ? props.onMove : undefined,
+    onRename: variant === "files" ? props.onRename : undefined,
+  })
+  return (
+    <TreeView
+      ariaLabel={ariaLabel}
+      className={className}
+      renderTrailing={variant === "files" ? props.renderTrailing : undefined}
+      tree={tree}
+    />
+  )
+}
+
+interface TreeViewProps {
+  tree: TreeController
+  ariaLabel?: string
+  className?: string
+  renderTrailing?: (node: TreeNode) => React.ReactNode
+}
+
+/** Rendering only — every piece of state and behaviour lives on `tree`. */
+function TreeView({
+  tree,
+  ariaLabel,
+  className,
+  renderTrailing,
+}: TreeViewProps): React.ReactElement {
+  const { variant, items, sectioned, collapsed } = tree
+  const rootRef = React.useRef<HTMLUListElement>(null)
+  const reduce = useReducedMotion()
+
+  // The rail animates between two px widths, so the expanded one has to be
+  // measured off the container. Watched rather than read once: the rail is
+  // as wide as whatever holds it, which can change on resize.
+  //
+  // A container with no width of its own sizes to the list — so it shrinks
+  // around the 40px rail once collapsed and follows the list mid-tween. Both
+  // would feed the list's own width back in as its target and pin it. So:
+  // no observing while collapsed (the last expanded width stands), and each
+  // sample is taken with the list's inline width cleared, so the classes'
+  // resting width — not the tween — is what the container is holding.
+  const railRef = React.useRef<HTMLElement>(null)
+  const [railWidth, setRailWidth] = React.useState<number | null>(null)
+  React.useLayoutEffect(() => {
+    const container = railRef.current
+    const list = rootRef.current
+    if (variant !== "sidebar" || collapsed || !container || !list) return
+    const measure = () => {
+      const inline = list.style.width
+      list.style.width = ""
+      const width = container.clientWidth
+      list.style.width = inline
+      setRailWidth(width)
+    }
+    measure()
+    const observer = new ResizeObserver(measure)
+    observer.observe(container)
+    return () => observer.disconnect()
+  }, [variant, collapsed])
+
+  // Until the measurement lands the className carries the width, so the
+  // rail is never wrong — just not animated on its very first frame.
+  const railTarget =
+    variant === "sidebar" && railWidth !== null
+      ? { width: collapsed ? RAIL_COLLAPSED_WIDTH : railWidth }
+      : undefined
+
+  // Roving over the DOM rather than a parallel model: collapsed branches
+  // unmount, so a row query is exactly the visible set in order.
+  function handleKeyDown(event: React.KeyboardEvent) {
+    const row = (event.target as HTMLElement).closest<HTMLElement>(
+      '[data-slot="tree-row"]'
+    )
+    const root = rootRef.current
+    if (!row || !root) return
+    const rows = Array.from(
+      root.querySelectorAll<HTMLElement>('[data-slot="tree-row"]')
+    )
+    const index = rows.indexOf(row)
+    if (index < 0) return
+    const id = row.getAttribute("data-id")
+    const branch = row.hasAttribute("data-branch")
+    const open = row.hasAttribute("data-expanded")
+
+    const focusRow = (target: HTMLElement | undefined) => {
+      if (!target) return
+      event.preventDefault()
+      target.focus()
+    }
+
+    switch (event.key) {
+      case "ArrowDown":
+        focusRow(rows[index + 1])
+        break
+      case "ArrowUp":
+        focusRow(rows[index - 1])
+        break
+      case "Home":
+        focusRow(rows[0])
+        break
+      case "End":
+        focusRow(rows[rows.length - 1])
+        break
+      case "ArrowRight":
+        if (branch && !open && id) {
+          event.preventDefault()
+          tree.expand(id)
+        } else if (open) {
+          focusRow(rows[index + 1])
+        }
+        break
+      case "ArrowLeft":
+        if (open && id) {
+          event.preventDefault()
+          tree.collapse(id)
+        } else {
+          focusRow(
+            row
+              .closest("li")
+              ?.parentElement?.closest("li")
+              ?.querySelector<HTMLElement>('[data-slot="tree-row"]') ??
+              undefined
+          )
+        }
+        break
+      case "F2":
+        if (id && tree.canRename) {
+          event.preventDefault()
+          tree.startRename(id)
+        }
+        break
+    }
+  }
+
+  // Rows take the tree's id and the stable drag handlers, never the
+  // controller — so this value keeps its identity and a toggle re-renders only
+  // the rows whose own atoms changed.
+  const dnd = useTreeDndHandlers(tree.treeId)
+  const context = React.useMemo<TreeContextValue>(
+    () => ({ treeId: tree.treeId, renderTrailing, dnd }),
+    [tree.treeId, renderTrailing, dnd]
+  )
+
+  const label = ariaLabel ?? DEFAULT_LABELS[variant]
+  let rendered = (
+    <motion.ul
+      aria-label={label}
+      className={cn(
+        "flex h-full min-w-0 flex-col",
+        // Resting widths, and the fallback until the rail is measured. The
+        // motion target below overrides these with an inline width.
+        collapsed ? "w-10 gap-y-2!" : "w-full",
+        variant === "files" ? "gap-px" : sectioned ? "gap-3" : "gap-0.5"
+      )}
+      // Both endpoints must be px: motion cannot interpolate a number
+      // against "100%", and animating 40 -> "100%" pinned the inline width
+      // at 40px, so the rail collapsed once and never reopened. The
+      // expanded target is the rail's own measured width.
+      initial={false}
+      animate={railTarget}
+      transition={
+        reduce
+          ? { duration: 0 }
+          : { duration: TREE_COLLAPSE_DURATION, ease: TREE_EASE }
+      }
+      data-collapsed={collapsed ? "" : undefined}
+      data-slot="tree"
+      data-variant={variant}
+      onKeyDown={handleKeyDown}
+      ref={rootRef}
+      role="tree"
+    >
+      {items.map((node) => (
+        <TreeRow depth={0} key={node.id} node={node} />
+      ))}
+    </motion.ul>
+  )
+
+  // The collapsed rail's rows carry tooltips — one provider groups their
+  // open state and drops the hover delay across the rail. Mounted for the
+  // expanded rail too: toggling the wrapper with `collapsed` would remount
+  // every row and skip the label fold animation.
+  if (variant === "sidebar")
+    rendered = <TooltipProvider>{rendered}</TooltipProvider>
+
+  return (
+    <TreeContext.Provider value={context}>
+      {variant === "files" ? (
+        <div className={cn("min-w-0", className)} data-slot="tree-root">
+          {rendered}
+        </div>
+      ) : (
+        <nav
+          aria-label={label}
+          className={cn("flex h-full min-w-0 justify-center", className)}
+          data-slot="tree-root"
+          ref={railRef}
+        >
+          {rendered}
+        </nav>
+      )}
+    </TreeContext.Provider>
+  )
+}

package/src/components/composed/tree/type.ts

@@ -0,0 +1,322 @@
+import type * as React from "react"
+
+/** One node in the tree. Nesting depth carries meaning per variant — see
+ * `TreeProps["variant"]`. */
+export interface TreeNode {
+  id: string
+  label: string
+  /** Leading icon. Required in practice for `sidebar` — it is all that
+   * remains of a row while the rail is collapsed. */
+  icon?: React.ReactNode
+  /** Route metadata for the consumer's `onNavigate` — every row renders as
+   * a button, so this is never turned into an anchor element. Read it (with
+   * `target`) off the node your handler receives. One native behaviour is
+   * kept: `toc` rows below the route level jump to `#{id}` after select
+   * (a `#hash` href overrides the id; a non-hash href disables the jump). */
+  href?: string
+  target?: "_blank" | "_self" | "_parent" | "_top"
+  disabled?: boolean
+  /** Start expanded. Ancestors of `activeId` expand regardless. */
+  defaultOpen?: boolean
+  /** Trailing hint — a count, a "New" pill. */
+  badge?: React.ReactNode
+  /** Fires on selection, before the tree-level `onNavigate`. */
+  onSelect?: () => void
+  children?: TreeNode[]
+}
+
+export type TreeVariant = "navigation" | "toc" | "sidebar" | "files"
+
+/** Where a dragged row lands relative to its drop target. */
+export type TreeDropPosition = "before" | "after" | "inside"
+
+/** Key for one tree’s state in the store. Any stable string; `useTree`
+ * generates one when you don't pass it. */
+export type TreeInstanceId = string
+
+/** Row a drag hovers, and where the drop would land. */
+export interface TreeDropTarget {
+  id: string
+  position: TreeDropPosition
+}
+
+interface TreeBaseProps {
+  items: TreeNode[]
+  /** Key this tree's state under a name your app can address —
+   * `useTreeState("app-nav")` / `useTreeActions("app-nav")` reach it from
+   * anywhere under `ExegiaProvider`. Without one the tree generates a key
+   * and its state is dropped when it unmounts. */
+  treeId?: TreeInstanceId
+  /** Never set on the data form — `tree` selects the controller form. */
+  tree?: never
+  /** `id` of the current entry — matches any depth. Its ancestors expand. */
+  activeId?: string
+  /** Fires for every selection (rows and leaves alike), after the node's
+   * own `onSelect`. Rows are buttons, so this is the routing path — wire
+   * your router's navigate here. `toc` rows below the route level still jump
+   * to `#{id}` natively, after this fires. */
+  onNavigate?: (node: TreeNode) => void
+  /** Expand/collapse cues. Silent until `bindSounds()`. */
+  sound?: boolean
+  ariaLabel?: string
+  className?: string
+}
+
+interface TreeReadonlyProps {
+  collapsed?: never
+  onMove?: never
+  onRename?: never
+  renderTrailing?: never
+}
+
+/** Drive the tree from a `useTree` controller instead of raw props. The
+ * controller carries the variant, the data and every handler; only the
+ * presentational props stay here. */
+export interface TreeControllerProps {
+  tree: TreeController
+  items?: never
+  ariaLabel?: string
+  className?: string
+  /** Row actions revealed on hover/focus (`files` only — ignored by the
+   * other variants, which the controller form cannot type-gate). */
+  renderTrailing?: (node: TreeNode) => React.ReactNode
+}
+
+/** Either form: raw props, or a `useTree` controller via `tree`. */
+export type TreeProps = TreeDataProps | TreeControllerProps
+
+/** The four shapes a Tree takes. Editing props only exist on `files`;
+ * `collapsed` only on `sidebar` — the union is the contract. */
+export type TreeDataProps = TreeBaseProps &
+  (
+    | ({
+        /** Nested app navigation. With 3 levels of nodes the top level
+         * becomes collapsible section names (styled as headings, not
+         * rows); with 2 it renders plain selectable rows. */
+        variant: "navigation"
+      } & TreeReadonlyProps)
+    | ({
+        /** Table of contents: top-level nodes are routes (handled in
+         * `onNavigate`); rows below jump to `#{id}` after select, like an
+         * anchor would. Parents select on the row and expand from a
+         * separate overlay chevron. */
+        variant: "toc"
+      } & TreeReadonlyProps)
+    | ({
+        /** Single-level icon rail. `collapsed` shrinks rows to their
+         * leading icon; nested children are ignored. */
+        variant: "sidebar"
+        collapsed?: boolean
+      } & Omit<TreeReadonlyProps, "collapsed">)
+    | {
+        /** File explorer: only leaves navigate, folders toggle. Compact
+         * spacing; rename, drag-and-drop and trailing actions enabled. */
+        variant: "files"
+        /** Enables drag-and-drop. Reorder `items` yourself: `parentId`
+         * `null` means the root list, `index` is the slot among the new
+         * siblings (computed on the list without the dragged node). */
+        onMove?: (id: string, parentId: string | null, index: number) => void
+        /** Enables inline rename (double-click or F2). */
+        onRename?: (id: string, label: string) => void
+        /** Row actions revealed on hover/focus — a menu, a delete icon. */
+        renderTrailing?: (node: TreeNode) => React.ReactNode
+        collapsed?: never
+      }
+  )
+
+/** Options for `useTree`. Each of `items`, `activeId` and `collapsed` is
+ * controlled when passed and hook-owned when its `default*` twin is used
+ * instead. */
+export interface UseTreeOptions {
+  /** Key this tree's state under a name your app can address —
+   * `useTreeState("app-nav")` / `useTreeActions("app-nav")` reach it from
+   * anywhere under `ExegiaProvider`. Without one the hook generates a key
+   * and the state is dropped when the component unmounts. */
+  treeId?: TreeInstanceId
+  /** Which shape the tree takes — gates rename/reorder (`files`) and the
+   * collapsible rail (`sidebar`). */
+  variant: TreeVariant
+  /** Controlled data. With it, `rename`/`move` only report the edit unless
+   * you also pass `onItemsChange`. */
+  items?: TreeNode[]
+  /** Hook-owned data — `rename` and `move` apply the edit themselves. */
+  defaultItems?: TreeNode[]
+  /** Next tree after a `rename`/`move`. Also enables self-applying edits
+   * on top of controlled `items`. */
+  onItemsChange?: (items: TreeNode[]) => void
+  /** Controlled selection. Ancestors of the active node expand. */
+  activeId?: string
+  defaultActiveId?: string
+  /** Fires for every selection (rows and leaves alike), after the node's
+   * own `onSelect` — wire your router's navigate here. */
+  onNavigate?: (node: TreeNode) => void
+  /** Start with these ids expanded instead of the `defaultOpen` set. */
+  defaultExpandedIds?: Iterable<string>
+  onExpandedChange?: (ids: string[]) => void
+  /** Controlled rail fold (`sidebar` only). */
+  collapsed?: boolean
+  defaultCollapsed?: boolean
+  onCollapsedChange?: (collapsed: boolean) => void
+  /** Enables rename (`files`). Not needed when the hook owns the data. */
+  onRename?: (id: string, label: string) => void
+  /** Enables drag-and-drop (`files`). `parentId` `null` means the root
+   * list, `index` is the slot among the new siblings (computed on the list
+   * without the moved node). Not needed when the hook owns the data. */
+  onMove?: (id: string, parentId: string | null, index: number) => void
+  /** Expand/collapse cues. Silent until `bindSounds()`. */
+  sound?: boolean
+}
+
+/** Everything the tree can do, callable from outside the component.
+ * Returned by `useTree` and accepted by `<Tree tree={…} />`. */
+export interface TreeController {
+  /** The key this tree's state is stored under. */
+  treeId: TreeInstanceId
+  variant: TreeVariant
+  items: TreeNode[]
+  /** `navigation` with 3 levels of nodes — depth 0 renders as sections. */
+  sectioned: boolean
+  /** Ids of the section headings, empty unless `sectioned`. Pass one to
+   * `expand`/`collapse`/`toggleExpanded` to work a whole section. */
+  sectionIds: string[]
+  sound: boolean
+  getNode: (id: string) => TreeNode | null
+
+  expandedIds: ReadonlySet<string>
+  isExpanded: (id: string) => boolean
+  expand: (id: string) => void
+  collapse: (id: string) => void
+  toggleExpanded: (id: string) => void
+  expandAll: () => void
+  collapseAll: () => void
+  /** Open every ancestor of `id`, leaving the rest of the tree alone. */
+  reveal: (id: string) => void
+
+  /** Rail folded to icons — always `false` outside `sidebar`. */
+  collapsed: boolean
+  setCollapsed: (collapsed: boolean) => void
+  toggleCollapsed: () => void
+
+  activeId?: string
+  /** Select a node: runs its `onSelect`, then `onNavigate`. Inert on
+   * disabled and unknown nodes. */
+  select: (id: string) => void
+
+  /** Whether rename is wired up at all (`files` + a handler or owned data). */
+  canRename: boolean
+  /** Rename target id, `null` while idle. */
+  renamingId: string | null
+  startRename: (id: string) => void
+  cancelRename: () => void
+  /** Commit a rename and leave rename mode. Blank or unchanged labels are
+   * dropped. */
+  rename: (id: string, label: string) => void
+
+  /** Whether reorder is wired up at all. */
+  canMove: boolean
+  move: (id: string, parentId: string | null, index: number) => void
+
+  /** Back to the values the tree mounted with. */
+  reset: () => void
+
+  dnd: TreeDndContextValue
+}
+
+/** @internal What a row needs from the root, threaded through context so
+ * the recursive rows stay prop-light.
+ *
+ * Deliberately free of tree state. Rows read state from per-node atoms, so
+ * this value keeps its identity for the life of the tree and expanding one
+ * branch no longer re-renders every row through context. */
+export interface TreeContextValue {
+  treeId: TreeInstanceId
+  renderTrailing?: (node: TreeNode) => React.ReactNode
+  dnd: TreeDndHandlers
+}
+
+/** @internal The drag event handlers, stable for the life of the tree —
+ * they read drag state out of the store instead of closing over it, so
+ * handing them to every row costs no re-renders. */
+export interface TreeDndHandlers {
+  enabled: boolean
+  onRowDragStart: (event: React.DragEvent, id: string) => void
+  onRowDragOver: (event: React.DragEvent, node: TreeNode) => void
+  onRowDragLeave: (event: React.DragEvent) => void
+  onRowDrop: (event: React.DragEvent, node: TreeNode) => void
+  onRowDragEnd: () => void
+}
+
+/** @internal Handlers plus live drag state — what `TreeController.dnd`
+ * exposes (all `null`/no-op outside `files`). */
+export interface TreeDndContextValue extends TreeDndHandlers {
+  draggedId: string | null
+  /** Row the pointer is over and where the drop would land. */
+  dropTarget: TreeDropTarget | null
+}
+
+/** Everything observable about one tree, for consumers reading it by id. */
+export interface TreeState {
+  variant: TreeVariant
+  items: TreeNode[]
+  activeId?: string
+  expandedIds: ReadonlySet<string>
+  collapsed: boolean
+  renamingId: string | null
+  sectioned: boolean
+  sectionIds: string[]
+  canRename: boolean
+  canMove: boolean
+  draggedId: string | null
+  dropTarget: TreeDropTarget | null
+}
+
+/** Everything doable to one tree from outside its component. */
+export interface TreeActions {
+  expand: (id: string) => void
+  collapse: (id: string) => void
+  toggleExpanded: (id: string) => void
+  expandAll: () => void
+  collapseAll: () => void
+  reveal: (id: string) => void
+  setCollapsed: (collapsed: boolean) => void
+  toggleCollapsed: () => void
+  select: (id: string) => void
+  startRename: (id: string) => void
+  cancelRename: () => void
+  rename: (id: string, label: string) => void
+  move: (id: string, parentId: string | null, index: number) => void
+  setItems: (items: TreeNode[]) => void
+  reset: () => void
+}
+
+/** @internal Projection of `useTree`'s options — primitives only, so the
+ * store write runs once per real change instead of once per render. */
+export interface TreeConfig {
+  variant: TreeVariant
+  sound: boolean
+  controlsItems: boolean
+  controlsActiveId: boolean
+  controlsCollapsed: boolean
+  managesItems: boolean
+  hasRenameHandler: boolean
+  hasMoveHandler: boolean
+}
+
+/** @internal Latest option callbacks. Only write atoms read this, so it
+ * can be refreshed every commit without re-rendering anything. */
+export interface TreeHandlers {
+  onNavigate?: (node: TreeNode) => void
+  onItemsChange?: (items: TreeNode[]) => void
+  onExpandedChange?: (ids: string[]) => void
+  onCollapsedChange?: (collapsed: boolean) => void
+  onRename?: (id: string, label: string) => void
+  onMove?: (id: string, parentId: string | null, index: number) => void
+}
+
+/** @internal What an instance starts from, replayed by `resetTreeAtom`. */
+export interface TreeSeed {
+  items: TreeNode[]
+  activeId?: string
+  collapsed: boolean
+  expandedIds?: string[]
+}