gesturx 1.2.0 → 1.6.0

package/README.md

@@ -4,7 +4,7 @@ Modern multi touch gesture recognizer using rxjs.
 
 # Documentation
 
-Head over the [wiki](https://github.com/mbret/gesturx/wiki).
+Head over the [documentation](https://github.com/mbret/gesturx/wiki/Documentation).
 
 # Demo
 

package/dist/index.d.ts

@@ -1,57 +1,45 @@
 import { BehaviorSubject } from 'rxjs';
 import { Observable } from 'rxjs';
+import { ObservedValueOf } from 'rxjs';
 
-export declare const createManager: ({ afterEventReceived, recognizers, }: {
-    recognizers: (TapRecognizer | PanRecognizer | SwipeRecognizer | RotateRecognizer | PinchRecognizer)[];
-    afterEventReceived?: (event: PointerEvent) => PointerEvent;
-}) => {
-    events$: Observable<PanEvent | SwipeEvent | TapEvent | RotateEvent | PinchEvent>;
-    initialize: (container: HTMLElement) => void;
-    recognizers: (PanRecognizer | SwipeRecognizer | TapRecognizer | RotateRecognizer | PinchRecognizer)[];
-};
-
-export declare type Manager = ReturnType<typeof createManager>;
-
-declare type Options = {
+declare type PanConfig = {
     posThreshold?: number;
-};
-
-declare type Options_2 = {
+    delay?: number;
     /**
-     * The minimum velocity (px/ms) that the gesture has to obtain by the end event.
+     * Number of inputs to trigger the event.
+     * Default to 1
      */
-    escapeVelocity?: number;
     numInputs?: number;
-    maxRestTime?: number;
-    posThreshold?: number;
 };
 
-declare interface Options_3 extends RecognizerOptions {
-    multiTapThreshold?: number;
-    maximumPressTime?: number;
-    maxTaps?: number;
-    posThreshold?: number;
+export declare interface PanEvent extends RecognizerEvent {
+    type: "panStart" | "panMove" | "panEnd";
 }
 
-declare type Options_4 = {
-    posThreshold?: number;
-};
-
-declare type Options_5 = {
-    posThreshold?: number;
-};
-
-export declare interface PanEvent extends RecognizerEvent {
+declare interface PanEvent_2 extends RecognizerEvent {
     type: "panStart" | "panMove" | "panEnd";
 }
 
-export declare class PanRecognizer extends Recognizer<Options> {
-    protected options: Options;
+export declare class PanRecognizer extends Recognizer<PanRecognizerOptions, PanEvent> implements PanRecognizerInterface {
     events$: Observable<PanEvent>;
     start$: Observable<PanEvent>;
     end$: Observable<PanEvent>;
-    fingers$: Observable<number>;
-    constructor(options?: Options);
+    constructor(config?: RecognizerConfig<PanRecognizerOptions>);
+    update(config: RecognizerConfig<PanRecognizerOptions>): void;
+}
+
+declare interface PanRecognizerInterface extends Recognizer<PanRecognizerOptions, PanEvent_2> {
+    events$: Observable<PanEvent_2>;
+    update(options: RecognizerConfig<PanRecognizerOptions>): void;
+}
+
+declare interface PanRecognizerOptions {
+    /**
+     * @default 15
+     */
+    posThreshold?: number;
+    delay?: number;
+    numInputs?: number;
 }
 
 export declare interface PinchEvent extends RecognizerEvent {
@@ -71,24 +59,106 @@ export declare interface PinchEvent extends RecognizerEvent {
     deltaDistanceScale: number;
 }
 
-export declare class PinchRecognizer extends Recognizer<Options_5> {
-    protected options: Options_5;
+export declare class PinchRecognizer extends Recognizer<PinchRecognizerOptions, PinchEvent> implements PinchRecognizerInterface {
+    events$: Observable<PinchEvent>;
+    constructor(config?: RecognizerConfig<PinchRecognizerOptions>);
+    update(options: RecognizerConfig<PinchRecognizerOptions>): void;
+}
+
+declare interface PinchRecognizerInterface extends Recognizer<PinchRecognizerOptions, PinchEvent> {
     events$: Observable<PinchEvent>;
-    constructor(options?: Options_5);
+    update(options: RecognizerConfig<PinchRecognizerOptions>): void;
+}
+
+declare interface PinchRecognizerOptions {
+    posThreshold?: number;
+}
+
+export declare class Recognizable<T extends Recognizer<any, any>[]> implements RecognizableInterface<T> {
+    protected options: {
+        recognizers: T;
+        afterEventReceived?: (event: PointerEvent) => PointerEvent;
+    };
+    events$: Observable<ObservedValueOf<T[number]["events$"]>>;
+    recognizers: T;
+    state$: Observable<RecognizableState>;
+    constructor(options: {
+        recognizers: T;
+        afterEventReceived?: (event: PointerEvent) => PointerEvent;
+    });
+    initialize(container: HTMLElement): void;
+}
+
+declare interface RecognizableInterface<T extends Recognizer<any, any>[]> {
+    /**
+     * List of recognizers registered.
+     *
+     * You can access them directly from here if needed.
+     */
+    readonly recognizers: T;
+    /**
+     * Dispatch events from all recognizer in one place.
+     */
+    readonly events$: Observable<ObservedValueOf<T[number]["events$"]>>;
+    /**
+     * Global state based on registered recognizers.
+     *
+     * It is similar to the recognizer state but is a conveniant access
+     * which merge all their state together.
+     */
+    readonly state$: Observable<RecognizableState>;
+    /**
+     * Initialize the instance with a given html element.
+     *
+     * You can only initialize one element per instance but you can
+     * change the element and call the method again if needed.
+     */
+    initialize(container: HTMLElement): void;
 }
 
-declare class Recognizer<Options> {
-    protected config$: BehaviorSubject<RecognizerConfig<Options>>;
-    protected validConfig$: Observable<ValidRecognizerConfig<Options>>;
-    constructor(options: Options);
-    initialize(config: RecognizerConfig<Options>): void;
-    update(options: Options): void;
+declare type RecognizableState = {
+    /**
+     * Number of maximum simultaneous fingers currently registered
+     * by all recognizers.
+     *
+     * You can use this to detect how many fingers are touching the screen.
+     *
+     * This is assuming one of your recognizer is registering gestures.
+     */
+    fingers: number;
+};
+
+export declare abstract class Recognizer<Options extends Record<any, any>, Event extends RecognizerEvent> {
+    protected configSubject: BehaviorSubject<RecognizerConfig<Options> & {
+        panConfig?: PanConfig | undefined;
+    }>;
+    protected panEvent$: Observable<PanEvent>;
+    protected pointerEvent$: Observable<PointerEvent>;
+    protected pointerDown$: Observable<PointerEvent>;
+    protected pointerUp$: Observable<PointerEvent>;
+    protected pointerCancel$: Observable<PointerEvent>;
+    protected pointerMove$: Observable<PointerEvent>;
+    protected pointerOff$: Observable<PointerEvent>;
+    state$: Observable<State>;
+    abstract events$: Observable<Event>;
+    protected failWith$: Observable<unknown>;
+    protected config$: Observable<RecognizerConfig<Options> & {
+        panConfig?: PanConfig | undefined;
+    } & {
+        container: HTMLElement;
+    }>;
+    constructor(config?: RecognizerConfig<Options>, panConfig?: PanConfig);
+    private updateInternal;
+    update(config: Partial<RecognizerConfig<Options>>, panConfig?: PanConfig): void;
 }
 
-declare type RecognizerConfig<Options> = {
+export declare type RecognizerConfig<Options> = {
     container?: HTMLElement;
     afterEventReceived?: (event: PointerEvent) => PointerEvent;
     options?: Options;
+    failWith?: {
+        start$: Observable<unknown>;
+    }[];
 };
 
 declare interface RecognizerEvent {
@@ -134,14 +204,8 @@ declare interface RecognizerEvent {
     pointersAverageDistance: number;
 }
 
-declare interface RecognizerOptions {
-    failWith?: {
-        start$: Observable<unknown>;
-    }[];
-}
-
-export declare interface RotateEvent extends RecognizerEvent {
-    type: "rotate" | "rotateStart" | "rotateEnd";
+declare interface RotateEvent extends RecognizerEvent {
+    type: "rotateMove" | "rotateStart" | "rotateEnd";
     /**
      * Current rotation angle
      */
@@ -152,13 +216,37 @@ export declare interface RotateEvent extends RecognizerEvent {
     deltaAngle: number;
 }
 
-export declare class RotateRecognizer extends Recognizer<Options_4> {
-    protected options: Options_4;
+export declare class RotateRecognizer extends Recognizer<RotateRecognizerOptions, RotateEvent> implements RotateRecognizerInterface {
+    events$: Observable<RotateEvent>;
+    constructor(config?: RecognizerConfig<RotateRecognizerOptions>);
+    update(options: RecognizerConfig<RotateRecognizerOptions>): void;
+}
+
+declare interface RotateRecognizerInterface extends Recognizer<RotateRecognizerOptions, RotateEvent> {
     events$: Observable<RotateEvent>;
-    constructor(options?: Options_4);
+    update(options: RecognizerConfig<RotateRecognizerOptions>): void;
 }
 
-export declare interface SwipeEvent extends RecognizerEvent {
+declare interface RotateRecognizerOptions {
+    /**
+     * @default 15
+     */
+    posThreshold?: number;
+    /**
+     * Minimum fingers required to trigger.
+     *
+     * A value lower than 2 will not work
+     *
+     * @default 2
+     */
+    numInputs?: number;
+}
+
+export declare type State = {
+    fingers: number;
+};
+
+declare interface SwipeEvent extends RecognizerEvent {
     type: "swipe";
     /**
      * Angle between first pointer and last one in degree
@@ -170,23 +258,80 @@ export declare interface SwipeEvent extends RecognizerEvent {
     angle: number;
 }
 
-export declare class SwipeRecognizer extends Recognizer<Options_2> {
-    protected options: Options_2;
+export declare class SwipeRecognizer extends Recognizer<SwipeRecognizerOptions, SwipeEvent> implements SwipeRecognizerInterface {
     events$: Observable<SwipeEvent>;
-    constructor(options?: Options_2);
+    constructor(config?: RecognizerConfig<SwipeRecognizerOptions>);
+    update(config: RecognizerConfig<SwipeRecognizerOptions>): void;
 }
 
-export declare interface TapEvent extends RecognizerEvent {
+declare interface SwipeRecognizerInterface extends Recognizer<SwipeRecognizerOptions, SwipeEvent> {
+    events$: Observable<SwipeEvent>;
+    update(options: RecognizerConfig<SwipeRecognizerOptions>): void;
+}
+
+declare interface SwipeRecognizerOptions {
+    /**
+     * The minimum velocity (px/ms) that the gesture has to obtain by the end event.
+     *
+     * @default 0.9
+     */
+    escapeVelocity?: number;
+}
+
+declare interface TapEvent extends RecognizerEvent {
     type: "tap";
     taps: number;
 }
 
-export declare class TapRecognizer extends Recognizer<Options_3> {
-    protected options: Options_3;
+export declare class TapRecognizer extends Recognizer<TapRecognizerOptions, TapEvent> implements TapRecognizerInterface {
+    events$: Observable<TapEvent>;
+    constructor(options?: RecognizerConfig<TapRecognizerOptions>);
+    update(config: RecognizerConfig<TapRecognizerOptions>): void;
+}
+
+declare interface TapRecognizerInterface extends Recognizer<TapRecognizerOptions, TapEvent> {
     events$: Observable<TapEvent>;
-    constructor(options: Options_3);
+    update(options: RecognizerConfig<TapRecognizerOptions>): void;
 }
 
-declare type ValidRecognizerConfig<Options> = Required<Pick<RecognizerConfig<Options>, "container">> & RecognizerConfig<Options>;
+declare interface TapRecognizerOptions {
+    /**
+     * Introduce a delay before recognizing a tap. This can be used to register more taps.
+     *
+     *
+     * A longer time will delay the click event but make it easier to multi taps.
+     * Try to find a good balance between latency and accessibility.
+     *
+     * @default 0
+     */
+    multiTapThreshold?: number;
+    /**
+     * Maximum time you allow a finger to be pressed on the screen before cancelling the gesture.
+     *
+     * This can be used to allow long press for example.
+     * The default value does not really allow long press but rather accomodate for slower
+     * taps.
+     *
+     * @default 150
+     */
+    maximumPressTime?: number;
+    /**
+     * Maximum number of taps allowed for the gesture. Going above will ignore the gesture.
+     * Going below will register a gesture with the number of taps.
+     *
+     * For example you can allow single and double tap only by setting `2` as value.
+     *
+     * @default 1
+     */
+    maxTaps?: number;
+    /**
+     * A tolerance value which allows the user to move their finger about a radius measured in pixels.
+     * This allows the Tap gesture to be triggered more easily since a User might move their
+     * finger slightly during a tap event.
+     *
+     * @default 10
+     */
+    tolerance?: number;
+}
 
 export { }