dnd-block-tree 1.0.0 → 1.2.0

package/README.md

@@ -1,12 +1,8 @@
 # dnd-block-tree
 
 [![npm version](https://img.shields.io/npm/v/dnd-block-tree.svg)](https://www.npmjs.com/package/dnd-block-tree)
-[![npm downloads](https://img.shields.io/npm/dm/dnd-block-tree.svg)](https://www.npmjs.com/package/dnd-block-tree)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/dnd-block-tree)](https://bundlephobia.com/package/dnd-block-tree)
 [![CI](https://github.com/thesandybridge/dnd-block-tree/actions/workflows/ci.yml/badge.svg)](https://github.com/thesandybridge/dnd-block-tree/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
-[![demo](https://img.shields.io/badge/demo-live-brightgreen.svg)](https://dnd-block-tree.vercel.app)
+[![demo](https://img.shields.io/badge/demo-live-brightgreen.svg)](https://blocktree.sandybridge.io)
 
 A headless React library for building hierarchical drag-and-drop interfaces. Bring your own components, we handle the complexity.
 
@@ -517,7 +513,7 @@ Enable accessible tree navigation with the `keyboardNavigation` prop:
 | Home | Focus first block |
 | End | Focus last block |
 
-Blocks receive `data-block-id` and `tabIndex` attributes for focus management, and the tree root gets `role="tree"`.
+Blocks receive `data-block-id` and `tabIndex` attributes for focus management, and the tree root gets `role="tree"`. Each block element includes WAI-ARIA TreeView attributes: `aria-level`, `aria-posinset`, `aria-setsize`, `aria-expanded` (containers only), and `aria-selected`.
 
 ## Multi-Select Drag
 
@@ -689,6 +685,7 @@ import {
   deleteBlockAndDescendants,  // Remove a block and all its descendants from index
   getBlockDepth,              // Compute depth of a block (root = 1)
   getSubtreeDepth,            // Max depth of a subtree (leaf = 1)
+  validateBlockTree,          // Validate tree for cycles, orphans, stale refs
 
   // Serialization
   flatToNested,               // Convert flat block array to nested tree
@@ -716,10 +713,19 @@ import {
   createStickyCollision,      // Hysteresis wrapper with snapshot support
   type SnapshotRectsRef,      // Ref type for frozen zone rects
 
+  // Internal helpers
+  cloneMap,                   // Clone a Map
+  cloneParentMap,             // Deep clone a parent->children Map
+  debounce,                   // Debounce with cancel()
+
   // Hooks
+  createBlockState,           // Factory for block state context + provider
+  createTreeState,            // Factory for tree UI state context + provider
   useBlockHistory,            // Undo/redo state management
   useLayoutAnimation,         // FLIP-based reorder animations
   useVirtualTree,             // Virtual scrolling primitives
+  useConfiguredSensors,       // Configure dnd-kit sensors
+  getSensorConfig,            // Get sensor config from SensorConfig
 
   // Components
   BlockTree,                  // Main drag-and-drop tree component
@@ -732,7 +738,7 @@ import {
 
 ## Demo
 
-Check out the [live demo](https://dnd-block-tree.vercel.app) to see the library in action with two example use cases:
+Check out the [live demo](https://blocktree.sandybridge.io) to see the library in action with two example use cases:
 
 - **Productivity** - Sections, tasks, and notes with undo/redo, max depth control, and keyboard navigation
 - **File System** - Folders and files

package/dist/index.d.mts

@@ -389,6 +389,78 @@ interface TreeStateProviderProps<T extends BaseBlock = BaseBlock> {
     blockMap: Map<string, T>;
 }
 
+/**
+ * Clone a Map
+ */
+declare function cloneMap<K, V>(map: Map<K, V>): Map<K, V>;
+/**
+ * Clone a parent map with arrays
+ */
+declare function cloneParentMap(map: Map<string | null, string[]>): Map<string | null, string[]>;
+/**
+ * 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[], orderingStrategy?: OrderingStrategy): BlockIndex<T>;
+/**
+ * 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[], orderingStrategy?: OrderingStrategy): T[];
+/**
+ * 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[], 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, visited?: Set<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>;
+/**
+ * Result of validating a block tree
+ */
+interface TreeValidationResult {
+    valid: boolean;
+    issues: string[];
+}
+/**
+ * Validate a block tree index for structural integrity.
+ * Checks for cycles, orphans (parentId references non-existent block),
+ * and stale refs (byParent lists IDs not present in byId).
+ *
+ * Opt-in utility — not called automatically.
+ */
+declare function validateBlockTree<T extends BaseBlock>(index: BlockIndex<T>): TreeValidationResult;
+/**
+ * Delete a block and all its descendants
+ */
+declare function deleteBlockAndDescendants<T extends BaseBlock>(state: BlockIndex<T>, id: string): BlockIndex<T>;
+
 type SnapshotRectsRef = {
     current: Map<UniqueIdentifier, DOMRect> | null;
 };
@@ -527,7 +599,8 @@ interface TreeRendererProps<T extends BaseBlock> {
 /**
  * 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, focusedId, selectedIds, onBlockClick, animation, virtualVisibleIds, }: TreeRendererProps<T>): react_jsx_runtime.JSX.Element;
+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;
@@ -672,63 +745,6 @@ interface UseVirtualTreeResult {
  */
 declare function useVirtualTree({ containerRef, itemCount, itemHeight, overscan, }: UseVirtualTreeOptions): UseVirtualTreeResult;
 
-/**
- * Clone a Map
- */
-declare function cloneMap<K, V>(map: Map<K, V>): Map<K, V>;
-/**
- * Clone a parent map with arrays
- */
-declare function cloneParentMap(map: Map<string | null, string[]>): Map<string | null, string[]>;
-/**
- * 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[], orderingStrategy?: OrderingStrategy): BlockIndex<T>;
-/**
- * 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[], orderingStrategy?: OrderingStrategy): T[];
-/**
- * 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[], 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
- */
-declare function deleteBlockAndDescendants<T extends BaseBlock>(state: BlockIndex<T>, id: string): BlockIndex<T>;
-
 /**
  * Extract UUID from a zone ID by removing the prefix (before-, after-, into-, end-)
  */
@@ -749,6 +765,42 @@ declare function generateId(): string;
  */
 declare function triggerHaptic(durationMs?: number): void;
 
+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;
+    /** Label function for diff view (default: block.type) */
+    getLabel?: (block: T) => string;
+    /** Initial open state (default: false) */
+    initialOpen?: boolean;
+    /** Position of the trigger button (default: 'bottom-left') */
+    position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
+    /** Custom inline styles for the trigger button */
+    buttonStyle?: React.CSSProperties;
+    /** Custom inline styles for the card panel */
+    panelStyle?: React.CSSProperties;
+}
+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, }: BlockTreeDevToolsProps<T>): react_jsx_runtime.JSX.Element;
+
 /**
  * A nested/tree representation of a block.
  * Omits `parentId` and `order` since they are reconstructed during flattening.
@@ -817,4 +869,4 @@ declare function initFractionalOrder<T extends {
     order: number | string;
 }>(blocks: T[]): T[];
 
-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 };
+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, BlockTreeDevTools, type BlockTreeDevToolsProps, type BlockTreeProps, BlockTreeSSR, type BlockTreeSSRProps, type CanDragFn, type CanDropFn, type ContainerRendererProps, type DevToolsCallbacks, type DevToolsEventEntry, 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 TreeValidationResult, 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, useDevToolsCallbacks, useLayoutAnimation, useVirtualTree, validateBlockTree, weightedVerticalCollision };

package/dist/index.d.ts

@@ -389,6 +389,78 @@ interface TreeStateProviderProps<T extends BaseBlock = BaseBlock> {
     blockMap: Map<string, T>;
 }
 
+/**
+ * Clone a Map
+ */
+declare function cloneMap<K, V>(map: Map<K, V>): Map<K, V>;
+/**
+ * Clone a parent map with arrays
+ */
+declare function cloneParentMap(map: Map<string | null, string[]>): Map<string | null, string[]>;
+/**
+ * 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[], orderingStrategy?: OrderingStrategy): BlockIndex<T>;
+/**
+ * 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[], orderingStrategy?: OrderingStrategy): T[];
+/**
+ * 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[], 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, visited?: Set<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>;
+/**
+ * Result of validating a block tree
+ */
+interface TreeValidationResult {
+    valid: boolean;
+    issues: string[];
+}
+/**
+ * Validate a block tree index for structural integrity.
+ * Checks for cycles, orphans (parentId references non-existent block),
+ * and stale refs (byParent lists IDs not present in byId).
+ *
+ * Opt-in utility — not called automatically.
+ */
+declare function validateBlockTree<T extends BaseBlock>(index: BlockIndex<T>): TreeValidationResult;
+/**
+ * Delete a block and all its descendants
+ */
+declare function deleteBlockAndDescendants<T extends BaseBlock>(state: BlockIndex<T>, id: string): BlockIndex<T>;
+
 type SnapshotRectsRef = {
     current: Map<UniqueIdentifier, DOMRect> | null;
 };
@@ -527,7 +599,8 @@ interface TreeRendererProps<T extends BaseBlock> {
 /**
  * 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, focusedId, selectedIds, onBlockClick, animation, virtualVisibleIds, }: TreeRendererProps<T>): react_jsx_runtime.JSX.Element;
+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;
@@ -672,63 +745,6 @@ interface UseVirtualTreeResult {
  */
 declare function useVirtualTree({ containerRef, itemCount, itemHeight, overscan, }: UseVirtualTreeOptions): UseVirtualTreeResult;
 
-/**
- * Clone a Map
- */
-declare function cloneMap<K, V>(map: Map<K, V>): Map<K, V>;
-/**
- * Clone a parent map with arrays
- */
-declare function cloneParentMap(map: Map<string | null, string[]>): Map<string | null, string[]>;
-/**
- * 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[], orderingStrategy?: OrderingStrategy): BlockIndex<T>;
-/**
- * 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[], orderingStrategy?: OrderingStrategy): T[];
-/**
- * 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[], 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
- */
-declare function deleteBlockAndDescendants<T extends BaseBlock>(state: BlockIndex<T>, id: string): BlockIndex<T>;
-
 /**
  * Extract UUID from a zone ID by removing the prefix (before-, after-, into-, end-)
  */
@@ -749,6 +765,42 @@ declare function generateId(): string;
  */
 declare function triggerHaptic(durationMs?: number): void;
 
+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;
+    /** Label function for diff view (default: block.type) */
+    getLabel?: (block: T) => string;
+    /** Initial open state (default: false) */
+    initialOpen?: boolean;
+    /** Position of the trigger button (default: 'bottom-left') */
+    position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
+    /** Custom inline styles for the trigger button */
+    buttonStyle?: React.CSSProperties;
+    /** Custom inline styles for the card panel */
+    panelStyle?: React.CSSProperties;
+}
+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, }: BlockTreeDevToolsProps<T>): react_jsx_runtime.JSX.Element;
+
 /**
  * A nested/tree representation of a block.
  * Omits `parentId` and `order` since they are reconstructed during flattening.
@@ -817,4 +869,4 @@ declare function initFractionalOrder<T extends {
     order: number | string;
 }>(blocks: T[]): T[];
 
-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 };
+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, BlockTreeDevTools, type BlockTreeDevToolsProps, type BlockTreeProps, BlockTreeSSR, type BlockTreeSSRProps, type CanDragFn, type CanDropFn, type ContainerRendererProps, type DevToolsCallbacks, type DevToolsEventEntry, 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 TreeValidationResult, 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, useDevToolsCallbacks, useLayoutAnimation, useVirtualTree, validateBlockTree, weightedVerticalCollision };