dnd-block-tree 0.4.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -213,6 +213,10 @@ interface SensorConfig {
213
213
  activationDistance?: number;
214
214
  activationDelay?: number;
215
215
  tolerance?: number;
216
+ /** Override the default long-press delay (200ms) for touch sensors */
217
+ longPressDelay?: number;
218
+ /** Trigger haptic feedback (vibration) on drag start for touch devices */
219
+ hapticFeedback?: boolean;
216
220
  }
217
221
  /**
218
222
  * Drop zone configuration
@@ -385,6 +389,9 @@ interface TreeStateProviderProps<T extends BaseBlock = BaseBlock> {
385
389
  blockMap: Map<string, T>;
386
390
  }
387
391
 
392
+ type SnapshotRectsRef = {
393
+ current: Map<UniqueIdentifier, DOMRect> | null;
394
+ };
388
395
  /**
389
396
  * Custom collision detection that scores drop zones by distance to nearest edge.
390
397
  * Uses edge-distance scoring with a bottom bias for more natural drag behavior.
@@ -400,8 +407,11 @@ declare const weightedVerticalCollision: CollisionDetection;
400
407
  * between adjacent drop zones.
401
408
  *
402
409
  * @param threshold - Minimum score improvement required to switch zones (default: 15px)
410
+ * @param snapshotRef - Optional ref to snapshotted zone rects. When populated,
411
+ * collision detection uses these frozen rects instead of live DOM measurements,
412
+ * preventing layout-shift feedback loops from in-flow ghost previews.
403
413
  */
404
- declare function createStickyCollision(threshold?: number): CollisionDetection & {
414
+ declare function createStickyCollision(threshold?: number, snapshotRef?: SnapshotRectsRef): CollisionDetection & {
405
415
  reset: () => void;
406
416
  };
407
417
  /**
@@ -466,12 +476,19 @@ interface BlockTreeProps<T extends BaseBlock, C extends readonly T['type'][] = r
466
476
  selectedIds?: Set<string>;
467
477
  /** Called when selection changes (for multi-select) */
468
478
  onSelectionChange?: (selectedIds: Set<string>) => void;
479
+ /** Enable virtual scrolling for large trees (fixed item height only) */
480
+ virtualize?: {
481
+ /** Fixed height of each item in pixels */
482
+ itemHeight: number;
483
+ /** Number of extra items to render outside the visible range (default: 5) */
484
+ overscan?: number;
485
+ };
469
486
  }
470
487
  /**
471
488
  * Main BlockTree component
472
489
  * Provides drag-and-drop functionality for hierarchical block structures
473
490
  */
474
- 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, initialExpanded, orderingStrategy, maxDepth, keyboardNavigation, multiSelect, selectedIds: externalSelectedIds, onSelectionChange, }: BlockTreeProps<T, C>): react_jsx_runtime.JSX.Element;
491
+ 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;
475
492
 
476
493
  interface TreeRendererProps<T extends BaseBlock> {
477
494
  blocks: T[];
@@ -502,11 +519,15 @@ interface TreeRendererProps<T extends BaseBlock> {
502
519
  selectedIds?: Set<string>;
503
520
  /** Click handler for multi-select */
504
521
  onBlockClick?: (blockId: string, event: React.MouseEvent) => void;
522
+ /** Animation configuration */
523
+ animation?: AnimationConfig;
524
+ /** When virtual scrolling is active, only render blocks in this set */
525
+ virtualVisibleIds?: Set<string> | null;
505
526
  }
506
527
  /**
507
528
  * Recursive tree renderer with smart drop zones
508
529
  */
509
- 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, }: TreeRendererProps<T>): react_jsx_runtime.JSX.Element;
530
+ 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;
510
531
 
511
532
  interface DropZoneProps {
512
533
  id: string;
@@ -536,6 +557,17 @@ interface DragOverlayProps<T extends BaseBlock> {
536
557
  */
537
558
  declare function DragOverlay<T extends BaseBlock>({ activeBlock, children, selectedCount, }: DragOverlayProps<T>): react_jsx_runtime.JSX.Element;
538
559
 
560
+ interface BlockTreeSSRProps<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]> extends BlockTreeProps<T, C> {
561
+ /** Content to render before hydration completes (default: null) */
562
+ fallback?: ReactNode;
563
+ }
564
+ /**
565
+ * Hydration-safe wrapper for BlockTree in SSR environments.
566
+ * Renders the fallback (or nothing) on the server and during initial hydration,
567
+ * then mounts the full BlockTree after the client has hydrated.
568
+ */
569
+ declare function BlockTreeSSR<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]>({ fallback, ...props }: BlockTreeSSRProps<T, C>): react_jsx_runtime.JSX.Element;
570
+
539
571
  /**
540
572
  * Create block state context and hooks
541
573
  */
@@ -588,6 +620,58 @@ interface UseBlockHistoryResult<T extends BaseBlock> {
588
620
  */
589
621
  declare function useBlockHistory<T extends BaseBlock>(initialBlocks: T[], options?: UseBlockHistoryOptions): UseBlockHistoryResult<T>;
590
622
 
623
+ interface UseLayoutAnimationOptions {
624
+ /** Duration of the transition in ms (default: 200) */
625
+ duration?: number;
626
+ /** CSS easing function (default: 'ease') */
627
+ easing?: string;
628
+ /** CSS selector for animated children (default: '[data-block-id]') */
629
+ selector?: string;
630
+ }
631
+ /**
632
+ * FLIP-based layout animation hook for reorder transitions.
633
+ *
634
+ * Captures block positions before render (layout effect cleanup),
635
+ * computes the delta after render, and applies a CSS transform transition.
636
+ *
637
+ * Usage:
638
+ * ```tsx
639
+ * const containerRef = useRef<HTMLDivElement>(null)
640
+ * useLayoutAnimation(containerRef, { duration: 200 })
641
+ * return <div ref={containerRef}>...</div>
642
+ * ```
643
+ */
644
+ declare function useLayoutAnimation(containerRef: React.RefObject<HTMLElement | null>, options?: UseLayoutAnimationOptions): void;
645
+
646
+ interface UseVirtualTreeOptions {
647
+ /** Ref to the scrollable container element */
648
+ containerRef: React.RefObject<HTMLElement | null>;
649
+ /** Total number of items in the tree */
650
+ itemCount: number;
651
+ /** Fixed height of each item in pixels */
652
+ itemHeight: number;
653
+ /** Number of extra items to render outside the visible range (default: 5) */
654
+ overscan?: number;
655
+ }
656
+ interface UseVirtualTreeResult {
657
+ /** Start and end indices of the visible range (inclusive) */
658
+ visibleRange: {
659
+ start: number;
660
+ end: number;
661
+ };
662
+ /** Total height of all items for the spacer div */
663
+ totalHeight: number;
664
+ /** Offset from top for the first rendered item */
665
+ offsetY: number;
666
+ }
667
+ /**
668
+ * Lightweight fixed-height virtual scrolling hook for tree lists.
669
+ *
670
+ * Tracks scroll position on the container and computes which items
671
+ * should be rendered based on the viewport and overscan.
672
+ */
673
+ declare function useVirtualTree({ containerRef, itemCount, itemHeight, overscan, }: UseVirtualTreeOptions): UseVirtualTreeResult;
674
+
591
675
  /**
592
676
  * Clone a Map
593
677
  */
@@ -659,6 +743,29 @@ declare function debounce<Args extends unknown[]>(fn: (...args: Args) => void, d
659
743
  * Generate a unique ID (simple implementation)
660
744
  */
661
745
  declare function generateId(): string;
746
+ /**
747
+ * Trigger haptic feedback (vibration) on supported devices.
748
+ * Safe to call in any environment — no-ops when `navigator.vibrate` is unavailable.
749
+ */
750
+ declare function triggerHaptic(durationMs?: number): void;
751
+
752
+ /**
753
+ * A nested/tree representation of a block.
754
+ * Omits `parentId` and `order` since they are reconstructed during flattening.
755
+ */
756
+ type NestedBlock<T extends BaseBlock> = Omit<T, 'parentId' | 'order'> & {
757
+ children: NestedBlock<T>[];
758
+ };
759
+ /**
760
+ * Convert a flat block array into a nested tree structure.
761
+ * Groups blocks by parentId, sorts siblings by order, and recursively builds children arrays.
762
+ */
763
+ declare function flatToNested<T extends BaseBlock>(blocks: T[]): NestedBlock<T>[];
764
+ /**
765
+ * Convert a nested tree structure back to a flat block array.
766
+ * DFS walk assigning parentId and integer order on the way down.
767
+ */
768
+ declare function nestedToFlat<T extends BaseBlock>(nested: NestedBlock<T>[]): T[];
662
769
 
663
770
  /**
664
771
  * Fractional indexing utilities
@@ -710,4 +817,4 @@ declare function initFractionalOrder<T extends {
710
817
  order: number | string;
711
818
  }>(blocks: T[]): T[];
712
819
 
713
- 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, 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 OrderingStrategy, type RendererPropsFor, type SensorConfig, TreeRenderer, type TreeRendererProps, type TreeStateContextValue, type TreeStateProviderProps, type UseBlockHistoryOptions, type UseBlockHistoryResult, buildOrderedBlocks, cloneMap, cloneParentMap, closestCenterCollision, compareFractionalKeys, computeNormalizedIndex, createBlockState, createStickyCollision, createTreeState, debounce, deleteBlockAndDescendants, extractBlockId, extractUUID, generateId, generateInitialKeys, generateKeyBetween, generateNKeysBetween, getBlockDepth, getDescendantIds, getDropZoneType, getSensorConfig, getSubtreeDepth, initFractionalOrder, reparentBlockIndex, reparentMultipleBlocks, useBlockHistory, useConfiguredSensors, weightedVerticalCollision };
820
+ 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, type SnapshotRectsRef, 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 };
package/dist/index.d.ts CHANGED
@@ -213,6 +213,10 @@ interface SensorConfig {
213
213
  activationDistance?: number;
214
214
  activationDelay?: number;
215
215
  tolerance?: number;
216
+ /** Override the default long-press delay (200ms) for touch sensors */
217
+ longPressDelay?: number;
218
+ /** Trigger haptic feedback (vibration) on drag start for touch devices */
219
+ hapticFeedback?: boolean;
216
220
  }
217
221
  /**
218
222
  * Drop zone configuration
@@ -385,6 +389,9 @@ interface TreeStateProviderProps<T extends BaseBlock = BaseBlock> {
385
389
  blockMap: Map<string, T>;
386
390
  }
387
391
 
392
+ type SnapshotRectsRef = {
393
+ current: Map<UniqueIdentifier, DOMRect> | null;
394
+ };
388
395
  /**
389
396
  * Custom collision detection that scores drop zones by distance to nearest edge.
390
397
  * Uses edge-distance scoring with a bottom bias for more natural drag behavior.
@@ -400,8 +407,11 @@ declare const weightedVerticalCollision: CollisionDetection;
400
407
  * between adjacent drop zones.
401
408
  *
402
409
  * @param threshold - Minimum score improvement required to switch zones (default: 15px)
410
+ * @param snapshotRef - Optional ref to snapshotted zone rects. When populated,
411
+ * collision detection uses these frozen rects instead of live DOM measurements,
412
+ * preventing layout-shift feedback loops from in-flow ghost previews.
403
413
  */
404
- declare function createStickyCollision(threshold?: number): CollisionDetection & {
414
+ declare function createStickyCollision(threshold?: number, snapshotRef?: SnapshotRectsRef): CollisionDetection & {
405
415
  reset: () => void;
406
416
  };
407
417
  /**
@@ -466,12 +476,19 @@ interface BlockTreeProps<T extends BaseBlock, C extends readonly T['type'][] = r
466
476
  selectedIds?: Set<string>;
467
477
  /** Called when selection changes (for multi-select) */
468
478
  onSelectionChange?: (selectedIds: Set<string>) => void;
479
+ /** Enable virtual scrolling for large trees (fixed item height only) */
480
+ virtualize?: {
481
+ /** Fixed height of each item in pixels */
482
+ itemHeight: number;
483
+ /** Number of extra items to render outside the visible range (default: 5) */
484
+ overscan?: number;
485
+ };
469
486
  }
470
487
  /**
471
488
  * Main BlockTree component
472
489
  * Provides drag-and-drop functionality for hierarchical block structures
473
490
  */
474
- 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, initialExpanded, orderingStrategy, maxDepth, keyboardNavigation, multiSelect, selectedIds: externalSelectedIds, onSelectionChange, }: BlockTreeProps<T, C>): react_jsx_runtime.JSX.Element;
491
+ 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;
475
492
 
476
493
  interface TreeRendererProps<T extends BaseBlock> {
477
494
  blocks: T[];
@@ -502,11 +519,15 @@ interface TreeRendererProps<T extends BaseBlock> {
502
519
  selectedIds?: Set<string>;
503
520
  /** Click handler for multi-select */
504
521
  onBlockClick?: (blockId: string, event: React.MouseEvent) => void;
522
+ /** Animation configuration */
523
+ animation?: AnimationConfig;
524
+ /** When virtual scrolling is active, only render blocks in this set */
525
+ virtualVisibleIds?: Set<string> | null;
505
526
  }
506
527
  /**
507
528
  * Recursive tree renderer with smart drop zones
508
529
  */
509
- 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, }: TreeRendererProps<T>): react_jsx_runtime.JSX.Element;
530
+ 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;
510
531
 
511
532
  interface DropZoneProps {
512
533
  id: string;
@@ -536,6 +557,17 @@ interface DragOverlayProps<T extends BaseBlock> {
536
557
  */
537
558
  declare function DragOverlay<T extends BaseBlock>({ activeBlock, children, selectedCount, }: DragOverlayProps<T>): react_jsx_runtime.JSX.Element;
538
559
 
560
+ interface BlockTreeSSRProps<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]> extends BlockTreeProps<T, C> {
561
+ /** Content to render before hydration completes (default: null) */
562
+ fallback?: ReactNode;
563
+ }
564
+ /**
565
+ * Hydration-safe wrapper for BlockTree in SSR environments.
566
+ * Renders the fallback (or nothing) on the server and during initial hydration,
567
+ * then mounts the full BlockTree after the client has hydrated.
568
+ */
569
+ declare function BlockTreeSSR<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]>({ fallback, ...props }: BlockTreeSSRProps<T, C>): react_jsx_runtime.JSX.Element;
570
+
539
571
  /**
540
572
  * Create block state context and hooks
541
573
  */
@@ -588,6 +620,58 @@ interface UseBlockHistoryResult<T extends BaseBlock> {
588
620
  */
589
621
  declare function useBlockHistory<T extends BaseBlock>(initialBlocks: T[], options?: UseBlockHistoryOptions): UseBlockHistoryResult<T>;
590
622
 
623
+ interface UseLayoutAnimationOptions {
624
+ /** Duration of the transition in ms (default: 200) */
625
+ duration?: number;
626
+ /** CSS easing function (default: 'ease') */
627
+ easing?: string;
628
+ /** CSS selector for animated children (default: '[data-block-id]') */
629
+ selector?: string;
630
+ }
631
+ /**
632
+ * FLIP-based layout animation hook for reorder transitions.
633
+ *
634
+ * Captures block positions before render (layout effect cleanup),
635
+ * computes the delta after render, and applies a CSS transform transition.
636
+ *
637
+ * Usage:
638
+ * ```tsx
639
+ * const containerRef = useRef<HTMLDivElement>(null)
640
+ * useLayoutAnimation(containerRef, { duration: 200 })
641
+ * return <div ref={containerRef}>...</div>
642
+ * ```
643
+ */
644
+ declare function useLayoutAnimation(containerRef: React.RefObject<HTMLElement | null>, options?: UseLayoutAnimationOptions): void;
645
+
646
+ interface UseVirtualTreeOptions {
647
+ /** Ref to the scrollable container element */
648
+ containerRef: React.RefObject<HTMLElement | null>;
649
+ /** Total number of items in the tree */
650
+ itemCount: number;
651
+ /** Fixed height of each item in pixels */
652
+ itemHeight: number;
653
+ /** Number of extra items to render outside the visible range (default: 5) */
654
+ overscan?: number;
655
+ }
656
+ interface UseVirtualTreeResult {
657
+ /** Start and end indices of the visible range (inclusive) */
658
+ visibleRange: {
659
+ start: number;
660
+ end: number;
661
+ };
662
+ /** Total height of all items for the spacer div */
663
+ totalHeight: number;
664
+ /** Offset from top for the first rendered item */
665
+ offsetY: number;
666
+ }
667
+ /**
668
+ * Lightweight fixed-height virtual scrolling hook for tree lists.
669
+ *
670
+ * Tracks scroll position on the container and computes which items
671
+ * should be rendered based on the viewport and overscan.
672
+ */
673
+ declare function useVirtualTree({ containerRef, itemCount, itemHeight, overscan, }: UseVirtualTreeOptions): UseVirtualTreeResult;
674
+
591
675
  /**
592
676
  * Clone a Map
593
677
  */
@@ -659,6 +743,29 @@ declare function debounce<Args extends unknown[]>(fn: (...args: Args) => void, d
659
743
  * Generate a unique ID (simple implementation)
660
744
  */
661
745
  declare function generateId(): string;
746
+ /**
747
+ * Trigger haptic feedback (vibration) on supported devices.
748
+ * Safe to call in any environment — no-ops when `navigator.vibrate` is unavailable.
749
+ */
750
+ declare function triggerHaptic(durationMs?: number): void;
751
+
752
+ /**
753
+ * A nested/tree representation of a block.
754
+ * Omits `parentId` and `order` since they are reconstructed during flattening.
755
+ */
756
+ type NestedBlock<T extends BaseBlock> = Omit<T, 'parentId' | 'order'> & {
757
+ children: NestedBlock<T>[];
758
+ };
759
+ /**
760
+ * Convert a flat block array into a nested tree structure.
761
+ * Groups blocks by parentId, sorts siblings by order, and recursively builds children arrays.
762
+ */
763
+ declare function flatToNested<T extends BaseBlock>(blocks: T[]): NestedBlock<T>[];
764
+ /**
765
+ * Convert a nested tree structure back to a flat block array.
766
+ * DFS walk assigning parentId and integer order on the way down.
767
+ */
768
+ declare function nestedToFlat<T extends BaseBlock>(nested: NestedBlock<T>[]): T[];
662
769
 
663
770
  /**
664
771
  * Fractional indexing utilities
@@ -710,4 +817,4 @@ declare function initFractionalOrder<T extends {
710
817
  order: number | string;
711
818
  }>(blocks: T[]): T[];
712
819
 
713
- 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, 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 OrderingStrategy, type RendererPropsFor, type SensorConfig, TreeRenderer, type TreeRendererProps, type TreeStateContextValue, type TreeStateProviderProps, type UseBlockHistoryOptions, type UseBlockHistoryResult, buildOrderedBlocks, cloneMap, cloneParentMap, closestCenterCollision, compareFractionalKeys, computeNormalizedIndex, createBlockState, createStickyCollision, createTreeState, debounce, deleteBlockAndDescendants, extractBlockId, extractUUID, generateId, generateInitialKeys, generateKeyBetween, generateNKeysBetween, getBlockDepth, getDescendantIds, getDropZoneType, getSensorConfig, getSubtreeDepth, initFractionalOrder, reparentBlockIndex, reparentMultipleBlocks, useBlockHistory, useConfiguredSensors, weightedVerticalCollision };
820
+ 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, type SnapshotRectsRef, 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 };