@djangocfg/widget-data 0.1.1

package/src/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) ?? 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/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/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/Tree/hooks/type-ahead/use-tree-type-ahead.ts

@@ -0,0 +1,89 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+import type { FlatRow, TreeNode } from '../../types';
+import { findRowByPrefix, isResetKey, isTypingTarget } from './match-prefix';
+
+const FLUSH_MS = 600;
+
+export interface UseTreeTypeAheadOptions<T> {
+  /** Visible flat rows in render order. */
+  rows: FlatRow<T>[];
+  /** How to read the displayed name of a node (matched case-insensitively). */
+  getItemName: (node: TreeNode<T>) => string;
+  /** Element receiving keydown events. */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Called with the matched node id so the consumer can focus / scroll. */
+  onMatch: (id: string) => void;
+  /** Disable without removing the call site. */
+  enabled?: boolean;
+}
+
+/**
+ * Type-ahead jump (Finder / VSCode style).
+ *
+ * Builds a rolling buffer of printable keys (within ~600 ms of each other)
+ * and notifies the consumer of the first row whose name starts with that
+ * prefix. Resets on Esc / Enter / navigation keys / timeout.
+ */
+export function useTreeTypeAhead<T>({
+  rows,
+  getItemName,
+  containerRef,
+  onMatch,
+  enabled = true,
+}: UseTreeTypeAheadOptions<T>) {
+  const bufferRef = useRef('');
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const rowsRef = useRef(rows);
+  const getNameRef = useRef(getItemName);
+  const onMatchRef = useRef(onMatch);
+  rowsRef.current = rows;
+  getNameRef.current = getItemName;
+  onMatchRef.current = onMatch;
+
+  useEffect(() => {
+    if (!enabled) return;
+    const target = containerRef.current;
+    if (!target) return;
+
+    const reset = () => {
+      bufferRef.current = '';
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+
+    const handler = (e: KeyboardEvent) => {
+      if (isTypingTarget(e.target)) return;
+      if (e.metaKey || e.ctrlKey || e.altKey) return;
+      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 hit = findRowByPrefix(
+        rowsRef.current,
+        getNameRef.current,
+        bufferRef.current,
+      );
+      if (hit) {
+        e.preventDefault();
+        onMatchRef.current(hit.node.id);
+      }
+    };
+
+    target.addEventListener('keydown', handler);
+    return () => {
+      target.removeEventListener('keydown', handler);
+      reset();
+    };
+  }, [containerRef, enabled]);
+}

package/src/Tree/index.tsx

@@ -0,0 +1,135 @@
+'use client';
+
+/**
+ * Decomposed shadcn-style tree component.
+ *
+ * Two usage patterns:
+ *
+ *   1) High-level (most cases):
+ *      <TreeRoot data={...} getItemName={...} onSelectionChange={...} />
+ *
+ *   2) Composition (full control):
+ *      <TreeProvider data={...} getItemName={...}>
+ *        <TreeSearchInput />
+ *        <TreeContent />
+ *      </TreeProvider>
+ */
+
+export { TreeRoot, TreeRoot as Tree, default as default } from './TreeRoot';
+export { FinderTree } from './FinderTree';
+
+export {
+  TreeProvider,
+  useTreeContext,
+  useTreeLabels,
+  useTreeRows,
+  useTreeSelection,
+  useTreeExpansion,
+  useTreeFocus,
+  useTreeSearch,
+  useTreeRename,
+  useTreeClipboard,
+  useTreeDnd,
+  useTreeActions,
+} from './context';
+export type { TreeProviderProps, TreeContextValue } from './context';
+
+export { useTreeTypeAhead, useTreeKeyboard, useTreeFinderHotkeys } from './hooks';
+export type {
+  UseTreeTypeAheadOptions,
+  UseTreeKeyboardOptions,
+  UseTreeFinderHotkeysOptions,
+} from './hooks';
+
+export {
+  TreeContent,
+  TreeRow,
+  TreeChevron,
+  TreeIcon,
+  TreeLabel,
+  TreeSearchInput,
+  TreeEmpty,
+  TreeSkeleton,
+  TreeError,
+  TreeIndentGuides,
+  TreeRenameInput,
+  TreeDropIndicator,
+  TreeEmptyArea,
+} from './components';
+export type {
+  TreeContentProps,
+  TreeRowProps,
+  TreeChevronProps,
+  TreeIconProps,
+  TreeLabelProps,
+  TreeSearchInputProps,
+  TreeEmptyProps,
+  TreeSkeletonProps,
+  TreeErrorProps,
+  TreeIndentGuidesProps,
+  TreeRenameInputProps,
+  TreeDropIndicatorProps,
+  TreeEmptyAreaProps,
+} from './components';
+
+export {
+  createChildCache,
+  resolveChildren,
+  flattenTree,
+  loadTreeState,
+  saveTreeState,
+  clearTreeState,
+  createDemoTree,
+  DEFAULT_TREE_APPEARANCE,
+  resolveAppearance,
+  appearanceToStyle,
+  splitFileName,
+  autoSelectRange,
+  resolveDropZone,
+  defaultCanDrop,
+  TREE_DND_MIME,
+} from './data';
+export type {
+  ChildCache,
+  ChildEntry,
+  ChildEntryStatus,
+  FlattenInput,
+  PersistedTreeState,
+  DemoNode,
+  TreeAppearance,
+  ResolvedAppearance,
+  TreeDensity,
+  TreeAccentIntensity,
+  TreeRadius,
+  TreeVariant,
+  TreeRowSizing,
+} from './data';
+
+export { DEFAULT_TREE_LABELS } from './types';
+export type {
+  TreeActionsHandle,
+  TreeRootProps,
+  TreeNode,
+  TreeItemId,
+  TreeLabels,
+  TreeSelectionMode,
+  TreeActivationMode,
+  TreeActivateOptions,
+  TreeRowRenderProps,
+  TreeRowSlot,
+  TreeContextMenuSlot,
+  TreeContextMenuAction,
+  TreeContextMenuItem,
+  TreeContextMenuActionsContext,
+  TreeContextMenuActionsResolver,
+  TreeLoadChildren,
+  TreeAdapter,
+  TreeBuiltinAction,
+  TreeMovePosition,
+  FlatRow,
+} from './types';
+
+// The dynamic-import wrapper. Exported here because the subpath resolves to
+// this barrel: in the retired ui-tools `lazy.tsx` was reachable from no declared export,
+// so `LazyTree` was dead code for every tool but `JsonTree`.
+export { LazyTree } from './lazy';

package/src/Tree/lazy.tsx

@@ -0,0 +1,14 @@
+'use client';
+
+import { createLazyComponent, LoadingFallback } from '@djangocfg/widget-kit/lazy';
+import type { TreeRootProps } from './types';
+
+export const LazyTree = createLazyComponent<TreeRootProps<unknown>>(
+  () => import('./TreeRoot'),
+  {
+    displayName: 'LazyTree',
+    fallback: <LoadingFallback minHeight={200} text="Loading tree…" />,
+  },
+);
+
+export type { TreeRootProps };

package/src/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/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/Tree/types/index.ts

@@ -0,0 +1,27 @@
+'use client';
+
+// Public surface — re-exports each types module. External code imports
+// from `'../types'` (or `'@djangocfg/widget-data/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';