@exegia/corpora-ui 0.19.0 → 0.21.0

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

@@ -0,0 +1,179 @@
+"use client"
+
+import * as React from "react"
+import { useAtomValue, useSetAtom, useStore } from "jotai"
+
+import {
+  endTreeDragAtom,
+  moveTreeNodeAtom,
+  treeCanMoveAtom,
+  treeDraggedIdAtom,
+  treeDropTargetAtom,
+  treeItemsAtom,
+} from "./tree-atom"
+import type {
+  TreeDndContextValue,
+  TreeDndHandlers,
+  TreeDropPosition,
+  TreeInstanceId,
+  TreeNode,
+} 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
+
+/**
+ * The drag handlers for the `files` variant, stable for the life of the tree.
+ *
+ * Nothing here subscribes to drag state: items, the dragged id and the drop
+ * target are read out of the store when a handler runs. That is what lets
+ * every row share one handler object without re-rendering when a drag moves —
+ * and it keeps `useTree` from subscribing to data it also projects from
+ * props, which would loop on an inline `items` array.
+ *
+ * Inert unless the tree `canMove`. `dataTransfer` is set for interop but
+ * never read, so the flow also works where the store is unavailable (tests,
+ * some webviews).
+ */
+export function useTreeDndHandlers(treeId: TreeInstanceId): TreeDndHandlers {
+  const store = useStore()
+  const enabled = useAtomValue(treeCanMoveAtom(treeId))
+  const setDraggedId = useSetAtom(treeDraggedIdAtom(treeId))
+  const setDropTarget = useSetAtom(treeDropTargetAtom(treeId))
+  const move = useSetAtom(moveTreeNodeAtom(treeId))
+  const reset = useSetAtom(endTreeDragAtom(treeId))
+
+  const readItems = React.useCallback(
+    () => store.get(treeItemsAtom(treeId)),
+    [store, treeId]
+  )
+  const readDraggedId = React.useCallback(
+    () => store.get(treeDraggedIdAtom(treeId)),
+    [store, treeId]
+  )
+  const readDropTarget = React.useCallback(
+    () => store.get(treeDropTargetAtom(treeId)),
+    [store, treeId]
+  )
+
+  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, setDraggedId]
+  )
+
+  const onRowDragOver = React.useCallback(
+    (event: React.DragEvent, node: TreeNode) => {
+      const draggedId = readDraggedId()
+      if (!enabled || draggedId === null) return
+      // A node never drops onto itself or into its own subtree.
+      if (containsNode(readItems(), 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, readDraggedId, readItems, setDropTarget]
+  )
+
+  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)
+    },
+    [setDropTarget]
+  )
+
+  const onRowDrop = React.useCallback(
+    (event: React.DragEvent, node: TreeNode) => {
+      if (!enabled) return
+      event.preventDefault()
+      event.stopPropagation()
+      const draggedId = readDraggedId()
+      const target = readDropTarget()
+      if (draggedId === null || target === null || target.id !== node.id) {
+        reset()
+        return
+      }
+      const items = readItems()
+
+      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
+        move(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
+          move(draggedId, location.parentId, index)
+        }
+      }
+      reset()
+    },
+    [enabled, move, readDraggedId, readDropTarget, readItems, reset]
+  )
+
+  return React.useMemo(
+    () => ({
+      enabled,
+      onRowDragStart,
+      onRowDragOver,
+      onRowDragLeave,
+      onRowDrop,
+      onRowDragEnd: reset,
+    }),
+    [enabled, onRowDragStart, onRowDragOver, onRowDragLeave, onRowDrop, reset]
+  )
+}
+
+/** The handlers plus live drag state, for `TreeController.dnd`. Rows take the
+ * handlers alone and read the state per node instead. */
+export function useTreeDnd(treeId: TreeInstanceId): TreeDndContextValue {
+  const handlers = useTreeDndHandlers(treeId)
+  const draggedId = useAtomValue(treeDraggedIdAtom(treeId))
+  const dropTarget = useAtomValue(treeDropTargetAtom(treeId))
+
+  return React.useMemo(
+    () => ({ ...handlers, draggedId, dropTarget }),
+    [handlers, draggedId, dropTarget]
+  )
+}

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

@@ -0,0 +1,105 @@
+"use client"
+
+import * as React from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+
+import {
+  cancelTreeRenameAtom,
+  collapseAllTreeNodesAtom,
+  collapseTreeNodeAtom,
+  expandAllTreeNodesAtom,
+  expandTreeNodeAtom,
+  moveTreeNodeAtom,
+  renameTreeNodeAtom,
+  resetTreeAtom,
+  revealTreeNodeAtom,
+  selectTreeNodeAtom,
+  setTreeCollapsedAtom,
+  setTreeItemsAtom,
+  startTreeRenameAtom,
+  toggleTreeCollapsedAtom,
+  toggleTreeNodeAtom,
+  treeStateAtom,
+} from "./tree-atom"
+import type { TreeActions, TreeInstanceId, TreeState } from "./type"
+
+/**
+ * Read the tree registered under `treeId` from anywhere below
+ * `ExegiaProvider` — no controller, no props, no provider of its own.
+ *
+ * ```tsx
+ * const { collapsed, activeId } = useTreeState("app-nav")
+ * ```
+ *
+ * This returns the whole state object, so the caller re-renders on any
+ * change. A component that reads one field should subscribe to that field's
+ * atom instead: `useAtomValue(treeCollapsedAtom("app-nav"))`.
+ */
+export function useTreeState(treeId: TreeInstanceId): TreeState {
+  return useAtomValue(treeStateAtom(treeId))
+}
+
+/**
+ * Drive the tree registered under `treeId` from anywhere. Writes only — the
+ * caller never re-renders when the tree changes, so this is what a command
+ * palette, a keyboard shortcut or a route guard should reach for.
+ *
+ * ```tsx
+ * const nav = useTreeActions("app-nav")
+ * <Button onClick={nav.collapseAll}>Collapse all</Button>
+ * ```
+ */
+export function useTreeActions(treeId: TreeInstanceId): TreeActions {
+  const expand = useSetAtom(expandTreeNodeAtom(treeId))
+  const collapse = useSetAtom(collapseTreeNodeAtom(treeId))
+  const toggleExpanded = useSetAtom(toggleTreeNodeAtom(treeId))
+  const expandAll = useSetAtom(expandAllTreeNodesAtom(treeId))
+  const collapseAll = useSetAtom(collapseAllTreeNodesAtom(treeId))
+  const reveal = useSetAtom(revealTreeNodeAtom(treeId))
+  const setCollapsed = useSetAtom(setTreeCollapsedAtom(treeId))
+  const toggleCollapsed = useSetAtom(toggleTreeCollapsedAtom(treeId))
+  const select = useSetAtom(selectTreeNodeAtom(treeId))
+  const startRename = useSetAtom(startTreeRenameAtom(treeId))
+  const cancelRename = useSetAtom(cancelTreeRenameAtom(treeId))
+  const rename = useSetAtom(renameTreeNodeAtom(treeId))
+  const move = useSetAtom(moveTreeNodeAtom(treeId))
+  const setItems = useSetAtom(setTreeItemsAtom(treeId))
+  const reset = useSetAtom(resetTreeAtom(treeId))
+
+  return React.useMemo(
+    () => ({
+      expand,
+      collapse,
+      toggleExpanded,
+      expandAll,
+      collapseAll,
+      reveal,
+      setCollapsed,
+      toggleCollapsed,
+      select,
+      startRename,
+      cancelRename,
+      rename,
+      move,
+      setItems,
+      reset,
+    }),
+    [
+      expand,
+      collapse,
+      toggleExpanded,
+      expandAll,
+      collapseAll,
+      reveal,
+      setCollapsed,
+      toggleCollapsed,
+      select,
+      startRename,
+      cancelRename,
+      rename,
+      move,
+      setItems,
+      reset,
+    ]
+  )
+}

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

@@ -0,0 +1,307 @@
+"use client"
+
+import * as React from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+
+import {
+  cancelTreeRenameAtom,
+  collapseAllTreeNodesAtom,
+  collapseTreeNodeAtom,
+  expandAllTreeNodesAtom,
+  expandTreeNodeAtom,
+  mountTreeAtom,
+  moveTreeNodeAtom,
+  projectTreeActiveIdAtom,
+  projectTreeCollapsedAtom,
+  projectTreeItemsAtom,
+  removeTreeInstance,
+  renameTreeNodeAtom,
+  resetTreeAtom,
+  revealTreeAncestorsAtom,
+  revealTreeNodeAtom,
+  selectTreeNodeAtom,
+  setTreeCollapsedAtom,
+  setTreeHandlersAtom,
+  startTreeRenameAtom,
+  toggleTreeCollapsedAtom,
+  toggleTreeNodeAtom,
+  treeActiveIdAtom,
+  treeCanMoveAtom,
+  treeCanRenameAtom,
+  treeCollapsedAtom,
+  treeExpandedIdsAtom,
+  treeOwnedItemsAtom,
+  treeRenamingIdAtom,
+} from "./tree-atom"
+import type {
+  TreeConfig,
+  TreeController,
+  TreeHandlers,
+  TreeSeed,
+  UseTreeOptions,
+} from "./type"
+import { useTreeDnd } from "./use-tree-dnd"
+import { findNode, hasThreeLevels } from "./utils"
+
+/**
+ * The tree's headless controller — every behaviour the component exposes,
+ * callable from outside it: expand/collapse (a node, a section, the whole
+ * tree), fold the `sidebar` rail, select a node, rename, reorder.
+ *
+ * Each piece of state is controlled-or-uncontrolled in the usual React
+ * shape: pass `items`/`activeId`/`collapsed` to own it yourself, or
+ * `defaultItems`/`defaultActiveId`/`defaultCollapsed` to let the hook. When
+ * the hook owns `items` (or you pass `onItemsChange`), `rename` and `move`
+ * apply the edit to the data themselves — otherwise they only report it
+ * through `onRename`/`onMove` and you reduce the tree yourself.
+ *
+ * ```tsx
+ * const tree = useTree({ variant: "files", defaultItems: files })
+ * <Tree tree={tree} />
+ * <Button onClick={tree.collapseAll}>Collapse all</Button>
+ * ```
+ *
+ * State lives in Jotai atoms keyed by `treeId`, so anything under
+ * `ExegiaProvider` can drive this tree without the controller — name it and
+ * reach for `useTreeState(treeId)` / `useTreeActions(treeId)` elsewhere.
+ */
+export function useTree(options: UseTreeOptions): TreeController {
+  const {
+    variant,
+    onNavigate,
+    onRename,
+    onMove,
+    onItemsChange,
+    onExpandedChange,
+    onCollapsedChange,
+    sound = true,
+  } = options
+
+  // A generated key isolates unnamed trees from each other; an explicit
+  // `treeId` is the app's handle on this one.
+  const generatedId = React.useId()
+  const treeId = options.treeId ?? generatedId
+
+  const controlsItems = options.items !== undefined
+  const controlsActiveId = options.activeId !== undefined
+  const controlsCollapsed = options.collapsed !== undefined
+  // The hook may only rewrite the data when it owns it, or when the consumer
+  // asked for the next tree through `onItemsChange`.
+  const managesItems = !controlsItems || onItemsChange !== undefined
+  const hasRenameHandler = onRename !== undefined
+  const hasMoveHandler = onMove !== undefined
+
+  // Primitives only, so this object is stable and the store write below runs
+  // once per real change rather than once per render.
+  const config = React.useMemo<TreeConfig>(
+    () => ({
+      variant,
+      sound,
+      controlsItems,
+      controlsActiveId,
+      controlsCollapsed,
+      managesItems,
+      hasRenameHandler,
+      hasMoveHandler,
+    }),
+    [
+      variant,
+      sound,
+      controlsItems,
+      controlsActiveId,
+      controlsCollapsed,
+      managesItems,
+      hasRenameHandler,
+      hasMoveHandler,
+    ]
+  )
+
+  const handlers = React.useMemo<TreeHandlers>(
+    () => ({
+      onNavigate,
+      onItemsChange,
+      onExpandedChange,
+      onCollapsedChange,
+      onRename,
+      onMove,
+    }),
+    [
+      onNavigate,
+      onItemsChange,
+      onExpandedChange,
+      onCollapsedChange,
+      onRename,
+      onMove,
+    ]
+  )
+
+  // Read once: the `default*` options describe the mount, not every render.
+  const [seed] = React.useState<TreeSeed>(() => ({
+    items: options.items ?? options.defaultItems ?? [],
+    activeId: options.activeId ?? options.defaultActiveId,
+    collapsed: options.collapsed ?? options.defaultCollapsed ?? false,
+    expandedIds: options.defaultExpandedIds
+      ? [...options.defaultExpandedIds]
+      : undefined,
+  }))
+
+  const mount = useSetAtom(mountTreeAtom(treeId))
+  const publishHandlers = useSetAtom(setTreeHandlersAtom(treeId))
+  const projectItems = useSetAtom(projectTreeItemsAtom(treeId))
+  const projectActiveId = useSetAtom(projectTreeActiveIdAtom(treeId))
+  const projectCollapsed = useSetAtom(projectTreeCollapsedAtom(treeId))
+  const revealAncestors = useSetAtom(revealTreeAncestorsAtom(treeId))
+
+  // Handlers first — they must be in the store before any action can fire.
+  // Rewritten every commit; no read atom depends on them, so nobody
+  // re-renders for it.
+  React.useLayoutEffect(() => {
+    publishHandlers(handlers)
+  }, [publishHandlers, handlers])
+
+  // Before paint, so a seeded branch never paints closed for a frame.
+  React.useLayoutEffect(() => {
+    mount(config, seed)
+  }, [mount, config, seed])
+
+  // Controlled props stay the source of truth; the store carries a projection
+  // so the action atoms and remote readers see current data.
+  React.useLayoutEffect(() => {
+    if (options.items !== undefined) projectItems(options.items)
+  }, [options.items, projectItems])
+
+  React.useLayoutEffect(() => {
+    if (options.activeId !== undefined) projectActiveId(options.activeId)
+  }, [options.activeId, projectActiveId])
+
+  React.useLayoutEffect(() => {
+    if (options.collapsed !== undefined) projectCollapsed(options.collapsed)
+  }, [options.collapsed, projectCollapsed])
+
+  // A tree the hook keyed is scrap once its component goes. An explicit
+  // `treeId` is the app's key and outlives the mount.
+  React.useEffect(() => {
+    if (options.treeId !== undefined) return
+    return () => removeTreeInstance(treeId)
+  }, [treeId, options.treeId])
+
+  // Never `treeItemsAtom` — see the note on `treeOwnedItemsAtom`.
+  const ownedItems = useAtomValue(treeOwnedItemsAtom(treeId))
+  const items = options.items ?? ownedItems
+  const activeId = useAtomValue(treeActiveIdAtom(treeId))
+  const expandedIds = useAtomValue(treeExpandedIdsAtom(treeId))
+  const collapsed = useAtomValue(treeCollapsedAtom(treeId))
+  const renamingId = useAtomValue(treeRenamingIdAtom(treeId))
+  const canRename = useAtomValue(treeCanRenameAtom(treeId))
+  const canMove = useAtomValue(treeCanMoveAtom(treeId))
+
+  // Navigating into a nested entry from elsewhere reveals its ancestors, even
+  // ones the reader had collapsed. In a layout effect, so the branch is open
+  // before the frame paints.
+  const lastActiveId = React.useRef(activeId)
+  React.useLayoutEffect(() => {
+    if (lastActiveId.current === activeId) return
+    lastActiveId.current = activeId
+    if (activeId !== undefined) revealAncestors(activeId)
+  }, [activeId, revealAncestors])
+
+  const sectioned = React.useMemo(
+    () => variant === "navigation" && hasThreeLevels(items),
+    [variant, items]
+  )
+  const sectionIds = React.useMemo(
+    () => (sectioned ? items.map((node) => node.id) : []),
+    [items, sectioned]
+  )
+  const getNode = React.useCallback(
+    (id: string) => findNode(items, id),
+    [items]
+  )
+  const isExpanded = React.useCallback(
+    (id: string) => expandedIds.has(id),
+    [expandedIds]
+  )
+
+  // `useSetAtom` setters are already stable — no useCallback needed.
+  const expand = useSetAtom(expandTreeNodeAtom(treeId))
+  const collapse = useSetAtom(collapseTreeNodeAtom(treeId))
+  const toggleExpanded = useSetAtom(toggleTreeNodeAtom(treeId))
+  const expandAll = useSetAtom(expandAllTreeNodesAtom(treeId))
+  const collapseAll = useSetAtom(collapseAllTreeNodesAtom(treeId))
+  const reveal = useSetAtom(revealTreeNodeAtom(treeId))
+  const setCollapsed = useSetAtom(setTreeCollapsedAtom(treeId))
+  const toggleCollapsed = useSetAtom(toggleTreeCollapsedAtom(treeId))
+  const select = useSetAtom(selectTreeNodeAtom(treeId))
+  const startRename = useSetAtom(startTreeRenameAtom(treeId))
+  const cancelRename = useSetAtom(cancelTreeRenameAtom(treeId))
+  const rename = useSetAtom(renameTreeNodeAtom(treeId))
+  const move = useSetAtom(moveTreeNodeAtom(treeId))
+  const reset = useSetAtom(resetTreeAtom(treeId))
+
+  const dnd = useTreeDnd(treeId)
+
+  return React.useMemo<TreeController>(
+    () => ({
+      treeId,
+      variant,
+      items,
+      sectioned,
+      sectionIds,
+      sound,
+      getNode,
+      expandedIds,
+      isExpanded,
+      expand,
+      collapse,
+      toggleExpanded,
+      expandAll,
+      collapseAll,
+      reveal,
+      collapsed,
+      setCollapsed,
+      toggleCollapsed,
+      activeId,
+      select,
+      canRename,
+      renamingId,
+      startRename,
+      cancelRename,
+      rename,
+      canMove,
+      move,
+      reset,
+      dnd,
+    }),
+    [
+      treeId,
+      variant,
+      items,
+      sectioned,
+      sectionIds,
+      sound,
+      getNode,
+      expandedIds,
+      isExpanded,
+      expand,
+      collapse,
+      toggleExpanded,
+      expandAll,
+      collapseAll,
+      reveal,
+      collapsed,
+      setCollapsed,
+      toggleCollapsed,
+      activeId,
+      select,
+      canRename,
+      renamingId,
+      startRename,
+      cancelRename,
+      rename,
+      canMove,
+      move,
+      reset,
+      dnd,
+    ]
+  )
+}