@dnd-block-tree/vanilla 2.1.0

package/README.md

@@ -0,0 +1,85 @@
+# @dnd-block-tree/vanilla
+
+[![npm version](https://img.shields.io/npm/v/@dnd-block-tree/vanilla.svg)](https://www.npmjs.com/package/@dnd-block-tree/vanilla)
+
+Vanilla JS/TS adapter for [dnd-block-tree](https://github.com/thesandybridge/dnd-block-tree) — zero framework dependencies. A two-layer architecture with a headless controller for state management and an optional default renderer for automatic DOM updates.
+
+## Installation
+
+```bash
+npm install @dnd-block-tree/vanilla
+```
+
+Only dependency is `@dnd-block-tree/core`. No framework peer dependencies required.
+
+## What's Included
+
+- **Headless Controller** — `createBlockTreeController` manages all tree state, drag logic, sensors, and events without touching the DOM
+- **Default Renderer** — `createDefaultRenderer` subscribes to controller events and automatically builds/updates the DOM
+- **Sensors** — pointer (mouse), touch (long-press + haptic), and keyboard navigation
+- **Collision Bridge** — DOM rect measurement and collision detection against snapshotted zones
+- **History** — opt-in undo/redo via `controller.enableHistory()`
+- **Layout Animation** — FLIP-based position animation for reorders
+- **Virtual Scroller** — windowed rendering for large trees
+
+## Quick Example
+
+```typescript
+import {
+  createBlockTreeController,
+  createDefaultRenderer,
+  createElement,
+  type BaseBlock,
+} from '@dnd-block-tree/vanilla'
+
+interface MyBlock extends BaseBlock {
+  type: 'folder' | 'file'
+  label: string
+}
+
+const controller = createBlockTreeController<MyBlock>({
+  initialBlocks: [
+    { id: '1', type: 'folder', label: 'Documents', parentId: null, order: 0 },
+    { id: '2', type: 'file', label: 'readme.txt', parentId: '1', order: 0 },
+  ],
+  containerTypes: ['folder'],
+})
+
+const container = document.getElementById('tree')!
+
+const renderer = createDefaultRenderer(controller, {
+  container,
+  renderBlock: (block, ctx) => {
+    const el = createElement('div', { class: 'block' })
+    el.textContent = block.label
+    if (ctx.children) el.appendChild(ctx.children)
+    return el
+  },
+})
+
+controller.mount(container)
+```
+
+## Data Attributes
+
+The renderer sets data attributes for CSS styling:
+
+| Attribute | Element | Description |
+|-----------|---------|-------------|
+| `data-block-id` | Block | Block's unique ID |
+| `data-block-type` | Block | Block's type string |
+| `data-depth` | Block | Nesting depth (0-based) |
+| `data-dragging` | Block | Present when being dragged |
+| `data-selected` | Block | Present when selected |
+| `data-zone-id` | Drop zone | Zone identifier |
+| `data-zone-active` | Drop zone | Present on active hover zone |
+| `data-drag-overlay` | Overlay | Floating drag ghost |
+| `data-dnd-ghost` | Ghost | Semi-transparent preview |
+
+## Documentation
+
+Full docs at **[blocktree.sandybridge.io](https://blocktree.sandybridge.io/docs)**.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,314 @@
+import { BaseBlock, BlockRendererProps as BlockRendererProps$1, BlockRenderers as BlockRenderers$1, OrderingStrategy, CanDragFn, CanDropFn, IdGeneratorFn, SensorConfig, BlockTreeCallbacks, ContainerRendererProps as ContainerRendererProps$1, InternalRenderers as InternalRenderers$1, RendererPropsFor as RendererPropsFor$1, BlockTreeInstance, Rect, CollisionCandidate, CoreCollisionDetection } from '@dnd-block-tree/core';
+export { AnimationConfig, AutoExpandConfig, BaseBlock, BlockAction, BlockAddEvent, BlockDeleteEvent, BlockIndex, BlockMoveEvent, BlockPosition, BlockStateContextValue, BlockTreeCallbacks, BlockTreeConfig, BlockTreeCustomization, BlockTreeEvents, BlockTreeInstance, BlockTreeOptions, CanDragFn, CanDropFn, CollisionCandidate, CollisionResult, CoreCollisionDetection, DragEndEvent, DragMoveEvent, DragStartEvent, DropZoneConfig, DropZoneType, EventEmitter, ExpandAction, ExpandChangeEvent, HistoryAction, HistoryState, HoverChangeEvent, IdGeneratorFn, MoveOperation, NestedBlock, OrderingStrategy, Rect, SensorConfig, SnapshotRectsRef, TreeValidationResult, blockReducer, buildOrderedBlocks, cloneMap, cloneParentMap, closestCenterCollision, compareFractionalKeys, computeNormalizedIndex, createBlockTree, createStickyCollision, debounce, deleteBlockAndDescendants, expandReducer, extractBlockId, extractUUID, flatToNested, generateId, generateInitialKeys, generateKeyBetween, generateNKeysBetween, getBlockDepth, getDescendantIds, getDropZoneType, getSubtreeDepth, historyReducer, initFractionalOrder, nestedToFlat, reparentBlockIndex, reparentMultipleBlocks, validateBlockTree, weightedVerticalCollision } from '@dnd-block-tree/core';
+
+type BlockRendererProps<T extends BaseBlock = BaseBlock> = BlockRendererProps$1<T, HTMLElement>;
+type ContainerRendererProps<T extends BaseBlock = BaseBlock> = ContainerRendererProps$1<T, HTMLElement>;
+type RendererPropsFor<T extends BaseBlock, K extends T['type'], C extends readonly string[]> = RendererPropsFor$1<T, K, C, HTMLElement>;
+type BlockRenderers<T extends BaseBlock = BaseBlock, C extends readonly string[] = readonly string[]> = BlockRenderers$1<T, C, HTMLElement>;
+type InternalRenderers<T extends BaseBlock = BaseBlock> = InternalRenderers$1<T, HTMLElement>;
+/** Controller configuration */
+interface BlockTreeControllerOptions<T extends BaseBlock = BaseBlock> {
+    initialBlocks?: T[];
+    containerTypes?: readonly string[];
+    orderingStrategy?: OrderingStrategy;
+    maxDepth?: number;
+    previewDebounce?: number;
+    canDrag?: CanDragFn<T>;
+    canDrop?: CanDropFn<T>;
+    idGenerator?: IdGeneratorFn;
+    initialExpanded?: string[] | 'all' | 'none';
+    sensors?: VanillaSensorConfig;
+    onChange?: (blocks: T[]) => void;
+    callbacks?: Partial<BlockTreeCallbacks<T>>;
+}
+/** Vanilla sensor configuration */
+interface VanillaSensorConfig extends SensorConfig {
+    /** Enable pointer sensor (default: true) */
+    pointer?: boolean;
+    /** Enable touch sensor (default: true) */
+    touch?: boolean;
+    /** Enable keyboard sensor (default: false) */
+    keyboard?: boolean;
+}
+/** Drag state exposed to consumers */
+interface DragState {
+    isDragging: boolean;
+    activeId: string | null;
+    hoverZone: string | null;
+}
+/** Controller event types */
+interface ControllerEvents<T extends BaseBlock = BaseBlock> {
+    render: (blocks: T[], expandedMap: Record<string, boolean>) => void;
+    'drag:statechange': (state: DragState) => void;
+    'selection:change': (selectedIds: Set<string>) => void;
+}
+/** Render context passed to renderBlock in DefaultRenderer */
+interface RenderBlockContext {
+    children: HTMLElement | null;
+    depth: number;
+    isExpanded: boolean;
+    isDragging: boolean;
+    isSelected: boolean;
+    onToggleExpand: (() => void) | null;
+}
+/** DefaultRenderer options */
+interface DefaultRendererOptions<T extends BaseBlock = BaseBlock> {
+    container: HTMLElement;
+    renderBlock: (block: T, ctx: RenderBlockContext) => HTMLElement;
+    dropZoneHeight?: number;
+    animateExpand?: boolean;
+}
+/** Cleanup function */
+type Unsubscribe = () => void;
+/** Disposable resource */
+interface Disposable {
+    dispose(): void;
+}
+
+interface BlockTreeController<T extends BaseBlock = BaseBlock> {
+    mount(container: HTMLElement): void;
+    unmount(): void;
+    registerDraggable(id: string, element: HTMLElement): Unsubscribe;
+    registerDropZone(id: string, element: HTMLElement): Unsubscribe;
+    getDragState(): DragState;
+    getBlocks(): T[];
+    getEffectiveBlocks(): T[];
+    getExpandedMap(): Record<string, boolean>;
+    getBlock(id: string): T | undefined;
+    toggleExpand(id: string): void;
+    setExpandAll(expanded: boolean): void;
+    addBlock(type: T['type'], parentId?: string | null): T;
+    deleteBlock(id: string): void;
+    setBlocks(blocks: T[]): void;
+    select(id: string, mode: 'single' | 'toggle' | 'range'): void;
+    clearSelection(): void;
+    getSelectedIds(): Set<string>;
+    enableHistory(maxSteps?: number): void;
+    undo(): T[] | null;
+    redo(): T[] | null;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    on<K extends keyof ControllerEvents<T>>(event: K, handler: ControllerEvents<T>[K]): Unsubscribe;
+    setOverlayRenderer(render: (block: T) => HTMLElement): void;
+    getTree(): BlockTreeInstance<T>;
+    destroy(): void;
+}
+declare function createBlockTreeController<T extends BaseBlock>(options?: BlockTreeControllerOptions<T>): BlockTreeController<T>;
+
+/**
+ * Measure DOM rects for all registered drop zones and build CollisionCandidate[].
+ * Snapshots rects once at drag start to prevent feedback loops.
+ */
+declare function measureDropZoneRects(zones: Map<string, HTMLElement>): Map<string, Rect>;
+/** Build collision candidates from a snapshot rect map */
+declare function buildCandidates(snapshotRects: Map<string, Rect>): CollisionCandidate[];
+/** Build a pointer rect from client coordinates */
+declare function pointerToRect(x: number, y: number): Rect;
+/** Run collision detection with snapshotted rects and pointer position */
+declare function detectCollision(detector: CoreCollisionDetection, snapshotRects: Map<string, Rect>, pointerX: number, pointerY: number): string | null;
+
+interface DragOverlayOptions {
+    /** Custom renderer for the overlay content */
+    renderOverlay?: (block: BaseBlock) => HTMLElement;
+}
+/**
+ * Floating drag overlay that follows the pointer during drag.
+ * Creates and manages a fixed-position overlay element.
+ */
+declare class DragOverlay {
+    private overlay;
+    private options;
+    constructor(options?: DragOverlayOptions);
+    show(block: BaseBlock, sourceEl: HTMLElement, x: number, y: number): void;
+    move(x: number, y: number): void;
+    hide(): void;
+    private setPosition;
+}
+
+interface BlockHistoryOptions {
+    maxSteps?: number;
+}
+interface BlockHistory<T extends BaseBlock> {
+    push(blocks: T[]): void;
+    undo(): T[] | null;
+    redo(): T[] | null;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    getPresent(): T[];
+    clear(blocks: T[]): void;
+}
+/**
+ * Imperative undo/redo history wrapping core's historyReducer.
+ */
+declare function createBlockHistory<T extends BaseBlock>(initialBlocks: T[], options?: BlockHistoryOptions): BlockHistory<T>;
+
+interface LayoutAnimationOptions {
+    duration?: number;
+    easing?: string;
+}
+/**
+ * FLIP animation for block layout changes.
+ * Records element positions before a DOM update, then animates from old to new.
+ */
+declare class LayoutAnimation {
+    private duration;
+    private easing;
+    private snapshots;
+    constructor(options?: LayoutAnimationOptions);
+    /** Record current positions of all block elements in a container */
+    snapshot(container: HTMLElement): void;
+    /** After DOM update, animate elements from old to new positions */
+    animate(container: HTMLElement): void;
+}
+
+interface VirtualScrollerOptions {
+    itemHeight: number;
+    overscan?: number;
+}
+interface VirtualRange {
+    startIndex: number;
+    endIndex: number;
+    offsetY: number;
+    totalHeight: number;
+    visibleIds: Set<string>;
+}
+/**
+ * Virtual scrolling for large trees.
+ * Calculates visible range based on scroll position and viewport height.
+ */
+declare class VirtualScroller {
+    private itemHeight;
+    private overscan;
+    constructor(options: VirtualScrollerOptions);
+    /** Calculate the visible range for a given scroll state */
+    calculate(scrollTop: number, viewportHeight: number, totalItems: number, blockIds: string[]): VirtualRange;
+}
+
+interface SensorCallbacks {
+    onDragStart(blockId: string, x: number, y: number): void;
+    onDragMove(x: number, y: number): void;
+    onDragEnd(x: number, y: number): void;
+    onDragCancel(): void;
+}
+interface Sensor {
+    attach(container: HTMLElement): void;
+    detach(): void;
+}
+
+interface PointerSensorOptions {
+    activationDistance?: number;
+}
+declare class PointerSensor implements Sensor {
+    private container;
+    private callbacks;
+    private activationDistance;
+    private isDragging;
+    private startX;
+    private startY;
+    private blockId;
+    private boundPointerDown;
+    private boundPointerMove;
+    private boundPointerUp;
+    constructor(callbacks: SensorCallbacks, options?: PointerSensorOptions);
+    attach(container: HTMLElement): void;
+    detach(): void;
+    private onPointerDown;
+    private onPointerMove;
+    private onPointerUp;
+    private cleanup;
+}
+
+interface TouchSensorOptions {
+    longPressDelay?: number;
+    hapticFeedback?: boolean;
+}
+declare class TouchSensor implements Sensor {
+    private container;
+    private callbacks;
+    private longPressDelay;
+    private hapticFeedback;
+    private isDragging;
+    private pressTimer;
+    private blockId;
+    private boundTouchStart;
+    private boundTouchMove;
+    private boundTouchEnd;
+    constructor(callbacks: SensorCallbacks, options?: TouchSensorOptions);
+    attach(container: HTMLElement): void;
+    detach(): void;
+    private onTouchStart;
+    private onTouchMove;
+    private onTouchEnd;
+    private cleanup;
+}
+
+interface KeyboardSensorCallbacks extends SensorCallbacks {
+    onFocusPrev(): void;
+    onFocusNext(): void;
+    onExpand(): void;
+    onCollapse(): void;
+    onFocusFirst(): void;
+    onFocusLast(): void;
+    onToggleExpand(): void;
+    onSelect(): void;
+}
+declare class KeyboardSensor implements Sensor {
+    private container;
+    private callbacks;
+    private boundKeyDown;
+    constructor(callbacks: KeyboardSensorCallbacks);
+    attach(container: HTMLElement): void;
+    detach(): void;
+    private onKeyDown;
+}
+
+interface DefaultRenderer extends Unsubscribe {
+    /** Force a re-render */
+    refresh(): void;
+}
+/**
+ * DefaultRenderer (Layer 2): Subscribes to controller events and
+ * automatically creates/updates DOM. User provides a renderBlock function.
+ */
+declare function createDefaultRenderer<T extends BaseBlock>(controller: BlockTreeController<T>, options: DefaultRendererOptions<T>): DefaultRenderer;
+
+interface TreeRendererOptions<T extends BaseBlock> {
+    renderBlock: (block: T, ctx: RenderBlockContext) => HTMLElement;
+    containerTypes: readonly string[];
+    dropZoneHeight?: number;
+}
+/**
+ * Recursive DOM tree builder. Creates the full tree DOM from blocks.
+ * Keyed by data-block-id for efficient reconciliation.
+ */
+declare function renderTree<T extends BaseBlock>(blocks: T[], expandedMap: Record<string, boolean>, controller: BlockTreeController<T>, options: TreeRendererOptions<T>, parentId?: string | null, depth?: number): HTMLElement;
+
+interface DropZoneOptions {
+    id: string;
+    height?: number;
+}
+declare function createDropZoneElement(options: DropZoneOptions): HTMLElement;
+declare function setDropZoneActive(el: HTMLElement, active: boolean): void;
+
+/** Create a semi-transparent in-flow preview of a block at its target position */
+declare function createGhostPreview(sourceEl: HTMLElement): HTMLElement;
+
+/** Create an element with attributes and optional children */
+declare function createElement<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Record<string, string>, children?: (HTMLElement | string)[]): HTMLElementTagNameMap[K];
+/** Set data attributes from an object */
+declare function setDataAttributes(el: HTMLElement, data: Record<string, string | boolean | number>): void;
+/** Find the closest ancestor with a given data attribute */
+declare function closestWithData(el: Element, dataAttr: string): HTMLElement | null;
+
+/**
+ * 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;
+
+/** Collect multiple cleanup functions into a single disposable */
+declare function createDisposable(): Disposable & {
+    add(fn: () => void): void;
+};
+
+export { type BlockHistory, type BlockHistoryOptions, type BlockRendererProps, type BlockRenderers, type BlockTreeController, type BlockTreeControllerOptions, type ContainerRendererProps, type ControllerEvents, type DefaultRenderer, type DefaultRendererOptions, type Disposable, DragOverlay, type DragOverlayOptions, type DragState, type InternalRenderers, KeyboardSensor, type KeyboardSensorCallbacks, LayoutAnimation, type LayoutAnimationOptions, PointerSensor, type PointerSensorOptions, type RenderBlockContext, type RendererPropsFor, type Sensor, type SensorCallbacks, TouchSensor, type TouchSensorOptions, type TreeRendererOptions, type Unsubscribe, type VanillaSensorConfig, type VirtualRange, VirtualScroller, type VirtualScrollerOptions, buildCandidates, closestWithData, createBlockHistory, createBlockTreeController, createDefaultRenderer, createDisposable, createDropZoneElement, createElement, createGhostPreview, detectCollision, measureDropZoneRects, pointerToRect, renderTree, setDataAttributes, setDropZoneActive, triggerHaptic };