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

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

/**
 * PressAndDragGesture - Detects press followed by drag gestures using composition
 *
 * This gesture uses internal PressGesture and PanGesture instances to:
 * 1. First, detect a press (hold for specified duration without movement)
 * 2. Then, track drag movements from the press position
 *
 * The gesture fires events when:
 * - A press is completed (press phase)
 * - Drag movement begins and passes threshold (dragStart)
 * - Drag movement continues (drag)
 * - Drag movement ends (dragEnd)
 * - The gesture is canceled at any point
 *
 * This is ideal for panning operations where you want to hold first, then drag.
 */
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 PressAndDragGesture
 * Extends PointerGestureOptions with press and drag specific settings
 */
export type PressAndDragGestureOptions<GestureName extends string> = PointerGestureOptions<GestureName> & {
  /**
   * Duration in milliseconds required to hold before the press gesture is recognized
   * @default 500
   */
  pressDuration?: number;
  /**
   * Maximum distance in pixels a pointer can move during the press phase for it to still be considered a press
   * @default 10
   */
  pressMaxDistance?: number;
  /**
   * Maximum time in milliseconds between the press completion and the start of the drag
   * If exceeded, the gesture will reset and wait for a new press
   * @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 press and drag gesture events
 * Contains information about the gesture state, position, and movement
 */
export type PressAndDragGestureEventData<CustomData extends Record<string, unknown> = Record<string, unknown>> = PanGestureEventData<CustomData> & {};
/**
 * Type definition for the CustomEvent created by PressAndDragGesture
 */
export type PressAndDragEvent<CustomData extends Record<string, unknown> = Record<string, unknown>> = CustomEvent<PressAndDragGestureEventData<CustomData>>;
/**
 * Represents the current phase of the PressAndDrag gesture
 */
export type PressAndDragPhase = 'waitingForPress' | 'pressDetected' | 'waitingForDrag' | 'dragging';
/**
 * State tracking for the PressAndDragGesture
 */
export type PressAndDragGestureState = GestureState & {
  /** Current phase of the press and drag gesture */
  phase: PressAndDragPhase;
  /** Timeout used to time drag interactions */
  dragTimeoutId: ReturnType<typeof setTimeout> | null;
};
/**
 * PressAndDragGesture class for handling press followed by drag interactions
 *
 * This gesture composes press and drag logic patterns from PressGesture and PanGesture
 * into a single coordinated gesture that handles press-then-drag interactions.
 */
export declare class PressAndDragGesture<GestureName extends string> extends PointerGesture<GestureName> {
  protected state: PressAndDragGestureState;
  protected readonly isSinglePhase: false;
  protected readonly eventType: PressAndDragEvent;
  protected readonly optionsType: PressAndDragGestureOptions<GestureName>;
  protected readonly mutableOptionsType: Omit<typeof this.optionsType, 'name'>;
  protected readonly mutableStateType: Omit<Partial<typeof this.state>, 'phase' | 'dragTimeoutId'>;
  /**
   * Duration required for press recognition
   */
  private pressDuration;
  /**
   * Maximum distance a pointer can move during press for it to still be considered a press
   */
  private pressMaxDistance;
  /**
   * Maximum time between press completion and drag start
   */
  private dragTimeout;
  /**
   * Movement threshold for drag activation
   */
  private dragThreshold;
  /**
   * Allowed directions for the drag gesture
   */
  private dragDirection;
  private pressGesture;
  private panGesture;
  constructor(options: PressAndDragGestureOptions<GestureName>);
  clone(overrides?: Record<string, unknown>): PressAndDragGesture<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 PressAndDragGesture relies on PressGesture 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 pressHandler;
  private dragStartHandler;
  private dragMoveHandler;
  private dragEndHandler;
  private setTouchAction;
  private restoreTouchAction;
}