@djangocfg/ui-tools 2.1.415 → 2.1.417

package/src/tools/data/Tree/hooks/keyboard/activation.ts

@@ -0,0 +1,27 @@
+'use client';
+
+import type { FlatRow } from '../../types';
+
+/**
+ * Enter / Space on the current row:
+ *   - folder: toggle (collapse if expanded, else expand)
+ *   - leaf:   activate
+ *
+ * Always selects (single-select semantics for keyboard input).
+ */
+export type ActivateOutcome<T> =
+  | { kind: 'toggle-folder'; id: string; willExpand: boolean }
+  | { kind: 'activate-leaf'; id: string }
+  | { kind: 'noop' };
+
+export function resolveActivate<T>(current: FlatRow<T> | null): ActivateOutcome<T> {
+  if (!current) return { kind: 'noop' };
+  if (current.isFolder) {
+    return {
+      kind: 'toggle-folder',
+      id: current.node.id,
+      willExpand: !current.isExpanded,
+    };
+  }
+  return { kind: 'activate-leaf', id: current.node.id };
+}

package/src/tools/data/Tree/hooks/keyboard/arrow-nav.ts

@@ -0,0 +1,26 @@
+'use client';
+
+import type { FlatRow, TreeItemId } from '../../types';
+
+/** Pick the id one row below the current focused row (clamped at the end). */
+export function nextRowId<T>(rows: readonly FlatRow<T>[], idx: number): TreeItemId | null {
+  if (rows.length === 0) return null;
+  const next = rows[Math.min(idx + 1, rows.length - 1)] ?? rows[0];
+  return next.node.id;
+}
+
+/** Pick the id one row above the current focused row (clamped at the start). */
+export function prevRowId<T>(rows: readonly FlatRow<T>[], idx: number): TreeItemId | null {
+  if (rows.length === 0) return null;
+  const prev = rows[Math.max(idx - 1, 0)] ?? rows[0];
+  return prev.node.id;
+}
+
+/** First / last visible row id, or null if the list is empty. */
+export function edgeRowId<T>(
+  rows: readonly FlatRow<T>[],
+  edge: 'first' | 'last',
+): TreeItemId | null {
+  if (rows.length === 0) return null;
+  return edge === 'first' ? rows[0].node.id : rows[rows.length - 1].node.id;
+}

package/src/tools/data/Tree/hooks/keyboard/expand-collapse.ts

@@ -0,0 +1,54 @@
+'use client';
+
+import type { FlatRow } from '../../types';
+
+/**
+ * What should `→` do on the current row?
+ *
+ *   - collapsed folder → expand it
+ *   - expanded folder  → jump to first visible child
+ *   - leaf             → no-op
+ */
+export type RightArrowOutcome<T> =
+  | { kind: 'expand'; id: string }
+  | { kind: 'focus'; id: string }
+  | { kind: 'noop' };
+
+export function resolveRightArrow<T>(
+  current: FlatRow<T> | null,
+  rows: readonly FlatRow<T>[],
+  idx: number,
+): RightArrowOutcome<T> {
+  if (!current) return { kind: 'noop' };
+  if (current.isFolder && !current.isExpanded) {
+    return { kind: 'expand', id: current.node.id };
+  }
+  if (current.isFolder && current.isExpanded) {
+    const next = rows[idx + 1];
+    return next ? { kind: 'focus', id: next.node.id } : { kind: 'noop' };
+  }
+  return { kind: 'noop' };
+}
+
+/**
+ * What should `←` do on the current row?
+ *
+ *   - expanded folder           → collapse it
+ *   - leaf / collapsed w/ parent → focus parent
+ *   - root leaf                  → no-op
+ */
+export type LeftArrowOutcome<T> =
+  | { kind: 'collapse'; id: string }
+  | { kind: 'focus'; id: string }
+  | { kind: 'noop' };
+
+export function resolveLeftArrow<T>(current: FlatRow<T> | null): LeftArrowOutcome<T> {
+  if (!current) return { kind: 'noop' };
+  if (current.isFolder && current.isExpanded) {
+    return { kind: 'collapse', id: current.node.id };
+  }
+  if (current.parentId) {
+    return { kind: 'focus', id: current.parentId };
+  }
+  return { kind: 'noop' };
+}

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

@@ -0,0 +1,10 @@
+'use client';
+
+export { useTreeKeyboard } from './use-tree-keyboard';
+export type {
+  UseTreeKeyboardOptions,
+  UseTreeKeyboardReturn,
+} from './types';
+export { nextRowId, prevRowId, edgeRowId } from './arrow-nav';
+export { resolveLeftArrow, resolveRightArrow } from './expand-collapse';
+export { resolveActivate } from './activation';

package/src/tools/data/Tree/hooks/keyboard/types.ts

@@ -0,0 +1,39 @@
+'use client';
+
+import type { FlatRow, TreeItemId } from '../../types';
+
+export interface UseTreeKeyboardOptions<T> {
+  rows: FlatRow<T>[];
+  focusedId: TreeItemId | null;
+  enabled?: boolean;
+  /**
+   * `true` when `selectionMode === 'multiple'` — enables shift-extend on
+   * arrow keys, Home / End, and `Cmd/Ctrl+A` select-all. Without it the
+   * shift-modifier just moves focus.
+   */
+  multiSelect?: boolean;
+  /**
+   * Move focus to `id`. When `extend` is true and multi-select is enabled,
+   * the consumer should extend the selection range from anchor through id.
+   */
+  onFocus: (id: TreeItemId, opts: { extend: boolean }) => void;
+  onSelect: (id: TreeItemId) => void;
+  onActivate: (id: TreeItemId) => void;
+  onExpand: (id: TreeItemId) => void;
+  onCollapse: (id: TreeItemId) => void;
+  onClearSelection: () => void;
+  /** Cmd/Ctrl+A — select all visible rows. Ignored if multiSelect is false. */
+  onSelectAll?: () => void;
+}
+
+export interface UseTreeKeyboardReturn {
+  /** Attach to the tree container. Hotkeys only fire when focus is inside. */
+  ref: (instance: HTMLElement | null) => void;
+}
+
+/** Reduced state shape passed to action helpers — keeps them pure. */
+export interface CurrentRow<T> {
+  rows: FlatRow<T>[];
+  idx: number;
+  current: FlatRow<T> | null;
+}

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

@@ -0,0 +1,196 @@
+'use client';
+
+import { useCallback, useRef } from 'react';
+import { useHotkey } from '@djangocfg/ui-core/hooks';
+
+import { edgeRowId, nextRowId, prevRowId } from './arrow-nav';
+import { resolveLeftArrow, resolveRightArrow } from './expand-collapse';
+import { resolveActivate } from './activation';
+import type {
+  CurrentRow,
+  UseTreeKeyboardOptions,
+  UseTreeKeyboardReturn,
+} from './types';
+
+/**
+ * Standard tree keyboard navigation, scoped to the container ref.
+ *
+ *   - ↑ / ↓          : prev / next visible row (Shift extends range)
+ *   - Home / End     : first / last visible row (Shift extends range)
+ *   - → / ←          : expand-or-jump-to-child / collapse-or-jump-to-parent
+ *   - Enter / Space  : activate (folder → toggle, leaf → onActivate)
+ *   - Esc            : clear selection
+ *   - Cmd/Ctrl + A   : select all (multi-select only)
+ *
+ * Pure decision-making lives in the sibling helpers (`arrow-nav.ts`,
+ * `expand-collapse.ts`, `activation.ts`) so it's unit-testable without
+ * a DOM. This file only wires up `useHotkey` bindings and dispatches
+ * the helper outcomes back to the consumer's callbacks.
+ */
+export function useTreeKeyboard<T>({
+  rows,
+  focusedId,
+  enabled = true,
+  multiSelect = false,
+  onFocus,
+  onSelect,
+  onActivate,
+  onExpand,
+  onCollapse,
+  onClearSelection,
+  onSelectAll,
+}: UseTreeKeyboardOptions<T>): UseTreeKeyboardReturn {
+  // Keep latest values in refs so the callbacks below stay stable across
+  // renders — react-hotkeys-hook re-binds on dep change otherwise.
+  const rowsRef = useRef(rows);
+  const focusedIdRef = useRef(focusedId);
+  rowsRef.current = rows;
+  focusedIdRef.current = focusedId;
+
+  const getCurrent = (): CurrentRow<T> => {
+    const r = rowsRef.current;
+    const id = focusedIdRef.current;
+    const idx = id ? r.findIndex((x) => x.node.id === id) : -1;
+    return { rows: r, idx, current: idx >= 0 ? r[idx] : null };
+  };
+
+  // Down / Shift+Down. Plain moves focus, shift extends selection range.
+  const refDown = useHotkey(
+    ['down', 'shift+down'],
+    (e) => {
+      const { rows: r, idx } = getCurrent();
+      const id = nextRowId(r, idx);
+      if (id) onFocus(id, { extend: multiSelect && e.shiftKey });
+    },
+    { enabled, preventDefault: true, description: 'Next row (Shift extends)' },
+  );
+
+  const refUp = useHotkey(
+    ['up', 'shift+up'],
+    (e) => {
+      const { rows: r, idx } = getCurrent();
+      const id = prevRowId(r, idx);
+      if (id) onFocus(id, { extend: multiSelect && e.shiftKey });
+    },
+    { enabled, preventDefault: true, description: 'Previous row (Shift extends)' },
+  );
+
+  const refHome = useHotkey(
+    ['home', 'shift+home'],
+    (e) => {
+      const id = edgeRowId(rowsRef.current, 'first');
+      if (id) onFocus(id, { extend: multiSelect && e.shiftKey });
+    },
+    { enabled, preventDefault: true, description: 'First row (Shift extends)' },
+  );
+
+  const refEnd = useHotkey(
+    ['end', 'shift+end'],
+    (e) => {
+      const id = edgeRowId(rowsRef.current, 'last');
+      if (id) onFocus(id, { extend: multiSelect && e.shiftKey });
+    },
+    { enabled, preventDefault: true, description: 'Last row (Shift extends)' },
+  );
+
+  const refSelectAll = useHotkey(
+    'mod+a',
+    () => {
+      if (!multiSelect) return;
+      onSelectAll?.();
+    },
+    {
+      enabled: enabled && multiSelect,
+      preventDefault: true,
+      description: 'Select all visible rows',
+    },
+  );
+
+  const refRight = useHotkey(
+    'right',
+    () => {
+      const { rows: r, idx, current } = getCurrent();
+      const out = resolveRightArrow(current, r, idx);
+      switch (out.kind) {
+        case 'expand':
+          onExpand(out.id);
+          return;
+        case 'focus':
+          onFocus(out.id, { extend: false });
+          return;
+        case 'noop':
+          return;
+      }
+    },
+    { enabled, preventDefault: true, description: 'Expand / first child' },
+  );
+
+  const refLeft = useHotkey(
+    'left',
+    () => {
+      const { current } = getCurrent();
+      const out = resolveLeftArrow(current);
+      switch (out.kind) {
+        case 'collapse':
+          onCollapse(out.id);
+          return;
+        case 'focus':
+          onFocus(out.id, { extend: false });
+          return;
+        case 'noop':
+          return;
+      }
+    },
+    { enabled, preventDefault: true, description: 'Collapse / parent' },
+  );
+
+  const refActivate = useHotkey(
+    ['enter', 'space'],
+    () => {
+      const { current } = getCurrent();
+      const out = resolveActivate(current);
+      if (out.kind === 'noop') return;
+      onSelect(out.kind === 'activate-leaf' ? out.id : out.id);
+      if (out.kind === 'toggle-folder') {
+        if (out.willExpand) onExpand(out.id);
+        else onCollapse(out.id);
+      } else {
+        onActivate(out.id);
+      }
+    },
+    { enabled, preventDefault: true, description: 'Activate / toggle' },
+  );
+
+  const refEscape = useHotkey(
+    'escape',
+    () => onClearSelection(),
+    { enabled, preventDefault: true, description: 'Clear selection' },
+  );
+
+  const ref = useCallback(
+    (instance: HTMLElement | null) => {
+      refDown(instance);
+      refUp(instance);
+      refHome(instance);
+      refEnd(instance);
+      refRight(instance);
+      refLeft(instance);
+      refActivate(instance);
+      refEscape(instance);
+      refSelectAll(instance);
+    },
+    [
+      refDown,
+      refUp,
+      refHome,
+      refEnd,
+      refRight,
+      refLeft,
+      refActivate,
+      refEscape,
+      refSelectAll,
+    ],
+  );
+
+  return { ref };
+}

package/src/tools/data/Tree/hooks/type-ahead/index.ts

@@ -0,0 +1,5 @@
+'use client';
+
+export { useTreeTypeAhead } from './use-tree-type-ahead';
+export type { UseTreeTypeAheadOptions } from './use-tree-type-ahead';
+export { findRowByPrefix, isResetKey, isTypingTarget } from './match-prefix';

package/src/tools/data/Tree/hooks/type-ahead/match-prefix.ts

@@ -0,0 +1,42 @@
+'use client';
+
+import type { FlatRow, TreeNode } from '../../types';
+
+/** Find the first row whose name starts with `prefix` (case-insensitive). */
+export function findRowByPrefix<T>(
+  rows: readonly FlatRow<T>[],
+  getName: (node: TreeNode<T>) => string,
+  prefix: string,
+): FlatRow<T> | undefined {
+  if (prefix.length === 0) return undefined;
+  return rows.find((row) => getName(row.node).toLowerCase().startsWith(prefix));
+}
+
+/**
+ * Should this key terminate type-ahead instead of extending the buffer?
+ * Navigation, Enter, Tab, Escape — all reset; everything else continues.
+ */
+export function isResetKey(key: string): boolean {
+  return (
+    key === 'Escape' ||
+    key === 'Enter' ||
+    key === 'Tab' ||
+    key.startsWith('Arrow') ||
+    key === 'Home' ||
+    key === 'End' ||
+    key === 'PageUp' ||
+    key === 'PageDown'
+  );
+}
+
+/**
+ * Skip keystrokes that originate inside a text field so type-ahead
+ * doesn't yank focus while the user is filling in a form.
+ */
+export function isTypingTarget(target: EventTarget | null): boolean {
+  const el = target as HTMLElement | null;
+  if (!el) return false;
+  const tag = el.tagName;
+  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return true;
+  return el.isContentEditable === true;
+}

package/src/tools/data/Tree/hooks/{useTreeTypeAhead.ts → type-ahead/use-tree-type-ahead.ts}

@@ -2,7 +2,8 @@
 
 import { useEffect, useRef } from 'react';
 
-import type { FlatRow, TreeNode } from '../types';
+import type { FlatRow, TreeNode } from '../../types';
+import { findRowByPrefix, isResetKey, isTypingTarget } from './match-prefix';
 
 const FLUSH_MS = 600;
 
@@ -56,34 +57,22 @@ export function useTreeTypeAhead<T>({
     };
 
     const handler = (e: KeyboardEvent) => {
-      const tag = (e.target as HTMLElement | null)?.tagName;
-      if (tag === 'INPUT' || tag === 'TEXTAREA') return;
-      if ((e.target as HTMLElement | null)?.isContentEditable) return;
+      if (isTypingTarget(e.target)) return;
       if (e.metaKey || e.ctrlKey || e.altKey) return;
-
-      if (
-        e.key === 'Escape' ||
-        e.key === 'Enter' ||
-        e.key === 'Tab' ||
-        e.key.startsWith('Arrow') ||
-        e.key === 'Home' ||
-        e.key === 'End' ||
-        e.key === 'PageUp' ||
-        e.key === 'PageDown'
-      ) {
+      if (isResetKey(e.key)) {
         reset();
         return;
       }
-
       if (e.key.length !== 1) return;
 
       bufferRef.current += e.key.toLowerCase();
       if (timerRef.current) clearTimeout(timerRef.current);
       timerRef.current = setTimeout(reset, FLUSH_MS);
 
-      const prefix = bufferRef.current;
-      const hit = rowsRef.current.find((row) =>
-        getNameRef.current(row.node).toLowerCase().startsWith(prefix),
+      const hit = findRowByPrefix(
+        rowsRef.current,
+        getNameRef.current,
+        bufferRef.current,
       );
       if (hit) {
         e.preventDefault();

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

@@ -16,6 +16,7 @@
  */
 
 export { TreeRoot, TreeRoot as Tree, default as default } from './TreeRoot';
+export { FinderTree } from './FinderTree';
 
 export {
   TreeProvider,
@@ -26,12 +27,19 @@ export {
   useTreeExpansion,
   useTreeFocus,
   useTreeSearch,
+  useTreeRename,
+  useTreeClipboard,
+  useTreeDnd,
   useTreeActions,
 } from './context';
 export type { TreeProviderProps, TreeContextValue } from './context';
 
-export { useTreeTypeAhead, useTreeKeyboard } from './hooks';
-export type { UseTreeTypeAheadOptions, UseTreeKeyboardOptions } from './hooks';
+export { useTreeTypeAhead, useTreeKeyboard, useTreeFinderHotkeys } from './hooks';
+export type {
+  UseTreeTypeAheadOptions,
+  UseTreeKeyboardOptions,
+  UseTreeFinderHotkeysOptions,
+} from './hooks';
 
 export {
   TreeContent,
@@ -44,6 +52,9 @@ export {
   TreeSkeleton,
   TreeError,
   TreeIndentGuides,
+  TreeRenameInput,
+  TreeDropIndicator,
+  TreeEmptyArea,
 } from './components';
 export type {
   TreeContentProps,
@@ -56,6 +67,9 @@ export type {
   TreeSkeletonProps,
   TreeErrorProps,
   TreeIndentGuidesProps,
+  TreeRenameInputProps,
+  TreeDropIndicatorProps,
+  TreeEmptyAreaProps,
 } from './components';
 
 export {
@@ -69,6 +83,11 @@ export {
   DEFAULT_TREE_APPEARANCE,
   resolveAppearance,
   appearanceToStyle,
+  splitFileName,
+  autoSelectRange,
+  resolveDropZone,
+  defaultCanDrop,
+  TREE_DND_MIME,
 } from './data';
 export type {
   ChildCache,
@@ -86,6 +105,7 @@ export type {
 
 export { DEFAULT_TREE_LABELS } from './types';
 export type {
+  TreeActionsHandle,
   TreeRootProps,
   TreeNode,
   TreeItemId,
@@ -98,7 +118,11 @@ export type {
   TreeContextMenuSlot,
   TreeContextMenuAction,
   TreeContextMenuItem,
+  TreeContextMenuActionsContext,
   TreeContextMenuActionsResolver,
   TreeLoadChildren,
+  TreeAdapter,
+  TreeBuiltinAction,
+  TreeMovePosition,
   FlatRow,
 } from './types';

package/src/tools/data/Tree/types/activation.ts

@@ -0,0 +1,30 @@
+'use client';
+
+/**
+ * How a node becomes "activated" (i.e. opened) on pointer interaction.
+ *
+ *   - `'single-click'` (default): single click activates a leaf immediately;
+ *     double-click also activates. Folders always toggle on single click.
+ *   - `'double-click'`: single click only selects + focuses; double-click is
+ *     required to activate. Mirrors classic file-manager behaviour.
+ *   - `'single-click-preview'`: VSCode Explorer / Cursor behaviour. Single
+ *     click activates with `{ preview: true }` (consumer renders a preview
+ *     tab); double-click activates with `{ preview: false }` (pinned tab).
+ *
+ * Folders ignore this setting — they always toggle on single click and
+ * never call `onActivate`.
+ */
+export type TreeActivationMode =
+  | 'single-click'
+  | 'double-click'
+  | 'single-click-preview';
+
+export interface TreeActivateOptions {
+  /**
+   * `true` when the activation came from a single click in
+   * `'single-click-preview'` mode. `false` for double-click and for
+   * non-preview modes. Consumers typically map this to a
+   * preview-tab vs pinned-tab distinction.
+   */
+  preview: boolean;
+}

package/src/tools/data/Tree/types/adapter.ts

@@ -0,0 +1,70 @@
+'use client';
+
+import type { TreeNode } from './node';
+
+/**
+ * Position of a drop / move relative to the target row. `inside` means
+ * "drop into this folder"; `before`/`after` are sibling reorder hints.
+ */
+export type TreeMovePosition = 'before' | 'inside' | 'after';
+
+/**
+ * CRUD adapter. Every method is optional — Tree only surfaces built-in
+ * menu items / hotkeys whose adapter method is defined. So an
+ * inspection-only tree just passes `{}` (or no adapter) and gets no
+ * destructive menu actions.
+ *
+ * Dialogs (`alert` / `confirm` / `prompt`) are taken from `window.dialog`
+ * exposed by `<DialogProvider />` in `@djangocfg/ui-core`. The host app
+ * is expected to mount that provider once at the layout level — Tree
+ * never re-implements its own dialogs.
+ */
+export interface TreeAdapter<T = unknown> {
+  /** Delete the given nodes. Tree calls `window.dialog.confirm` first. */
+  remove?: (nodes: TreeNode<T>[]) => Promise<void>;
+  /** Inline rename — node + new name (already non-empty, post-validate). */
+  rename?: (node: TreeNode<T>, nextName: string) => Promise<void>;
+  /** Create a file under `parent` (null → root). Tree prompts for name. */
+  createFile?: (parent: TreeNode<T> | null, name: string) => Promise<void>;
+  /** Create a folder under `parent` (null → root). Tree prompts for name. */
+  createFolder?: (parent: TreeNode<T> | null, name: string) => Promise<void>;
+  /** Duplicate the given nodes in-place. */
+  duplicate?: (nodes: TreeNode<T>[]) => Promise<void>;
+  /** Move nodes (drag-and-drop, cut+paste). */
+  move?: (
+    nodes: TreeNode<T>[],
+    target: TreeNode<T> | null,
+    position: TreeMovePosition,
+  ) => Promise<void>;
+  /** Copy nodes (copy+paste, drop with modifier). */
+  copy?: (
+    nodes: TreeNode<T>[],
+    target: TreeNode<T> | null,
+    position: TreeMovePosition,
+  ) => Promise<void>;
+
+  /**
+   * Optional name validator. Return a non-empty string to surface as an
+   * error via `window.dialog.alert`. Return `null` to accept.
+   */
+  validateName?: (
+    name: string,
+    ctx: { node?: TreeNode<T>; parent?: TreeNode<T> | null },
+  ) => string | null;
+}
+
+/**
+ * Built-in action ids. Used by `defaultMenuItems` and the internal
+ * built-in action registry. Each id maps 1:1 to an adapter method
+ * (plus a few selection helpers).
+ */
+export type TreeBuiltinAction =
+  | 'open'
+  | 'rename'
+  | 'duplicate'
+  | 'cut'
+  | 'copy'
+  | 'paste'
+  | 'delete'
+  | 'new-file'
+  | 'new-folder';

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

@@ -0,0 +1,27 @@
+'use client';
+
+// Public surface — re-exports each types module. External code imports
+// from `'../types'` (or `'@djangocfg/ui-tools/tree'`) and never touches
+// these files directly.
+
+export type { TreeItemId, TreeNode, FlatRow } from './node';
+export type { TreeSelectionMode } from './selection';
+export type { TreeActivationMode, TreeActivateOptions } from './activation';
+export type { TreeLoadChildren } from './loader';
+export type { TreeLabels } from './labels';
+export { DEFAULT_TREE_LABELS } from './labels';
+export type {
+  TreeRowRenderProps,
+  TreeRowSlot,
+  TreeContextMenuSlot,
+  TreeContextMenuAction,
+  TreeContextMenuItem,
+  TreeContextMenuActionsContext,
+  TreeContextMenuActionsResolver,
+} from './slots';
+export type {
+  TreeMovePosition,
+  TreeAdapter,
+  TreeBuiltinAction,
+} from './adapter';
+export type { TreeRootProps, TreeActionsHandle } from './root-props';