snap-dnd 0.1.2 → 0.2.0

package/dist/types/index.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Core types for Snap drag and drop library
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type Unsubscribe = () => void;
+export type Axis = 'x' | 'y' | 'both';
+export interface DragSession {
+    readonly id: string;
+    readonly element: HTMLElement;
+    readonly origin: Point;
+    readonly data: DataTransfer;
+    current: Point;
+    delta: Point;
+    dropZone: HTMLElement | null;
+    phase: DragPhase;
+}
+export type DragPhase = 'pending' | 'dragging' | 'dropping' | 'cancelled';
+export interface DataTransfer {
+    setData(type: string, value: unknown): void;
+    getData<T = unknown>(type: string): T | undefined;
+    hasType(type: string): boolean;
+    readonly types: string[];
+    clear(): void;
+}
+export interface DragStartEvent {
+    readonly element: HTMLElement;
+    readonly position: Point;
+    readonly data: DataTransfer;
+    cancel(): void;
+}
+export interface DragMoveEvent {
+    readonly element: HTMLElement;
+    readonly position: Point;
+    readonly delta: Point;
+    readonly dropZone: HTMLElement | null;
+}
+export interface DragEndEvent {
+    readonly element: HTMLElement;
+    readonly position: Point;
+    readonly delta: Point;
+    readonly cancelled: boolean;
+}
+export interface DropEvent {
+    readonly element: HTMLElement;
+    readonly dropZone: HTMLElement;
+    readonly position: Point;
+    readonly data: DataTransfer;
+    readonly insertionIndex?: number;
+    readonly sourceContainer?: HTMLElement;
+}
+export interface DropZoneEnterEvent {
+    readonly element: HTMLElement;
+    readonly dropZone: HTMLElement;
+    readonly position: Point;
+}
+export interface DropZoneLeaveEvent {
+    readonly element: HTMLElement;
+    readonly dropZone: HTMLElement;
+}
+export interface FileDropEvent {
+    readonly files: File[];
+    readonly position: Point;
+    readonly dropZone: HTMLElement;
+}
+export interface AutoScrollOptions {
+    threshold?: number;
+    maxSpeed?: number;
+    acceleration?: number;
+}
+export interface GridOptions {
+    x: number;
+    y: number;
+}
+export interface SortableOptions {
+    animation?: number;
+    ghostClass?: string;
+    placeholderClass?: string;
+}
+export interface KanbanOptions {
+    containers?: string;
+    items?: string;
+    animation?: number;
+}
+export interface FileDropOptions {
+    accept?: string[];
+    multiple?: boolean;
+    maxSize?: number;
+}
+export interface ItemOptions {
+    data?: Record<string, unknown>;
+    axis?: Axis;
+    handle?: string;
+    disabled?: boolean;
+}
+export interface DropZoneOptions {
+    accepts?: string[] | ((data: DataTransfer) => boolean);
+    onEnter?: (event: DropZoneEnterEvent) => void;
+    onLeave?: (event: DropZoneLeaveEvent) => void;
+}
+export interface SnapOptions {
+    draggableSelector?: string;
+    dropZoneSelector?: string;
+    handleSelector?: string;
+    axis?: Axis;
+    grid?: GridOptions;
+    delay?: number;
+    distance?: number;
+    autoScroll?: boolean | AutoScrollOptions;
+    onDragStart?: (event: DragStartEvent) => void | false;
+    onDragMove?: (event: DragMoveEvent) => void;
+    onDragEnd?: (event: DragEndEvent) => void;
+    onDrop?: (event: DropEvent) => void;
+    onDropZoneEnter?: (event: DropZoneEnterEvent) => void;
+    onDropZoneLeave?: (event: DropZoneLeaveEvent) => void;
+    sortable?: boolean | SortableOptions;
+    kanban?: boolean | KanbanOptions;
+    fileDrop?: boolean | FileDropOptions;
+    autoRefresh?: boolean;
+    ghostClass?: string;
+    placeholderClass?: string;
+}
+export type StateEvent = 'dragstart' | 'dragmove' | 'dragend' | 'dropzoneenter' | 'dropzoneleave' | 'drop';
+export interface Sensor {
+    attach(): void;
+    detach(): void;
+}
+export interface Plugin {
+    name: string;
+    init(snap: SnapInstance): void;
+    destroy(): void;
+}
+export interface Behavior {
+    name: string;
+    onDragStart?(session: DragSession): void;
+    onDragMove?(session: DragSession): void;
+    onDragEnd?(session: DragSession): void;
+    destroy(): void;
+}
+export interface SnapInstance {
+    readonly options: SnapOptions;
+    enable(): void;
+    disable(): void;
+    destroy(): void;
+    refresh(): void;
+    setOptions(options: Partial<SnapOptions>): void;
+    addDraggable(element: HTMLElement, options?: ItemOptions): void;
+    removeDraggable(element: HTMLElement): void;
+    addDropZone(element: HTMLElement, options?: DropZoneOptions): void;
+    removeDropZone(element: HTMLElement): void;
+    isDragging(): boolean;
+    getActiveElement(): HTMLElement | null;
+}

package/dist/utils/BoundsCache.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Cached bounding rect manager using WeakMap
+ * Automatically cleans up when elements are removed from DOM
+ */
+export declare class BoundsCache {
+    private _cache;
+    private _dirty;
+    private _invalidateAll;
+    /**
+     * Get cached bounds for an element, or compute and cache
+     */
+    get(element: Element): DOMRect;
+    /**
+     * Mark a specific element's bounds as dirty
+     */
+    invalidate(element: Element): void;
+    /**
+     * Mark all cached bounds as dirty (e.g., on scroll/resize)
+     */
+    invalidateAll(): void;
+    /**
+     * Force update bounds for an element
+     */
+    update(element: Element): DOMRect;
+    /**
+     * Remove element from cache
+     */
+    remove(element: Element): void;
+    /**
+     * Clear the dirty flag after a frame
+     */
+    clearDirty(): void;
+    private _update;
+}
+export declare const boundsCache: BoundsCache;
+/**
+ * Check if a point is inside a rect
+ */
+export declare function pointInRect(x: number, y: number, rect: DOMRect): boolean;
+/**
+ * Check if two rects intersect
+ */
+export declare function rectsIntersect(a: DOMRect, b: DOMRect): boolean;
+/**
+ * Get the center point of a rect
+ */
+export declare function rectCenter(rect: DOMRect): {
+    x: number;
+    y: number;
+};
+/**
+ * Calculate distance between two points
+ */
+export declare function distance(x1: number, y1: number, x2: number, y2: number): number;

package/dist/utils/DataTransfer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Custom DataTransfer implementation for passing data during drag operations
+ * Not the browser's native DataTransfer
+ */
+import type { DataTransfer as IDataTransfer } from '../types/index.js';
+export declare class SnapDataTransfer implements IDataTransfer {
+    private _data;
+    /**
+     * Set data for a given type
+     */
+    setData(type: string, value: unknown): void;
+    /**
+     * Get data for a given type
+     */
+    getData<T = unknown>(type: string): T | undefined;
+    /**
+     * Check if a type exists
+     */
+    hasType(type: string): boolean;
+    /**
+     * Get all registered types
+     */
+    get types(): string[];
+    /**
+     * Clear all data
+     */
+    clear(): void;
+    /**
+     * Create a copy of this transfer
+     */
+    clone(): SnapDataTransfer;
+}

package/dist/utils/EventEmitter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Lightweight pub/sub event emitter
+ * Optimized for minimal allocations
+ */
+import type { Unsubscribe } from '../types/index.js';
+export type EventCallback<T = unknown> = (data: T) => void;
+export declare class EventEmitter<Events extends Record<string, unknown>> {
+    private _listeners;
+    /**
+     * Subscribe to an event
+     */
+    on<K extends keyof Events>(event: K, callback: EventCallback<Events[K]>): Unsubscribe;
+    /**
+     * Subscribe to an event once
+     */
+    once<K extends keyof Events>(event: K, callback: EventCallback<Events[K]>): Unsubscribe;
+    /**
+     * Emit an event to all subscribers
+     */
+    emit<K extends keyof Events>(event: K, data: Events[K]): void;
+    /**
+     * Remove all listeners for an event, or all listeners
+     */
+    off<K extends keyof Events>(event?: K): void;
+    /**
+     * Check if there are any listeners for an event
+     */
+    hasListeners<K extends keyof Events>(event: K): boolean;
+    /**
+     * Get the number of listeners for an event
+     */
+    listenerCount<K extends keyof Events>(event: K): number;
+    /**
+     * Clear all listeners
+     */
+    destroy(): void;
+}

package/dist/utils/ObjectPool.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Generic object pool for reusing frequently allocated objects
+ * Reduces GC pressure during drag operations
+ */
+export declare class ObjectPool<T> {
+    private _pool;
+    private _factory;
+    private _reset;
+    private _maxSize;
+    constructor(factory: () => T, reset: (obj: T) => void, initialSize?: number, maxSize?: number);
+    /**
+     * Get an object from the pool or create a new one
+     */
+    acquire(): T;
+    /**
+     * Return an object to the pool for reuse
+     */
+    release(obj: T): void;
+    /**
+     * Clear all pooled objects
+     */
+    clear(): void;
+    /**
+     * Current pool size
+     */
+    get size(): number;
+}
+import type { Point, Rect } from '../types/index.js';
+export declare const pointPool: ObjectPool<Point>;
+export declare const rectPool: ObjectPool<Rect>;
+/**
+ * Helper to get a point from pool with initial values
+ */
+export declare function acquirePoint(x: number, y: number): Point;
+/**
+ * Helper to get a rect from pool with initial values
+ */
+export declare function acquireRect(x: number, y: number, width: number, height: number): Rect;

package/dist/utils/RAFThrottle.d.ts

@@ -0,0 +1,39 @@
+/**
+ * RAF-based throttling for high-frequency events
+ * Ensures only one callback per animation frame
+ */
+export declare class RAFThrottle<T> {
+    private _rafId;
+    private _pending;
+    private _callback;
+    constructor(callback: (data: T) => void);
+    /**
+     * Queue data to be processed on next animation frame
+     * Only the most recent data will be processed
+     */
+    queue(data: T): void;
+    /**
+     * Cancel any pending frame
+     */
+    cancel(): void;
+    /**
+     * Process immediately if there's pending data
+     */
+    flush(): void;
+    /**
+     * Check if there's a pending frame
+     */
+    get isPending(): boolean;
+    private _process;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}
+/**
+ * Create a throttled function using RAF
+ */
+export declare function rafThrottle<T extends (...args: unknown[]) => void>(fn: T): T & {
+    cancel: () => void;
+    flush: () => void;
+};

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+export { ObjectPool, pointPool, rectPool, acquirePoint, acquireRect } from './ObjectPool.js';
+export { EventEmitter, type EventCallback } from './EventEmitter.js';
+export { BoundsCache, boundsCache, pointInRect, rectsIntersect, rectCenter, distance } from './BoundsCache.js';
+export { RAFThrottle, rafThrottle } from './RAFThrottle.js';
+export { SnapDataTransfer } from './DataTransfer.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snap-dnd",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "A zero-dependency, memory-optimized drag and drop library for vanilla JS and Web Components",
   "type": "module",
   "main": "./dist/snap.umd.js",