@mui/x-internal-gestures/core/gestures/TapAndDragGesture.d.ts

The core engine of GestureEvents, a modern and robust multi-pointer gesture detection library for JavaScript.

/**
 * TapAndDragGesture - Detects tap followed by drag gestures using composition
 *
 * This gesture uses internal TapGesture and PanGesture instances to:
 * 1. First, detect a tap (quick touch without movement)
 * 2. Then, track drag movements on the next pointer down
 *
 * The gesture fires events when:
 * - A tap is completed (tap phase)
 * - Drag movement begins and passes threshold (dragStart)
 * - Drag movement continues (drag)
 * - Drag movement ends (dragEnd)
 * - The gesture is canceled at any point
 */
import type { ActiveGesturesRegistry } from "../ActiveGesturesRegistry.js";
import { GestureState } from "../Gesture.js";
import type { KeyboardManager } from "../KeyboardManager.js";
import { PointerGesture, type PointerGestureOptions } from "../PointerGesture.js";
import { type PointerManager } from "../PointerManager.js";
import { type PanGestureEventData } from "./PanGesture.js";
/**
 * Configuration options for TapAndDragGesture
 * Extends PointerGestureOptions with tap and drag specific settings
 */
export type TapAndDragGestureOptions<GestureName extends string> = PointerGestureOptions<GestureName> & {
  /**
   * Maximum distance in pixels a pointer can move during the tap phase for it to still be considered a tap
   * @default 10
   */
  tapMaxDistance?: number;
  /**
   * Maximum time in milliseconds between the tap completion and the start of the drag
   * If exceeded, the gesture will reset and wait for a new tap
   * @default 1000
   */
  dragTimeout?: number;
  /**
   * Distance threshold in pixels for drag activation.
   * The drag will only be recognized once the pointer has moved this many
   * pixels from its starting position in the drag phase.
   * @default 0
   */
  dragThreshold?: number;
  /**
   * Optional array of allowed directions for the drag gesture
   * If not specified, all directions are allowed
   */
  dragDirection?: Array<'up' | 'down' | 'left' | 'right'>;
};
/**
 * Event data specific to tap and drag gesture events
 * Contains information about the gesture state, position, and movement
 */
export type TapAndDragGestureEventData<CustomData extends Record<string, unknown> = Record<string, unknown>> = PanGestureEventData<CustomData> & {};
/**
 * Type definition for the CustomEvent created by TapAndDragGesture
 */
export type TapAndDragEvent<CustomData extends Record<string, unknown> = Record<string, unknown>> = CustomEvent<TapAndDragGestureEventData<CustomData>>;
/**
 * Represents the current phase of the TapAndDrag gesture
 */
export type TapAndDragPhase = 'waitingForTap' | 'tapDetected' | 'waitingForDrag' | 'dragging';
/**
 * State tracking for the TapAndDragGesture
 */
export type TapAndDragGestureState = GestureState & {
  /** Current phase of the tap and drag gesture */
  phase: TapAndDragPhase;
  /** Timeout used to time drag interactions */
  dragTimeoutId: ReturnType<typeof setTimeout> | null;
};
/**
 * TapAndDragGesture class for handling tap followed by drag interactions
 *
 * This gesture composes tap and drag logic patterns from TapGesture and PanGesture
 * into a single coordinated gesture that handles tap-then-drag interactions.
 */
export declare class TapAndDragGesture<GestureName extends string> extends PointerGesture<GestureName> {
  protected state: TapAndDragGestureState;
  protected readonly isSinglePhase: false;
  protected readonly eventType: TapAndDragEvent;
  protected readonly optionsType: TapAndDragGestureOptions<GestureName>;
  protected readonly mutableOptionsType: Omit<typeof this.optionsType, 'name'>;
  protected readonly mutableStateType: Omit<Partial<typeof this.state>, 'phase' | 'dragTimeoutId'>;
  /**
   * Maximum distance a pointer can move during tap for it to still be considered a tap
   * (Following TapGesture pattern)
   */
  private tapMaxDistance;
  /**
   * Maximum time between tap completion and drag start
   */
  private dragTimeout;
  /**
   * Movement threshold for drag activation
   */
  private dragThreshold;
  /**
   * Allowed directions for the drag gesture
   */
  private dragDirection;
  private tapGesture;
  private panGesture;
  constructor(options: TapAndDragGestureOptions<GestureName>);
  clone(overrides?: Record<string, unknown>): TapAndDragGesture<GestureName>;
  init(element: HTMLElement, pointerManager: PointerManager, gestureRegistry: ActiveGesturesRegistry<GestureName>, keyboardManager: KeyboardManager): void;
  destroy(): void;
  protected updateOptions(options: typeof this.mutableOptionsType): void;
  protected resetState(): void;
  /**
   * This can be empty because the TapAndDragGesture relies on TapGesture and PanGesture to handle pointer events
   * The internal gestures will manage their own state and events, while this class coordinates between them
   */
  protected handlePointerEvent(): void;
  private tapHandler;
  private dragStartHandler;
  private dragMoveHandler;
  private dragEndHandler;
  private setTouchAction;
  private restoreTouchAction;
}