@djangocfg/ui-tools 2.1.415 → 2.1.417

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__';

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

@@ -0,0 +1,67 @@
+'use client';
+
+import type { TreeBuiltinAction } from '../types';
+
+// =====================================================================
+// Finder / Explorer keyboard shortcuts.
+//
+// Each entry maps a built-in action to a list of `react-hotkeys-hook`
+// combos. `mod` resolves to ⌘ on macOS and Ctrl on Win/Linux automatically,
+// so a single declaration works cross-platform.
+//
+// Tree only binds shortcuts whose corresponding adapter method is
+// defined. So `delete` only fires if `adapter.remove` exists — same
+// gating used for context-menu items, no duplicated source of truth.
+// =====================================================================
+
+export interface FinderShortcut {
+  /** Built-in action id this shortcut runs. */
+  action: TreeBuiltinAction;
+  /** `react-hotkeys-hook` key combos. */
+  keys: string[];
+  /** Cheat-sheet description (registered via `useHotkey`). */
+  description: string;
+}
+
+export const FINDER_SHORTCUTS: FinderShortcut[] = [
+  {
+    action: 'delete',
+    keys: ['mod+backspace', 'delete'],
+    description: 'Delete selected items',
+  },
+  {
+    action: 'rename',
+    keys: ['f2'],
+    description: 'Rename selected item',
+  },
+  {
+    action: 'duplicate',
+    keys: ['mod+d'],
+    description: 'Duplicate selected items',
+  },
+  {
+    action: 'new-folder',
+    keys: ['mod+shift+n'],
+    description: 'New folder',
+  },
+  {
+    action: 'new-file',
+    keys: ['mod+n'],
+    description: 'New file',
+  },
+  {
+    action: 'cut',
+    keys: ['mod+x'],
+    description: 'Cut',
+  },
+  {
+    action: 'copy',
+    keys: ['mod+c'],
+    description: 'Copy',
+  },
+  {
+    action: 'paste',
+    keys: ['mod+v'],
+    description: 'Paste',
+  },
+];

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

@@ -8,6 +8,25 @@ export { loadTreeState, saveTreeState, clearTreeState } from './persist';
 export type { PersistedTreeState } from './persist';
 export { createDemoTree } from './createDemoTree';
 export type { DemoNode } from './createDemoTree';
+export {
+  computeRange,
+  selectionFromClick,
+  selectionFromMove,
+  selectionSelectAll,
+  selectionClear,
+} from './selection';
+export type { SelectionState, ClickModifiers } from './selection';
+export { splitFileName, autoSelectRange } from './renameUtils';
+export type { SplitName } from './renameUtils';
+export { isCutId } from './clipboard';
+export type { ClipboardKind, ClipboardEntry, ClipboardState } from './clipboard';
+export {
+  resolveDropZone,
+  defaultCanDrop,
+  TREE_DND_MIME,
+  TREE_ROOT_DROP_ID,
+} from './dnd';
+export type { DropZoneInput, CanDropInput } from './dnd';
 export {
   DEFAULT_TREE_APPEARANCE,
   resolveAppearance,

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

@@ -0,0 +1,51 @@
+'use client';
+
+// =====================================================================
+// Filename split — used by the inline-rename input to auto-select the
+// "base" portion without the extension (Finder / macOS behaviour).
+//
+// Rules:
+//   - dotfiles like ".env" or ".gitignore" → base = whole name, ext = ''
+//   - "foo"                                → base = 'foo', ext = ''
+//   - "foo.txt"                            → base = 'foo', ext = '.txt'
+//   - "foo.bar.baz"                        → base = 'foo.bar', ext = '.baz'
+//   - "folder/"  (trailing slash)          → trailing slash kept in ext
+//
+// We deliberately don't handle nested dots or multi-part extensions like
+// ".tar.gz". Finder picks the last `.` and so do we — it's good enough
+// for selection UX and consistent with the OS.
+// =====================================================================
+
+export interface SplitName {
+  base: string;
+  ext: string;
+}
+
+export function splitFileName(name: string): SplitName {
+  if (name.length === 0) return { base: '', ext: '' };
+
+  // Dotfiles — leading dot is part of the base, not an extension.
+  if (name.startsWith('.')) {
+    const rest = name.slice(1);
+    const dot = rest.lastIndexOf('.');
+    if (dot < 0) return { base: name, ext: '' };
+    return { base: '.' + rest.slice(0, dot), ext: rest.slice(dot) };
+  }
+
+  const dot = name.lastIndexOf('.');
+  if (dot <= 0) return { base: name, ext: '' };
+  return { base: name.slice(0, dot), ext: name.slice(dot) };
+}
+
+/**
+ * Returns the `[selectionStart, selectionEnd]` pair to use on focus of an
+ * `<input>` so only the base name is highlighted (Finder behaviour).
+ *
+ * Folders pass `isFolder=true` to skip extension detection and select
+ * the entire name — folders don't have file extensions semantically.
+ */
+export function autoSelectRange(name: string, isFolder: boolean): [number, number] {
+  if (isFolder) return [0, name.length];
+  const { base } = splitFileName(name);
+  return [0, base.length];
+}

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

@@ -0,0 +1,157 @@
+'use client';
+
+import type { FlatRow, TreeItemId } from '../types';
+
+// =====================================================================
+// Selection helpers — pure functions over flatRows + state.
+//
+// Finder/Explorer rules implemented here:
+//   - plain click  → replace selection, set anchor = id
+//   - meta-click   → toggle id, set anchor = id (clicked row becomes new anchor)
+//   - shift-click  → range [anchor..id] (replaces selection)
+//   - shift+meta   → union(range [anchor..id], previous selection)
+//   - shift+arrows → extend range from anchor through new focused row
+//   - mod+a        → select all visible rows
+//   - escape       → clear selection (anchor stays — focused stays)
+// =====================================================================
+
+export interface SelectionState {
+  selected: ReadonlySet<TreeItemId>;
+  /** Anchor for shift-range. `null` when nothing has been selected yet. */
+  anchor: TreeItemId | null;
+  /** Visual cursor — usually equals the last clicked / arrow-moved row. */
+  focused: TreeItemId | null;
+}
+
+function indexOf(rows: readonly FlatRow<unknown>[], id: TreeItemId | null): number {
+  if (id == null) return -1;
+  for (let i = 0; i < rows.length; i++) {
+    if (rows[i].node.id === id) return i;
+  }
+  return -1;
+}
+
+/**
+ * Inclusive range of ids between `fromId` and `toId` according to their
+ * positions in `rows`. Returns an empty array if either endpoint is not in
+ * `rows` (e.g. anchor pointed at a row that got collapsed away).
+ */
+export function computeRange<T>(
+  rows: readonly FlatRow<T>[],
+  fromId: TreeItemId | null,
+  toId: TreeItemId | null,
+): TreeItemId[] {
+  if (fromId == null || toId == null) return [];
+  const a = indexOf(rows, fromId);
+  const b = indexOf(rows, toId);
+  if (a < 0 || b < 0) return [];
+  const [lo, hi] = a <= b ? [a, b] : [b, a];
+  const out: TreeItemId[] = [];
+  for (let i = lo; i <= hi; i++) out.push(rows[i].node.id);
+  return out;
+}
+
+/**
+ * Click selection — derives next `{selected, anchor, focused}` from a
+ * pointer event's modifier keys. `rows` is the current flat view (used
+ * for shift-range computation).
+ */
+export interface ClickModifiers {
+  shift: boolean;
+  meta: boolean;
+}
+
+export function selectionFromClick<T>(
+  state: SelectionState,
+  rows: readonly FlatRow<T>[],
+  id: TreeItemId,
+  mods: ClickModifiers,
+  multi: boolean,
+): SelectionState {
+  // Single-selection mode → always collapse to one id.
+  if (!multi) {
+    return { selected: new Set([id]), anchor: id, focused: id };
+  }
+
+  // shift+meta → union of current selection with range from anchor to id.
+  if (mods.shift && mods.meta) {
+    const anchor = state.anchor ?? state.focused ?? id;
+    const range = computeRange(rows, anchor, id);
+    const next = new Set(state.selected);
+    for (const r of range) next.add(r);
+    return { selected: next, anchor: state.anchor ?? id, focused: id };
+  }
+
+  // shift-only → replace with range from anchor to id.
+  if (mods.shift) {
+    const anchor = state.anchor ?? state.focused ?? id;
+    const range = computeRange(rows, anchor, id);
+    return {
+      selected: new Set(range.length > 0 ? range : [id]),
+      anchor: state.anchor ?? anchor,
+      focused: id,
+    };
+  }
+
+  // meta-only → toggle id, reset anchor.
+  if (mods.meta) {
+    const next = new Set(state.selected);
+    if (next.has(id)) next.delete(id);
+    else next.add(id);
+    return { selected: next, anchor: id, focused: id };
+  }
+
+  // Plain click → replace selection.
+  return { selected: new Set([id]), anchor: id, focused: id };
+}
+
+/**
+ * Move-focus selection — used by arrow keys. When `extend` is true (shift),
+ * recompute the range from anchor through the new focused id. Otherwise
+ * collapse selection to the new id and reset anchor.
+ */
+export function selectionFromMove<T>(
+  state: SelectionState,
+  rows: readonly FlatRow<T>[],
+  nextFocusedId: TreeItemId,
+  extend: boolean,
+  multi: boolean,
+): SelectionState {
+  if (!multi || !extend) {
+    return { selected: new Set([nextFocusedId]), anchor: nextFocusedId, focused: nextFocusedId };
+  }
+  const anchor = state.anchor ?? state.focused ?? nextFocusedId;
+  const range = computeRange(rows, anchor, nextFocusedId);
+  return {
+    selected: new Set(range.length > 0 ? range : [nextFocusedId]),
+    anchor,
+    focused: nextFocusedId,
+  };
+}
+
+/**
+ * Select every visible row (Cmd/Ctrl+A). Anchor is set to the first row
+ * so a subsequent shift-click extends from a predictable starting point.
+ */
+export function selectionSelectAll<T>(
+  rows: readonly FlatRow<T>[],
+  focused: TreeItemId | null,
+): SelectionState {
+  if (rows.length === 0) {
+    return { selected: new Set(), anchor: null, focused };
+  }
+  const ids = rows.map((r) => r.node.id);
+  return {
+    selected: new Set(ids),
+    anchor: ids[0],
+    focused: focused ?? ids[0],
+  };
+}
+
+/**
+ * Esc behaviour — clear selected items and anchor, but keep focused so the
+ * visual cursor stays where the user left it (Finder mimics this).
+ */
+export function selectionClear(state: SelectionState): SelectionState {
+  return { selected: new Set(), anchor: null, focused: state.focused };
+}

package/src/tools/data/Tree/hooks/finder-hotkeys/build-ctx.ts

@@ -0,0 +1,48 @@
+'use client';
+
+import type { BuiltinActionContext } from '../../context/menu';
+import type {
+  TreeAdapter,
+  TreeItemId,
+  TreeLabels,
+  TreeNode,
+} from '../../types';
+
+export interface BuildCtxInput<T> {
+  adapter?: TreeAdapter<T>;
+  labels: TreeLabels;
+  selected: ReadonlySet<TreeItemId>;
+  focused: TreeItemId | null;
+  getNodeById: (id: TreeItemId) => TreeNode<T> | undefined;
+  getItemName: (node: TreeNode<T>) => string;
+  startInlineRename?: (id: TreeItemId) => void;
+  clipboard?: BuiltinActionContext<T>['clipboard'];
+}
+
+/**
+ * Build a `BuiltinActionContext<T>` snapshot from the current Tree state.
+ * Returns `null` when the adapter is missing — the hotkey handlers
+ * short-circuit on null so no built-in action fires without an adapter.
+ */
+export function buildBuiltinCtx<T>(
+  input: BuildCtxInput<T>,
+): BuiltinActionContext<T> | null {
+  if (!input.adapter) return null;
+  const selectedNodes: TreeNode<T>[] = [];
+  for (const id of input.selected) {
+    const n = input.getNodeById(id);
+    if (n) selectedNodes.push(n);
+  }
+  const targetNode = input.focused
+    ? input.getNodeById(input.focused) ?? null
+    : null;
+  return {
+    adapter: input.adapter,
+    labels: input.labels,
+    selectedNodes,
+    targetNode,
+    getName: input.getItemName,
+    startInlineRename: input.startInlineRename,
+    clipboard: input.clipboard,
+  };
+}

package/src/tools/data/Tree/hooks/finder-hotkeys/index.ts

@@ -0,0 +1,8 @@
+'use client';
+
+export { useTreeFinderHotkeys } from './use-tree-finder-hotkeys';
+export type {
+  UseTreeFinderHotkeysOptions,
+  UseTreeFinderHotkeysReturn,
+} from './use-tree-finder-hotkeys';
+export { buildBuiltinCtx } from './build-ctx';

package/src/tools/data/Tree/hooks/finder-hotkeys/use-tree-finder-hotkeys.ts

@@ -0,0 +1,166 @@
+'use client';
+
+import { useCallback, useRef } from 'react';
+import { useHotkey } from '@djangocfg/ui-core/hooks';
+
+import { runBuiltinAction, type BuiltinActionContext } from '../../context/menu';
+import type {
+  TreeAdapter,
+  TreeBuiltinAction,
+  TreeItemId,
+  TreeLabels,
+  TreeNode,
+} from '../../types';
+import { buildBuiltinCtx } from './build-ctx';
+
+export interface UseTreeFinderHotkeysOptions<T> {
+  /** Off by default — Tree opt-ins via `enableFinderHotkeys`. */
+  enabled: boolean;
+  /** Adapter — used both for action availability and dispatch. */
+  adapter?: TreeAdapter<T>;
+  /** Labels (passed through into adapter action context for dialogs). */
+  labels: TreeLabels;
+  /** Live selection (set of ids). */
+  selected: ReadonlySet<TreeItemId>;
+  /** Live focused id (used as "target" for new-file/new-folder actions). */
+  focused: TreeItemId | null;
+  /** Id → node lookup. */
+  getNodeById: (id: TreeItemId) => TreeNode<T> | undefined;
+  /** Display name resolver. */
+  getItemName: (node: TreeNode<T>) => string;
+  /** Open inline rename on the row (P3). Falls back to a prompt otherwise. */
+  startInlineRename?: (id: TreeItemId) => void;
+  /** Clipboard bindings (P5). When undefined, ⌘C/X/V are no-ops. */
+  clipboard?: BuiltinActionContext<T>['clipboard'];
+  /** Whether typing is currently in inline-rename input — pauses bindings. */
+  paused?: boolean;
+}
+
+export interface UseTreeFinderHotkeysReturn {
+  /** Attach to the tree container ref so hotkeys only fire when it has focus. */
+  ref: (instance: HTMLElement | null) => void;
+}
+
+/**
+ * Wire the platform-aware Finder/Explorer shortcuts to the built-in
+ * adapter actions. Bindings are scoped to the container ref via
+ * `useHotkey`, so they don't leak to the rest of the page.
+ *
+ * Each shortcut is bound by an explicit `useHotkey` call (no `.map(useHotkey)`
+ * loop, so the rules-of-hooks lint passes cleanly). The handler routes
+ * through `runBuiltinAction`, which silently no-ops when the adapter
+ * doesn't expose the matching method — so a Tree with `adapter = { remove }`
+ * only effectively reacts to ⌘⌫ / Delete.
+ */
+export function useTreeFinderHotkeys<T>(
+  opts: UseTreeFinderHotkeysOptions<T>,
+): UseTreeFinderHotkeysReturn {
+  const optsRef = useRef(opts);
+  optsRef.current = opts;
+
+  const run = useCallback(async (action: TreeBuiltinAction) => {
+    const o = optsRef.current;
+    if (o.paused) return;
+    const ctx = buildBuiltinCtx({
+      adapter: o.adapter,
+      labels: o.labels,
+      selected: o.selected,
+      focused: o.focused,
+      getNodeById: o.getNodeById,
+      getItemName: o.getItemName,
+      startInlineRename: o.startInlineRename,
+      clipboard: o.clipboard,
+    });
+    if (!ctx) return;
+    await runBuiltinAction(action, ctx);
+  }, []);
+
+  // One explicit binding per shortcut. Adding a new built-in action means
+  // adding one more line here — the trade-off is verbose-but-static vs.
+  // a fragile `.map(useHotkey)` loop.
+
+  const refDelete = useHotkey(
+    ['mod+backspace', 'delete'],
+    () => void run('delete'),
+    {
+      enabled: opts.enabled,
+      preventDefault: true,
+      description: 'Delete selected items',
+      scope: 'tree',
+    },
+  );
+
+  const refRename = useHotkey('f2', () => void run('rename'), {
+    enabled: opts.enabled,
+    preventDefault: true,
+    description: 'Rename selected item',
+    scope: 'tree',
+  });
+
+  const refDuplicate = useHotkey('mod+d', () => void run('duplicate'), {
+    enabled: opts.enabled,
+    preventDefault: true,
+    description: 'Duplicate selected items',
+    scope: 'tree',
+  });
+
+  const refNewFolder = useHotkey('mod+shift+n', () => void run('new-folder'), {
+    enabled: opts.enabled,
+    preventDefault: true,
+    description: 'New folder',
+    scope: 'tree',
+  });
+
+  const refNewFile = useHotkey('mod+n', () => void run('new-file'), {
+    enabled: opts.enabled,
+    preventDefault: true,
+    description: 'New file',
+    scope: 'tree',
+  });
+
+  const refCut = useHotkey('mod+x', () => void run('cut'), {
+    enabled: opts.enabled,
+    preventDefault: true,
+    description: 'Cut',
+    scope: 'tree',
+  });
+
+  const refCopy = useHotkey('mod+c', () => void run('copy'), {
+    enabled: opts.enabled,
+    preventDefault: true,
+    description: 'Copy',
+    scope: 'tree',
+  });
+
+  const refPaste = useHotkey('mod+v', () => void run('paste'), {
+    enabled: opts.enabled,
+    preventDefault: true,
+    description: 'Paste',
+    scope: 'tree',
+  });
+
+  const ref = useCallback(
+    (instance: HTMLElement | null) => {
+      refDelete(instance);
+      refRename(instance);
+      refDuplicate(instance);
+      refNewFolder(instance);
+      refNewFile(instance);
+      refCut(instance);
+      refCopy(instance);
+      refPaste(instance);
+    },
+    [
+      refDelete,
+      refRename,
+      refDuplicate,
+      refNewFolder,
+      refNewFile,
+      refCut,
+      refCopy,
+      refPaste,
+    ],
+  );
+
+  return { ref };
+}

package/src/tools/data/Tree/hooks/index.ts

@@ -1,6 +1,25 @@
 'use client';
 
-export { useTreeTypeAhead } from './useTreeTypeAhead';
-export type { UseTreeTypeAheadOptions } from './useTreeTypeAhead';
-export { useTreeKeyboard } from './useTreeKeyboard';
-export type { UseTreeKeyboardOptions } from './useTreeKeyboard';
+// Public surface — re-exports from each feature folder.
+//
+// Each folder owns one "scope" of keyboard interaction:
+//   - keyboard/        arrow / home / end / enter / esc / mod+a
+//   - type-ahead/      printable-keys rolling buffer
+//   - finder-hotkeys/  Finder/Explorer shortcuts wired to adapter actions
+//
+// Adding a new scope = adding a new folder, not editing this barrel.
+
+export { useTreeKeyboard } from './keyboard';
+export type {
+  UseTreeKeyboardOptions,
+  UseTreeKeyboardReturn,
+} from './keyboard';
+
+export { useTreeTypeAhead } from './type-ahead';
+export type { UseTreeTypeAheadOptions } from './type-ahead';
+
+export { useTreeFinderHotkeys } from './finder-hotkeys';
+export type {
+  UseTreeFinderHotkeysOptions,
+  UseTreeFinderHotkeysReturn,
+} from './finder-hotkeys';