@djangocfg/ui-tools 2.1.415 → 2.1.417

package/src/tools/data/Tree/context/menu/use-resolved-menu.ts

@@ -0,0 +1,141 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import type { ClipboardState } from '../../data/clipboard';
+import type {
+  TreeAdapter,
+  TreeBuiltinAction,
+  TreeContextMenuActionsResolver,
+  TreeContextMenuItem,
+  TreeItemId,
+  TreeLabels,
+  TreeMovePosition,
+  TreeNode,
+  TreeRowRenderProps,
+} from '../../types';
+
+export type { TreeContextMenuActionsResolver };
+import {
+  buildDefaultMenuItems,
+  type BuiltinActionContext,
+} from './builtin-actions';
+
+/**
+ * Internal row-driven resolver — same shape as
+ * `TreeContextMenuActionsResolver` but takes a plain `TreeRowRenderProps`
+ * instead of the context-with-selection. The provider injects
+ * `selectedNodes` itself.
+ */
+export type ResolvedMenuResolver<T> = (
+  row: TreeRowRenderProps<T>,
+) => TreeContextMenuItem<T>[] | null | undefined;
+
+export interface UseResolvedMenuOptions<T> {
+  adapter?: TreeAdapter<T>;
+  contextMenuActions?: TreeContextMenuActionsResolver<T>;
+  defaultMenuItems?: TreeBuiltinAction[];
+  labels: TreeLabels;
+  selected: ReadonlySet<TreeItemId>;
+  clipboard: ClipboardState;
+  nodeById: Map<TreeItemId, TreeNode<T>>;
+  getItemName: (node: TreeNode<T>) => string;
+  enableInlineRename: boolean;
+  startRename: (id: TreeItemId) => void;
+  cutToClipboard: (ids: TreeItemId[]) => void;
+  copyToClipboard: (ids: TreeItemId[]) => void;
+  pasteFromClipboard: (
+    target: TreeNode<T> | null,
+    position?: TreeMovePosition,
+  ) => Promise<void>;
+}
+
+/**
+ * Build the merged declarative menu resolver — built-in adapter actions
+ * (filtered by `defaultMenuItems`) prepended to the consumer's
+ * `contextMenuActions` result. Returns `undefined` when neither side
+ * supplies anything, so `TreeRow` can skip rendering a menu entirely.
+ *
+ * The resolver injects `selectedNodes` on every call so the consumer's
+ * resolver receives the multi-selection without having to read it from
+ * elsewhere. Finder/Explorer convention applies: if the right-clicked
+ * row isn't in the current selection, the menu acts on a single-row
+ * effective selection (the row itself).
+ */
+export function useResolvedMenu<T>(
+  opts: UseResolvedMenuOptions<T>,
+): ResolvedMenuResolver<T> | undefined {
+  const {
+    adapter,
+    contextMenuActions,
+    defaultMenuItems,
+    labels,
+    selected,
+    clipboard,
+    nodeById,
+    getItemName,
+    enableInlineRename,
+    startRename,
+    cutToClipboard,
+    copyToClipboard,
+    pasteFromClipboard,
+  } = opts;
+
+  return useMemo<ResolvedMenuResolver<T> | undefined>(() => {
+    if (!adapter && !contextMenuActions) return undefined;
+
+    return (rowProps) => {
+      const selectedIds = selected.has(rowProps.node.id)
+        ? [...selected]
+        : [rowProps.node.id];
+      const selectedNodes = selectedIds
+        .map((id) => nodeById.get(id))
+        .filter((n): n is TreeNode<T> => !!n);
+
+      const builtin = adapter
+        ? buildDefaultMenuItems<T>(
+            {
+              adapter,
+              labels,
+              selectedNodes,
+              targetNode: rowProps.node,
+              getName: getItemName,
+              startInlineRename:
+                enableInlineRename && adapter.rename ? startRename : undefined,
+              clipboard: {
+                hasItems: !!clipboard && clipboard.ids.length > 0,
+                cut: cutToClipboard,
+                copy: copyToClipboard,
+                paste: () => pasteFromClipboard(rowProps.node, 'inside'),
+              },
+            } satisfies BuiltinActionContext<T>,
+            defaultMenuItems
+              ? (defaultMenuItems as (TreeBuiltinAction | 'separator')[])
+              : undefined,
+          )
+        : null;
+
+      const user =
+        contextMenuActions?.({ ...rowProps, selectedNodes }) ?? null;
+
+      if (!builtin && !user) return null;
+      if (!user) return builtin;
+      if (!builtin) return user;
+      return [...builtin, 'separator', ...user];
+    };
+  }, [
+    adapter,
+    contextMenuActions,
+    defaultMenuItems,
+    labels,
+    selected,
+    clipboard,
+    nodeById,
+    getItemName,
+    enableInlineRename,
+    startRename,
+    cutToClipboard,
+    copyToClipboard,
+    pasteFromClipboard,
+  ]);
+}

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

@@ -0,0 +1,4 @@
+'use client';
+
+export { usePersistSync } from './use-persist-sync';
+export type { UsePersistSyncOptions } from './use-persist-sync';

package/src/tools/data/Tree/context/persist/use-persist-sync.ts

@@ -0,0 +1,74 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+import { saveTreeState } from '../../data/persist';
+import type { TreeItemId } from '../../types';
+
+export interface UsePersistSyncOptions {
+  expanded: ReadonlySet<TreeItemId>;
+  selected: ReadonlySet<TreeItemId>;
+  persistKey?: string;
+  persistSelection: boolean;
+  onSelectionChange?: (ids: TreeItemId[]) => void;
+  onExpansionChange?: (ids: TreeItemId[]) => void;
+}
+
+/**
+ * Persist `expanded` / `selected` into `localStorage` under `persistKey`,
+ * and forward changes through the consumer's notify callbacks. We
+ * compare by content (not identity) because the reducer recreates
+ * `Set`s on every change — without diffing we'd fire `onSelectionChange`
+ * on every render.
+ */
+export function usePersistSync({
+  expanded,
+  selected,
+  persistKey,
+  persistSelection,
+  onSelectionChange,
+  onExpansionChange,
+}: UsePersistSyncOptions): void {
+  // Stable refs so we don't re-bind effects every render.
+  const onSelectionChangeRef = useRef(onSelectionChange);
+  const onExpansionChangeRef = useRef(onExpansionChange);
+  onSelectionChangeRef.current = onSelectionChange;
+  onExpansionChangeRef.current = onExpansionChange;
+
+  const lastSelectedArrRef = useRef<TreeItemId[]>([...selected]);
+  const lastExpandedArrRef = useRef<TreeItemId[]>([...expanded]);
+
+  useEffect(() => {
+    const arr = [...expanded];
+    if (!setEqualsArr(expanded, lastExpandedArrRef.current)) {
+      lastExpandedArrRef.current = arr;
+      onExpansionChangeRef.current?.(arr);
+      if (persistKey) {
+        saveTreeState(persistKey, {
+          expandedItems: arr,
+          selectedItems: persistSelection ? [...selected] : [],
+        });
+      }
+    }
+  }, [expanded, persistKey, persistSelection, selected]);
+
+  useEffect(() => {
+    const arr = [...selected];
+    if (!setEqualsArr(selected, lastSelectedArrRef.current)) {
+      lastSelectedArrRef.current = arr;
+      onSelectionChangeRef.current?.(arr);
+      if (persistKey && persistSelection) {
+        saveTreeState(persistKey, {
+          expandedItems: [...expanded],
+          selectedItems: arr,
+        });
+      }
+    }
+  }, [selected, persistKey, persistSelection, expanded]);
+}
+
+function setEqualsArr(set: ReadonlySet<string>, arr: readonly string[]): boolean {
+  if (set.size !== arr.length) return false;
+  for (const id of arr) if (!set.has(id)) return false;
+  return true;
+}

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

@@ -0,0 +1,4 @@
+'use client';
+
+export { useRename } from './use-rename';
+export type { UseRenameOptions, UseRenameReturn } from './use-rename';

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

@@ -0,0 +1,113 @@
+'use client';
+
+import { useCallback } from 'react';
+
+import { getDialog } from '@djangocfg/ui-core/lib/dialog-service';
+
+import type {
+  TreeAdapter,
+  TreeItemId,
+  TreeLabels,
+  TreeNode,
+} from '../../types';
+import type { Action } from '../state';
+
+export interface UseRenameOptions<T> {
+  dispatch: React.Dispatch<Action>;
+  adapter?: TreeAdapter<T>;
+  /** Master switch — hooks honour it on every entrypoint. */
+  enableInlineRename: boolean;
+  nodeById: Map<TreeItemId, TreeNode<T>>;
+  getItemName: (node: TreeNode<T>) => string;
+  labels: TreeLabels;
+}
+
+export interface UseRenameReturn {
+  /** True only when both the host opted in AND adapter exposes `rename`. */
+  enabled: boolean;
+  startRename: (id: TreeItemId) => void;
+  cancelRename: () => void;
+  commitRename: (id: TreeItemId, nextName: string) => Promise<boolean>;
+}
+
+/**
+ * Inline rename callbacks. The visible UI lives in `TreeRenameInput`;
+ * this hook owns the start/cancel/commit transitions and dialog-driven
+ * error surfacing.
+ */
+export function useRename<T>({
+  dispatch,
+  adapter,
+  enableInlineRename,
+  nodeById,
+  getItemName,
+  labels,
+}: UseRenameOptions<T>): UseRenameReturn {
+  const enabled = enableInlineRename && !!adapter?.rename;
+
+  const startRename = useCallback(
+    (id: TreeItemId) => {
+      if (!enableInlineRename) return;
+      if (!adapter?.rename) {
+        if (process.env.NODE_ENV !== 'production') {
+          // eslint-disable-next-line no-console
+          console.warn(
+            '[Tree] startRename called but adapter.rename is not defined.',
+          );
+        }
+        return;
+      }
+      dispatch({ type: 'start-rename', id });
+    },
+    [dispatch, enableInlineRename, adapter],
+  );
+
+  const cancelRename = useCallback(
+    () => dispatch({ type: 'stop-rename' }),
+    [dispatch],
+  );
+
+  const commitRename = useCallback(
+    async (id: TreeItemId, nextName: string): Promise<boolean> => {
+      if (!adapter?.rename) {
+        dispatch({ type: 'stop-rename' });
+        return false;
+      }
+      const node = nodeById.get(id);
+      if (!node) {
+        dispatch({ type: 'stop-rename' });
+        return false;
+      }
+      const trimmed = nextName.trim();
+      if (trimmed === getItemName(node)) {
+        dispatch({ type: 'stop-rename' });
+        return true;
+      }
+      let err: string | null = null;
+      if (trimmed === '') err = labels.invalidNameEmpty;
+      else err = adapter.validateName?.(trimmed, { node }) ?? null;
+
+      if (err) {
+        const dialog = getDialog();
+        await dialog?.alert({ title: labels.error, message: err });
+        return false;
+      }
+
+      try {
+        await adapter.rename(node, trimmed);
+      } catch (e) {
+        const dialog = getDialog();
+        await dialog?.alert({
+          title: labels.error,
+          message: e instanceof Error ? e.message : String(e),
+        });
+        return false;
+      }
+      dispatch({ type: 'stop-rename' });
+      return true;
+    },
+    [dispatch, adapter, nodeById, getItemName, labels],
+  );
+
+  return { enabled, startRename, cancelRename, commitRename };
+}

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

@@ -0,0 +1,4 @@
+'use client';
+
+export { useSelection } from './use-selection';
+export type { UseSelectionOptions, UseSelectionReturn } from './use-selection';

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

@@ -0,0 +1,146 @@
+'use client';
+
+import { useCallback, useRef } from 'react';
+
+import {
+  selectionFromClick,
+  selectionFromMove,
+  selectionSelectAll,
+  type ClickModifiers,
+} from '../../data/selection';
+import type {
+  FlatRow,
+  TreeItemId,
+  TreeSelectionMode,
+} from '../../types';
+import type { Action } from '../state';
+
+export interface UseSelectionOptions<T> {
+  dispatch: React.Dispatch<Action>;
+  selectionMode: TreeSelectionMode;
+  /** Current visible rows — fed in each render, latched into a ref. */
+  flatRows: FlatRow<T>[];
+  /** Current selection snapshot (latched into a ref alongside `flatRows`). */
+  selected: ReadonlySet<TreeItemId>;
+  anchor: TreeItemId | null;
+  focused: TreeItemId | null;
+}
+
+export interface UseSelectionReturn {
+  select: (id: TreeItemId) => void;
+  setSelectedIds: (ids: TreeItemId[]) => void;
+  clearSelection: () => void;
+  clickSelect: (id: TreeItemId, mods: ClickModifiers) => void;
+  moveSelect: (id: TreeItemId, opts: { extend: boolean }) => void;
+  selectAll: () => void;
+  setFocus: (id: TreeItemId | null) => void;
+}
+
+/**
+ * Finder/Explorer-style selection actions. Reads the *current* rows /
+ * selection from refs latched per-render, so the returned callbacks
+ * stay stable across renders (which matters for `react-hotkeys-hook`
+ * and for memoised TreeRow children).
+ */
+export function useSelection<T>({
+  dispatch,
+  selectionMode,
+  flatRows,
+  selected,
+  anchor,
+  focused,
+}: UseSelectionOptions<T>): UseSelectionReturn {
+  // Latch the snapshot the callbacks read from.
+  const flatRowsRef = useRef<FlatRow<T>[]>(flatRows);
+  flatRowsRef.current = flatRows;
+  const selectionRef = useRef({ selected, anchor, focused });
+  selectionRef.current = { selected, anchor, focused };
+
+  const select = useCallback(
+    (id: TreeItemId) => dispatch({ type: 'select', id, mode: selectionMode }),
+    [dispatch, selectionMode],
+  );
+  const setSelectedIds = useCallback(
+    (ids: TreeItemId[]) => dispatch({ type: 'select-many', ids }),
+    [dispatch],
+  );
+  const clearSelection = useCallback(
+    () => dispatch({ type: 'clear-selection' }),
+    [dispatch],
+  );
+  const setFocus = useCallback(
+    (id: TreeItemId | null) => dispatch({ type: 'focus', id }),
+    [dispatch],
+  );
+
+  const clickSelect = useCallback(
+    (id: TreeItemId, mods: ClickModifiers) => {
+      if (selectionMode === 'none') return;
+      if (selectionMode === 'single') {
+        dispatch({ type: 'select', id, mode: 'single' });
+        return;
+      }
+      const next = selectionFromClick(
+        selectionRef.current,
+        flatRowsRef.current,
+        id,
+        mods,
+        true,
+      );
+      dispatch({
+        type: 'selection-replace',
+        selected: [...next.selected],
+        anchor: next.anchor,
+        focused: next.focused,
+      });
+    },
+    [dispatch, selectionMode],
+  );
+
+  const moveSelect = useCallback(
+    (id: TreeItemId, opts: { extend: boolean }) => {
+      if (selectionMode !== 'multiple' || !opts.extend) {
+        dispatch({ type: 'focus', id });
+        return;
+      }
+      const next = selectionFromMove(
+        selectionRef.current,
+        flatRowsRef.current,
+        id,
+        true,
+        true,
+      );
+      dispatch({
+        type: 'selection-replace',
+        selected: [...next.selected],
+        anchor: next.anchor,
+        focused: next.focused,
+      });
+    },
+    [dispatch, selectionMode],
+  );
+
+  const selectAll = useCallback(() => {
+    if (selectionMode !== 'multiple') return;
+    const next = selectionSelectAll(
+      flatRowsRef.current,
+      selectionRef.current.focused,
+    );
+    dispatch({
+      type: 'selection-replace',
+      selected: [...next.selected],
+      anchor: next.anchor,
+      focused: next.focused,
+    });
+  }, [dispatch, selectionMode]);
+
+  return {
+    select,
+    setSelectedIds,
+    clearSelection,
+    clickSelect,
+    moveSelect,
+    selectAll,
+    setFocus,
+  };
+}

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

@@ -0,0 +1,6 @@
+'use client';
+
+export type { State, Action } from './types';
+export { reducer } from './reducer';
+export { createInitialState } from './initial';
+export type { CreateInitialStateInput } from './initial';

package/src/tools/data/Tree/context/state/initial.ts

@@ -0,0 +1,41 @@
+'use client';
+
+import type { PersistedTreeState } from '../../data/persist';
+import type { TreeItemId } from '../../types';
+import type { State } from './types';
+
+export interface CreateInitialStateInput {
+  persisted: PersistedTreeState | null;
+  initialExpandedIds?: TreeItemId[];
+  initialSelectedIds?: TreeItemId[];
+  persistSelection: boolean;
+}
+
+/**
+ * Build the reducer's initial state from persistence + initial props.
+ * Anchor is set to the first restored selection (if any) so a hard
+ * reload doesn't break shift-extend.
+ */
+export function createInitialState(input: CreateInitialStateInput): State {
+  const { persisted, initialExpandedIds, initialSelectedIds, persistSelection } =
+    input;
+  const initialSelected = new Set(
+    (persistSelection ? persisted?.selectedItems : undefined) ??
+      initialSelectedIds ??
+      [],
+  );
+  const initialAnchor: TreeItemId | null =
+    initialSelected.size > 0
+      ? (initialSelected.values().next().value as TreeItemId)
+      : null;
+  return {
+    expanded: new Set(persisted?.expandedItems ?? initialExpandedIds ?? []),
+    selected: initialSelected,
+    anchor: initialAnchor,
+    focused: null,
+    query: '',
+    renaming: null,
+    clipboard: null,
+    cacheTick: 0,
+  };
+}

package/src/tools/data/Tree/context/state/reducer.ts

@@ -0,0 +1,76 @@
+'use client';
+
+import type { Action, State } from './types';
+
+/**
+ * Pure reducer for `<TreeProvider>`. Intentionally small — most domain
+ * logic (Finder selection rules, async cache, persistence) lives in
+ * dedicated hooks under `context/<feature>/` and only dispatches one of
+ * these actions when the result needs to land in React state.
+ */
+export function reducer(state: State, action: Action): State {
+  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]),
+          anchor: 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, anchor: action.id, focused: action.id };
+    }
+    case 'select-many':
+      return { ...state, selected: new Set(action.ids) };
+    case 'clear-selection':
+      return { ...state, selected: new Set(), anchor: null };
+    case 'selection-replace':
+      return {
+        ...state,
+        selected: new Set(action.selected),
+        anchor: action.anchor,
+        focused: action.focused,
+      };
+    case 'set-anchor':
+      return { ...state, anchor: action.id };
+    case 'focus':
+      return { ...state, focused: action.id };
+    case 'set-query':
+      return { ...state, query: action.q };
+    case 'start-rename':
+      return { ...state, renaming: action.id };
+    case 'stop-rename':
+      return state.renaming === null ? state : { ...state, renaming: null };
+    case 'clipboard-set':
+      return { ...state, clipboard: action.payload };
+    case 'cache-tick':
+      return { ...state, cacheTick: state.cacheTick + 1 };
+    default:
+      return state;
+  }
+}

package/src/tools/data/Tree/context/state/types.ts

@@ -0,0 +1,46 @@
+'use client';
+
+import type { ClipboardState } from '../../data/clipboard';
+import type { TreeItemId, TreeSelectionMode } from '../../types';
+
+/**
+ * The full reducer state for `<TreeProvider>`. Async children live
+ * outside this object (see `async-children/` hook) since they're
+ * managed via refs to avoid React re-renders on every fetch.
+ */
+export interface State {
+  expanded: Set<TreeItemId>;
+  selected: Set<TreeItemId>;
+  /** Anchor for shift-range selection (Finder/Explorer). */
+  anchor: TreeItemId | null;
+  focused: TreeItemId | null;
+  query: string;
+  /** Id of the row currently in inline-rename mode (P3). */
+  renaming: TreeItemId | null;
+  /** Tree-local clipboard (cut / copy) — P5. */
+  clipboard: ClipboardState;
+  /** Bumped on every cache mutation so memos see a fresh dep. */
+  cacheTick: number;
+}
+
+export type Action =
+  | { 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: 'selection-replace';
+      selected: TreeItemId[];
+      anchor: TreeItemId | null;
+      focused: TreeItemId | null;
+    }
+  | { type: 'set-anchor'; id: TreeItemId | null }
+  | { type: 'focus'; id: TreeItemId | null }
+  | { type: 'set-query'; q: string }
+  | { type: 'start-rename'; id: TreeItemId }
+  | { type: 'stop-rename' }
+  | { type: 'clipboard-set'; payload: ClipboardState }
+  | { type: 'cache-tick' };

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

@@ -0,0 +1,33 @@
+'use client';
+
+import type { TreeItemId } from '../types';
+
+// =====================================================================
+// Tree-local clipboard.
+//
+// Why not the system clipboard? Because we need a visual "cut" state
+// (Finder/Explorer dim cut items) and a single source of truth across
+// Tree's own keyboard / menu / DnD entry points. The system clipboard
+// can't carry that semantics in a way that survives focus changes.
+//
+// Clipboard owns *ids*, not full nodes — Tree resolves them through
+// `getNodeById` at paste time. This keeps the model immutable to the
+// underlying data refreshing under us (async load, refresh, etc.).
+// =====================================================================
+
+export type ClipboardKind = 'cut' | 'copy';
+
+export interface ClipboardEntry {
+  kind: ClipboardKind;
+  ids: TreeItemId[];
+}
+
+export type ClipboardState = ClipboardEntry | null;
+
+/**
+ * Was this id put on the clipboard with `kind: 'cut'`? Used by `TreeRow`
+ * to render dimmed (`opacity-60`) rows the way Finder does.
+ */
+export function isCutId(state: ClipboardState, id: TreeItemId): boolean {
+  return state?.kind === 'cut' && state.ids.includes(id);
+}