@exegia/corpora-ui 3.0.0 → 3.1.0

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

@@ -1,233 +0,0 @@
-"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 {
-  ITreeContextValue,
-  ITreeController,
-  TTreeDataProps,
-  ITreeNode,
-  TTreeProps,
-} from "./type"
-import { useTree } from "./use-tree"
-import { useTreeDndHandlers } from "./use-tree-dnd"
-
-const DEFAULT_LABELS: Record<ITreeController["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: TTreeProps): 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: TTreeDataProps): 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 ITreeViewProps {
-  tree: ITreeController
-  ariaLabel?: string
-  className?: string
-  renderTrailing?: (node: ITreeNode) => React.ReactNode
-}
-
-/** Rendering only — every piece of state and behaviour lives on `tree`. */
-function TreeView({
-  tree,
-  ariaLabel,
-  className,
-  renderTrailing,
-}: ITreeViewProps): React.ReactElement {
-  const { variant, items, sectioned, collapsed } = tree
-  const rootRef = React.useRef<HTMLUListElement>(null)
-
-  // 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<ITreeContextValue>(
-    () => ({ treeId: tree.treeId, renderTrailing, dnd }),
-    [tree.treeId, renderTrailing, dnd]
-  )
-
-  const label = ariaLabel ?? DEFAULT_LABELS[variant]
-  let rendered = (
-    <ul
-      aria-label={label}
-      className={cn(
-        // The list always spans its container — collapsed included. The
-        // rail's fold is its container's width change (an icon-collapsed
-        // panel) plus the labels folding; rows keep the full width so their
-        // hit areas and hover surfaces span the rail edge to edge.
-        "flex h-full w-full min-w-0 flex-col",
-        collapsed && "gap-y-2!",
-        variant === "files" ? "gap-px" : sectioned ? "gap-3" : "gap-0.5"
-      )}
-      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} />
-      ))}
-    </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 w-full min-w-0", className)}
-          data-slot="tree-root"
-        >
-          {rendered}
-        </nav>
-      )}
-    </TreeContext.Provider>
-  )
-}

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

@@ -1,322 +0,0 @@
-import type * as React from "react"
-
-/** One node in the tree. Nesting depth carries meaning per variant — see
- * `TreeProps["variant"]`. */
-export interface ITreeNode {
-  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?: ITreeNode[]
-}
-
-export type TTreeVariant = "navigation" | "toc" | "sidebar" | "files"
-
-/** Where a dragged row lands relative to its drop target. */
-export type TTreeDropPosition = "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 TTreeInstanceId = string
-
-/** Row a drag hovers, and where the drop would land. */
-export interface ITreeDropTarget {
-  id: string
-  position: TTreeDropPosition
-}
-
-interface ITreeBaseProps {
-  items: ITreeNode[]
-  /** 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?: TTreeInstanceId
-  /** 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: ITreeNode) => void
-  /** Expand/collapse cues. Silent until `bindSounds()`. */
-  sound?: boolean
-  ariaLabel?: string
-  className?: string
-}
-
-interface ITreeReadonlyProps {
-  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 ITreeControllerProps {
-  tree: ITreeController
-  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: ITreeNode) => React.ReactNode
-}
-
-/** Either form: raw props, or a `useTree` controller via `tree`. */
-export type TTreeProps = TTreeDataProps | ITreeControllerProps
-
-/** The four shapes a Tree takes. Editing props only exist on `files`;
- * `collapsed` only on `sidebar` — the union is the contract. */
-export type TTreeDataProps = ITreeBaseProps &
-  (
-    | ({
-        /** 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"
-      } & ITreeReadonlyProps)
-    | ({
-        /** 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"
-      } & ITreeReadonlyProps)
-    | ({
-        /** Single-level icon rail. `collapsed` shrinks rows to their
-         * leading icon; nested children are ignored. */
-        variant: "sidebar"
-        collapsed?: boolean
-      } & Omit<ITreeReadonlyProps, "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: ITreeNode) => 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 IUseTreeOptions {
-  /** 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?: TTreeInstanceId
-  /** Which shape the tree takes — gates rename/reorder (`files`) and the
-   * collapsible rail (`sidebar`). */
-  variant: TTreeVariant
-  /** Controlled data. With it, `rename`/`move` only report the edit unless
-   * you also pass `onItemsChange`. */
-  items?: ITreeNode[]
-  /** Hook-owned data — `rename` and `move` apply the edit themselves. */
-  defaultItems?: ITreeNode[]
-  /** Next tree after a `rename`/`move`. Also enables self-applying edits
-   * on top of controlled `items`. */
-  onItemsChange?: (items: ITreeNode[]) => 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: ITreeNode) => 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 ITreeController {
-  /** The key this tree's state is stored under. */
-  treeId: TTreeInstanceId
-  variant: TTreeVariant
-  items: ITreeNode[]
-  /** `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) => ITreeNode | 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: ITreeDndContextValue
-}
-
-/** @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 ITreeContextValue {
-  treeId: TTreeInstanceId
-  renderTrailing?: (node: ITreeNode) => React.ReactNode
-  dnd: ITreeDndHandlers
-}
-
-/** @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 ITreeDndHandlers {
-  enabled: boolean
-  onRowDragStart: (event: React.DragEvent, id: string) => void
-  onRowDragOver: (event: React.DragEvent, node: ITreeNode) => void
-  onRowDragLeave: (event: React.DragEvent) => void
-  onRowDrop: (event: React.DragEvent, node: ITreeNode) => void
-  onRowDragEnd: () => void
-}
-
-/** @internal Handlers plus live drag state — what `TreeController.dnd`
- * exposes (all `null`/no-op outside `files`). */
-export interface ITreeDndContextValue extends ITreeDndHandlers {
-  draggedId: string | null
-  /** Row the pointer is over and where the drop would land. */
-  dropTarget: ITreeDropTarget | null
-}
-
-/** Everything observable about one tree, for consumers reading it by id. */
-export interface ITreeState {
-  variant: TTreeVariant
-  items: ITreeNode[]
-  activeId?: string
-  expandedIds: ReadonlySet<string>
-  collapsed: boolean
-  renamingId: string | null
-  sectioned: boolean
-  sectionIds: string[]
-  canRename: boolean
-  canMove: boolean
-  draggedId: string | null
-  dropTarget: ITreeDropTarget | null
-}
-
-/** Everything doable to one tree from outside its component. */
-export interface ITreeActions {
-  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: ITreeNode[]) => 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 ITreeConfig {
-  variant: TTreeVariant
-  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 ITreeHandlers {
-  onNavigate?: (node: ITreeNode) => void
-  onItemsChange?: (items: ITreeNode[]) => 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 ITreeSeed {
-  items: ITreeNode[]
-  activeId?: string
-  collapsed: boolean
-  expandedIds?: string[]
-}