react-native-gtkx 0.2.0-alpha.2 → 0.3.0-alpha.1

package/dist/gesture-handler-compat/recognizer.d.ts

@@ -0,0 +1,268 @@
+import type { GestureResponderEvent } from "../responder/types";
+import type { Orchestrator, Participant } from "./orchestrator";
+import { type GestureHitSlop, type GestureKind, type RecognizerConfig } from "./types";
+export type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * What the recognizer needs from the world it is mounted in: where its view
+ * is, and how to take the interaction when no touch event is in flight.
+ */
+export type RecognizerEnvironment = {
+    /**
+     * The gesture's own view in WINDOW coordinates, or null before it is laid
+     * out. Window coordinates because that is the space RN's `pageX`/`pageY`
+     * are in, so no conversion sits between a touch and a bounds test.
+     */
+    boundsInWindow: () => Rect | null;
+    /**
+     * Ask for the responder outside a touch event. Returns whether it was
+     * granted. See `ResponderSystem.requestResponder`.
+     */
+    requestResponder: () => boolean;
+    /**
+     * The JS-only arbitration registry this gesture takes part in. Injected
+     * rather than imported so a test can drive one loop in isolation, exactly
+     * as the responder system is injected rather than imported.
+     */
+    orchestrator: Orchestrator;
+};
+/** The read-only view of the runtime the predicates are allowed to see. */
+export type RecognizerView = {
+    /** Measured from the point of ACTIVATION once there is one; see `Runtime`. */
+    translationX: number;
+    translationY: number;
+    /**
+     * Straight-line travel from the PRESS, which outlives activation.
+     *
+     * `LongPress` needs this and translation will not do: it activates on a
+     * timer, translation is re-based to the activation point, and upstream's
+     * `maxDist` is measured from the press for the whole gesture — so a hold
+     * that drifted 8px before the timer and 8px after it has travelled 16, not
+     * twice-nearly-nothing.
+     */
+    distanceFromPress: number;
+    velocityX: number;
+    velocityY: number;
+    /** Whether this press's own timer has already fired. */
+    timerElapsed: boolean;
+    /** Pointers down now, and the most this interaction has ever had at once. */
+    pointerCount: number;
+    maxPointerCount: number;
+    /** Completed press-release cycles, including the one being decided. */
+    taps: number;
+    /**
+     * `Pinch`: the scale since GTK recognized the gesture, 1 at the start.
+     * `Rotation`: radians since it did, 0 at the start and positive clockwise.
+     *
+     * Both are 1 and 0 for every pointer-driven kind, so a predicate that reads
+     * them on the wrong kind gets the identity rather than a lie.
+     */
+    scale: number;
+    rotation: number;
+    /**
+     * `ForceTouch`: the pressure, normalised to `[0, 1]`.
+     *
+     * 0 for every other kind — an input with no pressure axis reports no
+     * pressure, and a predicate reading this on the wrong kind gets the number
+     * that is true rather than one that looks plausible.
+     */
+    force: number;
+};
+/**
+ * The timer a recognizer arms on every press, and what its firing means.
+ *
+ * All three kinds want one and they disagree only about the outcome: `Pan`'s
+ * `activateAfterLongPress` and `LongPress`'s `minDuration` mature the gesture,
+ * `Tap`'s `maxDuration` is a deadline that kills it.
+ */
+export type RecognizerTimer = {
+    delay: number;
+    elapsed: "activate" | "fail";
+};
+/** What lifting the pointer means to a gesture that is still BEGAN. */
+export type ReleaseOutcome = {
+    kind: "activate";
+} | {
+    kind: "fail";
+}
+/** Not over — wait this long for another press, then fail. */
+ | {
+    kind: "await";
+    delay: number;
+}
+/**
+ * Nothing at all: stay BEGAN, with no timer and no decision.
+ *
+ * `Manual` alone, and it is upstream's documented rule for it — "it will not
+ * fail when all the pointers are lifted from the screen". A gesture the app
+ * drives has no business being failed by a lift the app did not ask about.
+ */
+ | {
+    kind: "hold";
+};
+/**
+ * What a recognizer kind contributes: predicates over the current state of
+ * one press. Everything else — the state progression, the callbacks, the
+ * responder plumbing, the bounds tests, the timer — is shared, which is what
+ * makes `Tap` and `LongPress` an afternoon rather than a second machine.
+ *
+ * Only `shouldFail` and `shouldActivate` are required, and `Pan` implements
+ * exactly those two: the rest exist because `Tap` activates on a RELEASE and
+ * `LongPress` can be cancelled after it is already ACTIVE, and neither shape
+ * was reachable from a pair of movement predicates.
+ */
+export type RecognizerDecider = {
+    /**
+     * Which kind this is.
+     *
+     * Carried by the decider because the decider IS what tells the kinds apart,
+     * and because the arbitration loop needs exactly one fact about a gesture
+     * beyond its relations: whether it is `Gesture.Native()`, the one kind that
+     * can cancel an already-active gesture.
+     */
+    kind: GestureKind;
+    shouldFail: (view: RecognizerView, config: RecognizerConfig) => boolean;
+    shouldActivate: (view: RecognizerView, config: RecognizerConfig) => boolean;
+    /** Absent means "no timer", which is `Pan` without `activateAfterLongPress`. */
+    timer?: (config: RecognizerConfig) => RecognizerTimer | null;
+    /** Absent means an ACTIVE gesture is only ever ended by the pointer. */
+    shouldCancelWhileActive?: (view: RecognizerView, config: RecognizerConfig) => boolean;
+    /** Absent means a lift while BEGAN is the end of it, which is `Pan`'s rule. */
+    onRelease?: (view: RecognizerView, config: RecognizerConfig) => ReleaseOutcome;
+    /**
+     * Whether activating means taking the responder. Absent means yes, which is
+     * every recognizer that decides the interaction is React Native's.
+     *
+     * `Native` is the one that says no, and it is not an optimisation: taking
+     * the responder is what makes the platform declare `CLAIMED` and suspend
+     * every enclosing `GtkScrolledWindow`'s kinetics
+     * (`responder/use-responder.ts`). A gesture whose entire meaning is "the
+     * native widget is handling this" cannot be the thing that stops the native
+     * widget from handling it.
+     *
+     * A recognizer that does not claim runs off the touch props alone — they
+     * fire regardless of responder status, which is the same seam the BEGAN
+     * phase already uses. It never receives `onResponderMove`, so its updates
+     * come from `onTouchMove` and its ending from `onTouchEnd`/`onTouchCancel`.
+     */
+    claimsResponder?: boolean;
+    /**
+     * Activating IS the whole gesture: end it, successfully, in the same breath.
+     *
+     * `Fling` alone, and it is upstream's own shape rather than a shortcut —
+     * `FlingGestureHandler.activate()` is overridden to call `this.end()`
+     * immediately after `super.activate()`. A fling is a verdict about a motion
+     * that has already happened, so there is nothing left to report once it is
+     * reached: BEGAN -> ACTIVE -> END, synchronously, with `onStart` and `onEnd`
+     * one after the other and no `onUpdate` between them.
+     */
+    endsOnActivate?: boolean;
+    /**
+     * Which entry surface drives this kind. Absent means `"pointer"`.
+     *
+     * The one structural concession this module makes, and it is about where
+     * events COME FROM rather than about what happens to them. Three kinds of
+     * input are simply not in the pointer stream:
+     *
+     *   - `"touchpad"` — `Pinch`/`Rotation`, fed by
+     *     `GtkGestureZoom`/`GtkGestureRotate`, because a touchpad pinch presses
+     *     no button and so opens no GTK sequence and no responder session;
+     *   - `"hover"` — `Hover`, fed by `GtkEventControllerMotion`, because a
+     *     pointer that is merely OVER a view has pressed nothing either, and
+     *     RN's touch props fire only from a press;
+     *   - `"stylus"` — `ForceTouch`, fed by `GtkGestureStylus`, because pressure
+     *     is a tablet axis and `wl_pointer` has none.
+     *
+     * Everything downstream of the entry point is this same machine: the same
+     * states, the same callbacks, the same payload, the same `tryActivate` and
+     * the same relation maps. There is no second arbitration path.
+     *
+     * Exactly one surface is live per recognizer. A non-pointer kind's
+     * touch/responder props are empty, so a mouse press cannot begin a pinch or
+     * a hover; a `"pointer"` kind's controller channel is inert, so a pinch
+     * cannot begin a pan.
+     */
+    source?: "pointer" | "touchpad" | "hover" | "stylus";
+};
+/**
+ * RNGH's `checkHitSlop`, restated: build the acceptable box in the view's own
+ * coordinates, then test the pointer's offset into the view against it.
+ *
+ * Every side is "outward is positive", so a NEGATIVE value shrinks the box —
+ * the capability RN's own View `hitSlop` does not have. Explicit sides
+ * override `horizontal`/`vertical`, and `width`/`height` then anchor the
+ * opposite edge to whichever side was named.
+ *
+ * The plain-number spelling is normalised into the four sides up front.
+ * Upstream's web path does not do this and silently ignores a number, which
+ * is a bug rather than a semantic worth reproducing — its own native paths
+ * normalise exactly this way.
+ */
+export declare const hitSlopRect: (bounds: Rect, hitSlop: GestureHitSlop | undefined) => Rect;
+/**
+ * One frame from whichever GTK controller feeds a non-pointer kind, in the
+ * terms the recognizer reads.
+ *
+ * ONE sample type for three sources rather than three, because what the
+ * machine needs from all of them is the same short list and only two fields
+ * differ per kind. `scale` and `rotation` are CUMULATIVE since GTK recognized
+ * the gesture, which is what `gtk_gesture_zoom_get_scale_delta` ("the zooming
+ * difference since the gesture was recognized, hence the starting point is
+ * considered 1:1") and `gtk_gesture_rotate_get_angle_delta` already are — the
+ * same shape as upstream's own accumulators, so nothing is re-derived on the
+ * way in.
+ */
+export type ControllerSample = {
+    /**
+     * Where the gesture is, in the gesture VIEW's own coordinates.
+     *
+     * A pinch's bounding-box centre, a hover's pointer, a stylus tip: three
+     * names for the position the payload's `x`/`y`, `focalX`/`focalY` and
+     * `anchorX`/`anchorY` are all filled from, which is why they are one pair
+     * of fields and not three.
+     */
+    x: number;
+    y: number;
+    /** `Pinch`: 1 at the start of the gesture, above 1 for a spread. */
+    scale?: number;
+    /** `Rotation`: 0 at the start; radians, positive clockwise. */
+    rotation?: number;
+    /** `ForceTouch`: pressure normalised to `[0, 1]`. */
+    force?: number;
+    /** Pointers GTK reported. A touchpad pinch is always two; a hover is one. */
+    pointers: number;
+};
+/**
+ * The non-pointer entry surface, for the kinds GTK feeds rather than the
+ * pointer stream. Null on every pointer kind — see `RecognizerDecider.source`.
+ */
+export type ControllerChannel = {
+    begin: (sample: ControllerSample) => void;
+    update: (sample: ControllerSample) => void;
+    end: () => void;
+    cancel: () => void;
+};
+export type Recognizer = {
+    /** The responder props to put on the gesture's view. Empty for a controller kind. */
+    handlers: Record<string, (event: GestureResponderEvent) => boolean | void>;
+    /**
+     * Where `GtkGestureZoom`/`GtkGestureRotate`/`GtkEventControllerMotion`/
+     * `GtkGestureStylus` deliver, or null for a pointer kind.
+     */
+    controller: ControllerChannel | null;
+    /** This gesture's seat in the arbitration loop. */
+    participant: Participant;
+    /** Cancels any pending timer and leaves the loop; called on unmount. */
+    dispose: () => void;
+};
+/**
+ * Builds the machine. `readConfig` is called on every event rather than
+ * captured, so a re-render that hands the detector a fresh gesture object —
+ * which is what both spellings produce, every render — takes effect without
+ * swapping the handler set mid-drag.
+ */
+export declare const createRecognizer: (handlerTag: number, decider: RecognizerDecider, readConfig: () => RecognizerConfig, env: RecognizerEnvironment) => Recognizer;