snap-dnd 0.1.0

package/README.md

@@ -0,0 +1,318 @@
+# Snap
+
+A zero-dependency, memory-optimized drag and drop library for vanilla JavaScript and Web Components.
+
+## Features
+
+- **Zero dependencies** - Pure vanilla JavaScript
+- **Tiny footprint** - Core ~5KB gzipped, Full ~9KB gzipped
+- **Memory efficient** - Object pooling, event delegation, WeakMap caches
+- **Web Component ready** - Works with Shadow DOM and Lit Elements
+- **Touch support** - Mouse, touch, and pointer events
+- **Beginner friendly** - Works with just data attributes
+- **Highly customizable** - Plugin system, behaviors, comprehensive options
+
+## Bundle Sizes
+
+| Import | Minified | Gzipped |
+|--------|----------|---------|
+| `snap-dnd/core` | 17.6 KB | **~5 KB** |
+| `snap-dnd` (full) | 35.3 KB | ~9 KB |
+
+## Installation
+
+```bash
+npm install snap-dnd
+```
+
+### Core Only (Minimal ~5KB)
+
+If you don't need plugins (Sortable, Kanban, FileDrop), import the core:
+
+```javascript
+import { Snap } from 'snap-dnd/core';
+```
+
+## Quick Start
+
+### Declarative (Data Attributes)
+
+The simplest way to use Snap - just add data attributes:
+
+```html
+<div id="container">
+  <div data-draggable>Drag me!</div>
+  <div data-draggable>Drag me too!</div>
+  <div data-droppable>Drop here</div>
+</div>
+
+<script type="module">
+  import { Snap } from 'snap-dnd';
+
+  const snap = new Snap(document.getElementById('container'), {
+    onDrop: (e) => console.log('Dropped!', e.element, 'into', e.dropZone)
+  });
+</script>
+```
+
+### Imperative (JavaScript)
+
+For more control, use the imperative API:
+
+```javascript
+import { Snap } from 'snap-dnd';
+
+const snap = new Snap(container, {
+  onDragStart: (e) => console.log('Started dragging', e.element),
+  onDragMove: (e) => console.log('Moving', e.position),
+  onDrop: (e) => console.log('Dropped', e.element, 'at index', e.insertionIndex),
+});
+
+// Add elements programmatically
+snap.addDraggable(myElement, {
+  data: { id: 1, type: 'task' },
+  axis: 'y'  // Only vertical movement
+});
+
+snap.addDropZone(myZone, {
+  accepts: ['task'],
+  onEnter: () => myZone.classList.add('highlight')
+});
+
+// Cleanup when done
+snap.destroy();
+```
+
+## Data Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `data-draggable` | Makes element draggable |
+| `data-droppable` | Makes element a drop zone |
+| `data-drag-handle` | Only this element can initiate drag |
+| `data-drag-axis="x\|y"` | Constrain to horizontal or vertical |
+| `data-drag-id="..."` | Custom ID passed to callbacks |
+| `data-drag-type="..."` | Type for drop zone filtering |
+| `data-accepts="a,b,c"` | Types this drop zone accepts |
+| `data-file-drop` | Enable file drop zone |
+
+## Options
+
+```typescript
+const snap = new Snap(container, {
+  // Selectors
+  draggableSelector: '[data-draggable]',
+  dropZoneSelector: '[data-droppable]',
+  handleSelector: '[data-drag-handle]',
+
+  // Behavior
+  axis: 'both',         // 'x', 'y', or 'both'
+  grid: { x: 20, y: 20 },  // Snap to grid
+  delay: 0,             // ms before drag starts
+  distance: 0,          // px before drag starts
+
+  // Auto-scroll when near edges
+  autoScroll: true,     // or { threshold: 40, maxSpeed: 15 }
+
+  // Callbacks
+  onDragStart: (e) => {},
+  onDragMove: (e) => {},
+  onDragEnd: (e) => {},
+  onDrop: (e) => {},
+  onDropZoneEnter: (e) => {},
+  onDropZoneLeave: (e) => {},
+
+  // Advanced
+  autoRefresh: false,   // Auto-detect DOM changes
+  ghostClass: 'my-ghost',
+});
+```
+
+## With Lit Elements
+
+Snap works seamlessly with Web Components:
+
+```javascript
+import { LitElement, html } from 'lit';
+import { Snap } from 'snap-dnd';
+
+class TaskBoard extends LitElement {
+  snap;
+
+  firstUpdated() {
+    this.snap = new Snap(this.shadowRoot, {
+      autoRefresh: true,  // Handle Lit re-renders
+      onDrop: this.handleDrop.bind(this)
+    });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.snap?.destroy();
+  }
+
+  handleDrop(e) {
+    // Update your state, Lit will re-render
+    this.tasks = reorder(this.tasks, e.insertionIndex);
+  }
+
+  render() {
+    return html`
+      <ul>
+        ${this.tasks.map(task => html`
+          <li data-draggable data-drag-id=${task.id}>${task.title}</li>
+        `)}
+      </ul>
+    `;
+  }
+}
+```
+
+## Plugins
+
+### Sortable
+
+Reorder items within a container:
+
+```javascript
+import { Snap, Sortable } from 'snap-dnd';
+
+const snap = new Snap(container).use(new Sortable({
+  animation: 150,
+  ghostClass: 'sortable-ghost',
+  placeholderClass: 'sortable-placeholder'
+}));
+```
+
+### Kanban
+
+Move items between multiple containers:
+
+```javascript
+import { Snap, Kanban } from 'snap-dnd';
+
+const snap = new Snap(board).use(new Kanban({
+  containers: '.column',
+  items: '.card',
+  animation: 150
+}));
+```
+
+### FileDrop
+
+Handle file drops from desktop:
+
+```javascript
+import { Snap, FileDrop } from 'snap-dnd';
+
+const snap = new Snap(container).use(
+  new FileDrop({
+    accept: ['image/*', '.pdf'],
+    multiple: true,
+    maxSize: 10 * 1024 * 1024  // 10MB
+  }).onFileDrop((e) => {
+    console.log('Files dropped:', e.files);
+  })
+);
+```
+
+Or use the standalone helper:
+
+```javascript
+import { createFileDropZone } from 'snap-dnd';
+
+const cleanup = createFileDropZone(element, {
+  accept: ['image/*'],
+  onDrop: (files) => uploadFiles(files)
+});
+
+// Later: cleanup();
+```
+
+## Behaviors
+
+Add optional behaviors for extra functionality:
+
+```javascript
+import { Snap, AutoScroll, SnapGrid } from 'snap-dnd';
+
+const snap = new Snap(container)
+  .addBehavior(new AutoScroll({ threshold: 50, maxSpeed: 20 }))
+  .addBehavior(new SnapGrid({ x: 10, y: 10 }));
+```
+
+## CSS
+
+Snap doesn't inject any CSS. Add your own styles:
+
+```css
+/* Required for touch devices */
+[data-draggable] {
+  touch-action: none;
+  user-select: none;
+  cursor: grab;
+}
+
+/* Optional visual feedback */
+.snap-dragging { opacity: 0.5; }
+.snap-drop-active { background: rgba(0,120,255,0.1); }
+.snap-ghost { box-shadow: 0 4px 12px rgba(0,0,0,0.15); }
+```
+
+See `examples/snap.css` for a complete reference stylesheet.
+
+## API Reference
+
+### Snap Instance
+
+```typescript
+interface Snap {
+  enable(): void;
+  disable(): void;
+  destroy(): void;
+  refresh(): 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;
+
+  use(plugin: Plugin): this;
+  addBehavior(behavior: Behavior): this;
+  setOptions(options: Partial<SnapOptions>): void;
+}
+```
+
+### Event Objects
+
+```typescript
+interface DragStartEvent {
+  element: HTMLElement;
+  position: { x: number; y: number };
+  data: DataTransfer;
+  cancel(): void;
+}
+
+interface DropEvent {
+  element: HTMLElement;
+  dropZone: HTMLElement;
+  position: { x: number; y: number };
+  data: DataTransfer;
+  insertionIndex?: number;
+  sourceContainer?: HTMLElement;
+}
+```
+
+## Browser Support
+
+- Chrome 88+
+- Firefox 85+
+- Safari 14+
+- Edge 88+
+
+## License
+
+MIT

package/dist/behaviors/AutoScroll.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AutoScroll behavior - scrolls containers when dragging near edges
+ */
+import type { Behavior, DragSession, AutoScrollOptions } from '../types/index.js';
+export declare class AutoScroll implements Behavior {
+    name: string;
+    private _options;
+    private _scrollableAncestors;
+    private _rafId;
+    private _active;
+    constructor(options?: AutoScrollOptions);
+    onDragStart(session: DragSession): void;
+    onDragMove(session: DragSession): void;
+    onDragEnd(): void;
+    destroy(): void;
+    private _performScroll;
+    private _calculateScrollSpeed;
+    private _getSpeed;
+    private _findScrollableAncestors;
+}

package/dist/behaviors/ConstraintAxis.d.ts

@@ -0,0 +1,37 @@
+/**
+ * ConstraintAxis behavior - constrain movement to specific axis
+ * Note: Basic axis constraint is handled in DragEngine via options.axis
+ * This behavior adds additional constraint features like bounds
+ */
+import type { Behavior, DragSession, Axis, Point } from '../types/index.js';
+export interface ConstraintOptions {
+    axis?: Axis;
+    /** Bounding rectangle to constrain within */
+    bounds?: {
+        minX?: number;
+        maxX?: number;
+        minY?: number;
+        maxY?: number;
+    };
+    /** Constrain to parent element bounds */
+    containWithinParent?: boolean;
+}
+export declare class ConstraintAxis implements Behavior {
+    name: string;
+    private _options;
+    private _bounds;
+    constructor(options?: ConstraintOptions);
+    onDragStart(session: DragSession): void;
+    onDragMove(_session: DragSession): void;
+    onDragEnd(): void;
+    destroy(): void;
+    /**
+     * Apply constraints to a point
+     */
+    constrain(point: Point, origin: Point): Point;
+    /**
+     * Get current bounds
+     */
+    getBounds(): typeof this._bounds;
+    private _calculateParentBounds;
+}

package/dist/behaviors/SnapGrid.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SnapGrid behavior - snaps drag position to a grid
+ * Note: This is handled in DragEngine via options.grid
+ * This behavior provides additional grid-related features
+ */
+import type { Behavior, DragSession, GridOptions } from '../types/index.js';
+export interface SnapGridOptions extends GridOptions {
+    /** Only snap when within threshold of grid line */
+    threshold?: number;
+    /** Show visual grid guides */
+    showGuides?: boolean;
+}
+export declare class SnapGrid implements Behavior {
+    name: string;
+    private _options;
+    private _guideContainer;
+    constructor(options: SnapGridOptions);
+    onDragStart(session: DragSession): void;
+    onDragMove(_session: DragSession): void;
+    onDragEnd(): void;
+    destroy(): void;
+    /**
+     * Snap a point to the grid
+     */
+    snap(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Snap with threshold - only snap when close to grid line
+     */
+    snapWithThreshold(x: number, y: number, threshold?: number): {
+        x: number;
+        y: number;
+    };
+    private _createGuides;
+    private _removeGuides;
+}

package/dist/behaviors/index.d.ts

@@ -0,0 +1,3 @@
+export { AutoScroll } from './AutoScroll.js';
+export { SnapGrid, type SnapGridOptions } from './SnapGrid.js';
+export { ConstraintAxis, type ConstraintOptions } from './ConstraintAxis.js';

package/dist/core/DragEngine.d.ts

@@ -0,0 +1,60 @@
+/**
+ * DragEngine orchestrates the drag operation
+ * Coordinates between sensors, state, and drop zones
+ */
+import type { SnapOptions, Axis } from '../types/index.js';
+import { DragState } from './DragState.js';
+export interface DragEngineOptions {
+    container: HTMLElement | ShadowRoot;
+    state: DragState;
+    options: SnapOptions;
+    getDropZones: () => HTMLElement[];
+    getItemData: (element: HTMLElement) => Record<string, unknown> | undefined;
+    getItemAxis: (element: HTMLElement) => Axis | undefined;
+}
+export declare class DragEngine {
+    private _container;
+    private _state;
+    private _options;
+    private _getDropZones;
+    private _getItemData;
+    private _getItemAxis;
+    private _pointerSensor;
+    private _enabled;
+    private _ghost;
+    private _ghostOffset;
+    constructor(engineOptions: DragEngineOptions);
+    /**
+     * Enable drag engine
+     */
+    enable(): void;
+    /**
+     * Disable drag engine
+     */
+    disable(): void;
+    /**
+     * Check if enabled
+     */
+    get isEnabled(): boolean;
+    /**
+     * Update options
+     */
+    updateOptions(options: Partial<SnapOptions>): void;
+    private _setupListeners;
+    private _onPointerDown;
+    private _onPointerMove;
+    private _onPointerUp;
+    private _onPointerCancel;
+    private _applyAxisConstraint;
+    private _applyGridSnap;
+    private _updateDropZone;
+    private _createGhost;
+    private _updateGhost;
+    private _removeGhost;
+    private _cleanup;
+    private _extractDataAttributes;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}

package/dist/core/DragState.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Centralized drag state management
+ * Single source of truth for the current drag session
+ */
+import type { DragSession, Point, StateEvent, Unsubscribe } from '../types/index.js';
+import { EventEmitter } from '../utils/EventEmitter.js';
+interface StateEvents {
+    dragstart: DragSession;
+    dragmove: DragSession;
+    dragend: DragSession;
+    dropzoneenter: DragSession;
+    dropzoneleave: DragSession;
+    drop: DragSession;
+}
+export declare class DragState extends EventEmitter<StateEvents> {
+    private _session;
+    private _idCounter;
+    /**
+     * Get current drag session (null if not dragging)
+     */
+    get session(): DragSession | null;
+    /**
+     * Check if currently dragging
+     */
+    isDragging(): boolean;
+    /**
+     * Get the element being dragged
+     */
+    getActiveElement(): HTMLElement | null;
+    /**
+     * Get current drop zone
+     */
+    getCurrentDropZone(): HTMLElement | null;
+    /**
+     * Start a new drag session
+     */
+    startDrag(element: HTMLElement, origin: Point, initialData?: Record<string, unknown>): DragSession;
+    /**
+     * Update position during drag
+     */
+    updatePosition(point: Point): void;
+    /**
+     * Set or clear drop zone target
+     */
+    setDropTarget(zone: HTMLElement | null): void;
+    /**
+     * Complete the drag with a drop
+     */
+    endDrag(): DragSession | null;
+    /**
+     * Cancel the current drag
+     */
+    cancelDrag(): DragSession | null;
+    /**
+     * Subscribe to state changes
+     */
+    subscribe(event: StateEvent, callback: (session: DragSession) => void): Unsubscribe;
+    /**
+     * Reset state
+     */
+    reset(): void;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}
+export {};

package/dist/core/DropZone.d.ts

@@ -0,0 +1,97 @@
+/**
+ * DropZone manages individual drop target areas
+ * Handles hit testing and insertion index calculation
+ */
+import type { DataTransfer, DropZoneOptions } from '../types/index.js';
+export declare class DropZone {
+    private _element;
+    private _options;
+    private _isActive;
+    constructor(element: HTMLElement, options?: DropZoneOptions);
+    /**
+     * The DOM element for this drop zone
+     */
+    get element(): HTMLElement;
+    /**
+     * Whether this zone is currently active (being hovered)
+     */
+    get isActive(): boolean;
+    /**
+     * Update options
+     */
+    setOptions(options: Partial<DropZoneOptions>): void;
+    /**
+     * Check if a point is inside this drop zone
+     */
+    containsPoint(x: number, y: number): boolean;
+    /**
+     * Check if this zone accepts the given data
+     */
+    accepts(data: DataTransfer): boolean;
+    /**
+     * Set active state and add/remove CSS class
+     */
+    setActive(active: boolean): void;
+    /**
+     * Calculate insertion index for sortable behavior
+     * Returns the index where an item should be inserted based on position
+     */
+    getInsertionIndex(x: number, y: number, itemSelector: string, excludeElement?: HTMLElement): number;
+    /**
+     * Get closest item to a point (for visual feedback)
+     */
+    getClosestItem(x: number, y: number, itemSelector: string, excludeElement?: HTMLElement): {
+        element: HTMLElement;
+        position: 'before' | 'after';
+    } | null;
+    /**
+     * Force update cached bounds
+     */
+    updateBounds(): void;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}
+/**
+ * DropZoneManager handles multiple drop zones
+ */
+export declare class DropZoneManager {
+    private _zones;
+    /**
+     * Register a drop zone
+     */
+    register(element: HTMLElement, options?: DropZoneOptions): DropZone;
+    /**
+     * Unregister a drop zone
+     */
+    unregister(element: HTMLElement): void;
+    /**
+     * Get drop zone for an element
+     */
+    get(element: HTMLElement): DropZone | undefined;
+    /**
+     * Get all drop zone elements
+     */
+    getElements(): HTMLElement[];
+    /**
+     * Get all drop zones
+     */
+    getAll(): DropZone[];
+    /**
+     * Find drop zone at point
+     */
+    findAtPoint(x: number, y: number): DropZone | null;
+    /**
+     * Clear all drop zones
+     */
+    clear(): void;
+    /**
+     * Update all bounds (e.g., after scroll/resize)
+     */
+    updateAllBounds(): void;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}