mtrl-addons 0.1.2 → 0.2.1

package/src/core/compose/features/gestures/tap.ts

@@ -0,0 +1,334 @@
+// src/core/compose/features/gestures/tap.ts
+/**
+ * @module core/compose/features/gestures
+ * @description Adds tap gesture recognition to components
+ */
+
+import type { BaseComponent, ElementComponent } from "mtrl";
+import { TapEvent, GestureHandler } from "../../../gestures";
+import { hasLifecycle, hasEmit } from "mtrl";
+
+/**
+ * Configuration for tap gesture feature
+ */
+export interface TapGestureConfig {
+  /**
+   * Distance threshold (in pixels) for tap recognition
+   * @default 10
+   */
+  tapDistanceThreshold?: number;
+
+  /**
+   * Whether to prevent default behaviors on touch events
+   * @default true
+   */
+  preventDefault?: boolean;
+
+  /**
+   * Handler for tap gesture
+   */
+  onTap?: GestureHandler;
+
+  /**
+   * Whether to enable tap recognition immediately
+   * @default true
+   */
+  enabled?: boolean;
+
+  [key: string]: any;
+}
+
+/**
+ * Component with tap gesture recognition capabilities
+ */
+export interface TapGestureComponent extends BaseComponent {
+  /**
+   * Add a tap event handler
+   * @param handler - Event handler function
+   * @returns Component for chaining
+   */
+  onTap: (handler: (event: TapEvent) => void) => TapGestureComponent;
+
+  /**
+   * Remove a tap event handler
+   * @param handler - Event handler function
+   * @returns Component for chaining
+   */
+  offTap: (handler: (event: TapEvent) => void) => TapGestureComponent;
+
+  /**
+   * Enable tap recognition
+   * @returns Component for chaining
+   */
+  enableTap: () => TapGestureComponent;
+
+  /**
+   * Disable tap recognition
+   * @returns Component for chaining
+   */
+  disableTap: () => TapGestureComponent;
+}
+
+/**
+ * Adds tap gesture recognition to a component.
+ * This is a lightweight alternative to the full gesture system,
+ * focused only on tap detection.
+ *
+ * @param config - Configuration object containing tap settings
+ * @returns Function that enhances a component with tap capabilities
+ *
+ * @example
+ * ```ts
+ * // Add tap gesture recognition to a component
+ * const component = pipe(
+ *   createBase,
+ *   withElement(...),
+ *   withTapGesture({
+ *     onTap: (e) => console.log('Tapped at', e.x, e.y)
+ *   })
+ * )(config);
+ * ```
+ */
+export const withTapGesture =
+  (config: TapGestureConfig = {}) =>
+  <C extends ElementComponent>(component: C): C & TapGestureComponent => {
+    if (!component.element) {
+      console.warn("Cannot add tap gesture recognition: missing element");
+      return component as C & TapGestureComponent;
+    }
+
+    // Default configuration
+    const {
+      tapDistanceThreshold = 10,
+      preventDefault = true,
+      onTap,
+      enabled = true,
+    } = config;
+
+    // Event handlers storage
+    const handlers: Set<(event: TapEvent) => void> = new Set();
+
+    // If initial handler provided, add it
+    if (onTap) {
+      handlers.add(onTap as (event: TapEvent) => void);
+    }
+
+    // Gesture state for tracking
+    let startX = 0;
+    let startY = 0;
+    let active = false;
+    let startTime = 0;
+    let lastTapTime = 0;
+    let tapCount = 0;
+    let isEnabled = enabled;
+
+    /**
+     * Dispatch a tap event to all handlers
+     */
+    const dispatchTap = (
+      e: MouseEvent | TouchEvent,
+      x: number,
+      y: number
+    ): void => {
+      const now = Date.now();
+      const isDoubleTap = now - lastTapTime < 300;
+
+      if (isDoubleTap) {
+        tapCount++;
+      } else {
+        tapCount = 1;
+      }
+
+      lastTapTime = now;
+
+      // Create the tap event
+      const tapEvent: TapEvent = {
+        type: "tap",
+        originalEvent: e,
+        target: e.target!,
+        startTime,
+        endTime: now,
+        duration: now - startTime,
+        defaultPrevented: false,
+        preventDefault: () => {
+          tapEvent.defaultPrevented = true;
+          if (e.cancelable) {
+            e.preventDefault();
+          }
+        },
+        stopPropagation: () => {
+          e.stopPropagation();
+        },
+        count: tapCount,
+        x,
+        y,
+      };
+
+      // Call each handler
+      handlers.forEach((handler) => {
+        try {
+          handler(tapEvent);
+        } catch (error) {
+          console.error("Error in tap handler:", error);
+        }
+      });
+
+      // Forward to component's event system if available
+      if (hasEmit(component)) {
+        component.emit("tap", tapEvent);
+      }
+
+      // Apply preventDefault if configured
+      if (preventDefault && !tapEvent.defaultPrevented) {
+        tapEvent.preventDefault();
+      }
+    };
+
+    /**
+     * Handle touch/mouse start
+     */
+    const handleStart = (e: MouseEvent | TouchEvent): void => {
+      if (!isEnabled) return;
+
+      const touch = "touches" in e ? e.touches[0] : e;
+
+      startX = touch.clientX;
+      startY = touch.clientY;
+      startTime = Date.now();
+      active = true;
+    };
+
+    /**
+     * Handle touch/mouse end
+     */
+    const handleEnd = (e: MouseEvent | TouchEvent): void => {
+      if (!active || !isEnabled) return;
+
+      const touch =
+        "changedTouches" in e && e.changedTouches.length > 0
+          ? e.changedTouches[0]
+          : (e as MouseEvent);
+
+      const endX = touch.clientX;
+      const endY = touch.clientY;
+
+      // Calculate distance moved
+      const deltaX = endX - startX;
+      const deltaY = endY - startY;
+      const distance = Math.sqrt(deltaX * deltaX + deltaY * deltaY);
+
+      // Check if movement is within threshold
+      if (distance < tapDistanceThreshold) {
+        dispatchTap(e, endX, endY);
+      }
+
+      active = false;
+    };
+
+    /**
+     * Handle touch/mouse cancel
+     */
+    const handleCancel = (): void => {
+      active = false;
+    };
+
+    // Event listeners dictionary
+    const eventListeners: Record<string, EventListener> = {
+      mousedown: handleStart as EventListener,
+      mouseup: handleEnd as EventListener,
+      mouseleave: handleCancel as EventListener,
+      touchstart: handleStart as EventListener,
+      touchend: handleEnd as EventListener,
+      touchcancel: handleCancel as EventListener,
+    };
+
+    /**
+     * Add event listeners to element
+     */
+    const setupEventListeners = (): void => {
+      Object.entries(eventListeners).forEach(([event, listener]) => {
+        component.element.addEventListener(event, listener, {
+          passive: !preventDefault,
+        });
+      });
+    };
+
+    /**
+     * Remove event listeners from element
+     */
+    const removeEventListeners = (): void => {
+      Object.entries(eventListeners).forEach(([event, listener]) => {
+        component.element.removeEventListener(event, listener);
+      });
+    };
+
+    // Setup listeners if initially enabled
+    if (isEnabled) {
+      setupEventListeners();
+    }
+
+    // Handle lifecycle integration
+    if (hasLifecycle(component)) {
+      const originalDestroy = component.lifecycle.destroy;
+
+      component.lifecycle.destroy = () => {
+        // Clean up event listeners
+        removeEventListeners();
+
+        // Clear handlers
+        handlers.clear();
+
+        // Call original destroy method
+        originalDestroy.call(component.lifecycle);
+      };
+    }
+
+    // Create enhanced component
+    return {
+      ...component,
+
+      /**
+       * Add a tap event handler
+       * @param handler - Event handler function
+       * @returns Component for chaining
+       */
+      onTap(handler: (event: TapEvent) => void) {
+        handlers.add(handler);
+        return this;
+      },
+
+      /**
+       * Remove a tap event handler
+       * @param handler - Event handler function
+       * @returns Component for chaining
+       */
+      offTap(handler: (event: TapEvent) => void) {
+        handlers.delete(handler);
+        return this;
+      },
+
+      /**
+       * Enable tap recognition
+       * @returns Component for chaining
+       */
+      enableTap() {
+        if (!isEnabled) {
+          isEnabled = true;
+          setupEventListeners();
+        }
+        return this;
+      },
+
+      /**
+       * Disable tap recognition
+       * @returns Component for chaining
+       */
+      disableTap() {
+        if (isEnabled) {
+          isEnabled = false;
+          removeEventListeners();
+        }
+        return this;
+      },
+    };
+  };

package/src/core/compose/features/index.ts

@@ -1,39 +1,3 @@
-/**
- * @module core/compose/features
- * @description Addons-specific compose features for creating and combining components
- */
+export { withGestures } from './gestures';
 
-// Collection feature
-export {
-  withCollection,
-  type CollectionConfig,
-  type CollectionComponent,
-} from "./collection";
-
-// Styling feature
-export {
-  withStyling,
-  type StylingConfig,
-  type StylingComponent,
-} from "./styling";
-
-// Selection feature
-export {
-  withSelection,
-  type SelectionConfig,
-  type SelectionComponent,
-  type SelectableItem,
-} from "./selection";
-
-// Performance feature
-export {
-  withPerformance,
-  type PerformanceConfig,
-  type PerformanceComponent,
-  type PerformanceMetrics,
-} from "./performance";
-
-// Future features will be exported here
-// export { withVirtualScroll } from './virtual-scroll';
-// export { withDataGrid } from './data-grid';
-// export { withInfiniteScroll } from './infinite-scroll';
+export type { GesturesComponent, GesturesFeatureConfig } from './gestures';

package/src/core/compose/index.ts

@@ -1,31 +1,15 @@
-/**
- * @module core/compose
- * @description Core composition utilities and addons-specific features
- */
-
-// Re-export mtrl compose system
 export {
-  pipe,
-  createBase,
-  withElement,
-  withEvents,
-  withLifecycle,
-} from "mtrl/src/core/compose";
+  withGestures
+} from './features/gestures';
 
-// Export addons-specific features
-export {
-  withCollection,
-  withStyling,
-  withSelection,
-  withPerformance,
-  type CollectionConfig,
-  type CollectionComponent,
-  type StylingConfig,
-  type StylingComponent,
-  type SelectionConfig,
-  type SelectionComponent,
-  type SelectableItem,
-  type PerformanceConfig,
-  type PerformanceComponent,
-  type PerformanceMetrics,
-} from "./features";
+// Gesture features
+export { withTapGesture } from './features/gestures/tap';
+export { withSwipeGesture } from './features/gestures/swipe';
+export { withLongPressGesture } from './features/gestures/longpress';
+export { withPanGesture } from './features/gestures/pan';
+
+
+export type {
+  GesturesComponent,
+  GesturesFeatureConfig
+} from './features';

package/src/core/gestures/index.ts

@@ -0,0 +1,31 @@
+// src/core/gestures/index.ts
+/**
+ * @module core/gestures
+ * @description Modular gesture recognition system for touch and mouse interactions
+ */
+
+// Export core gesture utilities and types
+export { createGestureManager, GESTURE_TYPES, SWIPE_DIRECTIONS } from './manager';
+export { detectTap } from './tap';
+export { detectSwipe } from './swipe';
+export { detectLongPress } from './longpress';
+export { detectPinch } from './pinch';
+export { detectRotate } from './rotate';
+export { detectPan } from './pan';
+
+// Export types
+export type { 
+  GestureManager,
+  GestureConfig,
+  GestureEvent,
+  TapEvent,
+  SwipeEvent,
+  LongPressEvent,
+  PinchEvent,
+  RotateEvent,
+  PanEvent,
+  AnyGestureEvent,
+  GestureHandler,
+  GestureState,
+  GestureDetectionContext
+} from './types';

package/src/core/gestures/longpress.ts

@@ -0,0 +1,68 @@
+// src/core/gestures/longpress.ts
+/**
+ * @module core/gestures
+ * @description Long press gesture detection
+ */
+
+import { LongPressEvent, GestureDetectionContext } from './types';
+import { createGestureEvent } from './utils';
+
+/**
+ * Detect long press gesture
+ * 
+ * This is slightly different from other gesture detectors as it sets up a timer
+ * and returns a callback function that will be triggered when the timer completes.
+ * 
+ * @param context - Gesture detection context
+ * @param callback - Function to call when long press is detected
+ * @returns Cleanup function to cancel the long press detection
+ */
+export function detectLongPress(
+  context: GestureDetectionContext,
+  callback: (event: LongPressEvent) => void
+): () => void {
+  const { state, options, originalEvent } = context;
+  
+  // Set a timer for long press detection
+  const timer = window.setTimeout(() => {
+    // Only trigger if gesture is still active
+    if (state.active) {
+      // Check if movement is within threshold
+      const diffX = Math.abs(state.currentX - state.startX);
+      const diffY = Math.abs(state.currentY - state.startY);
+      
+      if (diffX < options.tapDistanceThreshold && diffY < options.tapDistanceThreshold) {
+        // Create long press event
+        const longPressEvent: LongPressEvent = {
+          ...createGestureEvent('longpress', originalEvent, state),
+          type: 'longpress',
+          x: state.currentX,
+          y: state.currentY
+        };
+        
+        // Trigger callback
+        callback(longPressEvent);
+      }
+    }
+  }, options.longPressTime);
+  
+  // Return cleanup function
+  return () => {
+    clearTimeout(timer);
+  };
+}
+
+/**
+ * Check if movement would cancel a long press
+ * 
+ * @param context - Gesture detection context
+ * @returns Whether the long press should be canceled
+ */
+export function shouldCancelLongPress(context: GestureDetectionContext): boolean {
+  const { state, options } = context;
+  
+  const diffX = Math.abs(state.currentX - state.startX);
+  const diffY = Math.abs(state.currentY - state.startY);
+  
+  return diffX > options.tapDistanceThreshold || diffY > options.tapDistanceThreshold;
+}