@djangocfg/widget-data 0.1.1

package/src/Tree/TreeDndProvider.tsx

@@ -0,0 +1,137 @@
+'use client';
+
+import {
+  DndContext,
+  KeyboardSensor,
+  PointerSensor,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+  type DragMoveEvent,
+  type DragStartEvent,
+} from '@dnd-kit/core';
+import { useCallback, useRef } from 'react';
+
+import { useTreeContext } from './context/TreeContext';
+import { resolveDropZone, TREE_ROOT_DROP_ID } from './data/dnd';
+import type { TreeItemId } from './types';
+
+interface TreeDndProviderProps {
+  children: React.ReactNode;
+}
+
+/**
+ * Wrap Tree's body in a `<DndContext>` when DnD is enabled.
+ *
+ * One central drag handler decides the drop zone (`before` / `inside` /
+ * `after`) from the cursor position vs. the hovered row's bounding box.
+ * Rows themselves only register `useDraggable` + `useDroppable` — no
+ * per-row `onPointerMove`, so dragging across 1000 rows stays cheap.
+ *
+ * Sensors: pointer (with a small activation distance so a plain click
+ * doesn't initiate a drag) + keyboard (drag with Space/Enter, arrows,
+ * Space drops — built-in accessibility).
+ */
+export function TreeDndProvider({ children }: TreeDndProviderProps) {
+  const ctx = useTreeContext();
+  const { dnd } = ctx;
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 4 } }),
+    useSensor(KeyboardSensor),
+  );
+
+  // Latest cursor position — @dnd-kit gives us the active rectangle but
+  // not the raw pointer Y. We grab it from pointermove ourselves and
+  // use it inside `onDragMove` to compute the drop zone.
+  const cursorYRef = useRef(0);
+
+  const handleDragStart = useCallback(
+    (e: DragStartEvent) => {
+      dnd.beginDrag(e.active.id as TreeItemId);
+    },
+    [dnd],
+  );
+
+  const handleDragMove = useCallback(
+    (e: DragMoveEvent) => {
+      const overId = e.over?.id;
+      // Root drop target — TreeEmptyArea registers under this id.
+      if (overId === TREE_ROOT_DROP_ID) {
+        const current = dnd.dropTarget;
+        if (current?.id !== null || current?.position !== 'inside') {
+          dnd.setDropTarget({ id: null, position: 'inside' });
+        }
+        return;
+      }
+      if (typeof overId !== 'string') {
+        if (dnd.dropTarget !== null) dnd.setDropTarget(null);
+        return;
+      }
+
+      // The dnd-kit `over.rect` is the droppable's bounding box. Combined
+      // with the latest cursor Y we recover the same before/inside/after
+      // split Finder uses.
+      const rect = e.over?.rect;
+      if (!rect) return;
+
+      // `data-folder` on the dom row tells us if `inside` is allowed.
+      const el = document.querySelector<HTMLElement>(
+        `[data-tree-row][data-id="${CSS.escape(overId)}"]`,
+      );
+      const isFolder = el?.dataset.folder === 'true';
+
+      const position = resolveDropZone({
+        pointerY: cursorYRef.current,
+        rowRect: { top: rect.top, bottom: rect.top + rect.height, height: rect.height },
+        isFolder,
+      });
+
+      const current = dnd.dropTarget;
+      if (current?.id !== overId || current.position !== position) {
+        dnd.setDropTarget({ id: overId, position });
+      }
+    },
+    [dnd],
+  );
+
+  const handleDragEnd = useCallback(
+    async (_e: DragEndEvent) => {
+      await dnd.commitDrop();
+    },
+    [dnd],
+  );
+
+  const handleDragCancel = useCallback(() => {
+    dnd.cancelDrag();
+  }, [dnd]);
+
+  // Track the latest cursor Y position globally while a drag is in flight.
+  // Used by `handleDragMove` to figure out which third of the row we're
+  // over. Cheap — one passive listener, no re-renders.
+  const handlePointerMove = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+    cursorYRef.current = e.clientY;
+  }, []);
+
+  if (!dnd.active) {
+    return <>{children}</>;
+  }
+
+  return (
+    <DndContext
+      sensors={sensors}
+      onDragStart={handleDragStart}
+      onDragMove={handleDragMove}
+      onDragEnd={handleDragEnd}
+      onDragCancel={handleDragCancel}
+    >
+      <div
+        onPointerMove={handlePointerMove}
+        className="contents"
+        data-tree-dnd-surface=""
+      >
+        {children}
+      </div>
+    </DndContext>
+  );
+}

package/src/Tree/TreeRoot.tsx

@@ -0,0 +1,290 @@
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { TreeProvider, useTreeContext } from './context/TreeContext';
+import { TreeDndProvider } from './TreeDndProvider';
+import { TreeContent, treeRowDomId } from './components/TreeContent';
+import { TreeEmptyArea } from './components/TreeEmptyArea';
+import { TreeSearchInput } from './components/TreeSearchInput';
+import { appearanceToStyle } from './data/appearance';
+import {
+  useTreeKeyboard,
+  useTreeTypeAhead,
+  useTreeFinderHotkeys,
+} from './hooks';
+import type { TreeActionsHandle, TreeRootProps } from './types';
+
+/**
+ * High-level entry point. Wraps Provider + (optional) search bar + content.
+ *
+ * For full control, compose with <TreeProvider>, <TreeContent>,
+ * <TreeSearchInput>, <TreeRow>, etc. directly from `@djangocfg/widget-data/tree`.
+ */
+function TreeRoot<T>(props: TreeRootProps<T>) {
+  const {
+    data,
+    getItemName,
+    loadChildren,
+    selectionMode,
+    activationMode,
+    initialExpandedIds,
+    initialSelectedIds,
+    indent,
+    appearance,
+    onSelectionChange,
+    onExpansionChange,
+    onActivate,
+    filterNode,
+    enableSearch = false,
+    enableTypeAhead = true,
+    showIndentGuides = false,
+    enableInlineRename = false,
+    enableFinderHotkeys = false,
+    enableDnD = false,
+    canDrop,
+    renderRow,
+    renderIcon,
+    renderLabel,
+    renderActions,
+    renderContextMenu,
+    contextMenuActions,
+    labels,
+    persistKey,
+    persistSelection = false,
+    adapter,
+    defaultMenuItems,
+    actionsRef,
+    className,
+    style,
+  } = props;
+
+  return (
+    <TreeProvider<T>
+      data={data}
+      getItemName={getItemName}
+      loadChildren={loadChildren}
+      selectionMode={selectionMode}
+      activationMode={activationMode}
+      initialExpandedIds={initialExpandedIds}
+      initialSelectedIds={initialSelectedIds}
+      indent={indent}
+      appearance={appearance}
+      onSelectionChange={onSelectionChange}
+      onExpansionChange={onExpansionChange}
+      onActivate={onActivate}
+      filterNode={filterNode}
+      enableSearch={enableSearch}
+      showIndentGuides={showIndentGuides}
+      renderIcon={renderIcon}
+      renderLabel={renderLabel}
+      renderActions={renderActions}
+      // The provider builds the *declarative* merged resolver. Slot
+      // conversion happens inside <TreeRootShell /> via the inner ctx,
+      // so built-in actions can read live selection state.
+      renderContextMenu={renderContextMenu}
+      contextMenuActions={contextMenuActions}
+      adapter={adapter}
+      defaultMenuItems={defaultMenuItems}
+      enableInlineRename={enableInlineRename}
+      enableDnD={enableDnD}
+      canDrop={canDrop}
+      labels={labels}
+      persistKey={persistKey}
+      persistSelection={persistSelection}
+    >
+      <TreeRootShell<T>
+        className={className}
+        style={style}
+        enableSearch={enableSearch}
+        enableTypeAhead={enableTypeAhead}
+        enableFinderHotkeys={enableFinderHotkeys}
+        renderRow={renderRow}
+        actionsRef={actionsRef}
+      />
+    </TreeProvider>
+  );
+}
+
+interface TreeRootShellProps<T> {
+  className?: string;
+  style?: React.CSSProperties;
+  enableSearch: boolean;
+  enableTypeAhead: boolean;
+  enableFinderHotkeys: boolean;
+  renderRow?: TreeRootProps<T>['renderRow'];
+  actionsRef?: React.MutableRefObject<TreeActionsHandle | null>;
+}
+
+function TreeRootShell<T>({
+  className,
+  style,
+  enableSearch,
+  enableTypeAhead,
+  enableFinderHotkeys,
+  renderRow,
+  actionsRef,
+}: TreeRootShellProps<T>) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const ctx = useTreeContext<T>();
+
+  // Publish the action handle to the outer ref so host code can call
+  // refresh / refreshAll after a mutation that originated outside Tree.
+  // Effect runs after mount; the ref stays populated until unmount.
+  useEffect(() => {
+    if (!actionsRef) return;
+    actionsRef.current = {
+      refresh: ctx.refresh,
+      refreshAll: ctx.refreshAll,
+      expandAll: ctx.expandAll,
+      collapseAll: ctx.collapseAll,
+    };
+    return () => {
+      if (actionsRef.current) actionsRef.current = null;
+    };
+  }, [
+    actionsRef,
+    ctx.refresh,
+    ctx.refreshAll,
+    ctx.expandAll,
+    ctx.collapseAll,
+  ]);
+
+  // Keyboard navigation (↑↓ ←→ Home/End Enter Esc Cmd+A, Shift-extend) —
+  // scoped via callback ref.
+  const isMulti = ctx.selectionMode === 'multiple';
+  const { ref: keyboardRef } = useTreeKeyboard<T>({
+    rows: ctx.flatRows,
+    focusedId: ctx.focused,
+    multiSelect: isMulti,
+    // Pause container hotkeys while inline rename is active so the
+    // user can type freely (TreeRenameInput stops bubbling already, but
+    // gating here is the cleaner second line of defence).
+    enabled: ctx.renamingId === null,
+    onFocus: (id, { extend }) => {
+      if (extend && isMulti) {
+        ctx.moveSelect(id, { extend: true });
+      } else {
+        ctx.setFocus(id);
+      }
+    },
+    onSelect: ctx.select,
+    onActivate: (id) => {
+      // Keyboard Enter / Space is always an explicit action — pin (no preview).
+      const row = ctx.flatRows.find((r) => r.node.id === id);
+      if (row) ctx.activate(row.node, { preview: false });
+    },
+    onExpand: ctx.expand,
+    onCollapse: ctx.collapse,
+    onClearSelection: ctx.clearSelection,
+    onSelectAll: ctx.selectAll,
+  });
+
+  // Finder hotkeys (P4) — ⌘⌫, F2, ⌘D, ⌘N, ⌘⇧N, ⌘C/X/V. Bound only when
+  // `enableFinderHotkeys` is true; individual shortcuts further gated
+  // by adapter method availability inside the hook.
+  const { ref: finderHotkeysRef } = useTreeFinderHotkeys<T>({
+    enabled: enableFinderHotkeys,
+    paused: ctx.renamingId !== null,
+    adapter: ctx.adapter,
+    labels: ctx.labels,
+    selected: ctx.selected,
+    focused: ctx.focused,
+    getNodeById: ctx.getNodeById,
+    getItemName: ctx.getItemName,
+    startInlineRename: ctx.inlineRenameEnabled ? ctx.startRename : undefined,
+    clipboard: {
+      hasItems: !!ctx.clipboard && ctx.clipboard.ids.length > 0,
+      cut: ctx.cutToClipboard,
+      copy: ctx.copyToClipboard,
+      // Hotkey paste targets the currently focused row (or null = root).
+      paste: () => {
+        const target = ctx.focused ? ctx.getNodeById(ctx.focused) ?? null : null;
+        return ctx.pasteFromClipboard(target, 'inside');
+      },
+    },
+  });
+
+  const setContainerRef = useCallback(
+    (instance: HTMLDivElement | null) => {
+      containerRef.current = instance;
+      keyboardRef(instance);
+      finderHotkeysRef(instance);
+    },
+    [keyboardRef, finderHotkeysRef],
+  );
+
+  // Keep the focused row scrolled into view whenever focus moves (keyboard
+  // nav, type-ahead, programmatic). Centralised so every focus source gets
+  // consistent scrolling — previously only type-ahead scrolled.
+  const focusedId = ctx.focused;
+  const isEmpty = ctx.flatRows.length === 0;
+  useEffect(() => {
+    if (!focusedId) return;
+    const el = containerRef.current?.querySelector<HTMLElement>(
+      `[data-tree-row][data-id="${CSS.escape(focusedId)}"]`,
+    );
+    el?.scrollIntoView({ block: 'nearest' });
+  }, [focusedId]);
+
+  // Type-ahead jump — focus update; scrolling handled by the effect above.
+  const onTypeAheadMatch = useCallback(
+    (id: string) => {
+      ctx.setFocus(id);
+    },
+    [ctx],
+  );
+
+  useTreeTypeAhead<T>({
+    rows: ctx.flatRows,
+    getItemName: ctx.getItemName,
+    containerRef,
+    onMatch: onTypeAheadMatch,
+    enabled: enableTypeAhead,
+  });
+
+  // Tree body. `ctx.renderContextMenu` is already the final slot —
+  // TreeProvider does the declarative→slot merge centrally, so Shell
+  // doesn't re-derive it (and no nested provider override is needed).
+  const treeBody = (
+    <div
+      ref={setContainerRef}
+      tabIndex={isEmpty ? undefined : 0}
+      role={isEmpty ? undefined : 'tree'}
+      aria-label={isEmpty ? undefined : ctx.labels.ariaLabel}
+      aria-multiselectable={
+        !isEmpty && ctx.selectionMode === 'multiple' ? true : undefined
+      }
+      aria-activedescendant={
+        !isEmpty && focusedId ? treeRowDomId(focusedId) : undefined
+      }
+      className={cn(
+        'group/tree flex h-full w-full flex-col gap-2 rounded-sm outline-none',
+        'focus-visible:ring-1 focus-visible:ring-ring/50',
+        className,
+      )}
+      style={{ ...appearanceToStyle(ctx.appearance), ...style }}
+      data-tree-root=""
+    >
+      {enableSearch ? <TreeSearchInput className="mx-2 mt-2" /> : null}
+      <div className="flex min-h-0 flex-1 flex-col overflow-auto px-1">
+        <TreeContent<T> role={isEmpty ? "presentation" : "group"}>
+          {renderRow}
+        </TreeContent>
+        {/* Empty-area: catches right-clicks on whitespace below the
+            last row + acts as the root drop target for DnD. Always
+            rendered — it self-disables when there's nothing to do. */}
+        <TreeEmptyArea />
+      </div>
+    </div>
+  );
+
+  // Wrap in @dnd-kit context only when DnD is active — `TreeDndProvider`
+  // short-circuits to a fragment otherwise, so we don't pay the
+  // sensor-registration cost.
+  return <TreeDndProvider>{treeBody}</TreeDndProvider>;
+}
+
+export default TreeRoot;
+export { TreeRoot };

package/src/Tree/components/TreeChevron.tsx

@@ -0,0 +1,48 @@
+'use client';
+
+import { ChevronDown, ChevronRight } from 'lucide-react';
+import { memo } from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useTreeContext } from '../context/TreeContext';
+
+export interface TreeChevronProps {
+  isExpanded: boolean;
+  isFolder: boolean;
+  className?: string;
+}
+
+/**
+ * TreeChevron — expand/collapse chevron for a tree row.
+ *
+ * Memoised: re-renders only when `isExpanded`, `isFolder` or `className`
+ * change. Reads appearance from context.
+ */
+function TreeChevronRaw({ isExpanded, isFolder, className }: TreeChevronProps) {
+  const { appearance } = useTreeContext();
+  const size = { width: 'var(--tree-icon-size)', height: 'var(--tree-icon-size)' };
+
+  if (!isFolder) {
+    return (
+      <span
+        aria-hidden
+        style={size}
+        className={cn('inline-block shrink-0', className)}
+      />
+    );
+  }
+  const Icon = isExpanded ? ChevronDown : ChevronRight;
+  return (
+    <Icon
+      aria-hidden
+      strokeWidth={appearance.iconStrokeWidth}
+      style={size}
+      className={cn(
+        'shrink-0 text-muted-foreground/70 transition-transform',
+        className,
+      )}
+    />
+  );
+}
+
+export const TreeChevron = memo(TreeChevronRaw);

package/src/Tree/components/TreeContent.tsx

@@ -0,0 +1,70 @@
+'use client';
+
+import { Fragment, type ReactNode } from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useTreeContext } from '../context/TreeContext';
+import { appearanceToStyle } from '../data/appearance';
+import type { FlatRow, TreeRowRenderProps, TreeRowSlot } from '../types';
+import { TreeRow } from './TreeRow';
+import { TreeEmpty } from './TreeEmpty';
+
+export interface TreeContentProps<T> {
+  /** Custom row renderer; falls back to <TreeRow />. */
+  children?: TreeRowSlot<T>;
+  className?: string;
+  /** Override aria-label for the container. */
+  ariaLabel?: string;
+  /**
+   * Container ARIA role. Defaults to `'tree'` for standalone composition
+   * use. `<TreeRoot>` passes `'group'` because its own outer element
+   * already carries `role="tree"` + `aria-activedescendant`.
+   */
+  role?: 'tree' | 'group' | 'presentation';
+}
+
+/** DOM id for a tree row — referenced by `aria-activedescendant`. */
+export const treeRowDomId = (id: string) => `tree-row-${id}`;
+
+export function TreeContent<T>({
+  children,
+  className,
+  ariaLabel,
+  role = 'tree',
+}: TreeContentProps<T>) {
+  const { flatRows, labels, selected, focused, matchingIds, appearance, selectionMode } =
+    useTreeContext<T>();
+
+  if (flatRows.length === 0) {
+    return <TreeEmpty>{labels.empty}</TreeEmpty>;
+  }
+
+  const isTree = role === 'tree';
+
+  return (
+    <div
+      role={role}
+      aria-label={isTree ? (ariaLabel ?? labels.ariaLabel) : undefined}
+      aria-multiselectable={
+        isTree && selectionMode === 'multiple' ? true : undefined
+      }
+      className={cn('relative flex flex-col py-1', className)}
+      style={appearanceToStyle(appearance)}
+    >
+      {flatRows.map((row: FlatRow<T>) => {
+        const slot: TreeRowRenderProps<T> = {
+          node: row.node,
+          level: row.level,
+          isSelected: selected.has(row.node.id),
+          isExpanded: row.isExpanded,
+          isFocused: focused === row.node.id,
+          isFolder: row.isFolder,
+          isLoading: row.isLoading,
+          isMatchingSearch: matchingIds.has(row.node.id),
+        };
+        const node: ReactNode = children ? children(slot) : <TreeRow row={row} />;
+        return <Fragment key={row.node.id}>{node}</Fragment>;
+      })}
+    </div>
+  );
+}

package/src/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/Tree/components/TreeEmpty.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface TreeEmptyProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export function TreeEmpty({ children, className }: TreeEmptyProps) {
+  return (
+    <div
+      role="status"
+      className={cn(
+        'flex h-full min-h-32 items-center justify-center px-4 py-6 text-sm text-muted-foreground',
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+}