dnd-block-tree 0.2.0 → 0.4.0

package/README.md

@@ -1,5 +1,13 @@
 # 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)
+
 A headless React library for building hierarchical drag-and-drop interfaces. Bring your own components, we handle the complexity.
 
 ## Features
@@ -7,10 +15,16 @@ 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
-- **8px Activation Distance** - Prevents accidental drags. Pointer must move 8px before drag starts, allowing normal clicks
+- **Mobile & Touch Support** - Separate touch/pointer activation constraints prevent interference with scrolling on mobile devices
 - **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
+- **Max Depth Constraint** - Limit nesting depth via `maxDepth` prop, enforced in both drag validation and programmatic APIs
+- **Keyboard Navigation** - Arrow key traversal, Enter/Space to expand/collapse, Home/End to jump. Opt-in via `keyboardNavigation` prop
+- **Multi-Select Drag** - Cmd/Ctrl+Click and Shift+Click selection with batch drag. Opt-in via `multiSelect` prop
+- **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'`
 
 ## Installation
 
@@ -69,11 +83,32 @@ 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 |
+| `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 |
 | `className` | `string` | - | Root container class |
 | `dropZoneClassName` | `string` | - | Drop zone class |
 | `dropZoneActiveClassName` | `string` | - | Active drop zone class |
 | `indentClassName` | `string` | - | Nested children indent class |
 
+### Callbacks
+
+| Callback | Type | Description |
+|----------|------|-------------|
+| `onDragStart` | `(event: DragStartEvent<T>) => boolean \| void` | Called when drag starts. Return `false` to prevent. |
+| `onDragMove` | `(event: DragMoveEvent<T>) => void` | Called during drag movement (debounced) |
+| `onDragEnd` | `(event: DragEndEvent<T>) => void` | Called when drag ends |
+| `onDragCancel` | `(event: DragEndEvent<T>) => void` | Called when drag is cancelled |
+| `onBeforeMove` | `(op: MoveOperation<T>) => MoveOperation<T> \| false \| void` | Middleware to transform or cancel moves |
+| `onBlockMove` | `(event: BlockMoveEvent<T>) => void` | Called after a block is moved |
+| `onBlockAdd` | `(event: BlockAddEvent<T>) => void` | Called after a block is added |
+| `onBlockDelete` | `(event: BlockDeleteEvent<T>) => void` | Called after a block is deleted |
+| `onExpandChange` | `(event: ExpandChangeEvent<T>) => void` | Called when expand/collapse changes |
+| `onHoverChange` | `(event: HoverChangeEvent<T>) => void` | Called when hover zone changes |
+
 ### Types
 
 #### BaseBlock
@@ -85,7 +120,7 @@ interface BaseBlock {
   id: string
   type: string
   parentId: string | null
-  order: number
+  order: number | string  // number for integer ordering, string for fractional
 }
 ```
 
@@ -115,6 +150,78 @@ interface ContainerRendererProps<T extends BaseBlock> extends BlockRendererProps
 }
 ```
 
+## Undo/Redo
+
+The `useBlockHistory` hook provides undo/redo support as a composable layer on top of `BlockTree`:
+
+```tsx
+import { BlockTree, useBlockHistory } from 'dnd-block-tree'
+
+function App() {
+  const { blocks, set, undo, redo, canUndo, canRedo } = useBlockHistory<MyBlock>(initialBlocks, {
+    maxSteps: 50,  // optional, default 50
+  })
+
+  return (
+    <>
+      <div>
+        <button onClick={undo} disabled={!canUndo}>Undo</button>
+        <button onClick={redo} disabled={!canRedo}>Redo</button>
+      </div>
+      <BlockTree blocks={blocks} onChange={set} ... />
+    </>
+  )
+}
+```
+
+## Keyboard Navigation
+
+Enable accessible tree navigation with the `keyboardNavigation` prop:
+
+```tsx
+<BlockTree keyboardNavigation blocks={blocks} ... />
+```
+
+| Key | Action |
+|-----|--------|
+| Arrow Down | Focus next visible block |
+| Arrow Up | Focus previous visible block |
+| Arrow Right | Expand container, or focus first child |
+| Arrow Left | Collapse container, or focus parent |
+| Enter / Space | Toggle expand/collapse |
+| 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"`.
+
+## Multi-Select Drag
+
+Enable batch selection and drag with the `multiSelect` prop:
+
+```tsx
+<BlockTree multiSelect blocks={blocks} ... />
+```
+
+- **Cmd/Ctrl+Click** toggles a single block in the selection
+- **Shift+Click** range-selects between the last clicked and current block
+- **Plain click** clears selection and selects only the clicked block
+- Dragging a selected block moves all selected blocks, preserving relative order
+- The drag overlay shows a stacked card effect with a count badge
+
+You can also control selection externally via `selectedIds` and `onSelectionChange`.
+
+## Max Depth
+
+Limit nesting depth to prevent deeply nested trees:
+
+```tsx
+<BlockTree maxDepth={2} blocks={blocks} ... />
+```
+
+- `maxDepth={1}` - flat list, no nesting allowed
+- `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
+
 ## Type Safety
 
 The library provides automatic type inference for container vs non-container renderers:
@@ -142,10 +249,16 @@ The library exports several utility functions:
 
 ```typescript
 import {
-  computeNormalizedIndex,  // Convert flat array to normalized index
-  buildOrderedBlocks,      // Convert index back to ordered array
-  reparentBlockIndex,      // Move a block to a new position
-  generateId,              // Generate unique block IDs
+  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
 } from 'dnd-block-tree'
 ```
 
@@ -153,13 +266,13 @@ import {
 
 Check out the [live demo](https://dnd-block-tree.vercel.app) to see the library in action with two example use cases:
 
-- **Productivity** - Sections, tasks, and notes
+- **Productivity** - Sections, tasks, and notes with undo/redo, max depth control, and keyboard navigation
 - **File System** - Folders and files
 
 ## Built With
 
 - [dnd-kit](https://dndkit.com/) - Modern drag and drop toolkit for React
-- React 18+
+- React 18+ / React 19
 - TypeScript
 
 ## License

package/dist/index.d.mts

@@ -11,7 +11,8 @@ interface BaseBlock {
     id: string;
     type: string;
     parentId: string | null;
-    order: number;
+    /** Ordering value. Number for integer ordering (default), string for fractional ordering. */
+    order: number | string;
 }
 /**
  * Normalized index structure for efficient tree operations
@@ -106,6 +107,20 @@ interface BlockMoveEvent<T extends BaseBlock = BaseBlock> {
     to: BlockPosition;
     /** All blocks after the move */
     blocks: T[];
+    /** IDs of all blocks that were moved (for multi-select) */
+    movedIds: string[];
+}
+/**
+ * A pending move operation passed through the onBeforeMove middleware pipeline.
+ * Return a modified operation to transform the move, or return false to cancel.
+ */
+interface MoveOperation<T extends BaseBlock = BaseBlock> {
+    /** The block being moved */
+    block: T;
+    /** Position before the move */
+    from: BlockPosition;
+    /** Target drop zone ID */
+    targetZone: string;
 }
 /**
  * Event fired when expand state changes
@@ -115,6 +130,22 @@ interface ExpandChangeEvent<T extends BaseBlock = BaseBlock> {
     blockId: string;
     expanded: boolean;
 }
+/**
+ * Event fired when a block is added
+ */
+interface BlockAddEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    parentId: string | null;
+    index: number;
+}
+/**
+ * Event fired when a block (and optionally its descendants) is deleted
+ */
+interface BlockDeleteEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    deletedIds: string[];
+    parentId: string | null;
+}
 /**
  * Event fired when hover zone changes
  */
@@ -136,13 +167,33 @@ interface BlockTreeCallbacks<T extends BaseBlock = BaseBlock> {
     onDragEnd?: (event: DragEndEvent<T>) => void;
     /** Called when drag is cancelled */
     onDragCancel?: (event: DragEndEvent<T>) => void;
+    /**
+     * Called before a block move is committed. Return a modified MoveOperation to
+     * transform the move (e.g. change the target zone), or return false to cancel.
+     * Return void / undefined to allow the move as-is.
+     */
+    onBeforeMove?: (operation: MoveOperation<T>) => MoveOperation<T> | false | void;
     /** Called after a block is moved to a new position */
     onBlockMove?: (event: BlockMoveEvent<T>) => void;
     /** Called when expand/collapse state changes */
     onExpandChange?: (event: ExpandChangeEvent<T>) => void;
     /** Called when hover zone changes during drag */
     onHoverChange?: (event: HoverChangeEvent<T>) => void;
+    /** Called after a block is added */
+    onBlockAdd?: (event: BlockAddEvent<T>) => void;
+    /** Called after a block (and its descendants) is deleted */
+    onBlockDelete?: (event: BlockDeleteEvent<T>) => void;
 }
+/**
+ * Ordering strategy for block siblings.
+ *
+ * - `'integer'` (default): siblings are reindexed 0, 1, 2, … after every move.
+ *   Simple and efficient; not suitable for collaborative/CRDT scenarios.
+ * - `'fractional'`: each move only updates the moved block's `order` with a
+ *   lexicographically sortable string key (fractional index). Siblings are never
+ *   reindexed, making it conflict-free for concurrent edits.
+ */
+type OrderingStrategy = 'integer' | 'fractional';
 /**
  * Filter function to determine if a block can be dragged
  */
@@ -218,6 +269,14 @@ interface BlockTreeCustomization<T extends BaseBlock = BaseBlock> {
     idGenerator?: IdGeneratorFn;
     /** Initially expanded block IDs */
     initialExpanded?: string[] | 'all' | 'none';
+    /**
+     * Ordering strategy for block siblings.
+     * Defaults to `'integer'` (reindex all siblings on every move).
+     * Use `'fractional'` for CRDT-compatible collaborative editing.
+     */
+    orderingStrategy?: OrderingStrategy;
+    /** Maximum nesting depth (1 = flat list, 2 = one level of nesting, etc.) */
+    maxDepth?: number;
 }
 /**
  * Block action types for the reducer
@@ -312,6 +371,10 @@ interface BlockStateProviderProps<T extends BaseBlock = BaseBlock> {
     initialBlocks?: T[];
     containerTypes?: readonly string[];
     onChange?: (blocks: T[]) => void;
+    orderingStrategy?: OrderingStrategy;
+    maxDepth?: number;
+    onBlockAdd?: (event: BlockAddEvent<T>) => void;
+    onBlockDelete?: (event: BlockDeleteEvent<T>) => void;
 }
 /**
  * Tree state provider props
@@ -395,12 +458,20 @@ interface BlockTreeProps<T extends BaseBlock, C extends readonly T['type'][] = r
     indentClassName?: string;
     /** Show live preview of drop position during drag (default: true) */
     showDropPreview?: boolean;
+    /** Enable keyboard navigation with arrow keys (default: false) */
+    keyboardNavigation?: boolean;
+    /** Enable multi-select with Cmd/Ctrl+Click and Shift+Click (default: false) */
+    multiSelect?: boolean;
+    /** Externally-controlled selected IDs (for multi-select) */
+    selectedIds?: Set<string>;
+    /** Called when selection changes (for multi-select) */
+    onSelectionChange?: (selectedIds: Set<string>) => void;
 }
 /**
  * Main BlockTree component
  * Provides drag-and-drop functionality for hierarchical block structures
  */
-declare function BlockTree<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]>({ blocks, renderers, containerTypes, onChange, dragOverlay, activationDistance, previewDebounce, className, dropZoneClassName, dropZoneActiveClassName, indentClassName, showDropPreview, onDragStart, onDragMove, onDragEnd, onDragCancel, onBlockMove, onExpandChange, onHoverChange, canDrag, canDrop, collisionDetection, sensors: sensorConfig, initialExpanded, }: BlockTreeProps<T, C>): react_jsx_runtime.JSX.Element;
+declare function BlockTree<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]>({ blocks, renderers, containerTypes, onChange, dragOverlay, activationDistance, previewDebounce, className, dropZoneClassName, dropZoneActiveClassName, indentClassName, showDropPreview, onDragStart, onDragMove, onDragEnd, onDragCancel, onBeforeMove, onBlockMove, onExpandChange, onHoverChange, canDrag, canDrop, collisionDetection, sensors: sensorConfig, initialExpanded, orderingStrategy, maxDepth, keyboardNavigation, multiSelect, selectedIds: externalSelectedIds, onSelectionChange, }: BlockTreeProps<T, C>): react_jsx_runtime.JSX.Element;
 
 interface TreeRendererProps<T extends BaseBlock> {
     blocks: T[];
@@ -425,11 +496,17 @@ interface TreeRendererProps<T extends BaseBlock> {
     } | null;
     /** The dragged block for rendering preview ghost */
     draggedBlock?: T | null;
+    /** Currently focused block ID for keyboard navigation */
+    focusedId?: string | null;
+    /** Currently selected block IDs for multi-select */
+    selectedIds?: Set<string>;
+    /** Click handler for multi-select */
+    onBlockClick?: (blockId: string, event: React.MouseEvent) => void;
 }
 /**
  * Recursive tree renderer with smart drop zones
  */
-declare function TreeRenderer<T extends BaseBlock>({ blocks, blocksByParent, parentId, activeId, expandedMap, renderers, containerTypes, onHover, onToggleExpand, depth, dropZoneClassName, dropZoneActiveClassName, indentClassName, rootClassName, canDrag, previewPosition, draggedBlock, }: TreeRendererProps<T>): react_jsx_runtime.JSX.Element;
+declare function TreeRenderer<T extends BaseBlock>({ blocks, blocksByParent, parentId, activeId, expandedMap, renderers, containerTypes, onHover, onToggleExpand, depth, dropZoneClassName, dropZoneActiveClassName, indentClassName, rootClassName, canDrag, previewPosition, draggedBlock, focusedId, selectedIds, onBlockClick, }: TreeRendererProps<T>): react_jsx_runtime.JSX.Element;
 
 interface DropZoneProps {
     id: string;
@@ -450,18 +527,20 @@ declare const DropZone: react.MemoExoticComponent<typeof DropZoneComponent>;
 interface DragOverlayProps<T extends BaseBlock> {
     activeBlock: T | null;
     children?: (block: T) => ReactNode;
+    /** Number of selected items being dragged (for multi-select badge) */
+    selectedCount?: number;
 }
 /**
  * Default drag overlay component
  * Shows a preview of the dragged item
  */
-declare function DragOverlay<T extends BaseBlock>({ activeBlock, children, }: DragOverlayProps<T>): react_jsx_runtime.JSX.Element;
+declare function DragOverlay<T extends BaseBlock>({ activeBlock, children, selectedCount, }: DragOverlayProps<T>): react_jsx_runtime.JSX.Element;
 
 /**
  * Create block state context and hooks
  */
 declare function createBlockState<T extends BaseBlock>(): {
-    BlockStateProvider: ({ children, initialBlocks, containerTypes, onChange, }: BlockStateProviderProps<T>) => react_jsx_runtime.JSX.Element;
+    BlockStateProvider: ({ children, initialBlocks, containerTypes, onChange, orderingStrategy, maxDepth, onBlockAdd, onBlockDelete, }: BlockStateProviderProps<T>) => react_jsx_runtime.JSX.Element;
     useBlockState: () => BlockStateContextValue<T>;
 };
 
@@ -478,6 +557,37 @@ declare function createTreeState<T extends BaseBlock>(options?: CreateTreeStateO
     useTreeState: () => TreeStateContextValue<T>;
 };
 
+interface UseBlockHistoryOptions {
+    /** Maximum number of undo steps to retain (default: 50) */
+    maxSteps?: number;
+}
+interface UseBlockHistoryResult<T extends BaseBlock> {
+    /** Current blocks state */
+    blocks: T[];
+    /** Set new blocks state (pushes current to undo stack) */
+    set: (blocks: T[]) => void;
+    /** Undo the last change */
+    undo: () => void;
+    /** Redo the last undone change */
+    redo: () => void;
+    /** Whether undo is available */
+    canUndo: boolean;
+    /** Whether redo is available */
+    canRedo: boolean;
+}
+/**
+ * Composable hook for undo/redo support with BlockTree.
+ *
+ * Usage:
+ * ```tsx
+ * const { blocks, set, undo, redo, canUndo, canRedo } = useBlockHistory(initialBlocks)
+ * <BlockTree blocks={blocks} onChange={set} />
+ * <button onClick={undo} disabled={!canUndo}>Undo</button>
+ * <button onClick={redo} disabled={!canRedo}>Redo</button>
+ * ```
+ */
+declare function useBlockHistory<T extends BaseBlock>(initialBlocks: T[], options?: UseBlockHistoryOptions): UseBlockHistoryResult<T>;
+
 /**
  * Clone a Map
  */
@@ -487,26 +597,49 @@ declare function cloneMap<K, V>(map: Map<K, V>): Map<K, V>;
  */
 declare function cloneParentMap(map: Map<string | null, string[]>): Map<string | null, string[]>;
 /**
- * Compute normalized index from flat block array
+ * Compute normalized index from flat block array.
+ *
+ * With `orderingStrategy: 'fractional'`, siblings are sorted by their `order`
+ * field (lexicographic). With `'integer'` (default), the input order is preserved.
  */
-declare function computeNormalizedIndex<T extends BaseBlock>(blocks: T[]): BlockIndex<T>;
+declare function computeNormalizedIndex<T extends BaseBlock>(blocks: T[], orderingStrategy?: OrderingStrategy): BlockIndex<T>;
 /**
- * Build ordered flat array from BlockIndex
+ * Build ordered flat array from BlockIndex.
+ *
+ * With `'integer'` ordering (default), assigns sequential `order: 0, 1, 2, …`.
+ * With `'fractional'` ordering, preserves existing `order` values — the moved
+ * block already has its new fractional key set by `reparentBlockIndex`.
  */
-declare function buildOrderedBlocks<T extends BaseBlock>(index: BlockIndex<T>, containerTypes?: readonly string[]): T[];
+declare function buildOrderedBlocks<T extends BaseBlock>(index: BlockIndex<T>, containerTypes?: readonly string[], orderingStrategy?: OrderingStrategy): T[];
 /**
- * Reparent a block based on drop zone ID
+ * Reparent a block based on drop zone ID.
  *
  * @param state - Current block index
  * @param activeId - ID of the dragged block
  * @param targetZone - Drop zone ID (e.g., "after-uuid", "before-uuid", "into-uuid")
  * @param containerTypes - Block types that can have children
+ * @param orderingStrategy - Whether to assign a fractional key to the moved block
  */
-declare function reparentBlockIndex<T extends BaseBlock>(state: BlockIndex<T>, activeId: UniqueIdentifier, targetZone: string, containerTypes?: readonly string[]): BlockIndex<T>;
+declare function reparentBlockIndex<T extends BaseBlock>(state: BlockIndex<T>, activeId: UniqueIdentifier, targetZone: string, containerTypes?: readonly string[], orderingStrategy?: OrderingStrategy, maxDepth?: number): BlockIndex<T>;
+/**
+ * Compute the depth of a block by walking its parentId chain.
+ * Root-level blocks have depth 1.
+ */
+declare function getBlockDepth<T extends BaseBlock>(index: BlockIndex<T>, blockId: string): number;
+/**
+ * Compute the maximum depth of a subtree rooted at blockId (inclusive).
+ * A leaf block returns 1.
+ */
+declare function getSubtreeDepth<T extends BaseBlock>(index: BlockIndex<T>, blockId: string): number;
 /**
  * Get all descendant IDs of a block
  */
 declare function getDescendantIds<T extends BaseBlock>(state: BlockIndex<T>, parentId: string): Set<string>;
+/**
+ * Reparent multiple blocks to a target zone, preserving their relative order.
+ * The first block in `blockIds` is treated as the primary (anchor) block.
+ */
+declare function reparentMultipleBlocks<T extends BaseBlock>(state: BlockIndex<T>, blockIds: string[], targetZone: string, containerTypes?: readonly string[], orderingStrategy?: OrderingStrategy, maxDepth?: number): BlockIndex<T>;
 /**
  * Delete a block and all its descendants
  */
@@ -527,4 +660,54 @@ declare function debounce<Args extends unknown[]>(fn: (...args: Args) => void, d
  */
 declare function generateId(): string;
 
-export { type AnimationConfig, type AutoExpandConfig, type BaseBlock, type BlockAction, type BlockIndex, type BlockMoveEvent, type BlockPosition, type BlockRendererProps, type BlockRenderers, type BlockStateContextValue, type BlockStateProviderProps, BlockTree, type BlockTreeCallbacks, type BlockTreeConfig, type BlockTreeCustomization, type BlockTreeProps, type CanDragFn, type CanDropFn, type ContainerRendererProps, type DragEndEvent, type DragMoveEvent, DragOverlay, type DragOverlayProps$1 as DragOverlayProps, type DragStartEvent, DropZone, type DropZoneConfig, type DropZoneProps, type DropZoneType, type ExpandChangeEvent, type HoverChangeEvent, type IdGeneratorFn, type InternalRenderers, type RendererPropsFor, type SensorConfig, TreeRenderer, type TreeRendererProps, type TreeStateContextValue, type TreeStateProviderProps, buildOrderedBlocks, cloneMap, cloneParentMap, closestCenterCollision, computeNormalizedIndex, createBlockState, createStickyCollision, createTreeState, debounce, deleteBlockAndDescendants, extractBlockId, extractUUID, generateId, getDescendantIds, getDropZoneType, getSensorConfig, reparentBlockIndex, useConfiguredSensors, weightedVerticalCollision };
+/**
+ * Fractional indexing utilities
+ *
+ * Generates lexicographically sortable string keys that allow insertion between
+ * any two existing keys without reindexing siblings. Suitable for CRDT-based
+ * collaborative editing.
+ *
+ * Alphabet: 0-9a-z (base 36). Lexicographic order matches semantic order since
+ * '0' < '1' < ... < '9' < 'a' < ... < 'z' in ASCII.
+ */
+/**
+ * Generate a key that sorts strictly between `lo` and `hi`.
+ *
+ * @param lo - Lower bound (null means no lower bound)
+ * @param hi - Upper bound (null means no upper bound)
+ */
+declare function generateKeyBetween(lo: string | null, hi: string | null): string;
+/**
+ * Generate `n` evenly distributed keys between `lo` and `hi` using binary
+ * subdivision. Keys grow at O(log n) depth, avoiding unbounded length.
+ *
+ * @param lo - Lower bound (null means no lower bound)
+ * @param hi - Upper bound (null means no upper bound)
+ * @param n  - Number of keys to generate
+ */
+declare function generateNKeysBetween(lo: string | null, hi: string | null, n: number): string[];
+/**
+ * Generate initial keys for `n` items starting from an empty list.
+ */
+declare function generateInitialKeys(n: number): string[];
+/**
+ * Compare two fractional keys lexicographically.
+ * Returns negative if a < b, positive if a > b, 0 if equal.
+ */
+declare function compareFractionalKeys(a: string, b: string): number;
+/**
+ * Assign initial fractional `order` keys to a flat array of blocks.
+ *
+ * Groups siblings by `parentId`, sorts each group by existing `order`, then
+ * assigns evenly-distributed fractional keys via binary subdivision.
+ *
+ * Use this to migrate an integer-ordered (or unkeyed) dataset to fractional
+ * ordering before passing blocks to a `BlockTree` with `orderingStrategy="fractional"`.
+ */
+declare function initFractionalOrder<T extends {
+    id: string;
+    parentId: string | null;
+    order: number | string;
+}>(blocks: T[]): T[];
+
+export { type AnimationConfig, type AutoExpandConfig, type BaseBlock, type BlockAction, type 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 };