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/README.md +482 -14
- package/dist/index.d.mts +111 -4
- package/dist/index.d.ts +111 -4
- package/dist/index.js +311 -48
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +307 -50
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
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 };
|