dnd-block-tree 0.1.2 → 0.2.0

package/README.md

@@ -4,11 +4,13 @@ A headless React library for building hierarchical drag-and-drop interfaces. Bri
 
 ## Features
 
-- **Weighted Collision Detection** - Custom algorithm that scores drop zones by edge distance with bottom bias for natural drag behavior
-- **Smart Drop Zones** - Only one before-zone rendered, none around active block. Prevents visual clutter and accidental drops
+- **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
 - **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
 
 ## Installation
 
@@ -64,6 +66,9 @@ function App() {
 | `dragOverlay` | `(block: T) => ReactNode` | - | Custom drag overlay renderer |
 | `activationDistance` | `number` | `8` | Pixels to move before drag starts |
 | `previewDebounce` | `number` | `150` | Debounce delay for preview updates |
+| `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 |
 | `className` | `string` | - | Root container class |
 | `dropZoneClassName` | `string` | - | Drop zone class |
 | `dropZoneActiveClassName` | `string` | - | Active drop zone class |

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import * as _dnd_kit_core from '@dnd-kit/core';
-import { UniqueIdentifier, CollisionDetection } from '@dnd-kit/core';
+import { UniqueIdentifier, CollisionDetection, PointerActivationConstraint } from '@dnd-kit/core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
@@ -40,11 +40,6 @@ interface ContainerRendererProps<T extends BaseBlock = BaseBlock> extends BlockR
 }
 /**
  * Get the appropriate props type for a renderer based on whether it's a container type
- *
- * @example
- * type SectionProps = RendererPropsFor<MyBlock, 'section', typeof CONTAINER_TYPES>
- * // If CONTAINER_TYPES includes 'section', this is ContainerRendererProps
- * // Otherwise, it's BlockRendererProps
  */
 type RendererPropsFor<T extends BaseBlock, K extends T['type'], C extends readonly string[]> = K extends C[number] ? ContainerRendererProps<T & {
     type: K;
@@ -53,14 +48,6 @@ type RendererPropsFor<T extends BaseBlock, K extends T['type'], C extends readon
 }>;
 /**
  * Map of block types to their renderers with automatic container detection
- *
- * @example
- * const CONTAINER_TYPES = ['section'] as const
- *
- * const renderers: BlockRenderers<MyBlock, typeof CONTAINER_TYPES> = {
- *   section: (props) => <Section {...props} />,  // props includes isExpanded, onToggleExpand
- *   task: (props) => <Task {...props} />,        // props is BlockRendererProps
- * }
  */
 type BlockRenderers<T extends BaseBlock = BaseBlock, C extends readonly string[] = readonly string[]> = {
     [K in T['type']]: (props: RendererPropsFor<T, K, C>) => ReactNode;
@@ -71,6 +58,167 @@ type BlockRenderers<T extends BaseBlock = BaseBlock, C extends readonly string[]
 type InternalRenderers<T extends BaseBlock = BaseBlock> = {
     [K in T['type']]: (props: BlockRendererProps<T> | ContainerRendererProps<T>) => ReactNode;
 };
+/**
+ * Position info for a block
+ */
+interface BlockPosition {
+    parentId: string | null;
+    index: number;
+}
+/**
+ * Event fired when drag starts
+ */
+interface DragStartEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    blockId: string;
+}
+/**
+ * Event fired during drag movement
+ */
+interface DragMoveEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    blockId: string;
+    /** Current hover zone ID, if any */
+    overZone: string | null;
+    /** Pointer coordinates */
+    coordinates: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Event fired when drag ends
+ */
+interface DragEndEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    blockId: string;
+    /** Target zone where block was dropped */
+    targetZone: string | null;
+    /** Whether the drag was cancelled */
+    cancelled: boolean;
+}
+/**
+ * Event fired when a block is moved
+ */
+interface BlockMoveEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    from: BlockPosition;
+    to: BlockPosition;
+    /** All blocks after the move */
+    blocks: T[];
+}
+/**
+ * Event fired when expand state changes
+ */
+interface ExpandChangeEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    blockId: string;
+    expanded: boolean;
+}
+/**
+ * Event fired when hover zone changes
+ */
+interface HoverChangeEvent<T extends BaseBlock = BaseBlock> {
+    zoneId: string | null;
+    zoneType: DropZoneType | null;
+    /** Block being hovered over (if any) */
+    targetBlock: T | null;
+}
+/**
+ * All available callback handlers for BlockTree
+ */
+interface BlockTreeCallbacks<T extends BaseBlock = BaseBlock> {
+    /** Called when drag starts. Return false to prevent drag. */
+    onDragStart?: (event: DragStartEvent<T>) => boolean | void;
+    /** Called during drag movement (debounced) */
+    onDragMove?: (event: DragMoveEvent<T>) => void;
+    /** Called when drag ends (success or cancel) */
+    onDragEnd?: (event: DragEndEvent<T>) => void;
+    /** Called when drag is cancelled */
+    onDragCancel?: (event: DragEndEvent<T>) => 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;
+}
+/**
+ * Filter function to determine if a block can be dragged
+ */
+type CanDragFn<T extends BaseBlock = BaseBlock> = (block: T) => boolean;
+/**
+ * Filter function to determine if a block can be dropped at a location
+ */
+type CanDropFn<T extends BaseBlock = BaseBlock> = (draggedBlock: T, targetZone: string, targetBlock: T | null) => boolean;
+/**
+ * Custom ID generator function
+ */
+type IdGeneratorFn = () => string;
+/**
+ * Sensor configuration
+ */
+interface SensorConfig {
+    activationDistance?: number;
+    activationDelay?: number;
+    tolerance?: number;
+}
+/**
+ * Drop zone configuration
+ */
+interface DropZoneConfig {
+    /** Height of drop zones in pixels */
+    height?: number;
+    /** Gap between drop zones */
+    gap?: number;
+    /** Show drop zones inside empty containers */
+    showInEmptyContainers?: boolean;
+}
+/**
+ * Animation configuration
+ */
+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) */
+    easing?: string;
+}
+/**
+ * Auto-expand configuration for containers during drag
+ */
+interface AutoExpandConfig {
+    /** Enable auto-expand on hover */
+    enabled?: boolean;
+    /** Delay before expanding in ms */
+    delay?: number;
+    /** Auto-collapse when leaving */
+    collapseOnLeave?: boolean;
+}
+/**
+ * Full customization options for BlockTree
+ */
+interface BlockTreeCustomization<T extends BaseBlock = BaseBlock> {
+    /** Filter which blocks can be dragged */
+    canDrag?: CanDragFn<T>;
+    /** Filter valid drop targets */
+    canDrop?: CanDropFn<T>;
+    /** Custom collision detection algorithm */
+    collisionDetection?: CollisionDetection;
+    /** Sensor configuration */
+    sensors?: SensorConfig;
+    /** Drop zone configuration */
+    dropZones?: DropZoneConfig;
+    /** Animation configuration */
+    animation?: AnimationConfig;
+    /** Auto-expand containers during drag */
+    autoExpand?: AutoExpandConfig;
+    /** Custom ID generator */
+    idGenerator?: IdGeneratorFn;
+    /** Initially expanded block IDs */
+    initialExpanded?: string[] | 'all' | 'none';
+}
 /**
  * Block action types for the reducer
  */
@@ -184,16 +332,33 @@ interface TreeStateProviderProps<T extends BaseBlock = BaseBlock> {
  * - Returns single winner (lowest score)
  */
 declare const weightedVerticalCollision: CollisionDetection;
+/**
+ * Create a collision detection with hysteresis to prevent flickering
+ * between adjacent drop zones.
+ *
+ * @param threshold - Minimum score improvement required to switch zones (default: 15px)
+ */
+declare function createStickyCollision(threshold?: number): CollisionDetection & {
+    reset: () => void;
+};
 /**
  * Simple closest center collision (fallback)
  */
 declare const closestCenterCollision: CollisionDetection;
 
-interface SensorConfig {
-    activationDistance?: number;
+/**
+ * Return type for getSensorConfig
+ */
+interface SensorConfigResult {
+    pointer: {
+        activationConstraint: PointerActivationConstraint;
+    };
+    touch: {
+        activationConstraint: PointerActivationConstraint;
+    };
 }
 /**
- * Create configured sensors with activation distance constraint.
+ * Create configured sensors with activation constraints.
  * The activation distance prevents accidental drags while still allowing clicks.
  *
  * @param config - Sensor configuration
@@ -203,20 +368,9 @@ declare function useConfiguredSensors(config?: SensorConfig): _dnd_kit_core.Sens
 /**
  * Get sensor configuration for manual setup
  */
-declare function getSensorConfig(activationDistance?: number): {
-    pointer: {
-        activationConstraint: {
-            distance: number;
-        };
-    };
-    touch: {
-        activationConstraint: {
-            distance: number;
-        };
-    };
-};
+declare function getSensorConfig(config?: SensorConfig): SensorConfigResult;
 
-interface BlockTreeProps<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]> {
+interface BlockTreeProps<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]> extends BlockTreeCallbacks<T>, BlockTreeCustomization<T> {
     /** Current blocks array */
     blocks: T[];
     /** Block renderers for each type */
@@ -239,12 +393,14 @@ interface BlockTreeProps<T extends BaseBlock, C extends readonly T['type'][] = r
     dropZoneActiveClassName?: string;
     /** Indent className for nested items */
     indentClassName?: string;
+    /** Show live preview of drop position during drag (default: true) */
+    showDropPreview?: boolean;
 }
 /**
  * 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, }: 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, onBlockMove, onExpandChange, onHoverChange, canDrag, canDrop, collisionDetection, sensors: sensorConfig, initialExpanded, }: BlockTreeProps<T, C>): react_jsx_runtime.JSX.Element;
 
 interface TreeRendererProps<T extends BaseBlock> {
     blocks: T[];
@@ -261,11 +417,19 @@ interface TreeRendererProps<T extends BaseBlock> {
     dropZoneActiveClassName?: string;
     indentClassName?: string;
     rootClassName?: string;
+    canDrag?: CanDragFn<T>;
+    /** Preview position info - where to show the ghost */
+    previewPosition?: {
+        parentId: string | null;
+        index: number;
+    } | null;
+    /** The dragged block for rendering preview ghost */
+    draggedBlock?: T | 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, }: 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, }: TreeRendererProps<T>): react_jsx_runtime.JSX.Element;
 
 interface DropZoneProps {
     id: string;
@@ -349,7 +513,7 @@ declare function getDescendantIds<T extends BaseBlock>(state: BlockIndex<T>, par
 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-)
+ * Extract UUID from a zone ID by removing the prefix (before-, after-, into-, end-)
  */
 declare function extractUUID(id: string, pattern?: string): string;
 /**
@@ -363,4 +527,4 @@ declare function debounce<Args extends unknown[]>(fn: (...args: Args) => void, d
  */
 declare function generateId(): string;
 
-export { type BaseBlock, type BlockAction, type BlockIndex, type BlockRendererProps, type BlockRenderers, type BlockStateContextValue, type BlockStateProviderProps, BlockTree, type BlockTreeConfig, type BlockTreeProps, type ContainerRendererProps, DragOverlay, type DragOverlayProps$1 as DragOverlayProps, DropZone, type DropZoneProps, type DropZoneType, type RendererPropsFor, TreeRenderer, type TreeRendererProps, type TreeStateContextValue, type TreeStateProviderProps, buildOrderedBlocks, cloneMap, cloneParentMap, closestCenterCollision, computeNormalizedIndex, createBlockState, createTreeState, debounce, deleteBlockAndDescendants, extractBlockId, extractUUID, generateId, getDescendantIds, getDropZoneType, getSensorConfig, reparentBlockIndex, useConfiguredSensors, weightedVerticalCollision };
+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 };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import * as _dnd_kit_core from '@dnd-kit/core';
-import { UniqueIdentifier, CollisionDetection } from '@dnd-kit/core';
+import { UniqueIdentifier, CollisionDetection, PointerActivationConstraint } from '@dnd-kit/core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
@@ -40,11 +40,6 @@ interface ContainerRendererProps<T extends BaseBlock = BaseBlock> extends BlockR
 }
 /**
  * Get the appropriate props type for a renderer based on whether it's a container type
- *
- * @example
- * type SectionProps = RendererPropsFor<MyBlock, 'section', typeof CONTAINER_TYPES>
- * // If CONTAINER_TYPES includes 'section', this is ContainerRendererProps
- * // Otherwise, it's BlockRendererProps
  */
 type RendererPropsFor<T extends BaseBlock, K extends T['type'], C extends readonly string[]> = K extends C[number] ? ContainerRendererProps<T & {
     type: K;
@@ -53,14 +48,6 @@ type RendererPropsFor<T extends BaseBlock, K extends T['type'], C extends readon
 }>;
 /**
  * Map of block types to their renderers with automatic container detection
- *
- * @example
- * const CONTAINER_TYPES = ['section'] as const
- *
- * const renderers: BlockRenderers<MyBlock, typeof CONTAINER_TYPES> = {
- *   section: (props) => <Section {...props} />,  // props includes isExpanded, onToggleExpand
- *   task: (props) => <Task {...props} />,        // props is BlockRendererProps
- * }
  */
 type BlockRenderers<T extends BaseBlock = BaseBlock, C extends readonly string[] = readonly string[]> = {
     [K in T['type']]: (props: RendererPropsFor<T, K, C>) => ReactNode;
@@ -71,6 +58,167 @@ type BlockRenderers<T extends BaseBlock = BaseBlock, C extends readonly string[]
 type InternalRenderers<T extends BaseBlock = BaseBlock> = {
     [K in T['type']]: (props: BlockRendererProps<T> | ContainerRendererProps<T>) => ReactNode;
 };
+/**
+ * Position info for a block
+ */
+interface BlockPosition {
+    parentId: string | null;
+    index: number;
+}
+/**
+ * Event fired when drag starts
+ */
+interface DragStartEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    blockId: string;
+}
+/**
+ * Event fired during drag movement
+ */
+interface DragMoveEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    blockId: string;
+    /** Current hover zone ID, if any */
+    overZone: string | null;
+    /** Pointer coordinates */
+    coordinates: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Event fired when drag ends
+ */
+interface DragEndEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    blockId: string;
+    /** Target zone where block was dropped */
+    targetZone: string | null;
+    /** Whether the drag was cancelled */
+    cancelled: boolean;
+}
+/**
+ * Event fired when a block is moved
+ */
+interface BlockMoveEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    from: BlockPosition;
+    to: BlockPosition;
+    /** All blocks after the move */
+    blocks: T[];
+}
+/**
+ * Event fired when expand state changes
+ */
+interface ExpandChangeEvent<T extends BaseBlock = BaseBlock> {
+    block: T;
+    blockId: string;
+    expanded: boolean;
+}
+/**
+ * Event fired when hover zone changes
+ */
+interface HoverChangeEvent<T extends BaseBlock = BaseBlock> {
+    zoneId: string | null;
+    zoneType: DropZoneType | null;
+    /** Block being hovered over (if any) */
+    targetBlock: T | null;
+}
+/**
+ * All available callback handlers for BlockTree
+ */
+interface BlockTreeCallbacks<T extends BaseBlock = BaseBlock> {
+    /** Called when drag starts. Return false to prevent drag. */
+    onDragStart?: (event: DragStartEvent<T>) => boolean | void;
+    /** Called during drag movement (debounced) */
+    onDragMove?: (event: DragMoveEvent<T>) => void;
+    /** Called when drag ends (success or cancel) */
+    onDragEnd?: (event: DragEndEvent<T>) => void;
+    /** Called when drag is cancelled */
+    onDragCancel?: (event: DragEndEvent<T>) => 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;
+}
+/**
+ * Filter function to determine if a block can be dragged
+ */
+type CanDragFn<T extends BaseBlock = BaseBlock> = (block: T) => boolean;
+/**
+ * Filter function to determine if a block can be dropped at a location
+ */
+type CanDropFn<T extends BaseBlock = BaseBlock> = (draggedBlock: T, targetZone: string, targetBlock: T | null) => boolean;
+/**
+ * Custom ID generator function
+ */
+type IdGeneratorFn = () => string;
+/**
+ * Sensor configuration
+ */
+interface SensorConfig {
+    activationDistance?: number;
+    activationDelay?: number;
+    tolerance?: number;
+}
+/**
+ * Drop zone configuration
+ */
+interface DropZoneConfig {
+    /** Height of drop zones in pixels */
+    height?: number;
+    /** Gap between drop zones */
+    gap?: number;
+    /** Show drop zones inside empty containers */
+    showInEmptyContainers?: boolean;
+}
+/**
+ * Animation configuration
+ */
+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) */
+    easing?: string;
+}
+/**
+ * Auto-expand configuration for containers during drag
+ */
+interface AutoExpandConfig {
+    /** Enable auto-expand on hover */
+    enabled?: boolean;
+    /** Delay before expanding in ms */
+    delay?: number;
+    /** Auto-collapse when leaving */
+    collapseOnLeave?: boolean;
+}
+/**
+ * Full customization options for BlockTree
+ */
+interface BlockTreeCustomization<T extends BaseBlock = BaseBlock> {
+    /** Filter which blocks can be dragged */
+    canDrag?: CanDragFn<T>;
+    /** Filter valid drop targets */
+    canDrop?: CanDropFn<T>;
+    /** Custom collision detection algorithm */
+    collisionDetection?: CollisionDetection;
+    /** Sensor configuration */
+    sensors?: SensorConfig;
+    /** Drop zone configuration */
+    dropZones?: DropZoneConfig;
+    /** Animation configuration */
+    animation?: AnimationConfig;
+    /** Auto-expand containers during drag */
+    autoExpand?: AutoExpandConfig;
+    /** Custom ID generator */
+    idGenerator?: IdGeneratorFn;
+    /** Initially expanded block IDs */
+    initialExpanded?: string[] | 'all' | 'none';
+}
 /**
  * Block action types for the reducer
  */
@@ -184,16 +332,33 @@ interface TreeStateProviderProps<T extends BaseBlock = BaseBlock> {
  * - Returns single winner (lowest score)
  */
 declare const weightedVerticalCollision: CollisionDetection;
+/**
+ * Create a collision detection with hysteresis to prevent flickering
+ * between adjacent drop zones.
+ *
+ * @param threshold - Minimum score improvement required to switch zones (default: 15px)
+ */
+declare function createStickyCollision(threshold?: number): CollisionDetection & {
+    reset: () => void;
+};
 /**
  * Simple closest center collision (fallback)
  */
 declare const closestCenterCollision: CollisionDetection;
 
-interface SensorConfig {
-    activationDistance?: number;
+/**
+ * Return type for getSensorConfig
+ */
+interface SensorConfigResult {
+    pointer: {
+        activationConstraint: PointerActivationConstraint;
+    };
+    touch: {
+        activationConstraint: PointerActivationConstraint;
+    };
 }
 /**
- * Create configured sensors with activation distance constraint.
+ * Create configured sensors with activation constraints.
  * The activation distance prevents accidental drags while still allowing clicks.
  *
  * @param config - Sensor configuration
@@ -203,20 +368,9 @@ declare function useConfiguredSensors(config?: SensorConfig): _dnd_kit_core.Sens
 /**
  * Get sensor configuration for manual setup
  */
-declare function getSensorConfig(activationDistance?: number): {
-    pointer: {
-        activationConstraint: {
-            distance: number;
-        };
-    };
-    touch: {
-        activationConstraint: {
-            distance: number;
-        };
-    };
-};
+declare function getSensorConfig(config?: SensorConfig): SensorConfigResult;
 
-interface BlockTreeProps<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]> {
+interface BlockTreeProps<T extends BaseBlock, C extends readonly T['type'][] = readonly T['type'][]> extends BlockTreeCallbacks<T>, BlockTreeCustomization<T> {
     /** Current blocks array */
     blocks: T[];
     /** Block renderers for each type */
@@ -239,12 +393,14 @@ interface BlockTreeProps<T extends BaseBlock, C extends readonly T['type'][] = r
     dropZoneActiveClassName?: string;
     /** Indent className for nested items */
     indentClassName?: string;
+    /** Show live preview of drop position during drag (default: true) */
+    showDropPreview?: boolean;
 }
 /**
  * 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, }: 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, onBlockMove, onExpandChange, onHoverChange, canDrag, canDrop, collisionDetection, sensors: sensorConfig, initialExpanded, }: BlockTreeProps<T, C>): react_jsx_runtime.JSX.Element;
 
 interface TreeRendererProps<T extends BaseBlock> {
     blocks: T[];
@@ -261,11 +417,19 @@ interface TreeRendererProps<T extends BaseBlock> {
     dropZoneActiveClassName?: string;
     indentClassName?: string;
     rootClassName?: string;
+    canDrag?: CanDragFn<T>;
+    /** Preview position info - where to show the ghost */
+    previewPosition?: {
+        parentId: string | null;
+        index: number;
+    } | null;
+    /** The dragged block for rendering preview ghost */
+    draggedBlock?: T | 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, }: 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, }: TreeRendererProps<T>): react_jsx_runtime.JSX.Element;
 
 interface DropZoneProps {
     id: string;
@@ -349,7 +513,7 @@ declare function getDescendantIds<T extends BaseBlock>(state: BlockIndex<T>, par
 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-)
+ * Extract UUID from a zone ID by removing the prefix (before-, after-, into-, end-)
  */
 declare function extractUUID(id: string, pattern?: string): string;
 /**
@@ -363,4 +527,4 @@ declare function debounce<Args extends unknown[]>(fn: (...args: Args) => void, d
  */
 declare function generateId(): string;
 
-export { type BaseBlock, type BlockAction, type BlockIndex, type BlockRendererProps, type BlockRenderers, type BlockStateContextValue, type BlockStateProviderProps, BlockTree, type BlockTreeConfig, type BlockTreeProps, type ContainerRendererProps, DragOverlay, type DragOverlayProps$1 as DragOverlayProps, DropZone, type DropZoneProps, type DropZoneType, type RendererPropsFor, TreeRenderer, type TreeRendererProps, type TreeStateContextValue, type TreeStateProviderProps, buildOrderedBlocks, cloneMap, cloneParentMap, closestCenterCollision, computeNormalizedIndex, createBlockState, createTreeState, debounce, deleteBlockAndDescendants, extractBlockId, extractUUID, generateId, getDescendantIds, getDropZoneType, getSensorConfig, reparentBlockIndex, useConfiguredSensors, weightedVerticalCollision };
+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 };