gesturx 0.0.0 → 1.0.0

package/src/core/tap/TapRecognizer.ts

@@ -0,0 +1,172 @@
+import {
+  Observable,
+  buffer,
+  combineLatest,
+  debounceTime,
+  exhaustMap,
+  filter,
+  first,
+  ignoreElements,
+  map,
+  merge,
+  of,
+  share,
+  shareReplay,
+  switchMap,
+  takeUntil,
+  timer,
+  withLatestFrom,
+} from "rxjs"
+import {
+  fromFailWith,
+  filterNotEmpty,
+  isOutsidePosThreshold,
+} from "../utils/utils"
+import { Recognizer, RecognizerOptions } from "../recognizer/Recognizer"
+import { RecognizerEvent } from "../recognizer/RecognizerEvent"
+import { mapToRecognizerEvent } from "../recognizer/mapToRecognizerEvent"
+import {
+  fromPointerDown,
+  getPointerEvents,
+  trackFingers,
+} from "../utils/events"
+
+export interface TapEvent extends RecognizerEvent {
+  type: "tap"
+  taps: number
+}
+
+interface Options extends RecognizerOptions {
+  // Maximum time in ms between multiple taps.
+  multiTapThreshold?: number
+  // Maximum press time in ms.
+  maximumPressTime?: number
+  maxTaps?: number
+  posThreshold?: number
+}
+
+export class TapRecognizer extends Recognizer<Options> {
+  public events$: Observable<TapEvent>
+
+  constructor(protected options: Options) {
+    super(options)
+
+    this.events$ = this.validConfig$.pipe(
+      switchMap((config) => {
+        const { container, afterEventReceived } = config
+        const {
+          multiTapThreshold = 200,
+          maximumPressTime = 250,
+          maxTaps = 2,
+          // threshold should be high because of fingers size
+          // and potential margin due to it. clicks are nearly perfect
+          // not fingers.
+          posThreshold = 10,
+          failWith,
+        } = config.options ?? {}
+
+        const { pointerUp$, pointerLeave$, pointerCancel$, pointerMove$ } =
+          getPointerEvents({
+            container,
+            afterEventReceived,
+          })
+
+        const pointerDown$ = fromPointerDown({ container, afterEventReceived })
+        const activePointers$ = pointerDown$.pipe(
+          trackFingers({
+            pointerCancel$,
+            pointerLeave$,
+            pointerMove$,
+            pointerUp$,
+            trackMove: false,
+          }),
+          shareReplay(1),
+        )
+
+        const hasMoreThanOneActivePointer$ = activePointers$.pipe(
+          filter((pointers) => pointers.length > 1),
+        )
+
+        const onlyOnePointer = <T>(stream: Observable<T>) =>
+          stream.pipe(
+            withLatestFrom(activePointers$),
+            filter(([, pointers]) => pointers.length === 1),
+            map(([pointer]) => pointer),
+          )
+
+        const bufferPointerDowns = (stream: Observable<PointerEvent>) =>
+          stream.pipe(
+            buffer(pointerUp$.pipe(debounceTime(multiTapThreshold))),
+            first(),
+          )
+
+        const failWith$ = fromFailWith(failWith)
+
+        const tap$ = merge(
+          pointerDown$,
+          activePointers$.pipe(ignoreElements()),
+        ).pipe(
+          onlyOnePointer,
+          exhaustMap((initialPointerEvent) => {
+            const pointerDowns$ = merge(of(initialPointerEvent), pointerDown$)
+            const subsequentPointerEvents$ = merge(
+              pointerUp$,
+              pointerLeave$,
+              pointerCancel$,
+              pointerMove$,
+            )
+            const pointerDownsBuffered$ = pointerDowns$.pipe(bufferPointerDowns)
+            const subsequentPointersOutOfPositionThreshold$ =
+              subsequentPointerEvents$.pipe(
+                filter((event) =>
+                  isOutsidePosThreshold(
+                    initialPointerEvent,
+                    event,
+                    posThreshold,
+                  ),
+                ),
+                first(),
+              )
+            const waitedTooLong$ = activePointers$.pipe(
+              switchMap(() => timer(maximumPressTime)),
+            )
+
+            const takeUntil$ = merge(
+              failWith$,
+              pointerCancel$,
+              hasMoreThanOneActivePointer$,
+              subsequentPointersOutOfPositionThreshold$,
+              waitedTooLong$,
+            )
+
+            const rawEvent$ = pointerDownsBuffered$.pipe(
+              filterNotEmpty,
+              filter((events) => events.length <= maxTaps),
+              map((events) => ({
+                type: "tap" as const,
+                taps: events.length,
+                latestActivePointers: events,
+                event: events[0],
+              })),
+            )
+
+            return combineLatest([
+              rawEvent$.pipe(mapToRecognizerEvent),
+              rawEvent$,
+            ]).pipe(
+              map(([recognizerEvent, { type, taps }]) => ({
+                ...recognizerEvent,
+                type,
+                taps,
+              })),
+              takeUntil(takeUntil$),
+            )
+          }),
+        )
+
+        return tap$
+      }),
+      share(),
+    )
+  }
+}

package/src/core/utils/events.ts

@@ -0,0 +1,186 @@
+import {
+  NEVER,
+  Observable,
+  defer,
+  endWith,
+  filter,
+  fromEvent,
+  map,
+  merge,
+  mergeMap,
+  of,
+  scan,
+  takeUntil,
+} from "rxjs"
+import { isDefined } from "./utils"
+
+export function matchPointer(pointer: PointerEvent) {
+  return (stream: Observable<PointerEvent>) =>
+    stream.pipe(
+      filter((newPointer) => newPointer.pointerId === pointer.pointerId),
+    )
+}
+
+export const getPointerEvents = ({
+  container,
+  afterEventReceived = (event) => event,
+}: {
+  container: HTMLElement
+  afterEventReceived?: (event: PointerEvent) => PointerEvent
+}) => {
+  const pointerDown$ = fromPointerDown({ afterEventReceived, container })
+  const pointerUp$ = fromEvent<PointerEvent>(container, "pointerup").pipe(
+    map(afterEventReceived),
+  )
+  const pointerMove$ = fromEvent<PointerEvent>(container, "pointermove").pipe(
+    map(afterEventReceived),
+  )
+  /**
+   * Mostly used to handle cursor leaving window on mouse pointers.
+   */
+  const pointerLeave$ = fromEvent<PointerEvent>(container, "pointerleave").pipe(
+    map(afterEventReceived),
+  )
+  /**
+   * Handle things such as contextual menu popup or
+   * native swipe navigation conflict.
+   */
+  const pointerCancel$ = fromEvent<PointerEvent>(
+    container,
+    "pointercancel",
+  ).pipe(map(afterEventReceived))
+
+  return {
+    pointerDown$,
+    pointerCancel$,
+    pointerLeave$,
+    pointerUp$,
+    pointerMove$,
+  }
+}
+
+export const fromPointerDown = ({
+  container,
+  afterEventReceived = (event) => event,
+}: {
+  container: HTMLElement
+  afterEventReceived?: (event: PointerEvent) => PointerEvent
+}) =>
+  fromEvent<PointerEvent>(container, "pointerdown").pipe(
+    map(afterEventReceived),
+  )
+
+/**
+ * @todo test the strict stability
+ * @important
+ * Stable function, will not emit if the pointers don't change
+ */
+export const trackActivePointers = ({
+  container,
+}: {
+  container: HTMLElement
+}) => {
+  const pointerUp$ = fromEvent<PointerEvent>(container, "pointerup")
+  const pointerLeave$ = fromEvent<PointerEvent>(container, "pointerleave")
+  const pointerCancel$ = fromEvent<PointerEvent>(container, "pointercancel")
+
+  return fromEvent<PointerEvent>(container, "pointerdown").pipe(
+    mergeMap((pointerDown) => {
+      const pointerDownRelease$ = merge(
+        pointerUp$,
+        pointerLeave$,
+        pointerCancel$,
+      ).pipe(matchPointer(pointerDown))
+      const pointerDown$ = defer(() => of(pointerDown))
+
+      return pointerDown$.pipe(
+        mergeMap(() => merge(pointerDown$, NEVER)),
+        map((event) => ({ id: event.pointerId, event })),
+        takeUntil(pointerDownRelease$),
+        endWith({ id: pointerDown.pointerId, event: undefined }),
+      )
+    }),
+    scan(
+      (acc, { event, id }) => {
+        if (!event) {
+          // eslint-disable-next-line @typescript-eslint/no-unused-vars
+          const { [id]: _deleted, ...rest } = acc
+
+          return rest
+        }
+
+        return {
+          ...acc,
+          [id]: event,
+        }
+      },
+      {} as Record<number, PointerEvent | undefined>,
+    ),
+    map((events) => Object.values(events).filter(isDefined)),
+  )
+}
+
+/**
+ * Track all pointerEvent for active fingers
+ */
+export const trackFingers =
+  ({
+    pointerCancel$,
+    pointerLeave$,
+    pointerUp$,
+    pointerMove$,
+    trackMove,
+  }: {
+    pointerUp$: Observable<PointerEvent>
+    pointerLeave$: Observable<PointerEvent>
+    pointerCancel$: Observable<PointerEvent>
+    pointerMove$: Observable<PointerEvent>
+    /**
+     * Setting this value to false will not update the list
+     * on pointer move. Use it if you only need to track number of active
+     * fingers.
+     */
+    trackMove: boolean
+  }) =>
+  (stream: Observable<PointerEvent>) => {
+    return stream.pipe(
+      mergeMap((pointerDown) => {
+        const pointerDownRelease$ = merge(
+          pointerUp$,
+          pointerLeave$,
+          pointerCancel$,
+        ).pipe(matchPointer(pointerDown))
+
+        const pointerDown$ = defer(() => of(pointerDown))
+
+        const tracking$ = merge(
+          pointerDown$,
+          trackMove ? pointerMove$ : NEVER,
+        ).pipe(
+          matchPointer(pointerDown),
+          map((event) => ({ id: event.pointerId, event })),
+          takeUntil(pointerDownRelease$),
+          endWith({ id: pointerDown.pointerId, event: undefined }),
+        )
+
+        return tracking$
+      }),
+      scan(
+        (acc, { event, id }) => {
+          if (!event) {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { [id]: _deleted, ...rest } = acc
+
+            return rest
+          }
+
+          return {
+            ...acc,
+            [id]: event,
+          }
+        },
+        {} as Record<number, PointerEvent | undefined>,
+      ),
+      map((events) => Object.values(events).filter(isDefined)),
+    )
+  }

package/src/core/utils/geometry.ts

@@ -0,0 +1,115 @@
+type Point = { x: number; y: number }
+
+export function calculateDistance(pointA: Point, pointB: Point): number {
+  return Math.sqrt(
+    Math.pow(pointB.x - pointA.x, 2) + Math.pow(pointB.y - pointA.y, 2),
+  )
+}
+
+export function calculateAverageDistance(pointerEvents: Point[]): number {
+  const n = pointerEvents.length
+  if (n < 2) return 0 // No distance if fewer than 2 pointers
+
+  const totalDistance = pointerEvents.reduce((sum, event1, i) => {
+    return (
+      sum +
+      pointerEvents.slice(i + 1).reduce((innerSum, event2) => {
+        return innerSum + calculateDistance(event1, event2)
+      }, 0)
+    )
+  }, 0)
+
+  // Number of pairs is n choose 2: n * (n - 1) / 2
+  const numberOfPairs = (n * (n - 1)) / 2
+  return totalDistance / numberOfPairs
+}
+
+export function calculateRadianAngleBetweenPoints(
+  pointerA: Point,
+  pointerB: Point,
+): number {
+  // Calculate the differences in coordinates
+  const deltaX = pointerB.x - pointerA.x
+  const deltaY = pointerB.y - pointerA.y
+
+  // Calculate the angle in radians
+  const angleInRadians = Math.atan2(deltaY, deltaX)
+
+  // Return the angle in degrees
+  return angleInRadians
+}
+
+export function calculateDegreeAngleBetweenPoints(
+  pointerA: Point,
+  pointerB: Point,
+): number {
+  // Calculate the angle in radians
+  const angleInRadians = calculateRadianAngleBetweenPoints(pointerA, pointerB)
+
+  // Convert the angle to degrees (optional)
+  const angleInDegrees = angleInRadians * (180 / Math.PI)
+
+  // Return the angle in degrees
+  return angleInDegrees
+}
+
+export function calculateCentroid(points: Point[]) {
+  const sum = points.reduce(
+    (acc, point) => {
+      acc.x += point.x
+      acc.y += point.y
+
+      return acc
+    },
+    { x: 0, y: 0 },
+  )
+
+  const numPoints = points.length || 1
+
+  return {
+    x: sum.x / numPoints,
+    y: sum.y / numPoints,
+  }
+}
+
+export function calculateAngleDelta(
+  initialPoints: Point[],
+  newPoints: Point[],
+) {
+  if (initialPoints.length !== newPoints.length) {
+    throw new Error("Initial and new points arrays must have the same length.")
+  }
+
+  const initialCentroid = calculateCentroid(initialPoints)
+  const newCentroid = calculateCentroid(newPoints)
+
+  let totalAngleDelta = 0
+
+  for (let i = 0; i < initialPoints.length; i++) {
+    const initialAngle = calculateRadianAngleBetweenPoints(
+      initialCentroid,
+      initialPoints[i]!,
+    )
+    const newAngle = calculateRadianAngleBetweenPoints(
+      newCentroid,
+      newPoints[i]!,
+    )
+
+    let angleDelta = newAngle - initialAngle
+
+    // Normalize the angle delta to be within [-PI, PI]
+    if (angleDelta > Math.PI) {
+      angleDelta -= 2 * Math.PI
+    } else if (angleDelta < -Math.PI) {
+      angleDelta += 2 * Math.PI
+    }
+
+    totalAngleDelta += angleDelta
+  }
+
+  // Return the average angle delta
+  const radianDelta = totalAngleDelta / initialPoints.length
+  const degreesDelta = radianDelta * (180 / Math.PI)
+
+  return { radianDelta, degreesDelta }
+}

package/src/core/utils/utils.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from "vitest"
+import { calculateCentroid } from "./geometry"
+
+describe("calculateCentroid", () => {
+  it("calculates the correct center for a list of pointer events", () => {
+    const events = [
+      { x: 0, y: 0 },
+      { x: 2, y: 2 },
+      { x: 4, y: 6 },
+    ]
+    const center = calculateCentroid(events as any)
+    expect(center).toEqual({ x: 2, y: 2.6666666666666665 })
+  })
+
+  it("returns origin when no events are present", () => {
+    const events: any[] = []
+    const center = calculateCentroid(events)
+    expect(center).toEqual({ x: 0, y: 0 })
+  })
+
+  it("handles single point correctly", () => {
+    const events = [{ x: 5, y: 5 }]
+    const center = calculateCentroid(events as any)
+    expect(center).toEqual({ x: 5, y: 5 })
+  })
+})

package/src/core/utils/utils.ts

@@ -0,0 +1,58 @@
+import {
+  NEVER,
+  Observable,
+  filter,
+  merge,
+} from "rxjs"
+import { calculateCentroid } from "./geometry"
+
+export function isDefined<T>(
+  arg: T | null | undefined,
+): arg is T extends null | undefined ? never : T {
+  return arg !== null && arg !== undefined
+}
+
+export const hasAtLeastOneItem = <T>(events: T[]): events is [T, ...T[]] =>
+  events.length > 0
+
+export const filterNotEmpty = <T>(
+  stream: Observable<T[]>,
+): Observable<[T, ...T[]]> => stream.pipe(filter(hasAtLeastOneItem))
+
+export function isOutsidePosThreshold(
+  startEvent: PointerEvent,
+  endEvent: PointerEvent,
+  posThreshold: number,
+) {
+  const start = calculateCentroid([startEvent])
+  const end = calculateCentroid([endEvent])
+
+  // Determines if the movement qualifies as a drag
+  return (
+    Math.abs(end.x - start.x) > posThreshold ||
+    Math.abs(end.y - start.y) > posThreshold
+  )
+}
+
+export const fromFailWith = (failWith?: { start$: Observable<unknown> }[]) =>
+  !failWith?.length
+    ? NEVER
+    : merge(...(failWith?.map(({ start$ }) => start$) ?? []))
+
+/**
+ * Avoid division by zero
+ * Calculate velocity in pixels per second
+ */
+export const calculateVelocity = (
+  delay: number,
+  deltaX: number,
+  deltaY: number,
+) => {
+  const velocityX = delay > 0 ? deltaX / delay : 0
+  const velocityY = delay > 0 ? deltaY / delay : 0
+
+  return {
+    velocityX,
+    velocityY,
+  }
+}