@djangocfg/ui-tools 2.1.413 → 2.1.416

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,
@@ -98,7 +117,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 } from './root-props';

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

@@ -0,0 +1,97 @@
+'use client';
+
+export interface TreeLabels {
+  loading: string;
+  empty: string;
+  error: string;
+  searchPlaceholder: string;
+  searchMatches: (count: number) => string;
+  ariaLabel: string;
+
+  // ---- CRUD flow copy (used by built-in adapter actions + dialogs) ----
+
+  /** Default context-menu item labels. */
+  actionOpen: string;
+  actionRename: string;
+  actionDuplicate: string;
+  actionCut: string;
+  actionCopy: string;
+  actionPaste: string;
+  actionDelete: string;
+  actionNewFile: string;
+  actionNewFolder: string;
+
+  /** Delete confirmation dialog. */
+  confirmDeleteTitle: (count: number) => string;
+  confirmDeleteMessage: (names: string[]) => string;
+  confirmDeleteOk: string;
+  confirmDeleteCancel: string;
+
+  /** New file prompt. */
+  newFileTitle: string;
+  newFileMessage: string;
+  newFilePlaceholder: string;
+  newFileDefault: string;
+
+  /** New folder prompt. */
+  newFolderTitle: string;
+  newFolderMessage: string;
+  newFolderPlaceholder: string;
+  newFolderDefault: string;
+
+  /** Rename prompt (used when inline rename is unavailable / disabled). */
+  renameTitle: string;
+  renameMessage: string;
+
+  /** Name validation. */
+  invalidNameEmpty: string;
+
+  /** Suffix used by the default `duplicate` flow when the consumer's adapter
+   *  needs a hint name. Receives the source name. */
+  duplicateSuffix: (name: string) => string;
+}
+
+export const DEFAULT_TREE_LABELS: TreeLabels = {
+  loading: 'Loading…',
+  empty: 'Nothing to show',
+  error: 'Failed to load',
+  searchPlaceholder: 'Search…',
+  searchMatches: (n) => `${n} match${n === 1 ? '' : 'es'}`,
+  ariaLabel: 'Tree',
+
+  actionOpen: 'Open',
+  actionRename: 'Rename',
+  actionDuplicate: 'Duplicate',
+  actionCut: 'Cut',
+  actionCopy: 'Copy',
+  actionPaste: 'Paste',
+  actionDelete: 'Delete',
+  actionNewFile: 'New file',
+  actionNewFolder: 'New folder',
+
+  confirmDeleteTitle: (n) =>
+    n === 1 ? 'Delete item?' : `Delete ${n} items?`,
+  confirmDeleteMessage: (names) =>
+    names.length === 1
+      ? `"${names[0]}" will be removed. This action cannot be undone.`
+      : `${names.length} items will be removed. This action cannot be undone.`,
+  confirmDeleteOk: 'Delete',
+  confirmDeleteCancel: 'Cancel',
+
+  newFileTitle: 'New file',
+  newFileMessage: 'File name',
+  newFilePlaceholder: 'untitled.txt',
+  newFileDefault: 'untitled.txt',
+
+  newFolderTitle: 'New folder',
+  newFolderMessage: 'Folder name',
+  newFolderPlaceholder: 'untitled folder',
+  newFolderDefault: 'untitled folder',
+
+  renameTitle: 'Rename',
+  renameMessage: 'New name',
+
+  invalidNameEmpty: 'Name cannot be empty',
+
+  duplicateSuffix: (name) => `${name} copy`,
+};

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

@@ -0,0 +1,9 @@
+'use client';
+
+import type { TreeNode } from './node';
+
+/**
+ * Async loader: called the first time a folder is expanded with no inline
+ * `children`. Result is cached; concurrent expansions are de-duplicated.
+ */
+export type TreeLoadChildren<T> = (node: TreeNode<T>) => Promise<TreeNode<T>[]>;

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

@@ -0,0 +1,38 @@
+'use client';
+
+export type TreeItemId = string;
+
+/** A single node in the consumer's tree data. Generic over your payload. */
+export interface TreeNode<T = unknown> {
+  id: TreeItemId;
+  data: T;
+  /** Inline children. Omit (and provide a `loadChildren`) for async loading. */
+  children?: TreeNode<T>[];
+  /**
+   * Set to `true` to mark a node as a folder even when its `children` array
+   * is empty (e.g. an unloaded async folder). Default: derived from
+   * `Array.isArray(children)`.
+   */
+  isFolder?: boolean;
+  /** Disable interaction. */
+  disabled?: boolean;
+}
+
+/**
+ * Internal flat-row representation used by the renderer + keyboard nav.
+ * Produced by `flattenTree`; consumed by `TreeRow`, the keyboard hook,
+ * and the type-ahead hook.
+ */
+export interface FlatRow<T> {
+  node: TreeNode<T>;
+  level: number;
+  parentId: TreeItemId | null;
+  isFolder: boolean;
+  isExpanded: boolean;
+  isLoading: boolean;
+  hasError: boolean;
+  /** 1-based position among visible siblings (for `aria-posinset`). */
+  posInSet: number;
+  /** Count of visible siblings sharing this row's parent (for `aria-setsize`). */
+  setSize: number;
+}