@sigx/lynx-gestures 0.1.0

package/src/types.ts

@@ -0,0 +1,87 @@
+import type { Signal } from '@sigx/lynx';
+
+// ---------------------------------------------------------------------------
+// Touch event types (platform-agnostic, matches Lynx shape)
+//
+// Used by `usePinch` / `useRotation` — multi-touch JS-only fallbacks. The
+// rest of the gesture surface (Tap, LongPress, Pan, Fling, Swipe) is
+// arena-driven via `Gesture.*` + `useGestureDetector`; the legacy hooks
+// were deleted in Phase 2.12.4.
+// ---------------------------------------------------------------------------
+
+export interface TouchPoint {
+  identifier: number;
+  x: number;
+  y: number;
+  pageX: number;
+  pageY: number;
+  clientX: number;
+  clientY: number;
+}
+
+export interface TouchEvent {
+  touches: TouchPoint[];
+  changedTouches: TouchPoint[];
+}
+
+// ---------------------------------------------------------------------------
+// Gesture phase
+// ---------------------------------------------------------------------------
+
+export type GesturePhase = 'idle' | 'began' | 'active' | 'ended' | 'cancelled';
+
+// ---------------------------------------------------------------------------
+// Bind-prop handler bag (spread onto an element's main-thread-bindtouch* attrs)
+// ---------------------------------------------------------------------------
+
+export interface GestureHandlers {
+  bindtouchstart?: (e: TouchEvent) => void;
+  bindtouchmove?: (e: TouchEvent) => void;
+  bindtouchend?: (e: TouchEvent) => void;
+  bindtouchcancel?: (e: TouchEvent) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Pinch
+// ---------------------------------------------------------------------------
+
+export interface PinchState {
+  phase: GesturePhase;
+  scale: number;
+  focalX: number;
+  focalY: number;
+}
+
+export interface UsePinchOptions {
+  onPinch?: (state: PinchState) => void;
+}
+
+export interface UsePinchReturn {
+  state: Signal<PinchState>;
+  handlers: GestureHandlers;
+  reset: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Rotation
+// ---------------------------------------------------------------------------
+
+export interface RotationState {
+  phase: GesturePhase;
+  /** Cumulative rotation in radians since gesture start (signed). */
+  rotation: number;
+  /** Angular velocity in radians/ms. */
+  velocity: number;
+  focalX: number;
+  focalY: number;
+}
+
+export interface UseRotationOptions {
+  onRotation?: (state: RotationState) => void;
+}
+
+export interface UseRotationReturn {
+  state: Signal<RotationState>;
+  handlers: GestureHandlers;
+  reset: () => void;
+}

package/src/use-pinch.ts

@@ -0,0 +1,106 @@
+import { signal } from '@sigx/lynx';
+import type { UsePinchOptions, UsePinchReturn, TouchEvent, PinchState, TouchPoint } from './types.js';
+import { distance, midpoint } from './utils.js';
+
+/**
+ * Two-finger pinch/zoom gesture.
+ *
+ * Tracks fingers manually since Lynx fires separate touchstart events per
+ * finger (each with touches.length=1). Uses proximity-based matching on
+ * touchmove since Lynx identifiers are unreliable across events.
+ *
+ * NOTE: Requires a device/environment that delivers multi-touch events to
+ * the same element. Some Lynx hosts (e.g. Lynx Explorer on emulator) may
+ * not support this — test on a physical device.
+ */
+export function usePinch(options: UsePinchOptions = {}): UsePinchReturn {
+  const { onPinch } = options;
+
+  const state = signal<PinchState>({
+    phase: 'idle',
+    scale: 1,
+    focalX: 0,
+    focalY: 0,
+  });
+
+  let baseDistance = 0;
+  let active = false;
+  let finger1: TouchPoint | null = null;
+  let finger2: TouchPoint | null = null;
+
+  function onTouchStart(e: TouchEvent): void {
+    const t = e.touches[0];
+    if (!t) return;
+
+    if (!finger1) {
+      finger1 = { ...t };
+    } else if (!finger2) {
+      finger2 = { ...t };
+      active = true;
+      baseDistance = distance(finger1.pageX, finger1.pageY, finger2.pageX, finger2.pageY);
+      const [fx, fy] = midpoint(finger1.pageX, finger1.pageY, finger2.pageX, finger2.pageY);
+      state.phase = 'began';
+      state.scale = 1;
+      state.focalX = fx;
+      state.focalY = fy;
+    }
+  }
+
+  function onTouchMove(e: TouchEvent): void {
+    if (!active || !finger1 || !finger2) return;
+
+    const t = e.changedTouches[0];
+    if (!t) return;
+
+    // Determine which finger moved by proximity
+    const dist1 = distance(t.pageX, t.pageY, finger1.pageX, finger1.pageY);
+    const dist2 = distance(t.pageX, t.pageY, finger2.pageX, finger2.pageY);
+
+    if (dist1 < dist2) {
+      finger1 = { ...t };
+    } else {
+      finger2 = { ...t };
+    }
+
+    const currentDist = distance(finger1.pageX, finger1.pageY, finger2.pageX, finger2.pageY);
+    const scale = baseDistance > 0 ? currentDist / baseDistance : 1;
+    const [fx, fy] = midpoint(finger1.pageX, finger1.pageY, finger2.pageX, finger2.pageY);
+
+    state.phase = 'active';
+    state.scale = scale;
+    state.focalX = fx;
+    state.focalY = fy;
+    onPinch?.(state as PinchState);
+  }
+
+  function onTouchEnd(): void {
+    if (active) {
+      state.phase = 'ended';
+      onPinch?.(state as PinchState);
+    }
+    active = false;
+    finger1 = null;
+    finger2 = null;
+  }
+
+  function reset(): void {
+    active = false;
+    finger1 = null;
+    finger2 = null;
+    state.phase = 'idle';
+    state.scale = 1;
+    state.focalX = 0;
+    state.focalY = 0;
+  }
+
+  return {
+    state,
+    handlers: {
+      bindtouchstart: onTouchStart,
+      bindtouchmove: onTouchMove,
+      bindtouchend: onTouchEnd,
+      bindtouchcancel: onTouchEnd,
+    },
+    reset,
+  };
+}

package/src/use-rotation.ts

@@ -0,0 +1,129 @@
+import { signal } from '@sigx/lynx';
+import type {
+  UseRotationOptions,
+  UseRotationReturn,
+  TouchEvent,
+  TouchPoint,
+  RotationState,
+} from './types.js';
+import { angle, angleDelta, distance, midpoint } from './utils.js';
+
+/**
+ * Two-finger rotation gesture.
+ *
+ * Tracks the angle of the line between two fingers; reports cumulative rotation
+ * in radians from gesture start. Like usePinch, uses proximity-based finger
+ * matching on touchmove (Lynx touch identifiers are not stable across events).
+ *
+ * NOTE: requires multi-touch delivery to the same element. Some Lynx hosts
+ * (Lynx Explorer on emulator) may not support this — test on a physical device.
+ */
+export function useRotation(options: UseRotationOptions = {}): UseRotationReturn {
+  const { onRotation } = options;
+
+  const state = signal<RotationState>({
+    phase: 'idle',
+    rotation: 0,
+    velocity: 0,
+    focalX: 0,
+    focalY: 0,
+  });
+
+  let baseAngle = 0;
+  let prevAngle = 0;
+  let prevTime = 0;
+  let active = false;
+  let finger1: TouchPoint | null = null;
+  let finger2: TouchPoint | null = null;
+
+  function onTouchStart(e: TouchEvent): void {
+    const t = e.touches[0];
+    if (!t) return;
+
+    if (!finger1) {
+      finger1 = { ...t };
+    } else if (!finger2) {
+      finger2 = { ...t };
+      active = true;
+      baseAngle = angle(finger1.pageX, finger1.pageY, finger2.pageX, finger2.pageY);
+      prevAngle = baseAngle;
+      prevTime = Date.now();
+      const [fx, fy] = midpoint(finger1.pageX, finger1.pageY, finger2.pageX, finger2.pageY);
+      state.phase = 'began';
+      state.rotation = 0;
+      state.velocity = 0;
+      state.focalX = fx;
+      state.focalY = fy;
+    }
+  }
+
+  function onTouchMove(e: TouchEvent): void {
+    if (!active || !finger1 || !finger2) return;
+    const t = e.changedTouches[0];
+    if (!t) return;
+
+    const dist1 = distance(t.pageX, t.pageY, finger1.pageX, finger1.pageY);
+    const dist2 = distance(t.pageX, t.pageY, finger2.pageX, finger2.pageY);
+    if (dist1 < dist2) {
+      finger1 = { ...t };
+    } else {
+      finger2 = { ...t };
+    }
+
+    const now = Date.now();
+    const dt = Math.max(now - prevTime, 1);
+    const currentAngle = angle(finger1.pageX, finger1.pageY, finger2.pageX, finger2.pageY);
+    const rotation = angleDelta(baseAngle, currentAngle);
+    const velocity = angleDelta(prevAngle, currentAngle) / dt;
+    const [fx, fy] = midpoint(finger1.pageX, finger1.pageY, finger2.pageX, finger2.pageY);
+
+    prevAngle = currentAngle;
+    prevTime = now;
+
+    state.phase = 'active';
+    state.rotation = rotation;
+    state.velocity = velocity;
+    state.focalX = fx;
+    state.focalY = fy;
+    onRotation?.(state as RotationState);
+  }
+
+  function onTouchEnd(): void {
+    if (active) {
+      state.phase = 'ended';
+      onRotation?.(state as RotationState);
+    }
+    active = false;
+    finger1 = null;
+    finger2 = null;
+  }
+
+  function onTouchCancel(): void {
+    if (active) state.phase = 'cancelled';
+    active = false;
+    finger1 = null;
+    finger2 = null;
+  }
+
+  function reset(): void {
+    active = false;
+    finger1 = null;
+    finger2 = null;
+    state.phase = 'idle';
+    state.rotation = 0;
+    state.velocity = 0;
+    state.focalX = 0;
+    state.focalY = 0;
+  }
+
+  return {
+    state,
+    handlers: {
+      bindtouchstart: onTouchStart,
+      bindtouchmove: onTouchMove,
+      bindtouchend: onTouchEnd,
+      bindtouchcancel: onTouchCancel,
+    },
+    reset,
+  };
+}

package/src/utils.ts

@@ -0,0 +1,26 @@
+// Geometry helpers used by the multi-touch JS-only fallback hooks
+// (`usePinch`, `useRotation`). The arena-driven gesture surface
+// (`Gesture.*` + `useGestureDetector`) computes its own deltas natively;
+// this file is only relevant while the platform's pinch/rotation handlers
+// are unfinished.
+
+export function distance(x1: number, y1: number, x2: number, y2: number): number {
+  return Math.sqrt((x2 - x1) ** 2 + (y2 - y1) ** 2);
+}
+
+export function midpoint(x1: number, y1: number, x2: number, y2: number): [number, number] {
+  return [(x1 + x2) / 2, (y1 + y2) / 2];
+}
+
+/** Signed angle in radians from p1 to p2, range (-π, π]. */
+export function angle(x1: number, y1: number, x2: number, y2: number): number {
+  return Math.atan2(y2 - y1, x2 - x1);
+}
+
+/** Shortest signed angular delta between two radians, range (-π, π]. */
+export function angleDelta(from: number, to: number): number {
+  let d = to - from;
+  while (d > Math.PI) d -= 2 * Math.PI;
+  while (d <= -Math.PI) d += 2 * Math.PI;
+  return d;
+}