@aspect-ops/exon-ui 0.0.1 → 0.0.3

package/dist/utils/gestures.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Touch gesture utilities for mobile-friendly interactions
+ * Supports swipe, drag, and pinch gestures with velocity tracking
+ */
+/** Direction of a swipe gesture */
+export type SwipeDirection = 'left' | 'right' | 'up' | 'down';
+/** Options for swipe gesture detection */
+export interface SwipeOptions {
+    /** Minimum distance in pixels to trigger swipe (default: 50) */
+    threshold?: number;
+    /** Maximum time in ms for swipe to be valid (default: 300) */
+    maxTime?: number;
+    /** Callback when swipe is detected */
+    onSwipe?: (direction: SwipeDirection, velocity: number) => void;
+    /** Callback for swipe left */
+    onSwipeLeft?: (velocity: number) => void;
+    /** Callback for swipe right */
+    onSwipeRight?: (velocity: number) => void;
+    /** Callback for swipe up */
+    onSwipeUp?: (velocity: number) => void;
+    /** Callback for swipe down */
+    onSwipeDown?: (velocity: number) => void;
+}
+/** Current state of a drag gesture */
+export interface DragState {
+    /** Whether drag is currently active */
+    isDragging: boolean;
+    /** Starting X position */
+    startX: number;
+    /** Starting Y position */
+    startY: number;
+    /** Current X position */
+    currentX: number;
+    /** Current Y position */
+    currentY: number;
+    /** Change in X from start */
+    deltaX: number;
+    /** Change in Y from start */
+    deltaY: number;
+    /** Horizontal velocity in pixels/ms */
+    velocityX: number;
+    /** Vertical velocity in pixels/ms */
+    velocityY: number;
+}
+/** Options for drag gesture tracking */
+export interface DragOptions {
+    /** Minimum distance to start drag (default: 0) */
+    threshold?: number;
+    /** Callback on drag start */
+    onDragStart?: (state: DragState) => void;
+    /** Callback during drag */
+    onDrag?: (state: DragState) => void;
+    /** Callback on drag end */
+    onDragEnd?: (state: DragState) => void;
+}
+/** Current state of a pinch gesture */
+export interface PinchState {
+    /** Whether pinch is currently active */
+    isPinching: boolean;
+    /** Initial distance between touch points */
+    initialDistance: number;
+    /** Current distance between touch points */
+    currentDistance: number;
+    /** Scale factor (current / initial) */
+    scale: number;
+    /** Center X position between fingers */
+    centerX: number;
+    /** Center Y position between fingers */
+    centerY: number;
+    /** Rotation angle in degrees (if fingers rotate) */
+    rotation: number;
+}
+/** Options for pinch gesture detection */
+export interface PinchOptions {
+    /** Minimum scale change to trigger callback (default: 0.01) */
+    scaleThreshold?: number;
+    /** Callback on pinch start */
+    onPinchStart?: (state: PinchState) => void;
+    /** Callback during pinch */
+    onPinch?: (state: PinchState) => void;
+    /** Callback on pinch end */
+    onPinchEnd?: (state: PinchState) => void;
+}
+/** Handler interface returned by gesture creators */
+export interface GestureHandler {
+    start: (e: TouchEvent) => void;
+    move: (e: TouchEvent) => void;
+    end: (e: TouchEvent) => void;
+    cancel?: (e: TouchEvent) => void;
+}
+/**
+ * Creates a swipe gesture handler
+ * Detects horizontal and vertical swipes with velocity
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   const swipe = createSwipeHandler({
+ *     threshold: 50,
+ *     onSwipe: (direction) => console.log('Swiped:', direction)
+ *   });
+ * </script>
+ *
+ * <div ontouchstart={swipe.start} ontouchmove={swipe.move} ontouchend={swipe.end}>
+ *   Swipe me
+ * </div>
+ * ```
+ */
+export declare function createSwipeHandler(options?: SwipeOptions): GestureHandler;
+/**
+ * Creates a drag gesture handler
+ * Tracks position and velocity during drag
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let x = 0, y = 0;
+ *   const drag = createDragHandler({
+ *     onDrag: (state) => {
+ *       x = state.deltaX;
+ *       y = state.deltaY;
+ *     }
+ *   });
+ * </script>
+ *
+ * <div
+ *   style="transform: translate({x}px, {y}px)"
+ *   ontouchstart={drag.start}
+ *   ontouchmove={drag.move}
+ *   ontouchend={drag.end}
+ * >
+ *   Drag me
+ * </div>
+ * ```
+ */
+export declare function createDragHandler(options?: DragOptions): GestureHandler;
+/**
+ * Creates a pinch gesture handler
+ * Detects scale changes from two-finger pinch
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let scale = 1;
+ *   const pinch = createPinchHandler({
+ *     onPinch: (state) => {
+ *       scale = state.scale;
+ *     }
+ *   });
+ * </script>
+ *
+ * <div
+ *   style="transform: scale({scale})"
+ *   ontouchstart={pinch.start}
+ *   ontouchmove={pinch.move}
+ *   ontouchend={pinch.end}
+ * >
+ *   Pinch to zoom
+ * </div>
+ * ```
+ */
+export declare function createPinchHandler(options?: PinchOptions): GestureHandler;
+/** Action options for swipe */
+export interface SwipeActionOptions extends SwipeOptions {
+    /** Prevent default touch behavior */
+    preventDefault?: boolean;
+}
+/** Action options for drag */
+export interface DragActionOptions extends DragOptions {
+    /** Prevent default touch behavior */
+    preventDefault?: boolean;
+}
+/** Action options for pinch */
+export interface PinchActionOptions extends PinchOptions {
+    /** Prevent default touch behavior */
+    preventDefault?: boolean;
+}
+/**
+ * Svelte action for swipe gestures
+ *
+ * @example
+ * ```svelte
+ * <div use:swipeAction={{ onSwipeLeft: () => console.log('Left!') }}>
+ *   Swipe me
+ * </div>
+ * ```
+ */
+export declare function swipeAction(node: HTMLElement, options?: SwipeActionOptions): {
+    update(newOptions: SwipeActionOptions): void;
+    destroy(): void;
+};
+/**
+ * Svelte action for drag gestures
+ *
+ * @example
+ * ```svelte
+ * <div use:dragAction={{ onDrag: (state) => console.log(state.deltaX, state.deltaY) }}>
+ *   Drag me
+ * </div>
+ * ```
+ */
+export declare function dragAction(node: HTMLElement, options?: DragActionOptions): {
+    update(newOptions: DragActionOptions): void;
+    destroy(): void;
+};
+/**
+ * Svelte action for pinch gestures
+ *
+ * @example
+ * ```svelte
+ * <div use:pinchAction={{ onPinch: (state) => console.log('Scale:', state.scale) }}>
+ *   Pinch to zoom
+ * </div>
+ * ```
+ */
+export declare function pinchAction(node: HTMLElement, options?: PinchActionOptions): {
+    update(newOptions: PinchActionOptions): void;
+    destroy(): void;
+};

package/dist/utils/gestures.js

@@ -0,0 +1,492 @@
+/**
+ * Touch gesture utilities for mobile-friendly interactions
+ * Supports swipe, drag, and pinch gestures with velocity tracking
+ */
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/** Calculate distance between two points */
+function getDistance(x1, y1, x2, y2) {
+    return Math.sqrt(Math.pow(x2 - x1, 2) + Math.pow(y2 - y1, 2));
+}
+/** Calculate angle between two points in degrees */
+function getAngle(x1, y1, x2, y2) {
+    return Math.atan2(y2 - y1, x2 - x1) * (180 / Math.PI);
+}
+/** Calculate velocity (pixels per millisecond) */
+function calculateVelocity(distance, time) {
+    return time > 0 ? distance / time : 0;
+}
+// ============================================================================
+// Swipe Handler
+// ============================================================================
+/**
+ * Creates a swipe gesture handler
+ * Detects horizontal and vertical swipes with velocity
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   const swipe = createSwipeHandler({
+ *     threshold: 50,
+ *     onSwipe: (direction) => console.log('Swiped:', direction)
+ *   });
+ * </script>
+ *
+ * <div ontouchstart={swipe.start} ontouchmove={swipe.move} ontouchend={swipe.end}>
+ *   Swipe me
+ * </div>
+ * ```
+ */
+export function createSwipeHandler(options = {}) {
+    const { threshold = 50, maxTime = 300, onSwipe, onSwipeLeft, onSwipeRight, onSwipeUp, onSwipeDown } = options;
+    let startX = 0;
+    let startY = 0;
+    let startTime = 0;
+    let tracking = false;
+    return {
+        start(e) {
+            if (e.touches.length !== 1)
+                return;
+            const touch = e.touches[0];
+            startX = touch.clientX;
+            startY = touch.clientY;
+            startTime = Date.now();
+            tracking = true;
+        },
+        move(_e) {
+            // Swipe doesn't need move tracking, but included for API consistency
+        },
+        end(e) {
+            if (!tracking)
+                return;
+            tracking = false;
+            const touch = e.changedTouches[0];
+            const endX = touch.clientX;
+            const endY = touch.clientY;
+            const endTime = Date.now();
+            const diffX = endX - startX;
+            const diffY = endY - startY;
+            const elapsed = endTime - startTime;
+            // Check if swipe was quick enough
+            if (elapsed > maxTime)
+                return;
+            const absX = Math.abs(diffX);
+            const absY = Math.abs(diffY);
+            // Determine if horizontal or vertical swipe
+            if (absX > absY && absX > threshold) {
+                // Horizontal swipe
+                const velocity = calculateVelocity(absX, elapsed);
+                const direction = diffX > 0 ? 'right' : 'left';
+                onSwipe?.(direction, velocity);
+                if (direction === 'left')
+                    onSwipeLeft?.(velocity);
+                if (direction === 'right')
+                    onSwipeRight?.(velocity);
+            }
+            else if (absY > absX && absY > threshold) {
+                // Vertical swipe
+                const velocity = calculateVelocity(absY, elapsed);
+                const direction = diffY > 0 ? 'down' : 'up';
+                onSwipe?.(direction, velocity);
+                if (direction === 'up')
+                    onSwipeUp?.(velocity);
+                if (direction === 'down')
+                    onSwipeDown?.(velocity);
+            }
+        },
+        cancel() {
+            tracking = false;
+        }
+    };
+}
+// ============================================================================
+// Drag Handler
+// ============================================================================
+/**
+ * Creates a drag gesture handler
+ * Tracks position and velocity during drag
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let x = 0, y = 0;
+ *   const drag = createDragHandler({
+ *     onDrag: (state) => {
+ *       x = state.deltaX;
+ *       y = state.deltaY;
+ *     }
+ *   });
+ * </script>
+ *
+ * <div
+ *   style="transform: translate({x}px, {y}px)"
+ *   ontouchstart={drag.start}
+ *   ontouchmove={drag.move}
+ *   ontouchend={drag.end}
+ * >
+ *   Drag me
+ * </div>
+ * ```
+ */
+export function createDragHandler(options = {}) {
+    const { threshold = 0, onDragStart, onDrag, onDragEnd } = options;
+    let state = {
+        isDragging: false,
+        startX: 0,
+        startY: 0,
+        currentX: 0,
+        currentY: 0,
+        deltaX: 0,
+        deltaY: 0,
+        velocityX: 0,
+        velocityY: 0
+    };
+    let lastX = 0;
+    let lastY = 0;
+    let lastTime = 0;
+    let dragStarted = false;
+    let tracking = false;
+    function resetState() {
+        state = {
+            isDragging: false,
+            startX: 0,
+            startY: 0,
+            currentX: 0,
+            currentY: 0,
+            deltaX: 0,
+            deltaY: 0,
+            velocityX: 0,
+            velocityY: 0
+        };
+        dragStarted = false;
+        tracking = false;
+    }
+    return {
+        start(e) {
+            if (e.touches.length !== 1)
+                return;
+            const touch = e.touches[0];
+            state.startX = touch.clientX;
+            state.startY = touch.clientY;
+            state.currentX = touch.clientX;
+            state.currentY = touch.clientY;
+            lastX = touch.clientX;
+            lastY = touch.clientY;
+            lastTime = Date.now();
+            tracking = true;
+        },
+        move(e) {
+            if (!tracking || e.touches.length !== 1)
+                return;
+            const touch = e.touches[0];
+            const now = Date.now();
+            const elapsed = now - lastTime;
+            state.currentX = touch.clientX;
+            state.currentY = touch.clientY;
+            state.deltaX = state.currentX - state.startX;
+            state.deltaY = state.currentY - state.startY;
+            // Calculate velocity
+            if (elapsed > 0) {
+                state.velocityX = (touch.clientX - lastX) / elapsed;
+                state.velocityY = (touch.clientY - lastY) / elapsed;
+            }
+            lastX = touch.clientX;
+            lastY = touch.clientY;
+            lastTime = now;
+            // Check threshold for drag start
+            const distance = getDistance(state.startX, state.startY, state.currentX, state.currentY);
+            if (!dragStarted && distance >= threshold) {
+                dragStarted = true;
+                state.isDragging = true;
+                onDragStart?.({ ...state });
+            }
+            if (dragStarted) {
+                onDrag?.({ ...state });
+            }
+        },
+        end(_e) {
+            if (!tracking)
+                return;
+            if (dragStarted) {
+                state.isDragging = false;
+                onDragEnd?.({ ...state });
+            }
+            resetState();
+        },
+        cancel() {
+            if (dragStarted) {
+                state.isDragging = false;
+                onDragEnd?.({ ...state });
+            }
+            resetState();
+        }
+    };
+}
+// ============================================================================
+// Pinch Handler
+// ============================================================================
+/**
+ * Creates a pinch gesture handler
+ * Detects scale changes from two-finger pinch
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let scale = 1;
+ *   const pinch = createPinchHandler({
+ *     onPinch: (state) => {
+ *       scale = state.scale;
+ *     }
+ *   });
+ * </script>
+ *
+ * <div
+ *   style="transform: scale({scale})"
+ *   ontouchstart={pinch.start}
+ *   ontouchmove={pinch.move}
+ *   ontouchend={pinch.end}
+ * >
+ *   Pinch to zoom
+ * </div>
+ * ```
+ */
+export function createPinchHandler(options = {}) {
+    const { scaleThreshold = 0.01, onPinchStart, onPinch, onPinchEnd } = options;
+    let state = {
+        isPinching: false,
+        initialDistance: 0,
+        currentDistance: 0,
+        scale: 1,
+        centerX: 0,
+        centerY: 0,
+        rotation: 0
+    };
+    let initialAngle = 0;
+    let pinchStarted = false;
+    let lastScale = 1;
+    function resetState() {
+        state = {
+            isPinching: false,
+            initialDistance: 0,
+            currentDistance: 0,
+            scale: 1,
+            centerX: 0,
+            centerY: 0,
+            rotation: 0
+        };
+        pinchStarted = false;
+        lastScale = 1;
+    }
+    function getTouchData(e) {
+        if (e.touches.length < 2)
+            return null;
+        const touch1 = e.touches[0];
+        const touch2 = e.touches[1];
+        const distance = getDistance(touch1.clientX, touch1.clientY, touch2.clientX, touch2.clientY);
+        const centerX = (touch1.clientX + touch2.clientX) / 2;
+        const centerY = (touch1.clientY + touch2.clientY) / 2;
+        const angle = getAngle(touch1.clientX, touch1.clientY, touch2.clientX, touch2.clientY);
+        return { distance, centerX, centerY, angle };
+    }
+    return {
+        start(e) {
+            const data = getTouchData(e);
+            if (!data)
+                return;
+            state.initialDistance = data.distance;
+            state.currentDistance = data.distance;
+            state.centerX = data.centerX;
+            state.centerY = data.centerY;
+            state.scale = 1;
+            state.rotation = 0;
+            initialAngle = data.angle;
+            pinchStarted = true;
+            state.isPinching = true;
+            onPinchStart?.({ ...state });
+        },
+        move(e) {
+            if (!pinchStarted) {
+                // Check if pinch just started (second finger added)
+                const data = getTouchData(e);
+                if (data) {
+                    state.initialDistance = data.distance;
+                    state.currentDistance = data.distance;
+                    state.centerX = data.centerX;
+                    state.centerY = data.centerY;
+                    state.scale = 1;
+                    state.rotation = 0;
+                    initialAngle = data.angle;
+                    pinchStarted = true;
+                    state.isPinching = true;
+                    onPinchStart?.({ ...state });
+                }
+                return;
+            }
+            const data = getTouchData(e);
+            if (!data)
+                return;
+            state.currentDistance = data.distance;
+            state.centerX = data.centerX;
+            state.centerY = data.centerY;
+            // Calculate scale
+            if (state.initialDistance > 0) {
+                state.scale = state.currentDistance / state.initialDistance;
+            }
+            // Calculate rotation
+            state.rotation = data.angle - initialAngle;
+            // Only trigger callback if scale changed significantly
+            if (Math.abs(state.scale - lastScale) >= scaleThreshold) {
+                lastScale = state.scale;
+                onPinch?.({ ...state });
+            }
+        },
+        end(e) {
+            // Check if we still have 2 fingers
+            if (e.touches.length >= 2)
+                return;
+            if (pinchStarted) {
+                state.isPinching = false;
+                onPinchEnd?.({ ...state });
+            }
+            resetState();
+        },
+        cancel() {
+            if (pinchStarted) {
+                state.isPinching = false;
+                onPinchEnd?.({ ...state });
+            }
+            resetState();
+        }
+    };
+}
+/**
+ * Svelte action for swipe gestures
+ *
+ * @example
+ * ```svelte
+ * <div use:swipeAction={{ onSwipeLeft: () => console.log('Left!') }}>
+ *   Swipe me
+ * </div>
+ * ```
+ */
+export function swipeAction(node, options = {}) {
+    const { preventDefault = false, ...swipeOptions } = options;
+    const handler = createSwipeHandler(swipeOptions);
+    function handleStart(e) {
+        if (preventDefault)
+            e.preventDefault();
+        handler.start(e);
+    }
+    function handleMove(e) {
+        if (preventDefault)
+            e.preventDefault();
+        handler.move(e);
+    }
+    function handleEnd(e) {
+        handler.end(e);
+    }
+    node.addEventListener('touchstart', handleStart, { passive: !preventDefault });
+    node.addEventListener('touchmove', handleMove, { passive: !preventDefault });
+    node.addEventListener('touchend', handleEnd);
+    node.addEventListener('touchcancel', handler.cancel);
+    return {
+        update(newOptions) {
+            const { preventDefault: _newPrevent = false, ...newSwipeOptions } = newOptions;
+            Object.assign(options, newOptions);
+            Object.assign(swipeOptions, newSwipeOptions);
+        },
+        destroy() {
+            node.removeEventListener('touchstart', handleStart);
+            node.removeEventListener('touchmove', handleMove);
+            node.removeEventListener('touchend', handleEnd);
+            node.removeEventListener('touchcancel', handler.cancel);
+        }
+    };
+}
+/**
+ * Svelte action for drag gestures
+ *
+ * @example
+ * ```svelte
+ * <div use:dragAction={{ onDrag: (state) => console.log(state.deltaX, state.deltaY) }}>
+ *   Drag me
+ * </div>
+ * ```
+ */
+export function dragAction(node, options = {}) {
+    const { preventDefault = true, ...dragOptions } = options;
+    const handler = createDragHandler(dragOptions);
+    function handleStart(e) {
+        if (preventDefault)
+            e.preventDefault();
+        handler.start(e);
+    }
+    function handleMove(e) {
+        if (preventDefault)
+            e.preventDefault();
+        handler.move(e);
+    }
+    function handleEnd(e) {
+        handler.end(e);
+    }
+    node.addEventListener('touchstart', handleStart, { passive: !preventDefault });
+    node.addEventListener('touchmove', handleMove, { passive: !preventDefault });
+    node.addEventListener('touchend', handleEnd);
+    node.addEventListener('touchcancel', handler.cancel);
+    return {
+        update(newOptions) {
+            Object.assign(options, newOptions);
+            Object.assign(dragOptions, newOptions);
+        },
+        destroy() {
+            node.removeEventListener('touchstart', handleStart);
+            node.removeEventListener('touchmove', handleMove);
+            node.removeEventListener('touchend', handleEnd);
+            node.removeEventListener('touchcancel', handler.cancel);
+        }
+    };
+}
+/**
+ * Svelte action for pinch gestures
+ *
+ * @example
+ * ```svelte
+ * <div use:pinchAction={{ onPinch: (state) => console.log('Scale:', state.scale) }}>
+ *   Pinch to zoom
+ * </div>
+ * ```
+ */
+export function pinchAction(node, options = {}) {
+    const { preventDefault = true, ...pinchOptions } = options;
+    const handler = createPinchHandler(pinchOptions);
+    function handleStart(e) {
+        if (preventDefault)
+            e.preventDefault();
+        handler.start(e);
+    }
+    function handleMove(e) {
+        if (preventDefault)
+            e.preventDefault();
+        handler.move(e);
+    }
+    function handleEnd(e) {
+        handler.end(e);
+    }
+    node.addEventListener('touchstart', handleStart, { passive: !preventDefault });
+    node.addEventListener('touchmove', handleMove, { passive: !preventDefault });
+    node.addEventListener('touchend', handleEnd);
+    node.addEventListener('touchcancel', handler.cancel);
+    return {
+        update(newOptions) {
+            Object.assign(options, newOptions);
+            Object.assign(pinchOptions, newOptions);
+        },
+        destroy() {
+            node.removeEventListener('touchstart', handleStart);
+            node.removeEventListener('touchmove', handleMove);
+            node.removeEventListener('touchend', handleEnd);
+            node.removeEventListener('touchcancel', handler.cancel);
+        }
+    };
+}