@exegia/corpora-ui 0.19.0 → 0.20.0

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

@@ -0,0 +1,278 @@
+"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 { 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({
+    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 44px 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
+    }
+  }
+
+  const context = React.useMemo<TreeContextValue>(
+    () => ({ tree, renderTrailing }),
+    [tree, renderTrailing]
+  )
+
+  const label = ariaLabel ?? DEFAULT_LABELS[variant]
+  let rendered = (
+    <motion.ul
+      aria-label={label}
+      className={cn(
+        "flex min-w-0 flex-col h-full",
+        // Resting widths, and the fallback until the rail is measured. The
+        // motion target below overrides these with an inline width.
+        collapsed ? "w-11 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 44 -> "100%" pinned the inline width
+      // at 44px, 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("min-w-0 flex h-full justify-center", className)}
+          data-slot="tree-root"
+          ref={railRef}
+        >
+          {rendered}
+        </nav>
+      )}
+    </TreeContext.Provider>
+  )
+}

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

@@ -0,0 +1,212 @@
+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
+  /** Renders an anchor. Without one the row is a button; `toc` leaves
+   * default to `#{id}` so they scroll to the matching heading. */
+  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"
+
+interface TreeBaseProps {
+  items: TreeNode[]
+  /** 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 row's
+   * anchor default — wire your router's navigate here. */
+  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
+         * links); with 2 it renders plain link rows. */
+        variant: "navigation"
+      } & TreeReadonlyProps)
+    | ({
+        /** Table of contents: top-level nodes are routes, leaf nodes are
+         * in-page anchors (`#{id}` unless the node carries an `href`). */
+        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 {
+  /** 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 {
+  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
+
+  dnd: TreeDndContextValue
+}
+
+/** @internal What a row needs from the root, threaded through context so
+ * the recursive rows stay prop-light. */
+export interface TreeContextValue {
+  tree: TreeController
+  renderTrailing?: (node: TreeNode) => React.ReactNode
+}
+
+/** @internal Drag state shared by every row (all `null`/no-op outside
+ * `files`). */
+export interface TreeDndContextValue {
+  enabled: boolean
+  draggedId: string | null
+  /** Row the pointer is over and where the drop would land. */
+  dropTarget: { id: string; position: TreeDropPosition } | null
+  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
+}

package/src/components/composed/tree/use-tree-dnd.ts

@@ -0,0 +1,148 @@
+"use client"
+
+import * as React from "react"
+
+import type {
+  TreeDndContextValue,
+  TreeDropPosition,
+  TreeNode,
+  UseTreeOptions,
+} from "./type"
+import { containsNode, findNode, locateNode } from "./utils"
+
+/** How far into a folder row the pointer must sit (from either edge) to
+ * read as "inside" rather than "before"/"after". */
+const EDGE_RATIO = 0.25
+
+/** Owns drag state for the `files` variant: which row is in flight, which
+ * row the pointer rests on and where the drop would land. Everything is
+ * component state — `dataTransfer` is set for interop but never read, so
+ * the flow also works where the store is unavailable (tests, some
+ * webviews). Without `onMove` every handler is inert. */
+export function useTreeDnd(
+  items: readonly TreeNode[],
+  onMove: UseTreeOptions["onMove"]
+): TreeDndContextValue {
+  const enabled = onMove !== undefined
+  const [draggedId, setDraggedId] = React.useState<string | null>(null)
+  const [dropTarget, setDropTarget] = React.useState<{
+    id: string
+    position: TreeDropPosition
+  } | null>(null)
+
+  const reset = React.useCallback(() => {
+    setDraggedId(null)
+    setDropTarget(null)
+  }, [])
+
+  const onRowDragStart = React.useCallback(
+    (event: React.DragEvent, id: string) => {
+      if (!enabled) return
+      event.stopPropagation()
+      setDraggedId(id)
+      if (event.dataTransfer) {
+        event.dataTransfer.effectAllowed = "move"
+        event.dataTransfer.setData("text/plain", id)
+      }
+    },
+    [enabled]
+  )
+
+  const onRowDragOver = React.useCallback(
+    (event: React.DragEvent, node: TreeNode) => {
+      if (!enabled || draggedId === null) return
+      // A node never drops onto itself or into its own subtree.
+      if (containsNode(items, draggedId, node.id)) return
+      event.preventDefault()
+      event.stopPropagation()
+      if (event.dataTransfer) event.dataTransfer.dropEffect = "move"
+
+      const rect = event.currentTarget.getBoundingClientRect()
+      const ratio =
+        rect.height > 0 ? (event.clientY - rect.top) / rect.height : 0.5
+      // Any node carrying a children array is a folder — an empty one
+      // still accepts drops "inside".
+      const folder = node.children !== undefined
+      const position: TreeDropPosition = folder
+        ? ratio < EDGE_RATIO
+          ? "before"
+          : ratio > 1 - EDGE_RATIO
+            ? "after"
+            : "inside"
+        : ratio < 0.5
+          ? "before"
+          : "after"
+      setDropTarget((prev) =>
+        prev?.id === node.id && prev.position === position
+          ? prev
+          : { id: node.id, position }
+      )
+    },
+    [enabled, draggedId, items]
+  )
+
+  const onRowDragLeave = React.useCallback((event: React.DragEvent) => {
+    // Leaving for a child of the same row still counts as hovering it.
+    const next = event.relatedTarget as Node | null
+    if (next && event.currentTarget.contains(next)) return
+    setDropTarget(null)
+  }, [])
+
+  const onRowDrop = React.useCallback(
+    (event: React.DragEvent, node: TreeNode) => {
+      if (!enabled) return
+      event.preventDefault()
+      event.stopPropagation()
+      const target = dropTarget
+      if (draggedId === null || target === null || target.id !== node.id) {
+        reset()
+        return
+      }
+
+      if (target.position === "inside") {
+        // Append at the end of the folder, sized without the dragged node
+        // (it may already live there).
+        const children = node.children ?? []
+        const index = children.filter((child) => child.id !== draggedId).length
+        onMove?.(draggedId, node.id, index)
+      } else {
+        const location = locateNode(items, node.id)
+        if (location) {
+          const siblings = (
+            location.parentId === null
+              ? items
+              : (findNode(items, location.parentId)?.children ?? [])
+          ).filter((sibling) => sibling.id !== draggedId)
+          const at = siblings.findIndex((sibling) => sibling.id === node.id)
+          const index = target.position === "after" ? at + 1 : at
+          onMove?.(draggedId, location.parentId, index)
+        }
+      }
+      reset()
+    },
+    [enabled, draggedId, dropTarget, items, onMove, reset]
+  )
+
+  return React.useMemo(
+    () => ({
+      enabled,
+      draggedId,
+      dropTarget,
+      onRowDragStart,
+      onRowDragOver,
+      onRowDragLeave,
+      onRowDrop,
+      onRowDragEnd: reset,
+    }),
+    [
+      enabled,
+      draggedId,
+      dropTarget,
+      onRowDragStart,
+      onRowDragOver,
+      onRowDragLeave,
+      onRowDrop,
+      reset,
+    ]
+  )
+}