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

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

import { ActiveGesturesRegistry } from "./ActiveGesturesRegistry.js";
import { Gesture, GestureEventData, GestureOptions, type BaseGestureOptions } from "./Gesture.js";
import type { KeyboardManager } from "./KeyboardManager.js";
import { PointerData, PointerManager } from "./PointerManager.js";
import { TargetElement } from "./types/TargetElement.js";
/**
 * Base configuration options that can be overridden per pointer mode.
 */
export type BasePointerGestureOptions = BaseGestureOptions & {
  /**
   * Minimum number of pointers required to activate the gesture.
   * The gesture will not start until at least this many pointers are active.
   *
   * @default 1
   */
  minPointers?: number;
  /**
   * Maximum number of pointers allowed for this gesture to remain active.
   * If more than this many pointers are detected, the gesture may be canceled.
   *
   * @default Infinity (no maximum)
   */
  maxPointers?: number;
};
/**
 * Configuration options for pointer-based gestures, extending the base GestureOptions.
 *
 * These options provide fine-grained control over how pointer events are interpreted
 * and when the gesture should be recognized.
 */
export interface PointerGestureOptions<GestureName extends string> extends GestureOptions<GestureName, BasePointerGestureOptions> {}
export type PointerGestureEventData<CustomData extends Record<string, unknown> = Record<string, unknown>> = GestureEventData<CustomData> & {
  /** The original event that triggered this gesture */
  srcEvent: PointerEvent;
};
/**
 * Base class for all pointer-based gestures.
 *
 * This class extends the base Gesture class with specialized functionality for
 * handling pointer events via the PointerManager. It provides common logic for
 * determining when a gesture should activate, tracking pointer movements, and
 * managing pointer thresholds.
 *
 * All pointer-based gesture implementations should extend this class rather than
 * the base Gesture class.
 *
 * @example
 * ```ts
 * import { PointerGesture } from './PointerGesture';
 *
 * class CustomGesture extends PointerGesture {
 *   constructor(options) {
 *     super(options);
 *   }
 *
 *   clone(overrides) {
 *     return new CustomGesture({
 *       name: this.name,
 *       // ... other options
 *       ...overrides,
 *     });
 *   }
 *
 *   handlePointerEvent = (pointers, event) => {
 *     // Handle pointer events here
 *   }
 * }
 * ```
 */
export declare abstract class PointerGesture<GestureName extends string> extends Gesture<GestureName> {
  /** Function to unregister from the PointerManager when destroying this gesture */
  protected unregisterHandler: (() => void) | null;
  /** The original target element when the gesture began, used to prevent limbo state if target is removed */
  protected originalTarget: TargetElement | null;
  protected abstract readonly optionsType: PointerGestureOptions<GestureName>;
  protected abstract readonly mutableOptionsType: Omit<typeof this.optionsType, 'name'>;
  /**
   * Minimum number of simultaneous pointers required to activate the gesture.
   * The gesture will not start until at least this many pointers are active.
   */
  protected minPointers: number;
  /**
   * Maximum number of simultaneous pointers allowed for this gesture.
   * If more than this many pointers are detected, the gesture may be canceled.
   */
  protected maxPointers: number;
  constructor(options: PointerGestureOptions<GestureName>);
  init(element: TargetElement, pointerManager: PointerManager, gestureRegistry: ActiveGesturesRegistry<GestureName>, keyboardManager: KeyboardManager): void;
  protected updateOptions(options: typeof this.mutableOptionsType): void;
  protected getBaseConfig(): {
    requiredKeys: import("./KeyboardManager.js").KeyboardKey[];
    minPointers: number;
    maxPointers: number;
  };
  protected isWithinPointerCount(pointers: PointerData[], pointerMode: string): boolean;
  /**
   * Handler for pointer events from the PointerManager.
   * Concrete gesture implementations must override this method to provide
   * gesture-specific logic for recognizing and tracking the gesture.
   *
   * @param pointers - Map of active pointers by pointer ID
   * @param event - The original pointer event from the browser
   */
  protected abstract handlePointerEvent(pointers: Map<number, PointerData>, event: PointerEvent): void;
  /**
   * Calculate the target element for the gesture based on the active pointers.
   *
   * It takes into account the original target element.
   *
   * @param pointers - Map of active pointers by pointer ID
   * @param calculatedTarget - The target element calculated from getTargetElement
   * @returns A list of relevant pointers for this gesture
   */
  protected getRelevantPointers(pointers: PointerData[], calculatedTarget: TargetElement): PointerData[];
  destroy(): void;
}