@djangocfg/widget-data 0.1.1

package/src/Tree/context/TreeContext.tsx

@@ -0,0 +1,409 @@
+'use client';
+
+import * as React 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 TreeNode,
+  type TreeRootProps,
+} from '../types';
+
+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);
+  if (!ctx) {
+    throw new Error('useTreeContext must be used inside <TreeProvider>');
+  }
+  return ctx as TreeContextValue<T>;
+}
+
+// =====================================================================
+// 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>
+  extends Pick<
+    TreeRootProps<T>,
+    | 'data'
+    | 'getItemName'
+    | 'loadChildren'
+    | 'selectionMode'
+    | 'activationMode'
+    | 'initialExpandedIds'
+    | 'initialSelectedIds'
+    | 'indent'
+    | 'appearance'
+    | 'onSelectionChange'
+    | 'onExpansionChange'
+    | 'onActivate'
+    | 'filterNode'
+    | 'enableSearch'
+    | 'showIndentGuides'
+    | 'renderIcon'
+    | 'renderLabel'
+    | 'renderActions'
+    | 'renderContextMenu'
+    | 'contextMenuActions'
+    | 'labels'
+    | 'persistKey'
+    | 'persistSelection'
+    | 'adapter'
+    | 'defaultMenuItems'
+    | 'enableInlineRename'
+    | 'enableDnD'
+    | 'canDrop'
+  > {
+  children: React.ReactNode;
+}
+
+export function TreeProvider<T>(props: TreeProviderProps<T>) {
+  const {
+    data,
+    getItemName,
+    loadChildren,
+    selectionMode = 'single',
+    activationMode = 'single-click',
+    initialExpandedIds,
+    initialSelectedIds,
+    indent,
+    appearance,
+    onSelectionChange,
+    onExpansionChange,
+    onActivate,
+    filterNode,
+    enableSearch = false,
+    showIndentGuides = false,
+    renderIcon,
+    renderLabel,
+    renderActions,
+    renderContextMenu,
+    contextMenuActions,
+    labels: labelsOverride,
+    persistKey,
+    persistSelection = false,
+    adapter,
+    defaultMenuItems,
+    enableInlineRename = false,
+    enableDnD = false,
+    canDrop,
+    children,
+  } = props;
+
+  // ---- Stable config ------------------------------------------------
+
+  const labels = useMemo<TreeLabels>(
+    () => ({ ...DEFAULT_TREE_LABELS, ...labelsOverride }),
+    [labelsOverride],
+  );
+
+  const resolvedAppearance = useMemo(
+    () => resolveAppearance(appearance, indent),
+    [appearance, indent],
+  );
+
+  // ---- Reducer ------------------------------------------------------
+
+  const persisted = useMemo(
+    () => (persistKey ? loadTreeState(persistKey) : null),
+    [persistKey],
+  );
+
+  const [state, dispatch] = useReducer(reducer, undefined, () =>
+    createInitialState({
+      persisted,
+      initialExpandedIds,
+      initialSelectedIds,
+      persistSelection,
+    }),
+  );
+
+  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) --------------------
+
+  const flatRows = useMemo<FlatRow<T>[]>(
+    () =>
+      flattenTree<T>({
+        roots: data,
+        expandedIds: state.expanded,
+        cache,
+        filterNode,
+      }),
+    [data, state.expanded, state.cacheTick, cache, filterNode],
+  );
+
+  const matchingIds = useMemo(() => {
+    const set = new Set<TreeItemId>();
+    if (!enableSearch || state.query.trim() === '') return set;
+    const q = state.query.trim().toLowerCase();
+    for (const row of flatRows) {
+      if (getItemName(row.node).toLowerCase().includes(q)) {
+        set.add(row.node.id);
+      }
+    }
+    return set;
+  }, [enableSearch, state.query, flatRows, getItemName]);
+
+  // ---- 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);
+  onActivateRef.current = onActivate;
+  const activate = useCallback(
+    (node: TreeNode<T>, opts: TreeActivateOptions = { preview: false }) =>
+      onActivateRef.current?.(node, opts),
+    [],
+  );
+
+  const setQuery = useCallback(
+    (q: string) => dispatch({ type: 'set-query', q }),
+    [],
+  );
+
+  // ---- Persist + notify callbacks -----------------------------------
+
+  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,
+
+      // 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,
+      selectionMode,
+      activationMode,
+      enableSearch,
+      showIndentGuides,
+      getItemName,
+
+      // slots
+      renderIcon,
+      renderLabel,
+      renderActions,
+      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,
+      expansion,
+      selection,
+      setQuery,
+      clipboard,
+      refresh,
+      refreshAll,
+      activate,
+      labels,
+      resolvedAppearance,
+      selectionMode,
+      activationMode,
+      enableSearch,
+      showIndentGuides,
+      getItemName,
+      renderIcon,
+      renderLabel,
+      renderActions,
+      finalRenderContextMenu,
+      adapter,
+      resolvedContextMenuActions,
+      nodeById,
+      dnd,
+    ],
+  );
+
+  return (
+    <TreeContext.Provider value={value as TreeContextValue<unknown>}>
+      {children}
+    </TreeContext.Provider>
+  );
+}
+
+// Re-export internal types referenced by hook consumers.
+export type { ChildCache, ChildEntry } from '../data/childCache';

package/src/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/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/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';