[charts] Simplify zoom gesture jsdocs

Author: JCQuintas

packages/x-charts-pro/src/internals/plugins/zoomGestures/useDragGesture.ts

@@ -7,32 +7,30 @@ import { type ChartPoint, type GestureInstance, type PanGestureConfig } from './
 export interface UseDragGestureOptions {
   /** Whether the gesture is active. */
   enabled: boolean;
-  /** Pointer/keyboard gating forwarded to the interaction listener. */
+  /** Pointer and keyboard gating for the gesture. */
   config?: PanGestureConfig;
   /**
-   * Called once when a pan starts.
-   * @param {PanEvent} event The original pan start event.
+   * Called when the drag starts.
+   * @param {PanEvent} event The pan start event.
    */
   onPanStart?: (event: PanEvent) => void;
   /**
-   * Throttled call of the pan event
-   * @param {ChartPoint} delta The accumulated pixel delta since the last call.
-   * @param {PanEvent} event The original pan event.
+   * Called (rAF-throttled) on each drag update.
+   * @param {ChartPoint} delta The pixel delta since the last call.
+   * @param {PanEvent} event The pan event.
    */
   onPan: (delta: ChartPoint, event: PanEvent) => void;
   /**
-   * Called once when a pan ends.
-   * @param {PanEvent} event The original pan end event.
+   * Called when the drag ends.
+   * @param {PanEvent} event The pan end event.
    */
   onPanEnd?: (event: PanEvent) => void;
 }
 
 /**
- * Generic drag-to-pan gesture binding, decoupled from any coordinate system.
+ * Generic drag-to-pan gesture binding.
  *
- * It owns the listener lifecycle, the per-frame accumulation of the pixel delta, and
- * the rAF throttling. What to do with the delta is entirely up to `onPan` — cartesian
- * zoom translates an axis range, a map translates the projection, etc.
+ * It owns the listener lifecycle, and lets you create your own interactions by providing the delta change of the interaction.
  */
 export function useDragGesture(instance: GestureInstance, options: UseDragGestureOptions): void {
   const { enabled, config, onPanStart, onPan, onPanEnd } = options;

packages/x-charts-pro/src/internals/plugins/zoomGestures/useDragOnPressGesture.ts

@@ -7,30 +7,30 @@ import type { ChartPoint, GestureInstance, PanGestureConfig } from './zoomGestur
 export interface UseDragOnPressGestureOptions {
   /** Whether the gesture is active. */
   enabled: boolean;
-  /** Pointer/keyboard gating forwarded to the interaction listener. */
+  /** Pointer and keyboard gating for the gesture. */
   config?: PanGestureConfig;
   /**
-   * Called once when a pan starts.
-   * @param {PanEvent} event The original pan start event.
+   * Called when the drag starts.
+   * @param {PanEvent} event The pan start event.
    */
   onPanStart?: (event: PanEvent) => void;
   /**
-   * Throttled call of the pan event
-   * @param {ChartPoint} delta The accumulated pixel delta since the last call.
-   * @param {PanEvent} event The original pan event.
+   * Called (rAF-throttled) on each drag update.
+   * @param {ChartPoint} delta The pixel delta since the last call.
+   * @param {PanEvent} event The pan event.
    */
   onPan: (delta: ChartPoint, event: PanEvent) => void;
   /**
-   * Called once when a pan ends.
-   * @param {PanEvent} event The original pan end event.
+   * Called when the drag ends.
+   * @param {PanEvent} event The pan end event.
    */
   onPanEnd?: (event: PanEvent) => void;
 }
 
 /**
- * Generic drag-to-pan gesture binding.
+ * Generic press-and-drag-to-pan gesture binding.
  *
- * It owns the listener lifecycle, and allows the user to create their own interactions by providing the delta change of the interaction.
+ * It owns the listener lifecycle, and lets you create your own interactions by providing the delta change of the interaction.
  */
 export function useDragOnPressGesture(
   instance: GestureInstance,

packages/x-charts-pro/src/internals/plugins/zoomGestures/usePinchGesture.ts

@@ -14,14 +14,16 @@ export interface UsePinchGestureOptions {
    * Called (rAF-throttled) on each pinch update.
    *
    * @param {ChartPoint} point The pinch centroid, in SVG coordinates.
-   * @param {number} deltaScale The incremental scale change for this update.
+   * @param {number} deltaScale The scale change since the last call.
    * @param {number} direction `> 0` when zooming in, `< 0` when zooming out.
    */
   onPinch: (point: ChartPoint, deltaScale: number, direction: number) => void;
 }
 
 /**
- * Generic pinch gesture binding. Forwards the centroid and scale delta to `onPinch`.
+ * Generic pinch gesture binding.
+ *
+ * It owns the listener lifecycle, and lets you create your own interactions from the centroid and scale delta it forwards to `onPinch`.
  */
 export function usePinchGesture(instance: GestureInstance, options: UsePinchGestureOptions): void {
   const { enabled, requiredKeys, onPinch } = options;

packages/x-charts-pro/src/internals/plugins/zoomGestures/useWheelGesture.ts

@@ -11,17 +11,18 @@ export interface UseWheelGestureOptions {
   /** Keys that must be held for the wheel to trigger the gesture. */
   requiredKeys?: KeyboardKey[];
   /**
-   * Called on each wheel tick that lands inside the drawing area.
+   * Called on each wheel tick inside the drawing area.
    *
    * @param {ChartPoint} point The wheel focal point, in SVG coordinates.
-   * @param {WheelEvent} event The raw `WheelEvent`.
+   * @param {WheelEvent} event The `WheelEvent`.
    */
   onWheel: (point: ChartPoint, event: WheelEvent) => void;
 }
 
 /**
- * Generic wheel gesture binding. Handles the "started outside the chart" guard and
- * `preventDefault`, then forwards the focal point and wheel delta to `onWheel`.
+ * Generic wheel gesture binding.
+ *
+ * It owns the listener lifecycle, and lets you create your own interactions from the focal point and wheel event it forwards to `onWheel`.
  */
 export function useWheelGesture(instance: GestureInstance, options: UseWheelGestureOptions): void {
   const { enabled, requiredKeys, onWheel } = options;

packages/x-charts-pro/src/internals/plugins/zoomGestures/zoomGestures.types.ts

@@ -4,10 +4,6 @@ import type { UseChartInteractionListenerInstance } from '@mui/x-charts/internal
 
 /**
  * The minimal slice of a chart instance required to bind zoom/pan gestures.
- *
- * Every method here is provided by core plugins (`useChartInteractionListener`,
- * `useChartDimensions`, `useChartElementRef`), so any chart — cartesian or not —
- * can consume these gesture hooks.
  */
 export interface GestureInstance {
   chartsLayerContainerRef: React.RefObject<HTMLDivElement | null>;
@@ -17,8 +13,7 @@ export interface GestureInstance {
 }
 
 /**
- * Pointer/keyboard gating for a pan gesture, mirroring the options accepted by
- * `instance.updateZoomInteractionListeners('zoomPan', …)`.
+ * Pointer and keyboard gating for a pan gesture.
  */
 export interface PanGestureConfig {
   requiredKeys?: KeyboardKey[];