@dnd-block-tree/react 2.0.0

package/README.md

@@ -0,0 +1,61 @@
+# @dnd-block-tree/react
+
+[![npm version](https://img.shields.io/npm/v/@dnd-block-tree/react.svg)](https://www.npmjs.com/package/@dnd-block-tree/react)
+
+React adapter for [dnd-block-tree](https://github.com/thesandybridge/dnd-block-tree) — components, hooks, and [@dnd-kit](https://dndkit.com/) integration for building hierarchical drag-and-drop interfaces.
+
+## Installation
+
+```bash
+npm install @dnd-block-tree/react @dnd-kit/core @dnd-kit/utilities
+```
+
+Requires **React 18+** and **@dnd-kit/core 6+**.
+
+## What's Included
+
+- **Components** — `BlockTree`, `BlockTreeSSR`, `TreeRenderer`, `DropZone`, `DragOverlay`
+- **Hooks** — `useBlockHistory`, `useLayoutAnimation`, `useVirtualTree`, `useConfiguredSensors`
+- **Collision Bridge** — `adaptCollisionDetection` to bridge core's `CoreCollisionDetection` to @dnd-kit's `CollisionDetection`
+- **Re-exports** — all types and utilities from `@dnd-block-tree/core`
+
+## Quick Example
+
+```tsx
+import { BlockTree, type BaseBlock, type BlockRenderers } from '@dnd-block-tree/react'
+
+interface MyBlock extends BaseBlock {
+  type: 'section' | 'task'
+  title: string
+}
+
+const renderers: BlockRenderers<MyBlock, ['section']> = {
+  section: ({ block, children, isExpanded, onToggleExpand }) => (
+    <div>
+      <button onClick={onToggleExpand}>{isExpanded ? '▼' : '▶'} {block.title}</button>
+      {isExpanded && <div className="ml-4">{children}</div>}
+    </div>
+  ),
+  task: ({ block }) => <div>{block.title}</div>,
+}
+
+function App() {
+  const [blocks, setBlocks] = useState<MyBlock[]>(initialBlocks)
+  return (
+    <BlockTree
+      blocks={blocks}
+      renderers={renderers}
+      containerTypes={['section']}
+      onChange={setBlocks}
+    />
+  )
+}
+```
+
+## Documentation
+
+Full docs at **[blocktree.sandybridge.io](https://blocktree.sandybridge.io/docs)**.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,337 @@
+import { BaseBlock, BlockRendererProps as BlockRendererProps$1, BlockRenderers as BlockRenderers$1, OrderingStrategy, BlockAddEvent, BlockDeleteEvent, CanDragFn, CanDropFn, SensorConfig, DropZoneConfig, AnimationConfig, AutoExpandConfig, IdGeneratorFn, ContainerRendererProps as ContainerRendererProps$1, InternalRenderers as InternalRenderers$1, RendererPropsFor as RendererPropsFor$1, CoreCollisionDetection, BlockTreeCallbacks, BlockStateContextValue } from '@dnd-block-tree/core';
+export { AnimationConfig, AutoExpandConfig, BaseBlock, BlockAction, BlockAddEvent, BlockDeleteEvent, BlockIndex, BlockMoveEvent, BlockPosition, BlockStateContextValue, BlockTreeCallbacks, BlockTreeConfig, BlockTreeEvents, BlockTreeInstance, BlockTreeOptions, CanDragFn, CanDropFn, CollisionCandidate, CollisionResult, BlockTreeCustomization as CoreBlockTreeCustomization, CoreCollisionDetection, DragOverlayProps as CoreDragOverlayProps, DragEndEvent, DragMoveEvent, DragStartEvent, DropZoneConfig, DropZoneType, EventEmitter, ExpandAction, ExpandChangeEvent, HistoryAction, HistoryState, HoverChangeEvent, IdGeneratorFn, MoveOperation, NestedBlock, OrderingStrategy, Rect, SensorConfig, SnapshotRectsRef, TreeValidationResult, blockReducer, buildOrderedBlocks, cloneMap, cloneParentMap, closestCenterCollision, compareFractionalKeys, computeNormalizedIndex, createBlockTree, createStickyCollision, debounce, deleteBlockAndDescendants, expandReducer, extractBlockId, extractUUID, flatToNested, generateId, generateInitialKeys, generateKeyBetween, generateNKeysBetween, getBlockDepth, getDescendantIds, getDropZoneType, getSubtreeDepth, historyReducer, initFractionalOrder, nestedToFlat, reparentBlockIndex, reparentMultipleBlocks, validateBlockTree, weightedVerticalCollision } from '@dnd-block-tree/core';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as _dnd_kit_core from '@dnd-kit/core';
+import { CollisionDetection, PointerActivationConstraint } from '@dnd-kit/core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type BlockRendererProps<T extends BaseBlock = BaseBlock> = BlockRendererProps$1<T, ReactNode>;
+type ContainerRendererProps<T extends BaseBlock = BaseBlock> = ContainerRendererProps$1<T, ReactNode>;
+type RendererPropsFor<T extends BaseBlock, K extends T['type'], C extends readonly string[]> = RendererPropsFor$1<T, K, C, ReactNode>;
+type BlockRenderers<T extends BaseBlock = BaseBlock, C extends readonly string[] = readonly string[]> = BlockRenderers$1<T, C, ReactNode>;
+type InternalRenderers<T extends BaseBlock = BaseBlock> = InternalRenderers$1<T, ReactNode>;
+/**
+ * Block state provider props
+ */
+interface BlockStateProviderProps<T extends BaseBlock = BaseBlock> {
+    children: ReactNode;
+    initialBlocks?: T[];
+    containerTypes?: readonly string[];
+    onChange?: (blocks: T[]) => void;
+    orderingStrategy?: OrderingStrategy;
+    maxDepth?: number;
+    onBlockAdd?: (event: BlockAddEvent<T>) => void;
+    onBlockDelete?: (event: BlockDeleteEvent<T>) => void;
+}
+/**
+ * Tree state provider props
+ */
+interface TreeStateProviderProps<T extends BaseBlock = BaseBlock> {
+    children: ReactNode;
+    blocks: T[];
+    blockMap: Map<string, T>;
+}
+/**
+ * Tree state context value (UI state)
+ */
+interface TreeStateContextValue<T extends BaseBlock = BaseBlock> {
+    activeId: string | null;
+    activeBlock: T | null;
+    hoverZone: string | null;
+    expandedMap: Record<string, boolean>;
+    effectiveBlocks: T[];
+    blocksByParent: Map<string | null, T[]>;
+    setActiveId: (id: string | null) => void;
+    setHoverZone: (zone: string | null) => void;
+    toggleExpand: (id: string) => void;
+    setExpandAll: (expanded: boolean) => void;
+    handleHover: (zoneId: string, parentId: string | null) => void;
+}
+/**
+ * Full customization options for BlockTree (React version).
+ * Uses dnd-kit's CollisionDetection instead of core's CoreCollisionDetection.
+ */
+interface BlockTreeCustomization<T extends BaseBlock = BaseBlock> {
+    canDrag?: CanDragFn<T>;
+    canDrop?: CanDropFn<T>;
+    collisionDetection?: CollisionDetection;
+    sensors?: SensorConfig;
+    dropZones?: DropZoneConfig;
+    animation?: AnimationConfig;
+    autoExpand?: AutoExpandConfig;
+    idGenerator?: IdGeneratorFn;
+    initialExpanded?: string[] | 'all' | 'none';
+    orderingStrategy?: OrderingStrategy;
+    maxDepth?: number;
+}
+
+/**
+ * Adapt a framework-agnostic CoreCollisionDetection into a dnd-kit CollisionDetection.
+ *
+ * Converts:
+ *   droppableContainers → CollisionCandidate[]
+ *   Calls coreDetector
+ *   CollisionResult[] → CollisionDescriptor[]
+ */
+declare function adaptCollisionDetection(coreDetector: CoreCollisionDetection): CollisionDetection;
+
+/**
+ * Trigger haptic feedback (vibration) on supported devices.
+ * Safe to call in any environment -- no-ops when `navigator.vibrate` is unavailable.
+ */
+declare function triggerHaptic(durationMs?: number): void;
+
+interface SensorConfigResult {
+    pointer: {
+        activationConstraint: PointerActivationConstraint;
+    };
+    touch: {
+        activationConstraint: PointerActivationConstraint;
+    };
+}
+declare function useConfiguredSensors(config?: SensorConfig): _dnd_kit_core.SensorDescriptor<_dnd_kit_core.SensorOptions>[];
+declare function getSensorConfig(config?: SensorConfig): SensorConfigResult;
+
+interface BlockTreeProps<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]> extends BlockTreeCallbacks<T>, BlockTreeCustomization<T> {
+    /** Current blocks array */
+    blocks: T[];
+    /** Block renderers for each type */
+    renderers: BlockRenderers<T, C>;
+    /** Block types that can have children */
+    containerTypes?: C;
+    /** Called when blocks are reordered */
+    onChange?: (blocks: T[]) => void;
+    /** Custom drag overlay renderer */
+    dragOverlay?: (block: T) => ReactNode;
+    /** Activation distance in pixels (default: 8) */
+    activationDistance?: number;
+    /** Preview debounce in ms (default: 150) */
+    previewDebounce?: number;
+    /** Root container className */
+    className?: string;
+    /** Drop zone className */
+    dropZoneClassName?: string;
+    /** Active drop zone className */
+    dropZoneActiveClassName?: string;
+    /** Indent className for nested items */
+    indentClassName?: string;
+    /** Show live preview of drop position during drag (default: true) */
+    showDropPreview?: boolean;
+    /** Enable keyboard navigation with arrow keys (default: false) */
+    keyboardNavigation?: boolean;
+    /** Enable multi-select with Cmd/Ctrl+Click and Shift+Click (default: false) */
+    multiSelect?: boolean;
+    /** Externally-controlled selected IDs (for multi-select) */
+    selectedIds?: Set<string>;
+    /** Called when selection changes (for multi-select) */
+    onSelectionChange?: (selectedIds: Set<string>) => void;
+    /** Enable virtual scrolling for large trees (fixed item height only) */
+    virtualize?: {
+        /** Fixed height of each item in pixels */
+        itemHeight: number;
+        /** Number of extra items to render outside the visible range (default: 5) */
+        overscan?: number;
+    };
+}
+declare function BlockTree<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]>({ blocks, renderers, containerTypes, onChange, dragOverlay, activationDistance, previewDebounce, className, dropZoneClassName, dropZoneActiveClassName, indentClassName, showDropPreview, onDragStart, onDragMove, onDragEnd, onDragCancel, onBeforeMove, onBlockMove, onExpandChange, onHoverChange, canDrag, canDrop, collisionDetection, sensors: sensorConfig, animation, initialExpanded, orderingStrategy, maxDepth, keyboardNavigation, multiSelect, selectedIds: externalSelectedIds, onSelectionChange, virtualize, }: BlockTreeProps<T, C>): react_jsx_runtime.JSX.Element;
+
+interface TreeRendererProps<T extends BaseBlock> {
+    blocks: T[];
+    blocksByParent: Map<string | null, T[]>;
+    parentId: string | null;
+    activeId: string | null;
+    expandedMap: Record<string, boolean>;
+    renderers: InternalRenderers<T>;
+    containerTypes: readonly string[];
+    onHover: (zoneId: string, parentId: string | null) => void;
+    onToggleExpand: (id: string) => void;
+    depth?: number;
+    dropZoneClassName?: string;
+    dropZoneActiveClassName?: string;
+    indentClassName?: string;
+    rootClassName?: string;
+    canDrag?: CanDragFn<T>;
+    /** Preview position info - where to show the ghost */
+    previewPosition?: {
+        parentId: string | null;
+        index: number;
+    } | null;
+    /** The dragged block for rendering preview ghost */
+    draggedBlock?: T | null;
+    /** Currently focused block ID for keyboard navigation */
+    focusedId?: string | null;
+    /** Currently selected block IDs for multi-select */
+    selectedIds?: Set<string>;
+    /** Click handler for multi-select */
+    onBlockClick?: (blockId: string, event: React.MouseEvent) => void;
+    /** Animation configuration */
+    animation?: AnimationConfig;
+    /** When virtual scrolling is active, only render blocks in this set */
+    virtualVisibleIds?: Set<string> | null;
+}
+/**
+ * Recursive tree renderer with smart drop zones
+ */
+declare function TreeRendererInner<T extends BaseBlock>({ blocks, blocksByParent, parentId, activeId, expandedMap, renderers, containerTypes, onHover, onToggleExpand, depth, dropZoneClassName, dropZoneActiveClassName, indentClassName, rootClassName, canDrag, previewPosition, draggedBlock, focusedId, selectedIds, onBlockClick, animation, virtualVisibleIds, }: TreeRendererProps<T>): react_jsx_runtime.JSX.Element;
+declare const TreeRenderer: typeof TreeRendererInner;
+
+interface DropZoneProps {
+    id: string;
+    parentId: string | null;
+    onHover: (zoneId: string, parentId: string | null) => void;
+    activeId: string | null;
+    className?: string;
+    activeClassName?: string;
+    height?: number;
+}
+declare function DropZoneComponent({ id, parentId, onHover, activeId, className, activeClassName, height, }: DropZoneProps): react_jsx_runtime.JSX.Element | null;
+declare const DropZone: react.MemoExoticComponent<typeof DropZoneComponent>;
+
+interface DragOverlayProps<T extends BaseBlock> {
+    activeBlock: T | null;
+    children?: (block: T) => ReactNode;
+    /** Number of selected items being dragged (for multi-select badge) */
+    selectedCount?: number;
+}
+declare function DragOverlay<T extends BaseBlock>({ activeBlock, children, selectedCount, }: DragOverlayProps<T>): react_jsx_runtime.JSX.Element;
+
+interface BlockTreeSSRProps<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]> extends BlockTreeProps<T, C> {
+    /** Content to render before hydration completes (default: null) */
+    fallback?: ReactNode;
+}
+declare function BlockTreeSSR<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]>({ fallback, ...props }: BlockTreeSSRProps<T, C>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Create block state context and hooks
+ */
+declare function createBlockState<T extends BaseBlock>(): {
+    BlockStateProvider: ({ children, initialBlocks, containerTypes, onChange, orderingStrategy, maxDepth, onBlockAdd, onBlockDelete, }: BlockStateProviderProps<T>) => react_jsx_runtime.JSX.Element;
+    useBlockState: () => BlockStateContextValue<T>;
+};
+
+interface CreateTreeStateOptions<T extends BaseBlock> {
+    previewDebounce?: number;
+    containerTypes?: string[];
+}
+declare function createTreeState<T extends BaseBlock>(options?: CreateTreeStateOptions<T>): {
+    TreeStateProvider: ({ children, blocks, blockMap }: TreeStateProviderProps<T>) => react_jsx_runtime.JSX.Element;
+    useTreeState: () => TreeStateContextValue<T>;
+};
+
+interface UseBlockHistoryOptions {
+    /** Maximum number of undo steps to retain (default: 50) */
+    maxSteps?: number;
+}
+interface UseBlockHistoryResult<T extends BaseBlock> {
+    /** Current blocks state */
+    blocks: T[];
+    /** Set new blocks state (pushes current to undo stack) */
+    set: (blocks: T[]) => void;
+    /** Undo the last change */
+    undo: () => void;
+    /** Redo the last undone change */
+    redo: () => void;
+    /** Whether undo is available */
+    canUndo: boolean;
+    /** Whether redo is available */
+    canRedo: boolean;
+}
+/**
+ * Composable hook for undo/redo support with BlockTree.
+ *
+ * Usage:
+ * ```tsx
+ * const { blocks, set, undo, redo, canUndo, canRedo } = useBlockHistory(initialBlocks)
+ * <BlockTree blocks={blocks} onChange={set} />
+ * <button onClick={undo} disabled={!canUndo}>Undo</button>
+ * <button onClick={redo} disabled={!canRedo}>Redo</button>
+ * ```
+ */
+declare function useBlockHistory<T extends BaseBlock>(initialBlocks: T[], options?: UseBlockHistoryOptions): UseBlockHistoryResult<T>;
+
+interface UseLayoutAnimationOptions {
+    /** Duration of the transition in ms (default: 200) */
+    duration?: number;
+    /** CSS easing function (default: 'ease') */
+    easing?: string;
+    /** CSS selector for animated children (default: '[data-block-id]') */
+    selector?: string;
+}
+/**
+ * FLIP-based layout animation hook for reorder transitions.
+ *
+ * Captures block positions before render (layout effect cleanup),
+ * computes the delta after render, and applies a CSS transform transition.
+ *
+ * Usage:
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null)
+ * useLayoutAnimation(containerRef, { duration: 200 })
+ * return <div ref={containerRef}>...</div>
+ * ```
+ */
+declare function useLayoutAnimation(containerRef: React.RefObject<HTMLElement | null>, options?: UseLayoutAnimationOptions): void;
+
+interface UseVirtualTreeOptions {
+    /** Ref to the scrollable container element */
+    containerRef: React.RefObject<HTMLElement | null>;
+    /** Total number of items in the tree */
+    itemCount: number;
+    /** Fixed height of each item in pixels */
+    itemHeight: number;
+    /** Number of extra items to render outside the visible range (default: 5) */
+    overscan?: number;
+}
+interface UseVirtualTreeResult {
+    /** Start and end indices of the visible range (inclusive) */
+    visibleRange: {
+        start: number;
+        end: number;
+    };
+    /** Total height of all items for the spacer div */
+    totalHeight: number;
+    /** Offset from top for the first rendered item */
+    offsetY: number;
+}
+/**
+ * Lightweight fixed-height virtual scrolling hook for tree lists.
+ *
+ * Tracks scroll position on the container and computes which items
+ * should be rendered based on the viewport and overscan.
+ */
+declare function useVirtualTree({ containerRef, itemCount, itemHeight, overscan, }: UseVirtualTreeOptions): UseVirtualTreeResult;
+
+interface DevToolsEventEntry {
+    id: number;
+    timestamp: number;
+    type: 'dragStart' | 'dragEnd' | 'blockMove' | 'expandChange' | 'hoverChange';
+    summary: string;
+}
+interface DevToolsCallbacks<T extends BaseBlock = BaseBlock> {
+    onDragStart: NonNullable<BlockTreeCallbacks<T>['onDragStart']>;
+    onDragEnd: NonNullable<BlockTreeCallbacks<T>['onDragEnd']>;
+    onBlockMove: NonNullable<BlockTreeCallbacks<T>['onBlockMove']>;
+    onExpandChange: NonNullable<BlockTreeCallbacks<T>['onExpandChange']>;
+    onHoverChange: NonNullable<BlockTreeCallbacks<T>['onHoverChange']>;
+}
+interface BlockTreeDevToolsProps<T extends BaseBlock = BaseBlock> {
+    blocks: T[];
+    containerTypes?: readonly string[];
+    events: DevToolsEventEntry[];
+    onClearEvents: () => void;
+    getLabel?: (block: T) => string;
+    initialOpen?: boolean;
+    position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
+    buttonStyle?: React.CSSProperties;
+    panelStyle?: React.CSSProperties;
+    forceMount?: boolean;
+}
+declare function useDevToolsCallbacks<T extends BaseBlock = BaseBlock>(): {
+    callbacks: DevToolsCallbacks<T>;
+    events: DevToolsEventEntry[];
+    clearEvents: () => void;
+};
+declare function BlockTreeDevTools<T extends BaseBlock = BaseBlock>({ blocks, containerTypes, events, onClearEvents, getLabel, initialOpen, position, buttonStyle, panelStyle, forceMount, }: BlockTreeDevToolsProps<T>): react_jsx_runtime.JSX.Element | null;
+
+export { type BlockRendererProps, type BlockRenderers, type BlockStateProviderProps, BlockTree, type BlockTreeCustomization, BlockTreeDevTools, type BlockTreeDevToolsProps, type BlockTreeProps, BlockTreeSSR, type BlockTreeSSRProps, type ContainerRendererProps, type DevToolsCallbacks, type DevToolsEventEntry, DragOverlay, type DragOverlayProps, DropZone, type DropZoneProps, type InternalRenderers, type RendererPropsFor, type SensorConfigResult, TreeRenderer, type TreeRendererProps, type TreeStateContextValue, type TreeStateProviderProps, type UseBlockHistoryOptions, type UseBlockHistoryResult, type UseLayoutAnimationOptions, type UseVirtualTreeOptions, type UseVirtualTreeResult, adaptCollisionDetection, createBlockState, createTreeState, getSensorConfig, triggerHaptic, useBlockHistory, useConfiguredSensors, useDevToolsCallbacks, useLayoutAnimation, useVirtualTree };