@djangocfg/ui-tools 2.1.415 → 2.1.417

package/src/tools/data/Tree/context/TreeContext.tsx

@@ -1,164 +1,44 @@
 'use client';
 
 import * as React from 'react';
-import {
-  createContext,
-  useCallback,
-  useEffect,
-  useMemo,
-  useReducer,
-  useRef,
-} from 'react';
+import { createContext, useCallback, useMemo, useReducer, useRef } from 'react';
 
+import { flattenTree } from '../data/flatten';
+import { loadTreeState } from '../data/persist';
+import { resolveAppearance } from '../data/appearance';
 import {
   DEFAULT_TREE_LABELS,
   type FlatRow,
+  type TreeActivateOptions,
   type TreeContextMenuSlot,
   type TreeItemId,
   type TreeLabels,
-  type TreeLoadChildren,
   type TreeNode,
-  type TreeActivateOptions,
-  type TreeActivationMode,
   type TreeRootProps,
-  type TreeRowSlot,
-  type TreeSelectionMode,
 } from '../types';
-import {
-  createChildCache,
-  type ChildCache,
-  type ChildEntry,
-} from '../data/childCache';
-import { flattenTree } from '../data/flatten';
-import { loadTreeState, saveTreeState } from '../data/persist';
-import {
-  resolveAppearance,
-  type ResolvedAppearance,
-  type TreeAppearance,
-} from '../data/appearance';
-
-// =====================================================================
-// Reducer
-// =====================================================================
 
-interface State<T> {
-  expanded: Set<TreeItemId>;
-  selected: Set<TreeItemId>;
-  focused: TreeItemId | null;
-  query: string;
-  /** Bumped on every cache mutation so memos see a fresh dep. */
-  cacheTick: number;
-}
-
-type Action<T> =
-  | { type: 'expand'; id: TreeItemId }
-  | { type: 'collapse'; id: TreeItemId }
-  | { type: 'toggle'; id: TreeItemId }
-  | { type: 'set-expanded'; ids: TreeItemId[] }
-  | { type: 'select'; id: TreeItemId; mode: TreeSelectionMode }
-  | { type: 'select-many'; ids: TreeItemId[] }
-  | { type: 'clear-selection' }
-  | { type: 'focus'; id: TreeItemId | null }
-  | { type: 'set-query'; q: string }
-  | { type: 'cache-tick' };
-
-const reducer = <T,>(state: State<T>, action: Action<T>): State<T> => {
-  switch (action.type) {
-    case 'expand': {
-      if (state.expanded.has(action.id)) return state;
-      const next = new Set(state.expanded);
-      next.add(action.id);
-      return { ...state, expanded: next };
-    }
-    case 'collapse': {
-      if (!state.expanded.has(action.id)) return state;
-      const next = new Set(state.expanded);
-      next.delete(action.id);
-      return { ...state, expanded: next };
-    }
-    case 'toggle': {
-      const next = new Set(state.expanded);
-      if (next.has(action.id)) next.delete(action.id);
-      else next.add(action.id);
-      return { ...state, expanded: next };
-    }
-    case 'set-expanded':
-      return { ...state, expanded: new Set(action.ids) };
-    case 'select': {
-      if (action.mode === 'none') return state;
-      if (action.mode === 'single') {
-        return { ...state, selected: new Set([action.id]), focused: action.id };
-      }
-      const next = new Set(state.selected);
-      if (next.has(action.id)) next.delete(action.id);
-      else next.add(action.id);
-      return { ...state, selected: next, focused: action.id };
-    }
-    case 'select-many':
-      return { ...state, selected: new Set(action.ids) };
-    case 'clear-selection':
-      return { ...state, selected: new Set() };
-    case 'focus':
-      return { ...state, focused: action.id };
-    case 'set-query':
-      return { ...state, query: action.q };
-    case 'cache-tick':
-      return { ...state, cacheTick: state.cacheTick + 1 };
-    default:
-      return state;
-  }
-};
-
-// =====================================================================
-// Context value
-// =====================================================================
-
-export interface TreeContextValue<T> {
-  // State
-  expanded: ReadonlySet<TreeItemId>;
-  selected: ReadonlySet<TreeItemId>;
-  focused: TreeItemId | null;
-  query: string;
-
-  // Flattened render rows (visible items only)
-  flatRows: FlatRow<T>[];
-  /** Search-matching node ids (subset of all flatRows). */
-  matchingIds: ReadonlySet<TreeItemId>;
-
-  // Imperative actions
-  expand: (id: TreeItemId) => void;
-  collapse: (id: TreeItemId) => void;
-  toggle: (id: TreeItemId) => void;
-  expandAll: () => void;
-  collapseAll: () => void;
-  select: (id: TreeItemId) => void;
-  setSelectedIds: (ids: TreeItemId[]) => void;
-  clearSelection: () => void;
-  setFocus: (id: TreeItemId | null) => void;
-  setQuery: (q: string) => void;
-  refresh: (id: TreeItemId) => Promise<void>;
-  refreshAll: () => Promise<void>;
-  activate: (node: TreeNode<T>, opts?: TreeActivateOptions) => void;
-
-  // Config / slots
-  labels: TreeLabels;
-  /** Resolved cosmetic config — never null. */
-  appearance: ResolvedAppearance;
-  /** Convenience alias for `appearance.indent`. */
-  indent: number;
-  selectionMode: TreeSelectionMode;
-  activationMode: TreeActivationMode;
-  enableSearch: boolean;
-  showIndentGuides: boolean;
-  getItemName: (node: TreeNode<T>) => string;
-
-  renderIcon?: TreeRowSlot<T>;
-  renderLabel?: TreeRowSlot<T>;
-  renderActions?: TreeRowSlot<T>;
-  renderContextMenu?: TreeContextMenuSlot<T>;
-}
-
-const TreeContext = createContext<TreeContextValue<unknown> | null>(null);
+import { reducer, createInitialState } from './state';
+import { useAsyncChildren } from './async-children';
+import { useExpansion } from './expansion';
+import { useSelection } from './selection';
+import { useRename } from './rename';
+import { useClipboard } from './clipboard';
+import { useResolvedMenu, renderItemsAsContextMenu, tidyMenuItems } from './menu';
+import { useDnd, type UseDndReturn } from './dnd';
+import { usePersistSync } from './persist';
+import type { TreeContextValue } from './TreeContextValue';
+
+// Re-exported from this module: the value interface (so consumers
+// continue to `import type { TreeContextValue }` from `./context`).
+export type { TreeContextValue } from './TreeContextValue';
+
+/**
+ * Internal context object. Exported so `TreeRoot` can wrap it with an
+ * override-provider that injects a slot-form `renderContextMenu`
+ * derived from the declarative resolver. Consumers should use
+ * `useTreeContext()` instead of touching this directly.
+ */
+export const TreeContext = createContext<TreeContextValue<unknown> | null>(null);
 
 export function useTreeContext<T>(): TreeContextValue<T> {
   const ctx = React.useContext(TreeContext);
@@ -169,7 +49,20 @@ export function useTreeContext<T>(): TreeContextValue<T> {
 }
 
 // =====================================================================
-// Provider
+// Provider — thin assembly. The real work lives in:
+//
+//   state/           reducer + initial state
+//   async-children/  child cache, nodeById, fetchChildren, refresh, refreshAll
+//   expansion/       expand / collapse / toggle / expandAll / collapseAll
+//   selection/       click / move / select-all + plain select / clear
+//   rename/          start / cancel / commit
+//   clipboard/       cut / copy / paste / clear
+//   menu/            built-in actions registry + merged declarative resolver
+//   persist/         localStorage + onSelectionChange/onExpansionChange
+//
+// This file only stitches them together and shapes the final
+// `TreeContextValue`. If a feature grows, add a folder above — don't
+// extend this file.
 // =====================================================================
 
 export interface TreeProviderProps<T>
@@ -194,36 +87,19 @@ export interface TreeProviderProps<T>
     | 'renderLabel'
     | 'renderActions'
     | 'renderContextMenu'
+    | 'contextMenuActions'
     | 'labels'
     | 'persistKey'
     | 'persistSelection'
+    | 'adapter'
+    | 'defaultMenuItems'
+    | 'enableInlineRename'
+    | 'enableDnD'
+    | 'canDrop'
   > {
   children: React.ReactNode;
 }
 
-const setEqualsArr = (set: ReadonlySet<string>, arr: readonly string[]) => {
-  if (set.size !== arr.length) return false;
-  for (const id of arr) if (!set.has(id)) return false;
-  return true;
-};
-
-const collectAllIds = <T,>(
-  roots: TreeNode<T>[],
-  cache: ChildCache<T>,
-  out: TreeItemId[],
-) => {
-  for (const node of roots) {
-    if (Array.isArray(node.children)) {
-      out.push(node.id);
-      collectAllIds(node.children, cache, out);
-    } else if (node.isFolder) {
-      out.push(node.id);
-      const entry = cache.get(node.id);
-      if (entry?.children) collectAllIds(entry.children, cache, out);
-    }
-  }
-};
-
 export function TreeProvider<T>(props: TreeProviderProps<T>) {
   const {
     data,
@@ -245,13 +121,21 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
     renderLabel,
     renderActions,
     renderContextMenu,
+    contextMenuActions,
     labels: labelsOverride,
     persistKey,
     persistSelection = false,
+    adapter,
+    defaultMenuItems,
+    enableInlineRename = false,
+    enableDnD = false,
+    canDrop,
     children,
   } = props;
 
-  const labels = useMemo(
+  // ---- Stable config ------------------------------------------------
+
+  const labels = useMemo<TreeLabels>(
     () => ({ ...DEFAULT_TREE_LABELS, ...labelsOverride }),
     [labelsOverride],
   );
@@ -261,103 +145,53 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
     [appearance, indent],
   );
 
-  // Persisted state, loaded once.
+  // ---- Reducer ------------------------------------------------------
+
   const persisted = useMemo(
     () => (persistKey ? loadTreeState(persistKey) : null),
     [persistKey],
   );
 
-  const [state, dispatch] = useReducer(reducer<T>, undefined, () => ({
-    expanded: new Set(persisted?.expandedItems ?? initialExpandedIds ?? []),
-    selected: new Set(
-      (persistSelection ? persisted?.selectedItems : undefined) ??
-        initialSelectedIds ??
-        [],
-    ),
-    focused: null,
-    query: '',
-    cacheTick: 0,
-  }));
-
-  // Async cache survives provider re-renders, lives in a ref.
-  const cacheRef = useRef<ChildCache<T>>(createChildCache<T>());
-  const inflightRef = useRef<Map<TreeItemId, Promise<void>>>(new Map());
-
-  // Trigger one fetch per (folder id) — concurrent expansions are deduped.
-  const fetchChildren = useCallback(
-    async (node: TreeNode<T>) => {
-      if (!loadChildren) return;
-      if (Array.isArray(node.children)) return;
-      const existing = cacheRef.current.get(node.id);
-      if (existing?.status === 'loaded' || existing?.status === 'loading') return;
-      const inflight = inflightRef.current.get(node.id);
-      if (inflight) return inflight;
-
-      cacheRef.current.set(node.id, { status: 'loading', children: [] });
-      dispatch({ type: 'cache-tick' });
-
-      const promise = (async () => {
-        try {
-          const children = await loadChildren(node);
-          cacheRef.current.set(node.id, { status: 'loaded', children });
-        } catch (err) {
-          cacheRef.current.set(node.id, {
-            status: 'error',
-            children: [],
-            error: err instanceof Error ? err.message : String(err),
-          });
-        } finally {
-          inflightRef.current.delete(node.id);
-          dispatch({ type: 'cache-tick' });
-        }
-      })();
-
-      inflightRef.current.set(node.id, promise);
-      return promise;
-    },
-    [loadChildren],
+  const [state, dispatch] = useReducer(reducer, undefined, () =>
+    createInitialState({
+      persisted,
+      initialExpandedIds,
+      initialSelectedIds,
+      persistSelection,
+    }),
   );
 
-  // Build a quick id → node map for any visible node (incl. cached children).
-  const nodeById = useMemo(() => {
-    const map = new Map<TreeItemId, TreeNode<T>>();
-    const walk = (nodes: TreeNode<T>[]) => {
-      for (const n of nodes) {
-        map.set(n.id, n);
-        if (Array.isArray(n.children)) walk(n.children);
-        else {
-          const entry = cacheRef.current.get(n.id);
-          if (entry?.children) walk(entry.children);
-        }
-      }
-    };
-    walk(data);
-    return map;
-  }, [data, state.cacheTick]);
-
-  // On expand, kick async fetch (no-op if already cached or has inline children).
-  useEffect(() => {
-    if (!loadChildren) return;
-    for (const id of state.expanded) {
-      const node = nodeById.get(id);
-      if (!node) continue;
-      void fetchChildren(node);
-    }
-  }, [loadChildren, state.expanded, state.cacheTick, nodeById, fetchChildren]);
+  const bumpCacheTick = useCallback(() => dispatch({ type: 'cache-tick' }), []);
+
+  // ---- Async children (cache + nodeById + refresh) ------------------
+
+  const {
+    nodeById,
+    refresh,
+    refreshAll,
+    collectFolderIds,
+    cache,
+  } = useAsyncChildren<T>({
+    data,
+    loadChildren,
+    expanded: state.expanded,
+    cacheTick: state.cacheTick,
+    bumpCacheTick,
+  });
+
+  // ---- Flat rows (depend on cache via cacheTick) --------------------
 
-  // Flatten on relevant changes.
-  const flatRows = useMemo(
+  const flatRows = useMemo<FlatRow<T>[]>(
     () =>
       flattenTree<T>({
         roots: data,
         expandedIds: state.expanded,
-        cache: cacheRef.current,
+        cache,
         filterNode,
       }),
-    [data, state.expanded, state.cacheTick, filterNode],
+    [data, state.expanded, state.cacheTick, cache, filterNode],
   );
 
-  // Search matches (case-insensitive substring on getItemName).
   const matchingIds = useMemo(() => {
     const set = new Set<TreeItemId>();
     if (!enableSearch || state.query.trim() === '') return set;
@@ -370,127 +204,141 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
     return set;
   }, [enableSearch, state.query, flatRows, getItemName]);
 
-  // External callbacks via stable refs.
-  const onSelectionChangeRef = useRef(onSelectionChange);
-  const onExpansionChangeRef = useRef(onExpansionChange);
+  // ---- Feature hooks ------------------------------------------------
+
+  const expansion = useExpansion({ dispatch, collectFolderIds });
+  const selection = useSelection<T>({
+    dispatch,
+    selectionMode,
+    flatRows,
+    selected: state.selected,
+    anchor: state.anchor,
+    focused: state.focused,
+  });
+  const rename = useRename<T>({
+    dispatch,
+    adapter,
+    enableInlineRename,
+    nodeById,
+    getItemName,
+    labels,
+  });
+  const clipboard = useClipboard<T>({
+    dispatch,
+    clipboard: state.clipboard,
+    adapter,
+    nodeById,
+    labels,
+  });
+  const dnd = useDnd<T>({
+    enabled: enableDnD,
+    adapter,
+    nodeById,
+    selected: state.selected,
+    labels,
+    canDrop,
+  });
+
+  // ---- Activation ---------------------------------------------------
+
   const onActivateRef = useRef(onActivate);
-  onSelectionChangeRef.current = onSelectionChange;
-  onExpansionChangeRef.current = onExpansionChange;
   onActivateRef.current = onActivate;
-
-  // Notify on changes + persist.
-  const lastSelectedArrRef = useRef<TreeItemId[]>([...state.selected]);
-  const lastExpandedArrRef = useRef<TreeItemId[]>([...state.expanded]);
-
-  useEffect(() => {
-    const arr = [...state.expanded];
-    if (!setEqualsArr(state.expanded, lastExpandedArrRef.current)) {
-      lastExpandedArrRef.current = arr;
-      onExpansionChangeRef.current?.(arr);
-      if (persistKey) {
-        saveTreeState(persistKey, {
-          expandedItems: arr,
-          selectedItems: persistSelection ? [...state.selected] : [],
-        });
-      }
-    }
-  }, [state.expanded, persistKey, persistSelection, state.selected]);
-
-  useEffect(() => {
-    const arr = [...state.selected];
-    if (!setEqualsArr(state.selected, lastSelectedArrRef.current)) {
-      lastSelectedArrRef.current = arr;
-      onSelectionChangeRef.current?.(arr);
-      if (persistKey && persistSelection) {
-        saveTreeState(persistKey, {
-          expandedItems: [...state.expanded],
-          selectedItems: arr,
-        });
-      }
-    }
-  }, [state.selected, persistKey, persistSelection, state.expanded]);
-
-  // Imperative actions.
-  const expand = useCallback((id: TreeItemId) => dispatch({ type: 'expand', id }), []);
-  const collapse = useCallback((id: TreeItemId) => dispatch({ type: 'collapse', id }), []);
-  const toggle = useCallback((id: TreeItemId) => dispatch({ type: 'toggle', id }), []);
-
-  const expandAll = useCallback(() => {
-    const ids: TreeItemId[] = [];
-    collectAllIds(data, cacheRef.current, ids);
-    dispatch({ type: 'set-expanded', ids });
-  }, [data]);
-
-  const collapseAll = useCallback(
-    () => dispatch({ type: 'set-expanded', ids: [] }),
+  const activate = useCallback(
+    (node: TreeNode<T>, opts: TreeActivateOptions = { preview: false }) =>
+      onActivateRef.current?.(node, opts),
     [],
   );
 
-  const select = useCallback(
-    (id: TreeItemId) => dispatch({ type: 'select', id, mode: selectionMode }),
-    [selectionMode],
-  );
-  const setSelectedIds = useCallback(
-    (ids: TreeItemId[]) => dispatch({ type: 'select-many', ids }),
+  const setQuery = useCallback(
+    (q: string) => dispatch({ type: 'set-query', q }),
     [],
   );
-  const clearSelection = useCallback(() => dispatch({ type: 'clear-selection' }), []);
-  const setFocus = useCallback(
-    (id: TreeItemId | null) => dispatch({ type: 'focus', id }),
-    [],
-  );
-  const setQuery = useCallback((q: string) => dispatch({ type: 'set-query', q }), []);
-
-  const refresh = useCallback(
-    async (id: TreeItemId) => {
-      const node = nodeById.get(id);
-      if (!node || !loadChildren) return;
-      cacheRef.current.delete(id);
-      dispatch({ type: 'cache-tick' });
-      await fetchChildren(node);
-    },
-    [nodeById, loadChildren, fetchChildren],
-  );
 
-  const refreshAll = useCallback(async () => {
-    cacheRef.current.clear();
-    dispatch({ type: 'cache-tick' });
-    if (!loadChildren) return;
-    await Promise.all(
-      [...state.expanded].map((id) => {
-        const node = nodeById.get(id);
-        return node ? fetchChildren(node) : undefined;
-      }),
-    );
-  }, [loadChildren, state.expanded, nodeById, fetchChildren]);
+  // ---- Persist + notify callbacks -----------------------------------
 
-  const activate = useCallback(
-    (node: TreeNode<T>, opts: TreeActivateOptions = { preview: false }) =>
-      onActivateRef.current?.(node, opts),
-    [],
+  usePersistSync({
+    expanded: state.expanded,
+    selected: state.selected,
+    persistKey,
+    persistSelection,
+    onSelectionChange,
+    onExpansionChange,
+  });
+
+  // ---- Resolved context-menu resolver -------------------------------
+
+  const resolvedContextMenuActions = useResolvedMenu<T>({
+    adapter,
+    contextMenuActions,
+    defaultMenuItems,
+    labels,
+    selected: state.selected,
+    clipboard: state.clipboard,
+    nodeById,
+    getItemName,
+    enableInlineRename,
+    startRename: rename.startRename,
+    cutToClipboard: clipboard.cutToClipboard,
+    copyToClipboard: clipboard.copyToClipboard,
+    pasteFromClipboard: clipboard.pasteFromClipboard,
+  });
+
+  // Translate the declarative resolver into a slot-form
+  // `renderContextMenu` so <TreeRow> doesn't need to know about it.
+  // Explicit slot prop wins (escape-hatch for full custom menus).
+  const finalRenderContextMenu = useMemo<TreeContextMenuSlot<T> | undefined>(
+    () => {
+      if (renderContextMenu) return renderContextMenu;
+      const resolve = resolvedContextMenuActions;
+      if (!resolve) return undefined;
+      return (rowProps, trigger) => {
+        const items = resolve(rowProps);
+        const cleaned = items ? tidyMenuItems(items) : null;
+        if (!cleaned || cleaned.length === 0) return trigger;
+        return renderItemsAsContextMenu(rowProps, cleaned, trigger);
+      };
+    },
+    [renderContextMenu, resolvedContextMenuActions],
   );
 
+  // ---- Final value --------------------------------------------------
+
   const value = useMemo<TreeContextValue<T>>(
     () => ({
+      // state
       expanded: state.expanded,
       selected: state.selected,
+      anchor: state.anchor,
       focused: state.focused,
       query: state.query,
+      renamingId: state.renaming,
+      inlineRenameEnabled: rename.enabled,
+      clipboard: state.clipboard,
       flatRows,
       matchingIds,
-      expand,
-      collapse,
-      toggle,
-      expandAll,
-      collapseAll,
-      select,
-      setSelectedIds,
-      clearSelection,
-      setFocus,
+
+      // expansion
+      ...expansion,
+
+      // selection (note: `select` is from selection hook; expansion exports no `select`)
+      ...selection,
+
       setQuery,
+
+      // clipboard
+      ...clipboard,
+
+      // rename
+      startRename: rename.startRename,
+      cancelRename: rename.cancelRename,
+      commitRename: rename.commitRename,
+
+      // async
       refresh,
       refreshAll,
       activate,
+
+      // config
       labels,
       appearance: resolvedAppearance,
       indent: resolvedAppearance.indent,
@@ -499,28 +347,36 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
       enableSearch,
       showIndentGuides,
       getItemName,
+
+      // slots
       renderIcon,
       renderLabel,
       renderActions,
-      renderContextMenu,
+      renderContextMenu: finalRenderContextMenu,
+
+      adapter,
+      resolvedContextMenuActions,
+      getNodeById: (id: TreeItemId) => nodeById.get(id),
+      dnd,
     }),
     [
       state.expanded,
       state.selected,
+      state.anchor,
       state.focused,
       state.query,
+      state.renaming,
+      state.clipboard,
+      rename.enabled,
+      rename.startRename,
+      rename.cancelRename,
+      rename.commitRename,
       flatRows,
       matchingIds,
-      expand,
-      collapse,
-      toggle,
-      expandAll,
-      collapseAll,
-      select,
-      setSelectedIds,
-      clearSelection,
-      setFocus,
+      expansion,
+      selection,
       setQuery,
+      clipboard,
       refresh,
       refreshAll,
       activate,
@@ -534,7 +390,11 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
       renderIcon,
       renderLabel,
       renderActions,
-      renderContextMenu,
+      finalRenderContextMenu,
+      adapter,
+      resolvedContextMenuActions,
+      nodeById,
+      dnd,
     ],
   );
 
@@ -546,4 +406,4 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
 }
 
 // Re-export internal types referenced by hook consumers.
-export type { ChildCache, ChildEntry };
+export type { ChildCache, ChildEntry } from '../data/childCache';