dnd-block-tree 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -11,7 +11,8 @@ interface BaseBlock {
     id: string;
     type: string;
     parentId: string | null;
-    order: number;
+    /** Ordering value. Number for integer ordering (default), string for fractional ordering. */
+    order: number | string;
 }
 /**
  * Normalized index structure for efficient tree operations
@@ -106,6 +107,20 @@ interface BlockMoveEvent<T extends BaseBlock = BaseBlock> {
     to: BlockPosition;
     /** All blocks after the move */
     blocks: T[];
+    /** IDs of all blocks that were moved (for multi-select) */
+    movedIds: string[];
+}
+/**
+ * A pending move operation passed through the onBeforeMove middleware pipeline.
+ * Return a modified operation to transform the move, or return false to cancel.
+ */
+interface MoveOperation<T extends BaseBlock = BaseBlock> {
+    /** The block being moved */
+    block: T;
+    /** Position before the move */
+    from: BlockPosition;
+    /** Target drop zone ID */
+    targetZone: string;
 }
 /**
  * Event fired when expand state changes
@@ -115,6 +130,22 @@ interface ExpandChangeEvent<T extends BaseBlock = BaseBlock> {
     blockId: string;
     expanded: boolean;
 }
+/**
+ * Event fired when a block is added
+ */
+interface BlockAddEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    parentId: string | null;
+    index: number;
+}
+/**
+ * Event fired when a block (and optionally its descendants) is deleted
+ */
+interface BlockDeleteEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    deletedIds: string[];
+    parentId: string | null;
+}
 /**
  * Event fired when hover zone changes
  */
@@ -136,13 +167,33 @@ interface BlockTreeCallbacks<T extends BaseBlock = BaseBlock> {
     onDragEnd?: (event: DragEndEvent<T>) => void;
     /** Called when drag is cancelled */
     onDragCancel?: (event: DragEndEvent<T>) => void;
+    /**
+     * Called before a block move is committed. Return a modified MoveOperation to
+     * transform the move (e.g. change the target zone), or return false to cancel.
+     * Return void / undefined to allow the move as-is.
+     */
+    onBeforeMove?: (operation: MoveOperation<T>) => MoveOperation<T> | false | void;
     /** Called after a block is moved to a new position */
     onBlockMove?: (event: BlockMoveEvent<T>) => void;
     /** Called when expand/collapse state changes */
     onExpandChange?: (event: ExpandChangeEvent<T>) => void;
     /** Called when hover zone changes during drag */
     onHoverChange?: (event: HoverChangeEvent<T>) => void;
+    /** Called after a block is added */
+    onBlockAdd?: (event: BlockAddEvent<T>) => void;
+    /** Called after a block (and its descendants) is deleted */
+    onBlockDelete?: (event: BlockDeleteEvent<T>) => void;
 }
+/**
+ * Ordering strategy for block siblings.
+ *
+ * - `'integer'` (default): siblings are reindexed 0, 1, 2, … after every move.
+ *   Simple and efficient; not suitable for collaborative/CRDT scenarios.
+ * - `'fractional'`: each move only updates the moved block's `order` with a
+ *   lexicographically sortable string key (fractional index). Siblings are never
+ *   reindexed, making it conflict-free for concurrent edits.
+ */
+type OrderingStrategy = 'integer' | 'fractional';
 /**
  * Filter function to determine if a block can be dragged
  */
@@ -162,6 +213,10 @@ interface SensorConfig {
     activationDistance?: number;
     activationDelay?: number;
     tolerance?: number;
+    /** Override the default long-press delay (200ms) for touch sensors */
+    longPressDelay?: number;
+    /** Trigger haptic feedback (vibration) on drag start for touch devices */
+    hapticFeedback?: boolean;
 }
 /**
  * Drop zone configuration
@@ -218,6 +273,14 @@ interface BlockTreeCustomization<T extends BaseBlock = BaseBlock> {
     idGenerator?: IdGeneratorFn;
     /** Initially expanded block IDs */
     initialExpanded?: string[] | 'all' | 'none';
+    /**
+     * Ordering strategy for block siblings.
+     * Defaults to `'integer'` (reindex all siblings on every move).
+     * Use `'fractional'` for CRDT-compatible collaborative editing.
+     */
+    orderingStrategy?: OrderingStrategy;
+    /** Maximum nesting depth (1 = flat list, 2 = one level of nesting, etc.) */
+    maxDepth?: number;
 }
 /**
  * Block action types for the reducer
@@ -312,6 +375,10 @@ interface BlockStateProviderProps<T extends BaseBlock = BaseBlock> {
     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
@@ -395,12 +462,27 @@ interface BlockTreeProps<T extends BaseBlock, C extends readonly T['type'][] = r
     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;
+    };
 }
 /**
  * Main BlockTree component
  * Provides drag-and-drop functionality for hierarchical block structures
  */
-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, onBlockMove, onExpandChange, onHoverChange, canDrag, canDrop, collisionDetection, sensors: sensorConfig, initialExpanded, }: BlockTreeProps<T, C>): react_jsx_runtime.JSX.Element;
+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[];
@@ -425,11 +507,21 @@ interface TreeRendererProps<T extends BaseBlock> {
     } | 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 TreeRenderer<T extends BaseBlock>({ blocks, blocksByParent, parentId, activeId, expandedMap, renderers, containerTypes, onHover, onToggleExpand, depth, dropZoneClassName, dropZoneActiveClassName, indentClassName, rootClassName, canDrag, previewPosition, draggedBlock, }: TreeRendererProps<T>): react_jsx_runtime.JSX.Element;
+declare function TreeRenderer<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;
 
 interface DropZoneProps {
     id: string;
@@ -450,18 +542,31 @@ 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;
 }
 /**
  * Default drag overlay component
  * Shows a preview of the dragged item
  */
-declare function DragOverlay<T extends BaseBlock>({ activeBlock, children, }: DragOverlayProps<T>): react_jsx_runtime.JSX.Element;
+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;
+}
+/**
+ * Hydration-safe wrapper for BlockTree in SSR environments.
+ * Renders the fallback (or nothing) on the server and during initial hydration,
+ * then mounts the full BlockTree after the client has hydrated.
+ */
+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, }: BlockStateProviderProps<T>) => react_jsx_runtime.JSX.Element;
+    BlockStateProvider: ({ children, initialBlocks, containerTypes, onChange, orderingStrategy, maxDepth, onBlockAdd, onBlockDelete, }: BlockStateProviderProps<T>) => react_jsx_runtime.JSX.Element;
     useBlockState: () => BlockStateContextValue<T>;
 };
 
@@ -478,6 +583,89 @@ declare function createTreeState<T extends BaseBlock>(options?: CreateTreeStateO
     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;
+
 /**
  * Clone a Map
  */
@@ -487,26 +675,49 @@ declare function cloneMap<K, V>(map: Map<K, V>): Map<K, V>;
  */
 declare function cloneParentMap(map: Map<string | null, string[]>): Map<string | null, string[]>;
 /**
- * Compute normalized index from flat block array
+ * Compute normalized index from flat block array.
+ *
+ * With `orderingStrategy: 'fractional'`, siblings are sorted by their `order`
+ * field (lexicographic). With `'integer'` (default), the input order is preserved.
  */
-declare function computeNormalizedIndex<T extends BaseBlock>(blocks: T[]): BlockIndex<T>;
+declare function computeNormalizedIndex<T extends BaseBlock>(blocks: T[], orderingStrategy?: OrderingStrategy): BlockIndex<T>;
 /**
- * Build ordered flat array from BlockIndex
+ * Build ordered flat array from BlockIndex.
+ *
+ * With `'integer'` ordering (default), assigns sequential `order: 0, 1, 2, …`.
+ * With `'fractional'` ordering, preserves existing `order` values — the moved
+ * block already has its new fractional key set by `reparentBlockIndex`.
  */
-declare function buildOrderedBlocks<T extends BaseBlock>(index: BlockIndex<T>, containerTypes?: readonly string[]): T[];
+declare function buildOrderedBlocks<T extends BaseBlock>(index: BlockIndex<T>, containerTypes?: readonly string[], orderingStrategy?: OrderingStrategy): T[];
 /**
- * Reparent a block based on drop zone ID
+ * Reparent a block based on drop zone ID.
  *
  * @param state - Current block index
  * @param activeId - ID of the dragged block
  * @param targetZone - Drop zone ID (e.g., "after-uuid", "before-uuid", "into-uuid")
  * @param containerTypes - Block types that can have children
+ * @param orderingStrategy - Whether to assign a fractional key to the moved block
  */
-declare function reparentBlockIndex<T extends BaseBlock>(state: BlockIndex<T>, activeId: UniqueIdentifier, targetZone: string, containerTypes?: readonly string[]): BlockIndex<T>;
+declare function reparentBlockIndex<T extends BaseBlock>(state: BlockIndex<T>, activeId: UniqueIdentifier, targetZone: string, containerTypes?: readonly string[], orderingStrategy?: OrderingStrategy, maxDepth?: number): BlockIndex<T>;
+/**
+ * Compute the depth of a block by walking its parentId chain.
+ * Root-level blocks have depth 1.
+ */
+declare function getBlockDepth<T extends BaseBlock>(index: BlockIndex<T>, blockId: string): number;
+/**
+ * Compute the maximum depth of a subtree rooted at blockId (inclusive).
+ * A leaf block returns 1.
+ */
+declare function getSubtreeDepth<T extends BaseBlock>(index: BlockIndex<T>, blockId: string): number;
 /**
  * Get all descendant IDs of a block
  */
 declare function getDescendantIds<T extends BaseBlock>(state: BlockIndex<T>, parentId: string): Set<string>;
+/**
+ * Reparent multiple blocks to a target zone, preserving their relative order.
+ * The first block in `blockIds` is treated as the primary (anchor) block.
+ */
+declare function reparentMultipleBlocks<T extends BaseBlock>(state: BlockIndex<T>, blockIds: string[], targetZone: string, containerTypes?: readonly string[], orderingStrategy?: OrderingStrategy, maxDepth?: number): BlockIndex<T>;
 /**
  * Delete a block and all its descendants
  */
@@ -526,5 +737,78 @@ declare function debounce<Args extends unknown[]>(fn: (...args: Args) => void, d
  * Generate a unique ID (simple implementation)
  */
 declare function generateId(): string;
+/**
+ * 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;
+
+/**
+ * A nested/tree representation of a block.
+ * Omits `parentId` and `order` since they are reconstructed during flattening.
+ */
+type NestedBlock<T extends BaseBlock> = Omit<T, 'parentId' | 'order'> & {
+    children: NestedBlock<T>[];
+};
+/**
+ * Convert a flat block array into a nested tree structure.
+ * Groups blocks by parentId, sorts siblings by order, and recursively builds children arrays.
+ */
+declare function flatToNested<T extends BaseBlock>(blocks: T[]): NestedBlock<T>[];
+/**
+ * Convert a nested tree structure back to a flat block array.
+ * DFS walk assigning parentId and integer order on the way down.
+ */
+declare function nestedToFlat<T extends BaseBlock>(nested: NestedBlock<T>[]): T[];
+
+/**
+ * Fractional indexing utilities
+ *
+ * Generates lexicographically sortable string keys that allow insertion between
+ * any two existing keys without reindexing siblings. Suitable for CRDT-based
+ * collaborative editing.
+ *
+ * Alphabet: 0-9a-z (base 36). Lexicographic order matches semantic order since
+ * '0' < '1' < ... < '9' < 'a' < ... < 'z' in ASCII.
+ */
+/**
+ * Generate a key that sorts strictly between `lo` and `hi`.
+ *
+ * @param lo - Lower bound (null means no lower bound)
+ * @param hi - Upper bound (null means no upper bound)
+ */
+declare function generateKeyBetween(lo: string | null, hi: string | null): string;
+/**
+ * Generate `n` evenly distributed keys between `lo` and `hi` using binary
+ * subdivision. Keys grow at O(log n) depth, avoiding unbounded length.
+ *
+ * @param lo - Lower bound (null means no lower bound)
+ * @param hi - Upper bound (null means no upper bound)
+ * @param n  - Number of keys to generate
+ */
+declare function generateNKeysBetween(lo: string | null, hi: string | null, n: number): string[];
+/**
+ * Generate initial keys for `n` items starting from an empty list.
+ */
+declare function generateInitialKeys(n: number): string[];
+/**
+ * Compare two fractional keys lexicographically.
+ * Returns negative if a < b, positive if a > b, 0 if equal.
+ */
+declare function compareFractionalKeys(a: string, b: string): number;
+/**
+ * Assign initial fractional `order` keys to a flat array of blocks.
+ *
+ * Groups siblings by `parentId`, sorts each group by existing `order`, then
+ * assigns evenly-distributed fractional keys via binary subdivision.
+ *
+ * Use this to migrate an integer-ordered (or unkeyed) dataset to fractional
+ * ordering before passing blocks to a `BlockTree` with `orderingStrategy="fractional"`.
+ */
+declare function initFractionalOrder<T extends {
+    id: string;
+    parentId: string | null;
+    order: number | string;
+}>(blocks: T[]): T[];
 
-export { type AnimationConfig, type AutoExpandConfig, type BaseBlock, type BlockAction, type BlockIndex, type BlockMoveEvent, type BlockPosition, type BlockRendererProps, type BlockRenderers, type BlockStateContextValue, type BlockStateProviderProps, BlockTree, type BlockTreeCallbacks, type BlockTreeConfig, type BlockTreeCustomization, type BlockTreeProps, type CanDragFn, type CanDropFn, type ContainerRendererProps, type DragEndEvent, type DragMoveEvent, DragOverlay, type DragOverlayProps$1 as DragOverlayProps, type DragStartEvent, DropZone, type DropZoneConfig, type DropZoneProps, type DropZoneType, type ExpandChangeEvent, type HoverChangeEvent, type IdGeneratorFn, type InternalRenderers, type RendererPropsFor, type SensorConfig, TreeRenderer, type TreeRendererProps, type TreeStateContextValue, type TreeStateProviderProps, buildOrderedBlocks, cloneMap, cloneParentMap, closestCenterCollision, computeNormalizedIndex, createBlockState, createStickyCollision, createTreeState, debounce, deleteBlockAndDescendants, extractBlockId, extractUUID, generateId, getDescendantIds, getDropZoneType, getSensorConfig, reparentBlockIndex, useConfiguredSensors, weightedVerticalCollision };
+export { type AnimationConfig, type AutoExpandConfig, type BaseBlock, type BlockAction, type BlockAddEvent, type BlockDeleteEvent, type BlockIndex, type BlockMoveEvent, type BlockPosition, type BlockRendererProps, type BlockRenderers, type BlockStateContextValue, type BlockStateProviderProps, BlockTree, type BlockTreeCallbacks, type BlockTreeConfig, type BlockTreeCustomization, type BlockTreeProps, BlockTreeSSR, type BlockTreeSSRProps, type CanDragFn, type CanDropFn, type ContainerRendererProps, type DragEndEvent, type DragMoveEvent, DragOverlay, type DragOverlayProps$1 as DragOverlayProps, type DragStartEvent, DropZone, type DropZoneConfig, type DropZoneProps, type DropZoneType, type ExpandChangeEvent, type HoverChangeEvent, type IdGeneratorFn, type InternalRenderers, type MoveOperation, type NestedBlock, type OrderingStrategy, type RendererPropsFor, type SensorConfig, TreeRenderer, type TreeRendererProps, type TreeStateContextValue, type TreeStateProviderProps, type UseBlockHistoryOptions, type UseBlockHistoryResult, type UseLayoutAnimationOptions, type UseVirtualTreeOptions, type UseVirtualTreeResult, buildOrderedBlocks, cloneMap, cloneParentMap, closestCenterCollision, compareFractionalKeys, computeNormalizedIndex, createBlockState, createStickyCollision, createTreeState, debounce, deleteBlockAndDescendants, extractBlockId, extractUUID, flatToNested, generateId, generateInitialKeys, generateKeyBetween, generateNKeysBetween, getBlockDepth, getDescendantIds, getDropZoneType, getSensorConfig, getSubtreeDepth, initFractionalOrder, nestedToFlat, reparentBlockIndex, reparentMultipleBlocks, triggerHaptic, useBlockHistory, useConfiguredSensors, useLayoutAnimation, useVirtualTree, weightedVerticalCollision };