@exegia/corpora-ui 0.20.0 → 0.22.0

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

@@ -1,19 +1,47 @@
 "use client"
 
 import * as React from "react"
+import { useAtomValue, useSetAtom } from "jotai"
 
-import { playCue } from "@/lib/sound"
-import type { TreeController, TreeNode, UseTreeOptions } from "./type"
-import { useTreeDnd } from "./use-tree-dnd"
 import {
-  ancestorIdsOf,
-  expandableIdsOf,
-  findNode,
-  hasThreeLevels,
-  initialExpandedIds,
-  moveNode,
-  renameNode,
-} from "./utils"
+  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,
@@ -32,6 +60,10 @@ import {
  * <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 {
@@ -45,206 +77,172 @@ export function useTree(options: UseTreeOptions): TreeController {
     sound = true,
   } = options
 
-  // Data: controlled through `items`, otherwise owned here.
-  const [ownItems, setOwnItems] = React.useState<TreeNode[]>(
-    () => options.defaultItems ?? []
-  )
-  const items = options.items ?? ownItems
-  // The hook may only rewrite the data when it owns it, or when the
-  // consumer asked for the next tree through `onItemsChange`.
-  const managesItems =
-    options.items === undefined || onItemsChange !== undefined
-
-  const setItems = React.useCallback(
-    (next: TreeNode[]) => {
-      if (options.items === undefined) setOwnItems(next)
-      onItemsChange?.(next)
-    },
-    [options.items, onItemsChange]
-  )
-
-  const sectioned = variant === "navigation" && hasThreeLevels(items)
+  // 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
 
-  // Selection: controlled through `activeId`, otherwise owned here.
-  const [ownActiveId, setOwnActiveId] = React.useState(options.defaultActiveId)
-  const activeId = options.activeId ?? ownActiveId
+  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
 
-  const [expandedIds, setExpandedIds] = React.useState<Set<string>>(() => {
-    const expanded = options.defaultExpandedIds
-      ? new Set(options.defaultExpandedIds)
-      : initialExpandedIds(items, activeId)
-    // Section names default open — they are headings over their run of
-    // items, not drawers; `defaultOpen: false` still starts one closed.
-    if (sectioned && !options.defaultExpandedIds)
-      for (const node of items)
-        if (node.defaultOpen !== false) expanded.add(node.id)
-    return expanded
-  })
-
-  const commitExpanded = React.useCallback(
-    (next: Set<string>) => {
-      setExpandedIds(next)
-      onExpandedChange?.([...next])
-    },
-    [onExpandedChange]
+  // 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,
+    ]
   )
 
-  // Navigating into a nested entry from elsewhere reveals its ancestors,
-  // even ones the reader had collapsed. Adjusted during render so the
-  // branch never paints closed for a frame first.
-  const [prevActiveId, setPrevActiveId] = React.useState(activeId)
-  if (activeId !== prevActiveId) {
-    setPrevActiveId(activeId)
-    if (activeId !== undefined) {
-      const ancestors = ancestorIdsOf(items, activeId)
-      if (ancestors.some((id) => !expandedIds.has(id)))
-        setExpandedIds(new Set([...expandedIds, ...ancestors]))
-    }
-  }
-
-  // Rail fold: controlled through `collapsed`, otherwise owned here. Only
-  // `sidebar` has a rail — every other variant reads as expanded.
-  const [ownCollapsed, setOwnCollapsed] = React.useState(
-    options.defaultCollapsed ?? false
+  const handlers = React.useMemo<TreeHandlers>(
+    () => ({
+      onNavigate,
+      onItemsChange,
+      onExpandedChange,
+      onCollapsedChange,
+      onRename,
+      onMove,
+    }),
+    [
+      onNavigate,
+      onItemsChange,
+      onExpandedChange,
+      onCollapsedChange,
+      onRename,
+      onMove,
+    ]
   )
-  const collapsed =
-    variant === "sidebar" ? (options.collapsed ?? ownCollapsed) : false
 
-  const [renamingId, setRenamingId] = React.useState<string | null>(null)
+  // 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 canRename =
-    variant === "files" && (onRename !== undefined || managesItems)
-  const canMove = variant === "files" && (onMove !== undefined || managesItems)
+  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))
 
-  const isExpanded = React.useCallback(
-    (id: string) => expandedIds.has(id),
-    [expandedIds]
-  )
+  // 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])
 
-  const expand = React.useCallback(
-    (id: string) => {
-      if (expandedIds.has(id)) return
-      commitExpanded(new Set([...expandedIds, id]))
-      if (sound) playCue("toggle")
-    },
-    [commitExpanded, expandedIds, sound]
-  )
+  // Before paint, so a seeded branch never paints closed for a frame.
+  React.useLayoutEffect(() => {
+    mount(config, seed)
+  }, [mount, config, seed])
 
-  const collapse = React.useCallback(
-    (id: string) => {
-      if (!expandedIds.has(id)) return
-      const next = new Set(expandedIds)
-      next.delete(id)
-      commitExpanded(next)
-      if (sound) playCue("toggle")
-    },
-    [commitExpanded, expandedIds, sound]
-  )
+  // 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])
 
-  const toggleExpanded = React.useCallback(
-    (id: string) => {
-      const next = new Set(expandedIds)
-      if (next.has(id)) next.delete(id)
-      else next.add(id)
-      commitExpanded(next)
-      if (sound) playCue("toggle")
-    },
-    [commitExpanded, expandedIds, sound]
-  )
+  React.useLayoutEffect(() => {
+    if (options.activeId !== undefined) projectActiveId(options.activeId)
+  }, [options.activeId, projectActiveId])
 
-  const expandAll = React.useCallback(() => {
-    commitExpanded(new Set(expandableIdsOf(items, variant === "files")))
-  }, [commitExpanded, items, variant])
+  React.useLayoutEffect(() => {
+    if (options.collapsed !== undefined) projectCollapsed(options.collapsed)
+  }, [options.collapsed, projectCollapsed])
 
-  const collapseAll = React.useCallback(() => {
-    commitExpanded(new Set())
-  }, [commitExpanded])
+  // 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])
 
-  /** Open every ancestor of `id` without touching the rest of the tree. */
-  const reveal = React.useCallback(
-    (id: string) => {
-      const ancestors = ancestorIdsOf(items, id)
-      if (!ancestors.some((ancestor) => !expandedIds.has(ancestor))) return
-      commitExpanded(new Set([...expandedIds, ...ancestors]))
-    },
-    [commitExpanded, expandedIds, items]
-  )
+  // 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))
 
-  const setCollapsed = React.useCallback(
-    (next: boolean) => {
-      if (options.collapsed === undefined) setOwnCollapsed(next)
-      onCollapsedChange?.(next)
-      if (sound) playCue("toggle")
-    },
-    [options.collapsed, onCollapsedChange, sound]
-  )
+  // 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 toggleCollapsed = React.useCallback(
-    () => setCollapsed(!collapsed),
-    [collapsed, setCollapsed]
+  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]
   )
-
-  /** Selecting runs the node's own `onSelect` first, then `onNavigate` —
-   * the same order a row press follows. Disabled nodes are inert. */
-  const select = React.useCallback(
-    (id: string) => {
-      const node = findNode(items, id)
-      if (!node || node.disabled) return
-      if (options.activeId === undefined) setOwnActiveId(id)
-      node.onSelect?.()
-      onNavigate?.(node)
-    },
-    [items, options.activeId, onNavigate]
-  )
-
-  const startRename = React.useCallback(
-    (id: string) => {
-      // An id from elsewhere (a stale selection, another tree) would arm
-      // rename mode against a row that never renders.
-      if (!canRename || !findNode(items, id)) return
-      setRenamingId(id)
-    },
-    [canRename, items]
-  )
-
-  const cancelRename = React.useCallback(() => setRenamingId(null), [])
-
-  const rename = React.useCallback(
-    (id: string, label: string) => {
-      setRenamingId(null)
-      const next = label.trim()
-      if (!canRename || !next) return
-      const node = findNode(items, id)
-      if (!node || node.label === next) return
-      onRename?.(id, next)
-      if (managesItems) setItems(renameNode(items, id, next))
-    },
-    [canRename, items, managesItems, onRename, setItems]
-  )
-
-  const move = React.useCallback(
-    (id: string, parentId: string | null, index: number) => {
-      if (!canMove) return
-      onMove?.(id, parentId, index)
-      if (managesItems) setItems(moveNode(items, id, parentId, index))
-    },
-    [canMove, items, managesItems, onMove, setItems]
+  const isExpanded = React.useCallback(
+    (id: string) => expandedIds.has(id),
+    [expandedIds]
   )
 
-  const dnd = useTreeDnd(items, canMove ? move : undefined)
+  // `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 sectionIds = React.useMemo(
-    () => (sectioned ? items.map((node) => node.id) : []),
-    [items, sectioned]
-  )
+  const dnd = useTreeDnd(treeId)
 
   return React.useMemo<TreeController>(
     () => ({
+      treeId,
       variant,
       items,
       sectioned,
@@ -271,9 +269,11 @@ export function useTree(options: UseTreeOptions): TreeController {
       rename,
       canMove,
       move,
+      reset,
       dnd,
     }),
     [
+      treeId,
       variant,
       items,
       sectioned,
@@ -300,6 +300,7 @@ export function useTree(options: UseTreeOptions): TreeController {
       rename,
       canMove,
       move,
+      reset,
       dnd,
     ]
   )

package/src/components/composed/user-avatar.tsx

@@ -1,101 +1,13 @@
-"use client"
-
-import * as React from "react"
-
-import {
-  Avatar,
-  AvatarFallback,
-  AvatarImage,
-  type AvatarPrimitive,
-} from "@/components/ui/avatar"
-import { Skeleton } from "@/components/ui/skeleton"
-import { cn } from "@/lib/utils"
-
-type ImageStatus = Parameters<
-  NonNullable<AvatarPrimitive.Image.Props["onLoadingStatusChange"]>
->[0]
-
-export interface UserAvatarProps extends Omit<
-  AvatarPrimitive.Root.Props,
-  "children"
-> {
-  /** Image URL. Without one the initials show immediately — no skeleton. */
-  src?: string
-  /** Drives the initials, and the alt text unless `alt` overrides it. */
-  name?: string
-  /** Overrides the initials derived from `name`. */
-  initials?: string
-  /**
-   * Alt text for the image. Pass "" when adjacent text already names the
-   * person — the image is then decorative.
-   */
-  alt?: string
-  /**
-   * Force the skeleton, for when the identity itself is still being fetched.
-   * Omitted, it follows the image: a passed `src` skeletons until it resolves.
-   */
-  loading?: boolean
-}
-
-/** "Jenny Hamilton" → "JH", "luna" → "L". */
-export function initialsFrom(name: string): string {
-  const parts = name.trim().split(/\s+/).filter(Boolean)
-  if (parts.length === 0) return ""
-  const first = parts[0]?.[0] ?? ""
-  const last = parts.length > 1 ? (parts.at(-1)?.[0] ?? "") : ""
-  return (first + last).toUpperCase()
-}
-
 /**
- * Identity avatar: an image when one is given, initials otherwise.
- *
- * A passed `src` is assumed to be remote, so the slot holds a skeleton until
- * the image resolves rather than flashing initials that are about to be
- * replaced. A failed load settles on the initials.
+ * Back-compat path. The avatar moved to `components/user-avatar/` (split
+ * into component / atoms / hooks); this module re-exports it so existing
+ * imports keep resolving to the one implementation. Prefer the new path.
  */
-export function UserAvatar({
-  src,
-  name = "",
-  initials,
-  alt,
-  loading: loadingProp,
-  className,
-  ...props
-}: UserAvatarProps): React.ReactElement {
-  const [status, setStatus] = React.useState<ImageStatus>("idle")
-  const loading =
-    loadingProp ??
-    (src !== undefined && (status === "idle" || status === "loading"))
-
-  return (
-    <Avatar
-      className={cn(
-        "size-8 border-2 border-white bg-neutral-800 text-xl",
-        className
-      )}
-      data-loading={loading || undefined}
-      data-slot="user-avatar"
-      {...props}
-    >
-      {/* Held back while forced-loading: a loaded image would hide the
-          fallback the skeleton lives in. */}
-      {src === undefined || loadingProp === true ? null : (
-        <AvatarImage
-          alt={alt ?? name}
-          onLoadingStatusChange={setStatus}
-          src={src}
-        />
-      )}
-      <AvatarFallback>
-        {loading ? (
-          <Skeleton
-            className="size-full rounded-full"
-            data-slot="avatar-skeleton"
-          />
-        ) : (
-          (initials ?? initialsFrom(name))
-        )}
-      </AvatarFallback>
-    </Avatar>
-  )
-}
+export {
+  UserAvatar,
+  initialsFrom,
+  useUserAvatar,
+  useUserAvatarActions,
+  useUserAvatarState,
+} from "@/components/user-avatar"
+export type { UserAvatarProps, UserPresence } from "@/components/user-avatar"