@djangocfg/ui-tools 2.1.415 → 2.1.416

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);
+}

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

@@ -0,0 +1,123 @@
+'use client';
+
+import type { FlatRow, TreeItemId, TreeMovePosition, TreeNode } from '../types';
+
+// =====================================================================
+// Drag-and-drop primitives — pure, framework-agnostic.
+//
+// @dnd-kit handles the pointer/keyboard sensors and overlay rendering;
+// these helpers only translate pointer geometry into a domain-level
+// drop position (`before` / `inside` / `after`) and validate whether
+// a given drag/drop combo is allowed.
+//
+// Folder vs leaf semantics:
+//   - leaves        → no `inside` zone; row splits into top/bottom halves
+//                     for `before` / `after` reorder
+//   - folders       → top third = `before`, middle third = `inside`,
+//                     bottom third = `after`
+// =====================================================================
+
+export interface DropZoneInput {
+  /** Pointer Y in viewport coordinates. */
+  pointerY: number;
+  /** Row bounding box (`getBoundingClientRect()`). */
+  rowRect: { top: number; bottom: number; height: number };
+  /** Folders accept `inside` drops; leaves only reorder via before/after. */
+  isFolder: boolean;
+}
+
+/**
+ * Translate pointer geometry into a drop position relative to the row.
+ *
+ * For folders the row is split into three zones (top third / middle /
+ * bottom third). For leaves it's split in half (before / after).
+ */
+export function resolveDropZone(input: DropZoneInput): TreeMovePosition {
+  const { pointerY, rowRect, isFolder } = input;
+  const offset = pointerY - rowRect.top;
+  const ratio = rowRect.height > 0 ? offset / rowRect.height : 0.5;
+
+  if (isFolder) {
+    if (ratio < 0.33) return 'before';
+    if (ratio > 0.66) return 'after';
+    return 'inside';
+  }
+  return ratio < 0.5 ? 'before' : 'after';
+}
+
+// =====================================================================
+// canDrop — default validator.
+//
+// Rejects:
+//   1. Dropping a node onto itself.
+//   2. Dropping a folder into one of its own descendants (would create
+//      a cycle).
+//   3. Dropping `inside` a non-folder (defensive — UI already routes
+//      these as `before`/`after`, but the API can be called directly).
+//
+// Consumers can pass their own `canDrop` via `<TreeRoot canDrop={…}>`
+// to layer extra rules on top (e.g. read-only branches, type matching).
+// =====================================================================
+
+export interface CanDropInput<T> {
+  /** Nodes being dragged. */
+  source: TreeNode<T>[];
+  /** Row under the pointer (`null` = root drop zone). */
+  target: TreeNode<T> | null;
+  /** Resolved drop position. */
+  position: TreeMovePosition;
+  /** Tree's id→node lookup, used to walk descendants. */
+  getNodeById: (id: TreeItemId) => TreeNode<T> | undefined;
+}
+
+export function defaultCanDrop<T>(input: CanDropInput<T>): boolean {
+  const { source, target, position } = input;
+  if (source.length === 0) return false;
+  if (!target) return true; // root drop is always allowed when no other rule rejects.
+
+  // Inside a leaf doesn't make sense.
+  if (position === 'inside') {
+    const isFolder = Array.isArray(target.children) || !!target.isFolder;
+    if (!isFolder) return false;
+  }
+
+  for (const node of source) {
+    if (node.id === target.id) return false;
+    if (isDescendant(node, target.id)) return false;
+  }
+  return true;
+}
+
+/**
+ * Walk `root`'s inline children searching for `id`. Cached async children
+ * are *not* walked here because the cycle check needs to be cheap and
+ * deterministic — a missing cycle in unloaded branches is acceptable
+ * (the consumer's `adapter.move` is the final gatekeeper).
+ */
+function isDescendant<T>(root: TreeNode<T>, id: TreeItemId): boolean {
+  if (!Array.isArray(root.children)) return false;
+  for (const child of root.children) {
+    if (child.id === id) return true;
+    if (isDescendant(child, id)) return true;
+  }
+  return false;
+}
+
+// =====================================================================
+// DataTransfer mime — used both for in-tree drags and (later) for
+// receiving dragged files from the OS. The id payload is the JSON-
+// encoded list of `TreeItemId`s.
+// =====================================================================
+
+export const TREE_DND_MIME = 'application/x-djangocfg-tree';
+
+/**
+ * Sentinel droppable id used by `<TreeEmptyArea>` to claim the
+ * "root drop target" slot. `<TreeDndProvider>` recognises this id and
+ * maps it to `{ id: null, position: 'inside' }` in `dnd.dropTarget`.
+ *
+ * Lives in `data/` (not in the component) so both producer and
+ * consumer reference one constant instead of duplicating the magic
+ * string.
+ */
+export const TREE_ROOT_DROP_ID = '__tree_root_drop__';