@astryxdesign/core 0.7.4 → 0.7.5-canary.0418c47

package/dist/gestures/GestureRecognizer.d.ts

@@ -0,0 +1,239 @@
+/**
+ * @file GestureRecognizer.ts
+ * @input Touches delivered by a GestureArena
+ * @output Exports GestureRecognizer, the base every recognizer extends
+ *   (UIGestureRecognizer), and its options and listener types
+ * @position Core of packages/core/src/gestures: subclasses interpret touches
+ *   and request state changes; the arena decides whether a change is allowed
+ *   (require-to-fail, exclusivity, should-begin) and applies it
+ *
+ * The state machine is UIKit's:
+ *
+ *   possible ─► began ─► changed* ─► ended | cancelled     (continuous)
+ *   possible ─► ended                                       (discrete: "recognized")
+ *   possible ─► failed
+ *
+ * A recognizer in a terminal state ignores the touches it still has and
+ * returns to `possible` (its `reset()` runs) once all of them have ended,
+ * exactly as UIKit resets a recognizer before the next touch sequence.
+ *
+ * Listeners (UIKit's target-action) fire for `began`, `changed`, `ended` and
+ * `cancelled`, never for `failed`. They run synchronously inside the input
+ * event, so a listener that writes a transform writes it in the same frame
+ * as the input, with no React render in between.
+ *
+ * SYNC: When modified, update GestureArena.ts.
+ */
+import type { GestureArena } from './GestureArena.js';
+import type { GestureEnvironment, GestureEventContext, GestureState, GestureTouch, Point, PointerKind } from './types.js';
+export interface GestureRecognizerOptions<R = GestureRecognizer> {
+    /** A name for debugging and test output. */
+    name?: string;
+    /** A disabled recognizer receives no touches; disabling one mid-gesture cancels it. @default true */
+    isEnabled?: boolean;
+    /**
+     * When the gesture is recognized, cancel the view's touches: a pressed
+     * control un-highlights without acting, and the browser's click for the
+     * touch is swallowed. @default true
+     */
+    cancelsTouchesInView?: boolean;
+    /** Hold the view's touch-began until this recognizer fails. @default false */
+    delaysTouchesBegan?: boolean;
+    /**
+     * Hold the view's touch-ended (and the browser's click) while this
+     * recognizer may still recognize. @default true
+     */
+    delaysTouchesEnded?: boolean;
+    /** Pointer kinds this recognizer listens to (UIKit's `allowedTouchTypes`). @default all */
+    allowedPointerTypes?: ReadonlyArray<PointerKind>;
+    /** Ignore a touch of a different kind than the ones already tracked. @default true */
+    requiresExclusiveTouchType?: boolean;
+    /** gestureRecognizerShouldBegin: return false to fail instead of beginning. */
+    shouldBegin?: (recognizer: R) => boolean;
+    /** gestureRecognizer(_:shouldReceive:): return false to never see this touch. */
+    shouldReceiveTouch?: (recognizer: R, touch: GestureTouch) => boolean;
+    /** gestureRecognizer(_:shouldRecognizeSimultaneouslyWith:). */
+    shouldRecognizeSimultaneously?: (recognizer: R, other: GestureRecognizer) => boolean;
+    /** gestureRecognizer(_:shouldRequireFailureOf:). */
+    shouldRequireFailureOf?: (recognizer: R, other: GestureRecognizer) => boolean;
+    /** gestureRecognizer(_:shouldBeRequiredToFailBy:). */
+    shouldBeRequiredToFailBy?: (recognizer: R, other: GestureRecognizer) => boolean;
+}
+export type GestureListener<R> = (recognizer: R) => void;
+export type GestureTransitionListener<R> = (recognizer: R, from: GestureState, to: GestureState) => void;
+export declare function isTransitionAllowed(from: GestureState, to: GestureState): boolean;
+export declare function isTerminal(state: GestureState): boolean;
+export declare function isActive(state: GestureState): boolean;
+/** The browser behaviors `touch-action` can keep or remove. */
+export interface NativeTouchBehavior {
+    readonly panX: boolean;
+    readonly panY: boolean;
+    readonly pinchZoom: boolean;
+    /** Double-tap to zoom, the reason for the old 300 ms click delay. */
+    readonly doubleTapZoom: boolean;
+}
+export declare const ALL_NATIVE_TOUCH: NativeTouchBehavior;
+/** A tap-like recognizer only needs double-tap zoom gone (no click delay). */
+export declare const MANIPULATION: NativeTouchBehavior;
+export declare abstract class GestureRecognizer {
+    /** Stable id, for ordering and debugging. */
+    readonly id: number;
+    name: string;
+    isEnabled: boolean;
+    cancelsTouchesInView: boolean;
+    delaysTouchesBegan: boolean;
+    delaysTouchesEnded: boolean;
+    allowedPointerTypes: ReadonlySet<PointerKind> | null;
+    requiresExclusiveTouchType: boolean;
+    /**
+     * The element (or any object) the recognizer is attached to. The DOM host
+     * sets it; the arena treats it as opaque.
+     */
+    view: unknown;
+    /** @internal The arena delivering touches to this recognizer, if any. */
+    arena: GestureArena | null;
+    /** @internal A recognition waiting for a failure requirement. */
+    pending: 'began' | 'ended' | null;
+    /**
+     * The delegate functions. Typed against the base so a subclass stays
+     * assignable to GestureRecognizer; each is only ever called with `this`.
+     */
+    private readonly options;
+    private stateValue;
+    private readonly listeners;
+    private readonly transitionListeners;
+    private readonly failureRequirements;
+    private readonly simultaneousWith;
+    /** Touches currently tracked, by id. */
+    protected readonly touches: Map<number, GestureTouch>;
+    /** @internal Every touch id received since the last reset. */
+    readonly seenTouchIds: Set<number>;
+    private lastLocation;
+    constructor(options?: GestureRecognizerOptions<never>);
+    /** Discrete recognizers go from `possible` straight to `ended`. */
+    get isDiscrete(): boolean;
+    /**
+     * Whether recognizing takes the touches from the browser: while a claiming
+     * recognizer owns a touch, the host cancels the browser's pan and zoom for
+     * it. Every touch recognizer claims; hover has no touches to claim.
+     */
+    get claimsTouches(): boolean;
+    get state(): GestureState;
+    /**
+     * What the browser may still do natively on this recognizer's view: the
+     * host intersects these across a view's recognizers into its
+     * `touch-action`. A recognizer that takes no touches constrains nothing.
+     */
+    get nativeTouchBehavior(): NativeTouchBehavior;
+    /** @internal Whether this recognizer listens to touch at all. */
+    get acceptsTouchInput(): boolean;
+    /** How many touches the recognizer is tracking right now. */
+    get numberOfTouches(): number;
+    /** The touches being tracked, in the order they began. */
+    get trackedTouches(): ReadonlyArray<GestureTouch>;
+    /**
+     * The centroid of the tracked touches in client coordinates; after they
+     * end, where they were last.
+     */
+    location(): Point;
+    /** Facts about the page (viewport, writing direction). */
+    protected get environment(): GestureEnvironment;
+    /** UIKit's `require(toFail:)`: recognize only once `other` has failed. */
+    requireToFail(other: GestureRecognizer): this;
+    /** Let this and `others` be recognized at the same time (both directions). */
+    recognizeSimultaneouslyWith(...others: GestureRecognizer[]): this;
+    /** @internal Whether this recognizer must wait for `other` to fail. */
+    requiresFailureOf(other: GestureRecognizer): boolean;
+    /**
+     * @internal Whether this and `other` may be active together: both allow it
+     * (`recognizeSimultaneouslyWith` sets both sides; each delegate answers for
+     * its own recognizer), so one delegate alone keeps them exclusive (FR15).
+     */
+    allowsSimultaneous(other: GestureRecognizer): boolean;
+    /** @internal The delegate's should-begin answer. */
+    shouldBegin(): boolean;
+    /** UIKit's `canPrevent(_:)`: whether recognizing fails `other`. */
+    canPrevent(_other: GestureRecognizer): boolean;
+    /** UIKit's `canBePrevented(by:)`. */
+    canBePrevented(_other: GestureRecognizer): boolean;
+    /**
+     * Whether this recognizer is still part of the current interaction: it
+     * tracks touches, is waiting on a requirement, or (a multi-tap between
+     * taps) expects more input. An idle `possible` recognizer cannot recognize
+     * and so does not hold up anything that requires it to fail.
+     */
+    isInvolved(): boolean;
+    /** Called on began, changed, ended (recognized) and cancelled. */
+    addListener(listener: GestureListener<this>): () => void;
+    /** Called on every transition, including failed and the reset to possible. */
+    addTransitionListener(listener: GestureTransitionListener<this>): () => void;
+    /** New touches for this recognizer. */
+    protected touchesBegan(_touches: ReadonlyArray<GestureTouch>, _event: GestureEventContext): void;
+    protected touchesMoved(_touches: ReadonlyArray<GestureTouch>, _event: GestureEventContext): void;
+    /** Touches lifted; they are removed from `touches` after this returns. */
+    protected touchesEnded(_touches: ReadonlyArray<GestureTouch>, _event: GestureEventContext): void;
+    /**
+     * The system or the browser took these touches. By default an active
+     * gesture is cancelled and a possible one fails.
+     */
+    protected touchesCancelled(_touches: ReadonlyArray<GestureTouch>, _event: GestureEventContext): void;
+    /**
+     * The browser took these touches for its own pan or zoom (their pointer
+     * stream is gone). Return true to keep observing them; by default they are
+     * treated as cancelled. An observer never claims them: a drag the browser
+     * took stays the browser's (FR14).
+     */
+    protected touchesTakenByBrowser(touches: ReadonlyArray<GestureTouch>, event: GestureEventContext): boolean;
+    /**
+     * A touch began elsewhere (off this recognizer's hit path) while this
+     * recognizer tracks touches of its own. It is not this recognizer's touch
+     * and is never delivered as one; a recognizer that a foreign finger should
+     * end (a menu's press slide) cancels itself here. By default nothing
+     * happens.
+     */
+    protected touchBeganElsewhere(_touches: ReadonlyArray<GestureTouch>, _event: GestureEventContext): void;
+    /** Clear per-gesture state before the next attempt. */
+    protected reset(): void;
+    /**
+     * Whether a touch may join. The base checks enabled, pointer kind and
+     * exclusivity of kind; subclasses narrow it (a one-finger pan ignores a
+     * second finger once it is moving).
+     */
+    protected acceptsTouch(touch: GestureTouch): boolean;
+    /**
+     * Ask for a state change. The arena may refuse (the recognizer fails
+     * instead) or defer it until a failure requirement resolves.
+     */
+    protected setState(next: GestureState): void;
+    /** Arm the recognizer's one timer at an absolute time on the event clock. */
+    protected setTimer(deadline: number, callback: () => void): void;
+    protected clearTimer(): void;
+    /** The event clock's current time. */
+    protected now(): number;
+    /** @internal Whether this recognizer takes `touch` right now. */
+    wantsTouch(touch: GestureTouch): boolean;
+    /** @internal */
+    deliverBegan(touches: ReadonlyArray<GestureTouch>, event: GestureEventContext): void;
+    /** @internal */
+    deliverBeganElsewhere(touches: ReadonlyArray<GestureTouch>, event: GestureEventContext): void;
+    /** @internal */
+    deliverMoved(touches: ReadonlyArray<GestureTouch>, event: GestureEventContext): void;
+    /** @internal */
+    deliverEnded(touches: ReadonlyArray<GestureTouch>, event: GestureEventContext): void;
+    /** @internal */
+    deliverCancelled(touches: ReadonlyArray<GestureTouch>, event: GestureEventContext): void;
+    /** @internal */
+    deliverTakenByBrowser(touches: ReadonlyArray<GestureTouch>, event: GestureEventContext): void;
+    /**
+     * UIKit's `isEnabled` setter: turning a recognizer off mid-gesture cancels
+     * the gesture (an active one) or fails it (a possible one).
+     */
+    setEnabled(value: boolean): void;
+    /** Cancel this recognizer if it is active, or fail it if it is possible. */
+    cancel(): void;
+    /** @internal Apply a transition the arena has approved. */
+    applyState(next: GestureState): void;
+    /** @internal Return to `possible` for the next attempt. */
+    resetToPossible(): void;
+}
+//# sourceMappingURL=GestureRecognizer.d.ts.map

package/dist/gestures/GestureRecognizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GestureRecognizer.d.ts","sourceRoot":"","sources":["../../src/gestures/GestureRecognizer.ts"],"names":[],"mappings":"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"}