dnd-block-tree 0.4.0 → 0.5.0

package/README.md

@@ -15,7 +15,7 @@ A headless React library for building hierarchical drag-and-drop interfaces. Bri
 - **Stable Drop Zones** - Zones render based on original block positions, not preview state, ensuring consistent drop targets during drag
 - **Ghost Preview** - Semi-transparent preview shows where blocks will land without affecting zone positions
 - **Depth-Aware Collision** - Smart algorithm prefers nested zones when cursor is at indented levels, with hysteresis to prevent flickering
-- **Mobile & Touch Support** - Separate touch/pointer activation constraints prevent interference with scrolling on mobile devices
+- **Mobile & Touch Support** - Separate touch/pointer activation constraints with configurable `longPressDelay` and optional `hapticFeedback`
 - **Snapshot-Based Computation** - State captured at drag start. All preview computations use snapshot, ensuring consistent behavior
 - **Debounced Preview** - 150ms debounced virtual state for smooth drag previews without jitter
 - **Customizable Drag Rules** - `canDrag` and `canDrop` filters for fine-grained control over drag behavior
@@ -25,6 +25,10 @@ A headless React library for building hierarchical drag-and-drop interfaces. Bri
 - **Undo/Redo** - Composable `useBlockHistory` hook with past/future stacks for state history management
 - **Lifecycle Callbacks** - `onBlockAdd`, `onBlockDelete`, `onBlockMove`, `onBeforeMove` middleware, and more
 - **Fractional Indexing** - Opt-in CRDT-compatible ordering via `orderingStrategy: 'fractional'`
+- **Serialization** - `flatToNested` / `nestedToFlat` converters for flat array ↔ nested tree transforms
+- **SSR Compatible** - `BlockTreeSSR` wrapper for hydration-safe rendering in Next.js and other SSR environments
+- **Animation Support** - CSS expand/collapse transitions via `AnimationConfig` and FLIP reorder animations via `useLayoutAnimation`
+- **Virtual Scrolling** - Windowed rendering for large trees (1000+ blocks) via `virtualize` prop
 
 ## Installation
 
@@ -83,12 +87,17 @@ function App() {
 | `showDropPreview` | `boolean` | `true` | Show live preview of block at drop position |
 | `canDrag` | `(block: T) => boolean` | - | Filter which blocks can be dragged |
 | `canDrop` | `(block, zone, target) => boolean` | - | Filter valid drop targets |
+| `collisionDetection` | `CollisionDetection` | sticky | Custom collision detection algorithm (from `@dnd-kit/core`) |
+| `sensors` | `SensorConfig` | - | Sensor configuration (see [Sensor Config](#sensor-config)) |
+| `animation` | `AnimationConfig` | - | Animation configuration (see [Animation](#animation--transitions)) |
 | `maxDepth` | `number` | - | Maximum nesting depth (1 = flat, 2 = one level, etc.) |
 | `keyboardNavigation` | `boolean` | `false` | Enable keyboard navigation with arrow keys |
 | `multiSelect` | `boolean` | `false` | Enable multi-select with Cmd/Ctrl+Click and Shift+Click |
 | `selectedIds` | `Set<string>` | - | Externally-controlled selected IDs (for multi-select) |
 | `onSelectionChange` | `(ids: Set<string>) => void` | - | Called when selection changes |
 | `orderingStrategy` | `'integer' \| 'fractional'` | `'integer'` | Sibling ordering strategy |
+| `initialExpanded` | `string[] \| 'all' \| 'none'` | `'all'` | Initially expanded container IDs |
+| `virtualize` | `{ itemHeight: number; overscan?: number }` | - | Enable virtual scrolling (see [Virtual Scrolling](#virtual-scrolling)) |
 | `className` | `string` | - | Root container class |
 | `dropZoneClassName` | `string` | - | Drop zone class |
 | `dropZoneActiveClassName` | `string` | - | Active drop zone class |
@@ -109,6 +118,145 @@ function App() {
 | `onExpandChange` | `(event: ExpandChangeEvent<T>) => void` | Called when expand/collapse changes |
 | `onHoverChange` | `(event: HoverChangeEvent<T>) => void` | Called when hover zone changes |
 
+### Sensor Config
+
+```typescript
+interface SensorConfig {
+  /** Distance in pixels before drag starts (default: 8) */
+  activationDistance?: number
+  /** Delay in ms before drag starts (overrides distance) */
+  activationDelay?: number
+  /** Tolerance in px for delay-based activation (default: 5) */
+  tolerance?: number
+  /** Override the default long-press delay for touch sensors (default: 200ms) */
+  longPressDelay?: number
+  /** Trigger haptic feedback (vibration) on drag start for touch devices */
+  hapticFeedback?: boolean
+}
+```
+
+```tsx
+<BlockTree
+  sensors={{
+    longPressDelay: 300,    // 300ms long-press for touch
+    hapticFeedback: true,   // Vibrate on drag start
+  }}
+  ...
+/>
+```
+
+### Animation Config
+
+```typescript
+interface AnimationConfig {
+  /** Duration for expand/collapse animations in ms */
+  expandDuration?: number
+  /** Duration for drag overlay animation in ms */
+  dragOverlayDuration?: number
+  /** Easing function (CSS timing function, default: 'ease') */
+  easing?: string
+}
+```
+
+### Event Types
+
+All event types are exported and generic over your block type `T`.
+
+#### DragStartEvent
+
+```typescript
+interface DragStartEvent<T> {
+  block: T
+  blockId: string
+}
+```
+
+#### DragMoveEvent
+
+```typescript
+interface DragMoveEvent<T> {
+  block: T
+  blockId: string
+  overZone: string | null       // Current hover zone ID
+  coordinates: { x: number; y: number }
+}
+```
+
+#### DragEndEvent
+
+```typescript
+interface DragEndEvent<T> {
+  block: T
+  blockId: string
+  targetZone: string | null     // Zone where block was dropped
+  cancelled: boolean
+}
+```
+
+#### BlockMoveEvent
+
+```typescript
+interface BlockMoveEvent<T> {
+  block: T
+  from: BlockPosition           // { parentId, index }
+  to: BlockPosition
+  blocks: T[]                   // Full block array after the move
+  movedIds: string[]            // All moved block IDs (for multi-select)
+}
+```
+
+#### MoveOperation
+
+Passed to the `onBeforeMove` middleware:
+
+```typescript
+interface MoveOperation<T> {
+  block: T
+  from: BlockPosition
+  targetZone: string            // Drop zone ID (e.g. "after-uuid", "into-uuid")
+}
+```
+
+#### BlockAddEvent
+
+```typescript
+interface BlockAddEvent<T> {
+  block: T
+  parentId: string | null
+  index: number
+}
+```
+
+#### BlockDeleteEvent
+
+```typescript
+interface BlockDeleteEvent<T> {
+  block: T
+  deletedIds: string[]          // Block + all descendant IDs
+  parentId: string | null
+}
+```
+
+#### ExpandChangeEvent
+
+```typescript
+interface ExpandChangeEvent<T> {
+  block: T
+  blockId: string
+  expanded: boolean
+}
+```
+
+#### HoverChangeEvent
+
+```typescript
+interface HoverChangeEvent<T> {
+  zoneId: string | null
+  zoneType: 'before' | 'after' | 'into' | null
+  targetBlock: T | null
+}
+```
+
 ### Types
 
 #### BaseBlock
@@ -150,6 +298,182 @@ interface ContainerRendererProps<T extends BaseBlock> extends BlockRendererProps
 }
 ```
 
+#### NestedBlock
+
+Tree representation used by serialization helpers:
+
+```typescript
+type NestedBlock<T extends BaseBlock> = Omit<T, 'parentId' | 'order'> & {
+  children: NestedBlock<T>[]
+}
+```
+
+## Serialization Helpers
+
+Convert between flat block arrays and nested tree structures:
+
+```tsx
+import { flatToNested, nestedToFlat, type NestedBlock } from 'dnd-block-tree'
+
+// Flat array -> nested tree (e.g. for JSON export)
+const nested: NestedBlock<MyBlock>[] = flatToNested(blocks)
+
+// Nested tree -> flat array (e.g. for JSON import)
+const flat: MyBlock[] = nestedToFlat(nested)
+```
+
+`flatToNested` groups by `parentId`, sorts siblings by `order`, and recursively builds `children` arrays. `parentId` and `order` are omitted from the output since they're structural.
+
+`nestedToFlat` performs a DFS walk, assigning `parentId` and integer `order` on the way down.
+
+## SSR Compatibility
+
+For Next.js App Router or other SSR environments, use `BlockTreeSSR` to avoid hydration mismatches:
+
+```tsx
+import { BlockTreeSSR } from 'dnd-block-tree'
+
+function Page() {
+  return (
+    <BlockTreeSSR
+      blocks={blocks}
+      renderers={renderers}
+      containerTypes={CONTAINER_TYPES}
+      onChange={setBlocks}
+      fallback={<div>Loading tree...</div>}
+    />
+  )
+}
+```
+
+`BlockTreeSSR` renders the `fallback` (default: `null`) on the server, then mounts the full `BlockTree` after hydration via `useEffect`. All `BlockTree` props are passed through.
+
+```typescript
+interface BlockTreeSSRProps<T, C> extends BlockTreeProps<T, C> {
+  fallback?: ReactNode
+}
+```
+
+## Animation & Transitions
+
+### Expand/Collapse Transitions
+
+Pass an `AnimationConfig` to enable CSS transitions on container expand/collapse:
+
+```tsx
+<BlockTree
+  animation={{
+    expandDuration: 200,    // ms
+    easing: 'ease-in-out',  // CSS timing function
+  }}
+  ...
+/>
+```
+
+### FLIP Reorder Animation
+
+The `useLayoutAnimation` hook provides FLIP-based (First-Last-Invert-Play) animations for block reorder transitions. It's a standalone composable — not built into BlockTree:
+
+```tsx
+import { useLayoutAnimation } from 'dnd-block-tree'
+
+function MyTree() {
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  useLayoutAnimation(containerRef, {
+    duration: 200,          // Transition duration in ms (default: 200)
+    easing: 'ease',         // CSS easing (default: 'ease')
+    selector: '[data-block-id]',  // Selector for animated children (default)
+  })
+
+  return (
+    <div ref={containerRef}>
+      <BlockTree ... />
+    </div>
+  )
+}
+```
+
+```typescript
+interface UseLayoutAnimationOptions {
+  duration?: number    // default: 200
+  easing?: string      // default: 'ease'
+  selector?: string    // default: '[data-block-id]'
+}
+```
+
+## Virtual Scrolling
+
+Enable windowed rendering for large trees (1000+ blocks) with the `virtualize` prop:
+
+```tsx
+<BlockTree
+  virtualize={{
+    itemHeight: 40,   // Fixed height of each item in pixels
+    overscan: 5,      // Extra items rendered outside viewport (default: 5)
+  }}
+  blocks={blocks}
+  ...
+/>
+```
+
+When enabled, only visible blocks (plus overscan) are rendered. The tree is wrapped in a scrollable container with a spacer div maintaining correct total height.
+
+**Limitations:** Fixed item height only. Variable height items are not supported.
+
+### useVirtualTree Hook
+
+For custom virtual scrolling implementations outside of BlockTree:
+
+```tsx
+import { useVirtualTree } from 'dnd-block-tree'
+
+const containerRef = useRef<HTMLDivElement>(null)
+const { visibleRange, totalHeight, offsetY } = useVirtualTree({
+  containerRef,
+  itemCount: 1000,
+  itemHeight: 40,
+  overscan: 5,
+})
+```
+
+```typescript
+interface UseVirtualTreeOptions {
+  containerRef: React.RefObject<HTMLElement | null>
+  itemCount: number
+  itemHeight: number
+  overscan?: number   // default: 5
+}
+
+interface UseVirtualTreeResult {
+  visibleRange: { start: number; end: number }
+  totalHeight: number
+  offsetY: number
+}
+```
+
+## Touch & Mobile
+
+Touch support is built-in with sensible defaults (200ms long-press, 5px tolerance). For fine-tuning:
+
+```tsx
+<BlockTree
+  sensors={{
+    longPressDelay: 300,    // Override default 200ms touch activation
+    hapticFeedback: true,   // Vibrate on drag start (uses navigator.vibrate)
+  }}
+  ...
+/>
+```
+
+The `triggerHaptic` utility is also exported for use in custom components:
+
+```tsx
+import { triggerHaptic } from 'dnd-block-tree'
+
+triggerHaptic(10)  // Vibrate for 10ms (default)
+```
+
 ## Undo/Redo
 
 The `useBlockHistory` hook provides undo/redo support as a composable layer on top of `BlockTree`:
@@ -222,6 +546,87 @@ Limit nesting depth to prevent deeply nested trees:
 - `maxDepth={2}` - blocks can nest one level inside containers
 - When a move would exceed the limit, the drop zone is rejected and the move is a no-op
 
+## Move Middleware (`onBeforeMove`)
+
+The `onBeforeMove` callback intercepts moves before they are committed. You can use it to validate, transform, or cancel moves:
+
+```tsx
+<BlockTree
+  blocks={blocks}
+  onChange={setBlocks}
+  onBeforeMove={(operation) => {
+    // Cancel: return false to prevent the move
+    if (operation.block.type === 'locked') {
+      return false
+    }
+
+    // Transform: change the target zone
+    if (operation.targetZone.startsWith('into-') && someCondition) {
+      return { ...operation, targetZone: `after-${extractBlockId(operation.targetZone)}` }
+    }
+
+    // Allow: return void/undefined to proceed as-is
+  }}
+/>
+```
+
+The middleware receives a `MoveOperation` with the block, its original position (`from`), and the target drop zone. Returning:
+- `false` cancels the move entirely
+- A modified `MoveOperation` transforms the move (e.g. redirect to a different zone)
+- `void` / `undefined` allows the move as-is
+
+## Fractional Indexing
+
+By default, siblings are reindexed `0, 1, 2, ...` on every move. For collaborative or CRDT-compatible scenarios, use fractional indexing:
+
+```tsx
+import { BlockTree, initFractionalOrder } from 'dnd-block-tree'
+
+// Convert existing blocks to fractional ordering
+const [blocks, setBlocks] = useState(() => initFractionalOrder(initialBlocks))
+
+<BlockTree
+  blocks={blocks}
+  onChange={setBlocks}
+  orderingStrategy="fractional"
+/>
+```
+
+With fractional ordering, only the moved block receives a new `order` value (a lexicographically sortable string key). Siblings are never reindexed, making it safe for concurrent edits.
+
+Related utilities:
+
+```typescript
+import {
+  generateKeyBetween,     // Generate a key between two existing keys
+  generateNKeysBetween,   // Generate N keys between two existing keys
+  generateInitialKeys,    // Generate N evenly-spaced initial keys
+  initFractionalOrder,    // Convert integer-ordered blocks to fractional
+  compareFractionalKeys,  // Compare two fractional keys
+} from 'dnd-block-tree'
+```
+
+## Collision Detection
+
+The library ships with three collision detection strategies:
+
+```typescript
+import {
+  weightedVerticalCollision,  // Default: edge-distance based, depth-aware
+  closestCenterCollision,     // Simple closest-center algorithm
+  createStickyCollision,      // Wraps any strategy with hysteresis to prevent flickering
+} from 'dnd-block-tree'
+
+// Use a custom collision strategy
+<BlockTree collisionDetection={closestCenterCollision} ... />
+
+// Or use the sticky wrapper with a custom threshold (px)
+const collision = createStickyCollision(20)
+<BlockTree collisionDetection={collision} ... />
+```
+
+You can also pass any `CollisionDetection` function from `@dnd-kit/core`.
+
 ## Type Safety
 
 The library provides automatic type inference for container vs non-container renderers:
@@ -245,20 +650,56 @@ const renderers: BlockRenderers<MyBlock, typeof CONTAINER_TYPES> = {
 
 ## Utilities
 
-The library exports several utility functions:
+The library exports utility functions for tree manipulation, ID generation, and zone parsing:
 
 ```typescript
 import {
-  computeNormalizedIndex,   // Convert flat array to normalized index
-  buildOrderedBlocks,       // Convert index back to ordered array
-  reparentBlockIndex,       // Move a block to a new position
-  reparentMultipleBlocks,   // Move multiple blocks preserving relative order
-  getDescendantIds,         // Get all descendant IDs of a block
-  getBlockDepth,            // Compute depth of a block in the tree
-  getSubtreeDepth,          // Compute max depth of a subtree
-  generateId,               // Generate unique block IDs
-  generateKeyBetween,       // Generate a fractional key between two keys
-  initFractionalOrder,      // Convert integer-ordered blocks to fractional
+  // Tree operations
+  computeNormalizedIndex,     // Convert flat array to { byId, byParent } index
+  buildOrderedBlocks,         // Convert index back to ordered flat array
+  reparentBlockIndex,         // Move a single block to a new position
+  reparentMultipleBlocks,     // Move multiple blocks preserving relative order
+  getDescendantIds,           // Get all descendant IDs of a block (Set)
+  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)
+
+  // Serialization
+  flatToNested,               // Convert flat block array to nested tree
+  nestedToFlat,               // Convert nested tree to flat block array
+
+  // ID / zone helpers
+  generateId,                 // Generate unique block IDs
+  extractUUID,                // Extract block ID from zone ID string
+  getDropZoneType,            // Parse zone type: 'before' | 'after' | 'into'
+  extractBlockId,             // Extract block ID from zone ID (alias)
+
+  // Touch
+  triggerHaptic,              // Trigger haptic feedback (navigator.vibrate)
+
+  // Fractional indexing
+  generateKeyBetween,         // Generate a fractional key between two keys
+  generateNKeysBetween,       // Generate N keys between two existing keys
+  generateInitialKeys,        // Generate N evenly-spaced initial keys
+  initFractionalOrder,        // Convert integer-ordered blocks to fractional
+  compareFractionalKeys,      // Compare two fractional keys
+
+  // Collision detection
+  weightedVerticalCollision,  // Edge-distance collision, depth-aware
+  closestCenterCollision,     // Simple closest-center collision
+  createStickyCollision,      // Hysteresis wrapper to prevent flickering
+
+  // Hooks
+  useBlockHistory,            // Undo/redo state management
+  useLayoutAnimation,         // FLIP-based reorder animations
+  useVirtualTree,             // Virtual scrolling primitives
+
+  // Components
+  BlockTree,                  // Main drag-and-drop tree component
+  BlockTreeSSR,               // SSR-safe wrapper
+  TreeRenderer,               // Recursive tree renderer
+  DropZone,                   // Individual drop zone
+  DragOverlay,                // Drag overlay wrapper
 } from 'dnd-block-tree'
 ```
 

package/dist/index.d.mts

@@ -213,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
@@ -466,12 +470,19 @@ interface BlockTreeProps<T extends BaseBlock, C extends readonly T['type'][] = r
     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, 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;
+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[];
@@ -502,11 +513,15 @@ interface TreeRendererProps<T extends BaseBlock> {
     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, focusedId, selectedIds, onBlockClick, }: 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;
@@ -536,6 +551,17 @@ interface DragOverlayProps<T extends BaseBlock> {
  */
 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
  */
@@ -588,6 +614,58 @@ interface UseBlockHistoryResult<T extends BaseBlock> {
  */
 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
  */
@@ -659,6 +737,29 @@ 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
@@ -710,4 +811,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, 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 };
+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 };