snap-dnd 0.1.3 → 0.2.0

package/README.md

@@ -351,6 +351,111 @@ interface DropEvent {
 }
 ```
 
+## Security Considerations
+
+Snap is designed with security in mind for enterprise and banking applications.
+
+### Built-in Security Features
+
+1. **Prototype Pollution Protection**
+   - All option merging uses `safeMerge()` which blocks `__proto__`, `constructor`, and `prototype` keys
+
+2. **Selector Validation**
+   - User-provided CSS selectors are validated before use
+   - Blocks potentially dangerous patterns (javascript:, expression(), etc.)
+   - Falls back to safe defaults if validation fails
+
+3. **Data Attribute Sanitization**
+   - Only allowed data attributes are extracted (`data-drag-id`, `data-drag-type`, etc.)
+   - Values are sanitized to prevent XSS via HTML tags
+
+4. **Banking-Grade File Validation** (FileDrop plugin)
+   ```javascript
+   const snap = new Snap(container).use(new FileDrop({
+     secureValidation: true,        // Enable strict validation
+     validateMagicBytes: true,      // Detect extension spoofing
+     maxSize: 10 * 1024 * 1024,     // 10MB limit
+     minSize: 1,                    // Reject empty files
+     maxFiles: 10,                  // Limit batch uploads
+     accept: ['.pdf', '.docx'],     // Whitelist extensions
+     onValidationError: (errors) => {
+       // Handle rejected files
+       errors.forEach(({ file, error }) => {
+         console.warn(`${file.name}: ${error}`);
+       });
+     }
+   }));
+   ```
+
+### Content Security Policy (CSP)
+
+Snap requires the following CSP directives:
+
+```
+style-src 'unsafe-inline';  /* Required for ghost/placeholder positioning */
+```
+
+For strict CSP environments without `unsafe-inline`:
+- Provide your own ghost/placeholder elements via CSS classes
+- Override the default ghost creation using callbacks
+
+### Security Best Practices
+
+1. **Validate Drop Data**
+   ```javascript
+   onDrop: (e) => {
+     // Always validate data from drag operations
+     const itemId = e.data.getData('id');
+     if (!isValidId(itemId)) return;
+
+     // Verify user permissions server-side
+     await api.moveItem(itemId, e.dropZone.id);
+   }
+   ```
+
+2. **Sanitize File Uploads**
+   ```javascript
+   // Always validate files server-side even with client validation
+   onFileDrop: async (e) => {
+     const formData = new FormData();
+     for (const file of e.files) {
+       formData.append('files', file);
+     }
+
+     // Server should re-validate file types, scan for malware
+     const response = await fetch('/upload', {
+       method: 'POST',
+       body: formData,
+       credentials: 'same-origin'
+     });
+   }
+   ```
+
+3. **CSRF Protection**
+   - Include CSRF tokens in any server requests triggered by drop events
+   - Use `credentials: 'same-origin'` for fetch requests
+
+4. **Disable in Sensitive Contexts**
+   ```javascript
+   // Disable drag when viewing sensitive data
+   if (isViewingSecureDocument) {
+     snap.disable();
+   }
+   ```
+
+### Security Utilities
+
+Snap exports security utilities for custom use:
+
+```javascript
+import {
+  safeMerge,           // Prototype pollution-safe object merge
+  sanitizeSelector,    // Validate CSS selectors
+  validateFiles,       // Banking-grade file validation
+  sanitizeDataValue,   // Strip HTML from strings
+} from 'snap-dnd';
+```
+
 ## Browser Support
 
 - Chrome 88+

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;
+}

package/dist/core/Snap.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Snap - Main entry point for the drag and drop library
+ * Coordinates all subsystems and provides the public API
+ */
+import type { SnapOptions, SnapInstance, ItemOptions, DropZoneOptions, Plugin, Behavior } from '../types/index.js';
+export declare class Snap implements SnapInstance {
+    private _container;
+    private _options;
+    private _state;
+    private _engine;
+    private _dropZoneManager;
+    private _imperativeDraggables;
+    private _imperativeDropZones;
+    private _plugins;
+    private _behaviors;
+    private _observer;
+    private _refreshScheduled;
+    private _scrollHandler;
+    private _resizeHandler;
+    constructor(container: HTMLElement | ShadowRoot, options?: SnapOptions);
+    /**
+     * Current options
+     */
+    get options(): SnapOptions;
+    /**
+     * Enable drag and drop
+     */
+    enable(): void;
+    /**
+     * Disable drag and drop
+     */
+    disable(): void;
+    /**
+     * Cleanup and destroy instance
+     */
+    destroy(): void;
+    /**
+     * Re-scan for declarative elements (call after DOM changes)
+     */
+    refresh(): void;
+    /**
+     * Register a draggable element imperatively
+     */
+    addDraggable(element: HTMLElement, options?: ItemOptions): void;
+    /**
+     * Unregister a draggable element
+     */
+    removeDraggable(element: HTMLElement): void;
+    /**
+     * Register a drop zone imperatively
+     */
+    addDropZone(element: HTMLElement, options?: DropZoneOptions): void;
+    /**
+     * Unregister a drop zone
+     */
+    removeDropZone(element: HTMLElement): void;
+    /**
+     * Check if currently dragging
+     */
+    isDragging(): boolean;
+    /**
+     * Get the element currently being dragged
+     */
+    getActiveElement(): HTMLElement | null;
+    /**
+     * Register a plugin
+     */
+    use(plugin: Plugin): this;
+    /**
+     * Add a behavior
+     */
+    addBehavior(behavior: Behavior): this;
+    /**
+     * Update options dynamically
+     */
+    setOptions(options: Partial<SnapOptions>): void;
+    private _getDropZones;
+    private _getItemData;
+    private _getItemAxis;
+    private _scanDeclarativeElements;
+    private _setupStateListeners;
+    private _setupAutoRefresh;
+    private _setupScrollResize;
+}
+export default Snap;

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export { Snap, default } from './Snap.js';
+export { DragState } from './DragState.js';
+export { DragEngine, type DragEngineOptions } from './DragEngine.js';
+export { DropZone, DropZoneManager } from './DropZone.js';

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Snap - A zero-dependency, memory-optimized drag and drop library
+ *
+ * @example Basic usage with data attributes
+ * ```html
+ * <div id="container">
+ *   <div data-draggable>Drag me</div>
+ *   <div data-droppable>Drop here</div>
+ * </div>
+ *
+ * <script>
+ *   const snap = new Snap(document.getElementById('container'));
+ * </script>
+ * ```
+ *
+ * @example Imperative usage
+ * ```javascript
+ * const snap = new Snap(container, {
+ *   onDrop: (e) => console.log('Dropped!', e.element, e.dropZone)
+ * });
+ *
+ * snap.addDraggable(myElement, { data: { id: 1 } });
+ * snap.addDropZone(myZone, { accepts: ['item'] });
+ * ```
+ *
+ * @example With Lit Element
+ * ```javascript
+ * class MyComponent extends LitElement {
+ *   snap;
+ *
+ *   firstUpdated() {
+ *     this.snap = new Snap(this.shadowRoot, {
+ *       autoRefresh: true,
+ *       onDrop: this.handleDrop.bind(this)
+ *     });
+ *   }
+ *
+ *   disconnectedCallback() {
+ *     super.disconnectedCallback();
+ *     this.snap?.destroy();
+ *   }
+ * }
+ * ```
+ */
+export { Snap, default } from './core/Snap.js';
+export { DragState } from './core/DragState.js';
+export { DragEngine } from './core/DragEngine.js';
+export { DropZone, DropZoneManager } from './core/DropZone.js';
+export { Sortable } from './plugins/Sortable.js';
+export { Kanban } from './plugins/Kanban.js';
+export { FileDrop, createFileDropZone } from './plugins/FileDrop.js';
+export { AutoScroll } from './behaviors/AutoScroll.js';
+export { SnapGrid } from './behaviors/SnapGrid.js';
+export { ConstraintAxis } from './behaviors/ConstraintAxis.js';
+export { EventEmitter } from './utils/EventEmitter.js';
+export { ObjectPool, pointPool, rectPool } from './utils/ObjectPool.js';
+export { BoundsCache, boundsCache } from './utils/BoundsCache.js';
+export { RAFThrottle, rafThrottle } from './utils/RAFThrottle.js';
+export { SnapDataTransfer } from './utils/DataTransfer.js';
+export { PointerSensor } from './sensors/PointerSensor.js';
+export { FileSensor } from './sensors/FileSensor.js';
+export type { Point, Rect, Axis, Unsubscribe, DragSession, DragPhase, DataTransfer, DragStartEvent, DragMoveEvent, DragEndEvent, DropEvent, DropZoneEnterEvent, DropZoneLeaveEvent, FileDropEvent, SnapOptions, SnapInstance, ItemOptions, DropZoneOptions, AutoScrollOptions, GridOptions, SortableOptions, KanbanOptions, FileDropOptions, Plugin, Behavior, Sensor, } from './types/index.js';

package/dist/plugins/FileDrop.d.ts

@@ -0,0 +1,33 @@
+/**
+ * FileDrop plugin - enables file drop zones for external files
+ */
+import type { Plugin, SnapInstance, FileDropOptions, FileDropEvent } from '../types/index.js';
+export declare class FileDrop implements Plugin {
+    name: string;
+    private _snap;
+    private _options;
+    private _sensor;
+    private _onFileDrop;
+    constructor(options?: FileDropOptions);
+    init(snap: SnapInstance): void;
+    destroy(): void;
+    /**
+     * Set callback for file drop events
+     */
+    onFileDrop(callback: (event: FileDropEvent) => void): this;
+    /**
+     * Update file drop options
+     */
+    setOptions(options: Partial<FileDropOptions>): void;
+    private _getContainer;
+    private _setupEventHandlers;
+}
+/**
+ * Simple file drop zone creation helper
+ * For basic use cases without full Snap instance
+ */
+export declare function createFileDropZone(element: HTMLElement, options: FileDropOptions & {
+    onDrop: (files: File[]) => void;
+    onDragEnter?: () => void;
+    onDragLeave?: () => void;
+}): () => void;

package/dist/plugins/Kanban.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Kanban plugin - enables moving items between multiple containers
+ */
+import type { Plugin, SnapInstance, KanbanOptions } from '../types/index.js';
+export declare class Kanban implements Plugin {
+    name: string;
+    private _snap;
+    private _options;
+    private _sourceContainer;
+    private _targetContainer;
+    private _placeholder;
+    private _originalIndex;
+    private _currentIndex;
+    constructor(options?: KanbanOptions);
+    init(snap: SnapInstance): void;
+    destroy(): void;
+    private _onDragStart;
+    private _onDragMove;
+    private _onDropZoneEnter;
+    private _onDropZoneLeave;
+    private _onDragEnd;
+    private _createPlaceholder;
+    private _movePlaceholder;
+    private _calculateInsertionIndex;
+    private _getItemCount;
+    private _animateItems;
+    private _cleanup;
+    /**
+     * Get source container during drag
+     */
+    getSourceContainer(): HTMLElement | null;
+    /**
+     * Get target container during drag
+     */
+    getTargetContainer(): HTMLElement | null;
+    /**
+     * Get current insertion index
+     */
+    getCurrentIndex(): number;
+}