@djangocfg/ui-tools 2.1.415 → 2.1.416

package/src/tools/data/Tree/context/TreeContextValue.ts

@@ -0,0 +1,139 @@
+'use client';
+
+import type { ClipboardState } from '../data/clipboard';
+import type { UseDndReturn } from './dnd';
+import type { ResolvedAppearance } from '../data/appearance';
+import type { ClickModifiers } from '../data/selection';
+import type {
+  FlatRow,
+  TreeActivateOptions,
+  TreeActivationMode,
+  TreeAdapter,
+  TreeContextMenuItem,
+  TreeContextMenuSlot,
+  TreeItemId,
+  TreeLabels,
+  TreeMovePosition,
+  TreeNode,
+  TreeRowRenderProps,
+  TreeRowSlot,
+  TreeSelectionMode,
+} from '../types';
+
+export interface TreeContextValue<T> {
+  // State
+  expanded: ReadonlySet<TreeItemId>;
+  selected: ReadonlySet<TreeItemId>;
+  /** Anchor for shift-range. `null` when nothing has been clicked yet. */
+  anchor: TreeItemId | null;
+  focused: TreeItemId | null;
+  query: string;
+  /** Id of the row currently in inline-rename mode (or `null`). */
+  renamingId: TreeItemId | null;
+  /** Is inline rename allowed by the host? */
+  inlineRenameEnabled: boolean;
+
+  /** Tree-local clipboard (cut / copy) — P5. `null` when empty. */
+  clipboard: ClipboardState;
+
+  // 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;
+  /**
+   * Finder/Explorer-style click selection. Reads modifier keys from the
+   * passed event and decides between replace / toggle / range / union.
+   */
+  clickSelect: (id: TreeItemId, mods: ClickModifiers) => void;
+  /**
+   * Move-focus with optional range-extend (shift+arrows).
+   */
+  moveSelect: (id: TreeItemId, opts: { extend: boolean }) => void;
+  /** Select every currently visible row (mod+a). */
+  selectAll: () => void;
+  setFocus: (id: TreeItemId | null) => void;
+  setQuery: (q: string) => void;
+
+  /** Put the given ids on Tree's clipboard as `cut`. */
+  cutToClipboard: (ids: TreeItemId[]) => void;
+  /** Put the given ids on Tree's clipboard as `copy`. */
+  copyToClipboard: (ids: TreeItemId[]) => void;
+  /**
+   * Apply clipboard onto `target` (a row, or `null` for the root). Cut →
+   * `adapter.move`; copy → `adapter.copy`. After a successful cut+paste
+   * the clipboard is cleared. No-op when clipboard is empty or the
+   * matching adapter method is undefined.
+   */
+  pasteFromClipboard: (
+    target: TreeNode<T> | null,
+    position?: TreeMovePosition,
+  ) => Promise<void>;
+  /** Clear the clipboard without pasting. */
+  clearClipboard: () => void;
+
+  /** Begin inline rename on the given row. */
+  startRename: (id: TreeItemId) => void;
+  /** Cancel inline rename without committing. */
+  cancelRename: () => void;
+  /**
+   * Commit inline rename. Tree calls `adapter.rename` and then clears
+   * the renaming state. On validation failure surfaces an error via
+   * `window.dialog.alert` and keeps the input open.
+   */
+  commitRename: (id: TreeItemId, nextName: string) => Promise<boolean>;
+
+  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>;
+
+  /** CRUD adapter (P2). May be undefined — Tree still renders normally. */
+  adapter?: TreeAdapter<T>;
+  /**
+   * Final, merged declarative menu resolver. Combines built-in adapter
+   * actions (filtered by `defaultMenuItems`) with the consumer's
+   * `contextMenuActions` resolver, and injects the current
+   * `selectedNodes` before delegating.
+   */
+  resolvedContextMenuActions?: (
+    row: TreeRowRenderProps<T>,
+  ) => TreeContextMenuItem<T>[] | null | undefined;
+  /**
+   * Imperative lookup for any node currently known to Tree (root +
+   * cached async children).
+   */
+  getNodeById: (id: TreeItemId) => TreeNode<T> | undefined;
+
+  /**
+   * Drag-and-drop state and handlers (P6). `dnd.active` is `false`
+   * when the host didn't enable DnD or `adapter.move` is missing — in
+   * that case `TreeRow` skips all drag setup.
+   */
+  dnd: UseDndReturn<T>;
+}

package/src/tools/data/Tree/context/async-children/collect-ids.ts

@@ -0,0 +1,27 @@
+'use client';
+
+import type { ChildCache } from '../../data/childCache';
+import type { TreeItemId, TreeNode } from '../../types';
+
+/**
+ * Walk `roots` + cached async children and push every *folder* id into
+ * `out`. Used by `expandAll`.
+ *
+ * Leaves are intentionally not collected — expanding a leaf is a no-op.
+ */
+export function collectAllFolderIds<T>(
+  roots: TreeNode<T>[],
+  cache: ChildCache<T>,
+  out: TreeItemId[],
+): void {
+  for (const node of roots) {
+    if (Array.isArray(node.children)) {
+      out.push(node.id);
+      collectAllFolderIds(node.children, cache, out);
+    } else if (node.isFolder) {
+      out.push(node.id);
+      const entry = cache.get(node.id);
+      if (entry?.children) collectAllFolderIds(entry.children, cache, out);
+    }
+  }
+}

package/src/tools/data/Tree/context/async-children/index.ts

@@ -0,0 +1,8 @@
+'use client';
+
+export { useAsyncChildren } from './use-async-children';
+export type {
+  UseAsyncChildrenOptions,
+  UseAsyncChildrenReturn,
+} from './use-async-children';
+export { collectAllFolderIds } from './collect-ids';

package/src/tools/data/Tree/context/async-children/use-async-children.ts

@@ -0,0 +1,157 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+
+import { createChildCache, type ChildCache } from '../../data/childCache';
+import type {
+  TreeItemId,
+  TreeLoadChildren,
+  TreeNode,
+} from '../../types';
+import { collectAllFolderIds } from './collect-ids';
+
+export interface UseAsyncChildrenOptions<T> {
+  data: TreeNode<T>[];
+  loadChildren?: TreeLoadChildren<T>;
+  /** Current set of expanded ids — controls which async fetches fire. */
+  expanded: ReadonlySet<TreeItemId>;
+  /** Bumps every time the cache mutates — invalidates downstream memos. */
+  cacheTick: number;
+  /** Dispatch into the reducer (used to bump `cacheTick`). */
+  bumpCacheTick: () => void;
+}
+
+export interface UseAsyncChildrenReturn<T> {
+  /** Live async-children cache (mutable ref, not React state). */
+  cache: ChildCache<T>;
+  /** Id → node lookup across the root tree + cached async children. */
+  nodeById: Map<TreeItemId, TreeNode<T>>;
+  /** Fetch a single folder's children (deduped, idempotent). */
+  fetchChildren: (node: TreeNode<T>) => Promise<void> | void;
+  /** Drop one node's cache entry and refetch. */
+  refresh: (id: TreeItemId) => Promise<void>;
+  /** Clear the entire cache and refetch every currently-expanded folder. */
+  refreshAll: () => Promise<void>;
+  /** Collect every folder id known to Tree (root + cached). For `expandAll`. */
+  collectFolderIds: () => TreeItemId[];
+}
+
+/**
+ * Manage async children: a long-lived cache (in a ref), dedup-ed
+ * `loadChildren` calls, and a `nodeById` map that walks both inline
+ * children and cached async ones. The cache lives outside reducer state
+ * because mutating a Map per render is cheaper than spreading it; we
+ * trigger downstream re-renders via the `cacheTick` counter.
+ */
+export function useAsyncChildren<T>({
+  data,
+  loadChildren,
+  expanded,
+  cacheTick,
+  bumpCacheTick,
+}: UseAsyncChildrenOptions<T>): UseAsyncChildrenReturn<T> {
+  // The cache survives provider re-renders and async work.
+  const cacheRef = useRef<ChildCache<T>>(createChildCache<T>());
+  const inflightRef = useRef<Map<TreeItemId, Promise<void>>>(new Map());
+
+  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: [] });
+      bumpCacheTick();
+
+      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);
+          bumpCacheTick();
+        }
+      })();
+
+      inflightRef.current.set(node.id, promise);
+      return promise;
+    },
+    [loadChildren, bumpCacheTick],
+  );
+
+  // Build a quick id → node map across roots + cached async children.
+  // Re-runs whenever the cache mutates (cacheTick) or `data` changes.
+  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, cacheTick]);
+
+  // Auto-fetch every expanded folder that isn't already in cache. Cheap
+  // — `fetchChildren` short-circuits when cached or already inflight.
+  useEffect(() => {
+    if (!loadChildren) return;
+    for (const id of expanded) {
+      const node = nodeById.get(id);
+      if (!node) continue;
+      void fetchChildren(node);
+    }
+  }, [loadChildren, expanded, cacheTick, nodeById, fetchChildren]);
+
+  const refresh = useCallback(
+    async (id: TreeItemId) => {
+      const node = nodeById.get(id);
+      if (!node || !loadChildren) return;
+      cacheRef.current.delete(id);
+      bumpCacheTick();
+      await fetchChildren(node);
+    },
+    [nodeById, loadChildren, fetchChildren, bumpCacheTick],
+  );
+
+  const refreshAll = useCallback(async () => {
+    cacheRef.current.clear();
+    bumpCacheTick();
+    if (!loadChildren) return;
+    await Promise.all(
+      [...expanded].map((id) => {
+        const node = nodeById.get(id);
+        return node ? fetchChildren(node) : undefined;
+      }),
+    );
+  }, [loadChildren, expanded, nodeById, fetchChildren, bumpCacheTick]);
+
+  const collectFolderIds = useCallback(() => {
+    const ids: TreeItemId[] = [];
+    collectAllFolderIds(data, cacheRef.current, ids);
+    return ids;
+  }, [data]);
+
+  return {
+    cache: cacheRef.current,
+    nodeById,
+    fetchChildren,
+    refresh,
+    refreshAll,
+    collectFolderIds,
+  };
+}

package/src/tools/data/Tree/context/clipboard/index.ts

@@ -0,0 +1,4 @@
+'use client';
+
+export { useClipboard } from './use-clipboard';
+export type { UseClipboardOptions, UseClipboardReturn } from './use-clipboard';

package/src/tools/data/Tree/context/clipboard/use-clipboard.ts

@@ -0,0 +1,115 @@
+'use client';
+
+import { useCallback, useRef } from 'react';
+
+import { getDialog } from '@djangocfg/ui-core/lib/dialog-service';
+
+import type { ClipboardState } from '../../data/clipboard';
+import type {
+  TreeAdapter,
+  TreeItemId,
+  TreeLabels,
+  TreeMovePosition,
+  TreeNode,
+} from '../../types';
+import type { Action } from '../state';
+
+export interface UseClipboardOptions<T> {
+  dispatch: React.Dispatch<Action>;
+  /** Current clipboard snapshot — latched into a ref for async paste. */
+  clipboard: ClipboardState;
+  adapter?: TreeAdapter<T>;
+  nodeById: Map<TreeItemId, TreeNode<T>>;
+  labels: TreeLabels;
+}
+
+export interface UseClipboardReturn<T> {
+  cutToClipboard: (ids: TreeItemId[]) => void;
+  copyToClipboard: (ids: TreeItemId[]) => void;
+  /** Apply clipboard to `target` (a row, or `null` = root). */
+  pasteFromClipboard: (
+    target: TreeNode<T> | null,
+    position?: TreeMovePosition,
+  ) => Promise<void>;
+  clearClipboard: () => void;
+}
+
+/**
+ * Tree-local clipboard. Cut + paste dispatches `adapter.move`, copy +
+ * paste dispatches `adapter.copy`. Errors are surfaced through
+ * `window.dialog.alert` so they don't get swallowed silently.
+ */
+export function useClipboard<T>({
+  dispatch,
+  clipboard,
+  adapter,
+  nodeById,
+  labels,
+}: UseClipboardOptions<T>): UseClipboardReturn<T> {
+  const clipboardRef = useRef(clipboard);
+  clipboardRef.current = clipboard;
+
+  const cutToClipboard = useCallback(
+    (ids: TreeItemId[]) => {
+      if (ids.length === 0) return;
+      dispatch({ type: 'clipboard-set', payload: { kind: 'cut', ids } });
+    },
+    [dispatch],
+  );
+
+  const copyToClipboard = useCallback(
+    (ids: TreeItemId[]) => {
+      if (ids.length === 0) return;
+      dispatch({ type: 'clipboard-set', payload: { kind: 'copy', ids } });
+    },
+    [dispatch],
+  );
+
+  const clearClipboard = useCallback(
+    () => dispatch({ type: 'clipboard-set', payload: null }),
+    [dispatch],
+  );
+
+  const pasteFromClipboard = useCallback(
+    async (
+      target: TreeNode<T> | null,
+      position: TreeMovePosition = 'inside',
+    ) => {
+      const cb = clipboardRef.current;
+      if (!cb || cb.ids.length === 0) return;
+      if (!adapter) return;
+      const nodes = cb.ids
+        .map((id) => nodeById.get(id))
+        .filter((n): n is TreeNode<T> => !!n);
+      if (nodes.length === 0) {
+        dispatch({ type: 'clipboard-set', payload: null });
+        return;
+      }
+      try {
+        if (cb.kind === 'cut') {
+          if (!adapter.move) return;
+          await adapter.move(nodes, target, position);
+          // Cut + paste consumes the clipboard. Copy + paste retains it.
+          dispatch({ type: 'clipboard-set', payload: null });
+        } else {
+          if (!adapter.copy) return;
+          await adapter.copy(nodes, target, position);
+        }
+      } catch (e) {
+        const dialog = getDialog();
+        await dialog?.alert({
+          title: labels.error,
+          message: e instanceof Error ? e.message : String(e),
+        });
+      }
+    },
+    [dispatch, adapter, nodeById, labels],
+  );
+
+  return {
+    cutToClipboard,
+    copyToClipboard,
+    pasteFromClipboard,
+    clearClipboard,
+  };
+}

package/src/tools/data/Tree/context/dnd/index.ts

@@ -0,0 +1,8 @@
+'use client';
+
+export { useDnd } from './use-dnd';
+export type {
+  UseDndOptions,
+  UseDndReturn,
+  DropTargetState,
+} from './use-dnd';

package/src/tools/data/Tree/context/dnd/use-dnd.ts

@@ -0,0 +1,194 @@
+'use client';
+
+import { useCallback, useMemo, useState } from 'react';
+
+import { getDialog } from '@djangocfg/ui-core/lib/dialog-service';
+
+import { defaultCanDrop } from '../../data/dnd';
+import type {
+  TreeAdapter,
+  TreeItemId,
+  TreeLabels,
+  TreeMovePosition,
+  TreeNode,
+} from '../../types';
+
+export interface UseDndOptions<T> {
+  enabled: boolean;
+  adapter?: TreeAdapter<T>;
+  nodeById: Map<TreeItemId, TreeNode<T>>;
+  /**
+   * Multi-selection at the moment dragging begins. If the dragged row
+   * is part of the selection, we drag all selected rows; otherwise we
+   * drag just the row.
+   */
+  selected: ReadonlySet<TreeItemId>;
+  labels: TreeLabels;
+  /** Optional consumer-defined drop validator (layered on top of `defaultCanDrop`). */
+  canDrop?: (ctx: {
+    source: TreeNode<T>[];
+    target: TreeNode<T> | null;
+    position: TreeMovePosition;
+  }) => boolean;
+}
+
+export interface DropTargetState {
+  id: TreeItemId | null; // null = root drop zone
+  position: TreeMovePosition;
+}
+
+export interface UseDndReturn<T> {
+  /** True when the host enabled DnD AND adapter.move is defined. */
+  active: boolean;
+  /** Ids currently being dragged (empty when not dragging). */
+  draggingIds: ReadonlySet<TreeItemId>;
+  /** Live drop target (`null` when nothing under the pointer). */
+  dropTarget: DropTargetState | null;
+  /** Called by row sensors on dragstart. */
+  beginDrag: (rowId: TreeItemId) => void;
+  /**
+   * Called on dragover. `null` clears the indicator. Tree already
+   * filters self/cycle drops via `defaultCanDrop` — the row component
+   * decides the position from pointer geometry first.
+   */
+  setDropTarget: (target: DropTargetState | null) => void;
+  /** Commit drop — calls `adapter.move` and resets transient state. */
+  commitDrop: () => Promise<void>;
+  /** Cancel without committing (Esc, drop outside). */
+  cancelDrag: () => void;
+  /**
+   * Validate a candidate drop in real time. Combines `defaultCanDrop`
+   * with the consumer's `canDrop`. Used by the row component to
+   * suppress the indicator on invalid hovers.
+   */
+  isAllowedDrop: (target: TreeNode<T> | null, position: TreeMovePosition) => boolean;
+}
+
+export function useDnd<T>({
+  enabled,
+  adapter,
+  nodeById,
+  selected,
+  labels,
+  canDrop,
+}: UseDndOptions<T>): UseDndReturn<T> {
+  const active = enabled && !!adapter?.move;
+
+  const [draggingIds, setDraggingIds] = useState<ReadonlySet<TreeItemId>>(
+    () => new Set(),
+  );
+  const [dropTarget, setDropTarget] = useState<DropTargetState | null>(null);
+
+  const beginDrag = useCallback(
+    (rowId: TreeItemId) => {
+      if (!active) return;
+      // If the dragged row is part of the selection, drag the whole
+      // selection. Otherwise it's a single-row drag (and we don't
+      // touch the existing selection).
+      const ids = selected.has(rowId)
+        ? new Set(selected)
+        : new Set<TreeItemId>([rowId]);
+      setDraggingIds(ids);
+    },
+    [active, selected],
+  );
+
+  const cancelDrag = useCallback(() => {
+    setDraggingIds(new Set());
+    setDropTarget(null);
+  }, []);
+
+  const resolveSourceNodes = useCallback((): TreeNode<T>[] => {
+    const out: TreeNode<T>[] = [];
+    for (const id of draggingIds) {
+      const node = nodeById.get(id);
+      if (node) out.push(node);
+    }
+    return out;
+  }, [draggingIds, nodeById]);
+
+  const isAllowedDrop = useCallback(
+    (target: TreeNode<T> | null, position: TreeMovePosition): boolean => {
+      if (!active) return false;
+      if (draggingIds.size === 0) return false;
+      const source = resolveSourceNodes();
+      if (
+        !defaultCanDrop<T>({
+          source,
+          target,
+          position,
+          getNodeById: (id) => nodeById.get(id),
+        })
+      ) {
+        return false;
+      }
+      // Layer the consumer's rule on top.
+      return canDrop?.({ source, target, position }) ?? true;
+    },
+    [active, draggingIds, resolveSourceNodes, nodeById, canDrop],
+  );
+
+  const commitDrop = useCallback(async () => {
+    if (!active || !adapter?.move) {
+      cancelDrag();
+      return;
+    }
+    const t = dropTarget;
+    if (!t) {
+      cancelDrag();
+      return;
+    }
+    const targetNode = t.id ? nodeById.get(t.id) ?? null : null;
+    const source = resolveSourceNodes();
+    if (source.length === 0) {
+      cancelDrag();
+      return;
+    }
+    if (!isAllowedDrop(targetNode, t.position)) {
+      cancelDrag();
+      return;
+    }
+    try {
+      await adapter.move(source, targetNode, t.position);
+    } catch (e) {
+      const dialog = getDialog();
+      await dialog?.alert({
+        title: labels.error,
+        message: e instanceof Error ? e.message : String(e),
+      });
+    } finally {
+      cancelDrag();
+    }
+  }, [
+    active,
+    adapter,
+    cancelDrag,
+    dropTarget,
+    isAllowedDrop,
+    labels,
+    nodeById,
+    resolveSourceNodes,
+  ]);
+
+  return useMemo(
+    () => ({
+      active,
+      draggingIds,
+      dropTarget,
+      beginDrag,
+      setDropTarget,
+      commitDrop,
+      cancelDrag,
+      isAllowedDrop,
+    }),
+    [
+      active,
+      draggingIds,
+      dropTarget,
+      beginDrag,
+      commitDrop,
+      cancelDrag,
+      isAllowedDrop,
+    ],
+  );
+}

package/src/tools/data/Tree/context/expansion/index.ts

@@ -0,0 +1,4 @@
+'use client';
+
+export { useExpansion } from './use-expansion';
+export type { UseExpansionOptions, UseExpansionReturn } from './use-expansion';