@djangocfg/ui-tools 2.1.415 → 2.1.416

package/src/tools/data/Tree/__tests__/keyboard.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from 'vitest';
+
+import { edgeRowId, nextRowId, prevRowId } from '../hooks/keyboard/arrow-nav';
+import { resolveActivate } from '../hooks/keyboard/activation';
+import {
+  resolveLeftArrow,
+  resolveRightArrow,
+} from '../hooks/keyboard/expand-collapse';
+import type { FlatRow } from '../types';
+
+function row(
+  id: string,
+  overrides: Partial<FlatRow<unknown>> = {},
+): FlatRow<unknown> {
+  return {
+    node: { id, data: undefined },
+    level: 0,
+    parentId: null,
+    isFolder: false,
+    isExpanded: false,
+    isLoading: false,
+    hasError: false,
+    posInSet: 1,
+    setSize: 1,
+    ...overrides,
+  };
+}
+
+const rows = ['a', 'b', 'c'].map((id) => row(id));
+
+// ----------------------------------------------------------------------
+// arrow-nav
+// ----------------------------------------------------------------------
+
+describe('nextRowId / prevRowId', () => {
+  it('moves one row forward / back', () => {
+    expect(nextRowId(rows, 0)).toBe('b');
+    expect(prevRowId(rows, 2)).toBe('b');
+  });
+
+  it('clamps at edges', () => {
+    expect(nextRowId(rows, 2)).toBe('c'); // last → last
+    expect(prevRowId(rows, 0)).toBe('a'); // first → first
+  });
+
+  it('returns null on empty list', () => {
+    expect(nextRowId([], 0)).toBeNull();
+    expect(prevRowId([], 0)).toBeNull();
+  });
+});
+
+describe('edgeRowId', () => {
+  it('picks first / last row', () => {
+    expect(edgeRowId(rows, 'first')).toBe('a');
+    expect(edgeRowId(rows, 'last')).toBe('c');
+  });
+
+  it('returns null on empty list', () => {
+    expect(edgeRowId([], 'first')).toBeNull();
+  });
+});
+
+// ----------------------------------------------------------------------
+// expand-collapse
+// ----------------------------------------------------------------------
+
+describe('resolveRightArrow', () => {
+  it('expands a collapsed folder', () => {
+    const f = row('f', { isFolder: true, isExpanded: false });
+    expect(resolveRightArrow(f, [f], 0)).toEqual({ kind: 'expand', id: 'f' });
+  });
+
+  it('jumps to first child on an expanded folder', () => {
+    const f = row('f', { isFolder: true, isExpanded: true });
+    const c = row('f/c', { parentId: 'f', level: 1 });
+    expect(resolveRightArrow(f, [f, c], 0)).toEqual({ kind: 'focus', id: 'f/c' });
+  });
+
+  it('no-op for an expanded folder with no children visible', () => {
+    const f = row('f', { isFolder: true, isExpanded: true });
+    expect(resolveRightArrow(f, [f], 0)).toEqual({ kind: 'noop' });
+  });
+
+  it('no-op for a leaf', () => {
+    expect(resolveRightArrow(row('a'), rows, 0)).toEqual({ kind: 'noop' });
+  });
+
+  it('no-op when current is null', () => {
+    expect(resolveRightArrow(null, rows, 0)).toEqual({ kind: 'noop' });
+  });
+});
+
+describe('resolveLeftArrow', () => {
+  it('collapses an expanded folder', () => {
+    const f = row('f', { isFolder: true, isExpanded: true });
+    expect(resolveLeftArrow(f)).toEqual({ kind: 'collapse', id: 'f' });
+  });
+
+  it('focuses parent for a leaf with a parent', () => {
+    const c = row('f/c', { parentId: 'f' });
+    expect(resolveLeftArrow(c)).toEqual({ kind: 'focus', id: 'f' });
+  });
+
+  it('no-op for a root leaf', () => {
+    expect(resolveLeftArrow(row('root'))).toEqual({ kind: 'noop' });
+  });
+});
+
+// ----------------------------------------------------------------------
+// activation
+// ----------------------------------------------------------------------
+
+describe('resolveActivate', () => {
+  it('toggles a folder — flags `willExpand` from current state', () => {
+    const collapsed = row('f', { isFolder: true, isExpanded: false });
+    expect(resolveActivate(collapsed)).toEqual({
+      kind: 'toggle-folder',
+      id: 'f',
+      willExpand: true,
+    });
+
+    const expanded = row('f', { isFolder: true, isExpanded: true });
+    expect(resolveActivate(expanded)).toEqual({
+      kind: 'toggle-folder',
+      id: 'f',
+      willExpand: false,
+    });
+  });
+
+  it('activates a leaf', () => {
+    expect(resolveActivate(row('a'))).toEqual({ kind: 'activate-leaf', id: 'a' });
+  });
+
+  it('no-op for null', () => {
+    expect(resolveActivate(null)).toEqual({ kind: 'noop' });
+  });
+});

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

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+
+import { autoSelectRange, splitFileName } from '../data/renameUtils';
+
+describe('splitFileName', () => {
+  it('splits a regular file name into base + ext', () => {
+    expect(splitFileName('foo.txt')).toEqual({ base: 'foo', ext: '.txt' });
+  });
+
+  it('returns whole name as base when there is no dot', () => {
+    expect(splitFileName('readme')).toEqual({ base: 'readme', ext: '' });
+  });
+
+  it('treats dotfiles as base-only', () => {
+    expect(splitFileName('.env')).toEqual({ base: '.env', ext: '' });
+    expect(splitFileName('.gitignore')).toEqual({ base: '.gitignore', ext: '' });
+  });
+
+  it('splits a dotfile with an extension', () => {
+    expect(splitFileName('.env.local')).toEqual({ base: '.env', ext: '.local' });
+  });
+
+  it('uses the last dot for multi-dot names', () => {
+    expect(splitFileName('foo.bar.baz')).toEqual({ base: 'foo.bar', ext: '.baz' });
+  });
+
+  it('handles the empty string', () => {
+    expect(splitFileName('')).toEqual({ base: '', ext: '' });
+  });
+});
+
+describe('autoSelectRange', () => {
+  it('selects only the base for a regular file', () => {
+    expect(autoSelectRange('foo.txt', false)).toEqual([0, 3]);
+  });
+
+  it('selects the entire name for a folder', () => {
+    expect(autoSelectRange('foo.txt', true)).toEqual([0, 7]);
+  });
+
+  it('selects the full dotfile name (no extension)', () => {
+    expect(autoSelectRange('.env', false)).toEqual([0, 4]);
+  });
+
+  it('selects only base for a dotfile with extension', () => {
+    expect(autoSelectRange('.env.local', false)).toEqual([0, 4]);
+  });
+
+  it('selects [0, 0] for empty name', () => {
+    expect(autoSelectRange('', false)).toEqual([0, 0]);
+  });
+});

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

@@ -0,0 +1,227 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  computeRange,
+  selectionFromClick,
+  selectionFromMove,
+  selectionSelectAll,
+  selectionClear,
+  type SelectionState,
+} from '../data/selection';
+import type { FlatRow } from '../types';
+
+// =====================================================================
+// Test fixtures
+// =====================================================================
+
+function row(id: string): FlatRow<unknown> {
+  return {
+    node: { id, data: undefined },
+    level: 0,
+    parentId: null,
+    isFolder: false,
+    isExpanded: false,
+    isLoading: false,
+    hasError: false,
+    posInSet: 1,
+    setSize: 1,
+  };
+}
+
+const rows = ['a', 'b', 'c', 'd', 'e'].map(row);
+
+const emptyState: SelectionState = {
+  selected: new Set(),
+  anchor: null,
+  focused: null,
+};
+
+// =====================================================================
+// computeRange
+// =====================================================================
+
+describe('computeRange', () => {
+  it('returns ids between anchor and target (inclusive)', () => {
+    expect(computeRange(rows, 'b', 'd')).toEqual(['b', 'c', 'd']);
+  });
+
+  it('works when target is before anchor', () => {
+    expect(computeRange(rows, 'd', 'b')).toEqual(['b', 'c', 'd']);
+  });
+
+  it('returns a single id when from === to', () => {
+    expect(computeRange(rows, 'c', 'c')).toEqual(['c']);
+  });
+
+  it('returns empty array when endpoint is missing', () => {
+    expect(computeRange(rows, 'b', 'missing')).toEqual([]);
+    expect(computeRange(rows, 'missing', 'b')).toEqual([]);
+  });
+
+  it('returns empty array when from or to is null', () => {
+    expect(computeRange(rows, null, 'b')).toEqual([]);
+    expect(computeRange(rows, 'b', null)).toEqual([]);
+  });
+});
+
+// =====================================================================
+// selectionFromClick
+// =====================================================================
+
+describe('selectionFromClick (single-select mode)', () => {
+  it('collapses any modifier combo to one id when multi is false', () => {
+    const next = selectionFromClick(
+      { selected: new Set(['a', 'b']), anchor: 'a', focused: 'b' },
+      rows,
+      'c',
+      { shift: true, meta: true },
+      false,
+    );
+    expect([...next.selected]).toEqual(['c']);
+    expect(next.anchor).toBe('c');
+    expect(next.focused).toBe('c');
+  });
+});
+
+describe('selectionFromClick (multi-select mode)', () => {
+  it('plain click replaces selection and resets anchor', () => {
+    const next = selectionFromClick(
+      { selected: new Set(['a', 'b']), anchor: 'a', focused: 'b' },
+      rows,
+      'd',
+      { shift: false, meta: false },
+      true,
+    );
+    expect([...next.selected]).toEqual(['d']);
+    expect(next.anchor).toBe('d');
+    expect(next.focused).toBe('d');
+  });
+
+  it('meta-click toggles a single id and updates anchor', () => {
+    const next = selectionFromClick(
+      { selected: new Set(['a', 'b']), anchor: 'a', focused: 'b' },
+      rows,
+      'c',
+      { shift: false, meta: true },
+      true,
+    );
+    expect([...next.selected].sort()).toEqual(['a', 'b', 'c']);
+    expect(next.anchor).toBe('c');
+  });
+
+  it('meta-click removes an already-selected id', () => {
+    const next = selectionFromClick(
+      { selected: new Set(['a', 'b']), anchor: 'a', focused: 'b' },
+      rows,
+      'b',
+      { shift: false, meta: true },
+      true,
+    );
+    expect([...next.selected]).toEqual(['a']);
+    expect(next.anchor).toBe('b');
+  });
+
+  it('shift-click selects range from anchor to clicked row', () => {
+    const next = selectionFromClick(
+      { selected: new Set(['b']), anchor: 'b', focused: 'b' },
+      rows,
+      'd',
+      { shift: true, meta: false },
+      true,
+    );
+    expect([...next.selected]).toEqual(['b', 'c', 'd']);
+    expect(next.anchor).toBe('b'); // anchor stays put
+    expect(next.focused).toBe('d');
+  });
+
+  it('shift-click without anchor falls back to focused', () => {
+    const next = selectionFromClick(
+      { selected: new Set(['c']), anchor: null, focused: 'c' },
+      rows,
+      'e',
+      { shift: true, meta: false },
+      true,
+    );
+    expect([...next.selected]).toEqual(['c', 'd', 'e']);
+  });
+
+  it('shift+meta unions the range with existing selection', () => {
+    const next = selectionFromClick(
+      { selected: new Set(['a']), anchor: 'b', focused: 'b' },
+      rows,
+      'd',
+      { shift: true, meta: true },
+      true,
+    );
+    expect([...next.selected].sort()).toEqual(['a', 'b', 'c', 'd']);
+    expect(next.anchor).toBe('b');
+  });
+});
+
+// =====================================================================
+// selectionFromMove
+// =====================================================================
+
+describe('selectionFromMove', () => {
+  it('non-extend move collapses to single id', () => {
+    const next = selectionFromMove(
+      { selected: new Set(['a', 'b']), anchor: 'a', focused: 'b' },
+      rows,
+      'c',
+      false,
+      true,
+    );
+    expect([...next.selected]).toEqual(['c']);
+    expect(next.anchor).toBe('c');
+  });
+
+  it('extend move with anchor recomputes range', () => {
+    const next = selectionFromMove(
+      { selected: new Set(['b']), anchor: 'b', focused: 'b' },
+      rows,
+      'd',
+      true,
+      true,
+    );
+    expect([...next.selected]).toEqual(['b', 'c', 'd']);
+    expect(next.anchor).toBe('b');
+    expect(next.focused).toBe('d');
+  });
+
+  it('extend without multi-select treats it as a plain move', () => {
+    const next = selectionFromMove(emptyState, rows, 'c', true, false);
+    expect([...next.selected]).toEqual(['c']);
+  });
+});
+
+// =====================================================================
+// selectionSelectAll + selectionClear
+// =====================================================================
+
+describe('selectionSelectAll', () => {
+  it('selects every visible id and anchors the first row', () => {
+    const next = selectionSelectAll(rows, 'c');
+    expect([...next.selected]).toEqual(['a', 'b', 'c', 'd', 'e']);
+    expect(next.anchor).toBe('a');
+    expect(next.focused).toBe('c');
+  });
+
+  it('returns empty state for an empty row list', () => {
+    const next = selectionSelectAll([], null);
+    expect(next.selected.size).toBe(0);
+    expect(next.anchor).toBeNull();
+  });
+});
+
+describe('selectionClear', () => {
+  it('drops selection and anchor but keeps focused', () => {
+    const next = selectionClear({
+      selected: new Set(['a', 'b']),
+      anchor: 'a',
+      focused: 'b',
+    });
+    expect(next.selected.size).toBe(0);
+    expect(next.anchor).toBeNull();
+    expect(next.focused).toBe('b');
+  });
+});

package/src/tools/data/Tree/components/TreeDropIndicator.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { TreeMovePosition } from '../types';
+
+export interface TreeDropIndicatorProps {
+  position: TreeMovePosition;
+  /** Indent in pixels — keeps the line aligned with the row's text. */
+  indent: number;
+  /** Render a "rejected" style (red wash) when the drop is forbidden. */
+  invalid?: boolean;
+}
+
+/**
+ * Visual hint for an in-progress drag-and-drop. Three modes:
+ *
+ *   - `before` / `after`  → a 2px horizontal line above / below the row
+ *   - `inside`            → a translucent primary wash filling the row
+ *
+ * Indents the line by the row's depth so it visually aligns with the
+ * target's content (rather than running edge-to-edge).
+ *
+ * Positioned absolutely — the parent `TreeRow` provides `position: relative`.
+ */
+export function TreeDropIndicator({
+  position,
+  indent,
+  invalid = false,
+}: TreeDropIndicatorProps) {
+  if (position === 'inside') {
+    return (
+      <span
+        aria-hidden
+        data-tree-drop="inside"
+        className={cn(
+          'pointer-events-none absolute inset-0 rounded-sm ring-1',
+          invalid
+            ? 'bg-destructive/10 ring-destructive/40'
+            : 'bg-primary/10 ring-primary/40',
+        )}
+      />
+    );
+  }
+
+  const isBefore = position === 'before';
+  return (
+    <span
+      aria-hidden
+      data-tree-drop={position}
+      style={{ paddingLeft: indent }}
+      className={cn(
+        'pointer-events-none absolute right-0 left-0 h-px',
+        isBefore ? 'top-0' : 'bottom-0',
+      )}
+    >
+      <span
+        className={cn(
+          'block h-0.5 rounded-full',
+          invalid ? 'bg-destructive/70' : 'bg-primary',
+        )}
+      />
+    </span>
+  );
+}

package/src/tools/data/Tree/components/TreeEmptyArea.tsx

@@ -0,0 +1,160 @@
+'use client';
+
+import { useMemo } from 'react';
+import { useDroppable } from '@dnd-kit/core';
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+  ContextMenuTrigger,
+} from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useTreeContext } from '../context/TreeContext';
+import {
+  buildDefaultMenuItems,
+  type BuiltinActionContext,
+} from '../context/menu';
+import { TREE_ROOT_DROP_ID } from '../data/dnd';
+import type { TreeContextMenuItem } from '../types';
+
+export interface TreeEmptyAreaProps {
+  className?: string;
+}
+
+/**
+ * Fills the remaining vertical space below `<TreeContent>` so the user
+ * can right-click "into nothing" to get a Finder/Explorer-style empty
+ * area menu (paste / new file / new folder at root), and so DnD has a
+ * root drop target.
+ *
+ * Built-in actions are derived the same way as for rows — through
+ * `buildDefaultMenuItems`, with `targetNode = null` (root) and
+ * `selectedNodes = []` (nothing under the right-click). Items whose
+ * `available()` predicate fails are simply skipped, so a tree without
+ * `adapter.createFile/Folder` and without a clipboard payload shows
+ * no menu at all.
+ */
+export function TreeEmptyArea({ className }: TreeEmptyAreaProps) {
+  const ctx = useTreeContext();
+  const {
+    adapter,
+    labels,
+    getItemName,
+    clipboard,
+    cutToClipboard,
+    copyToClipboard,
+    pasteFromClipboard,
+    startRename,
+    inlineRenameEnabled,
+    dnd,
+  } = ctx;
+
+  // Root drop target — receives drops that miss every row. The shared
+  // `TreeDndProvider.onDragMove` detects when `e.over.id === ROOT_DROP_ID`
+  // and pushes `{ id: null, position: 'inside' }` into `dnd.dropTarget`,
+  // so this component doesn't need an `onPointerMove` of its own.
+  const { setNodeRef: setDroppableRef, isOver } = useDroppable({
+    id: TREE_ROOT_DROP_ID,
+    disabled: !dnd.active,
+  });
+
+  // Resolve menu items every render — they depend on clipboard state
+  // (paste shows/hides) and on whether the adapter exposes
+  // createFile / createFolder.
+  const items = useMemo<TreeContextMenuItem<unknown>[] | null>(() => {
+    if (!adapter) return null;
+    const builtinCtx: BuiltinActionContext<unknown> = {
+      adapter,
+      labels,
+      selectedNodes: [],
+      targetNode: null,
+      getName: getItemName,
+      startInlineRename: inlineRenameEnabled ? startRename : undefined,
+      clipboard: {
+        hasItems: !!clipboard && clipboard.ids.length > 0,
+        cut: cutToClipboard,
+        copy: copyToClipboard,
+        paste: () => pasteFromClipboard(null, 'inside'),
+      },
+    };
+    return buildDefaultMenuItems(builtinCtx);
+  }, [
+    adapter,
+    labels,
+    getItemName,
+    inlineRenameEnabled,
+    startRename,
+    clipboard,
+    cutToClipboard,
+    copyToClipboard,
+    pasteFromClipboard,
+  ]);
+
+  const surface = (
+    <div
+      ref={dnd.active ? setDroppableRef : undefined}
+      data-tree-empty-area=""
+      data-drop-active={dnd.active && isOver ? 'true' : undefined}
+      className={cn(
+        // Soaks up the remaining vertical space inside the scroll
+        // container so right-click on whitespace lands here, not on
+        // the scroll viewport.
+        'min-h-[2.5rem] flex-1',
+        dnd.active && isOver && 'bg-primary/5 rounded-sm ring-1 ring-primary/30',
+        className,
+      )}
+    />
+  );
+
+  // No items and no DnD overlap → render plain spacer. Wrapping in a
+  // `<ContextMenu>` with zero items would still capture right-clicks
+  // and show an empty popover — that's worse than browser default.
+  if (!items || items.length === 0) {
+    return surface;
+  }
+
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger asChild>{surface}</ContextMenuTrigger>
+      <ContextMenuContent>
+        {items.map((item, idx) => {
+          if (item === 'separator') {
+            return <ContextMenuSeparator key={`sep-${idx}`} />;
+          }
+          const Icon = item.icon;
+          return (
+            <ContextMenuItem
+              key={item.id}
+              disabled={item.disabled}
+              variant={item.destructive ? 'destructive' : undefined}
+              // Pass a synthetic "no-target" row props — the built-in
+              // action handlers we surface here (new-file / new-folder
+              // / paste) don't read row-specific fields anyway.
+              onSelect={() =>
+                item.onSelect({
+                  node: undefined as never,
+                  level: 0,
+                  isSelected: false,
+                  isExpanded: false,
+                  isFocused: false,
+                  isFolder: false,
+                  isLoading: false,
+                  isMatchingSearch: false,
+                })
+              }
+            >
+              {Icon ? <Icon /> : null}
+              {item.label}
+              {item.shortcut ? (
+                <ContextMenuShortcut>{item.shortcut}</ContextMenuShortcut>
+              ) : null}
+            </ContextMenuItem>
+          );
+        })}
+      </ContextMenuContent>
+    </ContextMenu>
+  );
+}