@djangocfg/ui-tools 2.1.415 → 2.1.416

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

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