@mui/x-charts-pro 9.4.0 → 9.5.0

package/internals/plugins/zoomGestures/useDragGesture.mjs

@@ -0,0 +1,99 @@
+'use client';
+
+import * as React from 'react';
+import { rafThrottle } from '@mui/x-internals/rafThrottle';
+/**
+ * Generic drag-to-pan gesture binding.
+ *
+ * It owns the listener lifecycle, and lets you create your own interactions by providing the delta change of the interaction.
+ */
+export function useDragGesture(instance, options) {
+  const {
+    enabled,
+    config,
+    onPanStart,
+    onPan,
+    onPanEnd
+  } = options;
+  const {
+    chartsLayerContainerRef
+  } = instance;
+
+  // Keep the latest handlers in a ref so changing them doesn't rebind listeners.
+  const handlersRef = React.useRef({
+    onPanStart,
+    onPan,
+    onPanEnd
+  });
+  React.useEffect(() => {
+    handlersRef.current = {
+      onPanStart,
+      onPan,
+      onPanEnd
+    };
+  });
+  React.useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+    instance.updateZoomInteractionListeners('zoomPan', {
+      requiredKeys: config?.requiredKeys,
+      pointerMode: config?.pointerMode,
+      pointerOptions: {
+        mouse: config?.mouse,
+        touch: config?.touch
+      }
+    });
+  }, [enabled, config, instance]);
+  React.useEffect(() => {
+    const element = chartsLayerContainerRef.current;
+    if (element === null || !enabled) {
+      return () => {};
+    }
+    let isInteracting = false;
+    let lastEvent = null;
+    const accumulated = {
+      x: 0,
+      y: 0
+    };
+    const handlePanStart = event => {
+      if (!event.detail.target?.closest('[data-charts-zoom-slider]')) {
+        isInteracting = true;
+        handlersRef.current.onPanStart?.(event);
+      }
+    };
+    const handlePanEnd = event => {
+      isInteracting = false;
+      handlersRef.current.onPanEnd?.(event);
+    };
+    const throttled = rafThrottle(() => {
+      const delta = {
+        x: accumulated.x,
+        y: accumulated.y
+      };
+      accumulated.x = 0;
+      accumulated.y = 0;
+      if (lastEvent) {
+        handlersRef.current.onPan(delta, lastEvent);
+      }
+    });
+    const handlePan = event => {
+      if (!isInteracting) {
+        return;
+      }
+      lastEvent = event;
+      accumulated.x += event.detail.deltaX;
+      accumulated.y += event.detail.deltaY;
+      throttled();
+    };
+    const panHandler = instance.addInteractionListener('zoomPan', handlePan);
+    const panStartHandler = instance.addInteractionListener('zoomPanStart', handlePanStart);
+    const panEndHandler = instance.addInteractionListener('zoomPanEnd', handlePanEnd);
+    return () => {
+      panHandler.cleanup();
+      panStartHandler.cleanup();
+      panEndHandler.cleanup();
+      throttled.clear();
+    };
+  }, [instance, chartsLayerContainerRef, enabled]);
+}

package/internals/plugins/zoomGestures/useDragOnPressGesture.d.mts

@@ -0,0 +1,30 @@
+import type { PanEvent } from '@mui/x-internal-gestures/core';
+import type { ChartPoint, GestureInstance, PanGestureConfig } from "./zoomGestures.types.mjs";
+export interface UseDragOnPressGestureOptions {
+  /** Whether the gesture is active. */
+  enabled: boolean;
+  /** Pointer and keyboard gating for the gesture. */
+  config?: PanGestureConfig;
+  /**
+   * Called when the drag starts.
+   * @param {PanEvent} event The pan start event.
+   */
+  onPanStart?: (event: PanEvent) => void;
+  /**
+   * 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 when the drag ends.
+   * @param {PanEvent} event The pan end event.
+   */
+  onPanEnd?: (event: PanEvent) => void;
+}
+/**
+ * Generic press-and-drag-to-pan gesture binding.
+ *
+ * It owns the listener lifecycle, and lets you create your own interactions by providing the delta change of the interaction.
+ */
+export declare function useDragOnPressGesture(instance: GestureInstance, options: UseDragOnPressGestureOptions): void;

package/internals/plugins/zoomGestures/useDragOnPressGesture.d.ts

@@ -0,0 +1,30 @@
+import type { PanEvent } from '@mui/x-internal-gestures/core';
+import type { ChartPoint, GestureInstance, PanGestureConfig } from "./zoomGestures.types.js";
+export interface UseDragOnPressGestureOptions {
+  /** Whether the gesture is active. */
+  enabled: boolean;
+  /** Pointer and keyboard gating for the gesture. */
+  config?: PanGestureConfig;
+  /**
+   * Called when the drag starts.
+   * @param {PanEvent} event The pan start event.
+   */
+  onPanStart?: (event: PanEvent) => void;
+  /**
+   * 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 when the drag ends.
+   * @param {PanEvent} event The pan end event.
+   */
+  onPanEnd?: (event: PanEvent) => void;
+}
+/**
+ * Generic press-and-drag-to-pan gesture binding.
+ *
+ * It owns the listener lifecycle, and lets you create your own interactions by providing the delta change of the interaction.
+ */
+export declare function useDragOnPressGesture(instance: GestureInstance, options: UseDragOnPressGestureOptions): void;

package/internals/plugins/zoomGestures/useDragOnPressGesture.js

@@ -0,0 +1,105 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useDragOnPressGesture = useDragOnPressGesture;
+var React = _interopRequireWildcard(require("react"));
+var _rafThrottle = require("@mui/x-internals/rafThrottle");
+/**
+ * Generic press-and-drag-to-pan gesture binding.
+ *
+ * It owns the listener lifecycle, and lets you create your own interactions by providing the delta change of the interaction.
+ */
+function useDragOnPressGesture(instance, options) {
+  const {
+    enabled,
+    config,
+    onPanStart,
+    onPan,
+    onPanEnd
+  } = options;
+  const {
+    chartsLayerContainerRef
+  } = instance;
+
+  // Keep the latest handlers in a ref so changing them doesn't rebind listeners.
+  const handlersRef = React.useRef({
+    onPanStart,
+    onPan,
+    onPanEnd
+  });
+  React.useEffect(() => {
+    handlersRef.current = {
+      onPanStart,
+      onPan,
+      onPanEnd
+    };
+  });
+  React.useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+    instance.updateZoomInteractionListeners('zoomPressAndDrag', {
+      requiredKeys: config?.requiredKeys,
+      pointerMode: config?.pointerMode,
+      pointerOptions: {
+        mouse: config?.mouse,
+        touch: config?.touch
+      }
+    });
+  }, [enabled, config, instance]);
+  React.useEffect(() => {
+    const element = chartsLayerContainerRef.current;
+    if (element === null || !enabled) {
+      return () => {};
+    }
+    let isInteracting = false;
+    let lastEvent = null;
+    const accumulated = {
+      x: 0,
+      y: 0
+    };
+    const handlePanStart = event => {
+      if (!event.detail.target?.closest('[data-charts-zoom-slider]')) {
+        isInteracting = true;
+        handlersRef.current.onPanStart?.(event);
+      }
+    };
+    const handlePanEnd = event => {
+      isInteracting = false;
+      handlersRef.current.onPanEnd?.(event);
+    };
+    const throttled = (0, _rafThrottle.rafThrottle)(() => {
+      const delta = {
+        x: accumulated.x,
+        y: accumulated.y
+      };
+      accumulated.x = 0;
+      accumulated.y = 0;
+      if (lastEvent) {
+        handlersRef.current.onPan(delta, lastEvent);
+      }
+    });
+    const handlePan = event => {
+      if (!isInteracting) {
+        return;
+      }
+      lastEvent = event;
+      accumulated.x += event.detail.deltaX;
+      accumulated.y += event.detail.deltaY;
+      throttled();
+    };
+    const panHandler = instance.addInteractionListener('zoomPressAndDrag', handlePan);
+    const panStartHandler = instance.addInteractionListener('zoomPressAndDragStart', handlePanStart);
+    const panEndHandler = instance.addInteractionListener('zoomPressAndDragEnd', handlePanEnd);
+    return () => {
+      panHandler.cleanup();
+      panStartHandler.cleanup();
+      panEndHandler.cleanup();
+      throttled.clear();
+    };
+  }, [instance, chartsLayerContainerRef, enabled]);
+}

package/internals/plugins/zoomGestures/useDragOnPressGesture.mjs

@@ -0,0 +1,99 @@
+'use client';
+
+import * as React from 'react';
+import { rafThrottle } from '@mui/x-internals/rafThrottle';
+/**
+ * Generic press-and-drag-to-pan gesture binding.
+ *
+ * It owns the listener lifecycle, and lets you create your own interactions by providing the delta change of the interaction.
+ */
+export function useDragOnPressGesture(instance, options) {
+  const {
+    enabled,
+    config,
+    onPanStart,
+    onPan,
+    onPanEnd
+  } = options;
+  const {
+    chartsLayerContainerRef
+  } = instance;
+
+  // Keep the latest handlers in a ref so changing them doesn't rebind listeners.
+  const handlersRef = React.useRef({
+    onPanStart,
+    onPan,
+    onPanEnd
+  });
+  React.useEffect(() => {
+    handlersRef.current = {
+      onPanStart,
+      onPan,
+      onPanEnd
+    };
+  });
+  React.useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+    instance.updateZoomInteractionListeners('zoomPressAndDrag', {
+      requiredKeys: config?.requiredKeys,
+      pointerMode: config?.pointerMode,
+      pointerOptions: {
+        mouse: config?.mouse,
+        touch: config?.touch
+      }
+    });
+  }, [enabled, config, instance]);
+  React.useEffect(() => {
+    const element = chartsLayerContainerRef.current;
+    if (element === null || !enabled) {
+      return () => {};
+    }
+    let isInteracting = false;
+    let lastEvent = null;
+    const accumulated = {
+      x: 0,
+      y: 0
+    };
+    const handlePanStart = event => {
+      if (!event.detail.target?.closest('[data-charts-zoom-slider]')) {
+        isInteracting = true;
+        handlersRef.current.onPanStart?.(event);
+      }
+    };
+    const handlePanEnd = event => {
+      isInteracting = false;
+      handlersRef.current.onPanEnd?.(event);
+    };
+    const throttled = rafThrottle(() => {
+      const delta = {
+        x: accumulated.x,
+        y: accumulated.y
+      };
+      accumulated.x = 0;
+      accumulated.y = 0;
+      if (lastEvent) {
+        handlersRef.current.onPan(delta, lastEvent);
+      }
+    });
+    const handlePan = event => {
+      if (!isInteracting) {
+        return;
+      }
+      lastEvent = event;
+      accumulated.x += event.detail.deltaX;
+      accumulated.y += event.detail.deltaY;
+      throttled();
+    };
+    const panHandler = instance.addInteractionListener('zoomPressAndDrag', handlePan);
+    const panStartHandler = instance.addInteractionListener('zoomPressAndDragStart', handlePanStart);
+    const panEndHandler = instance.addInteractionListener('zoomPressAndDragEnd', handlePanEnd);
+    return () => {
+      panHandler.cleanup();
+      panStartHandler.cleanup();
+      panEndHandler.cleanup();
+      throttled.clear();
+    };
+  }, [instance, chartsLayerContainerRef, enabled]);
+}

package/internals/plugins/zoomGestures/usePinchGesture.d.mts

@@ -0,0 +1,22 @@
+import type { KeyboardKey } from '@mui/x-internal-gestures/core';
+import type { ChartPoint, GestureInstance } from "./zoomGestures.types.mjs";
+export interface UsePinchGestureOptions {
+  /** Whether the gesture is active. */
+  enabled: boolean;
+  /** Keys that must be held for the pinch to trigger the gesture. */
+  requiredKeys?: KeyboardKey[];
+  /**
+   * Called (rAF-throttled) on each pinch update.
+   *
+   * @param {ChartPoint} point The pinch centroid, in SVG coordinates.
+   * @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.
+ *
+ * It owns the listener lifecycle, and lets you create your own interactions from the centroid and scale delta it forwards to `onPinch`.
+ */
+export declare function usePinchGesture(instance: GestureInstance, options: UsePinchGestureOptions): void;

package/internals/plugins/zoomGestures/usePinchGesture.d.ts

@@ -0,0 +1,22 @@
+import type { KeyboardKey } from '@mui/x-internal-gestures/core';
+import type { ChartPoint, GestureInstance } from "./zoomGestures.types.js";
+export interface UsePinchGestureOptions {
+  /** Whether the gesture is active. */
+  enabled: boolean;
+  /** Keys that must be held for the pinch to trigger the gesture. */
+  requiredKeys?: KeyboardKey[];
+  /**
+   * Called (rAF-throttled) on each pinch update.
+   *
+   * @param {ChartPoint} point The pinch centroid, in SVG coordinates.
+   * @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.
+ *
+ * It owns the listener lifecycle, and lets you create your own interactions from the centroid and scale delta it forwards to `onPinch`.
+ */
+export declare function usePinchGesture(instance: GestureInstance, options: UsePinchGestureOptions): void;

package/internals/plugins/zoomGestures/usePinchGesture.js

@@ -0,0 +1,77 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.usePinchGesture = usePinchGesture;
+var React = _interopRequireWildcard(require("react"));
+var _internals = require("@mui/x-charts/internals");
+var _rafThrottle = require("@mui/x-internals/rafThrottle");
+/**
+ * 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`.
+ */
+function usePinchGesture(instance, options) {
+  const {
+    enabled,
+    requiredKeys,
+    onPinch
+  } = options;
+  const {
+    chartsLayerContainerRef
+  } = instance;
+  const onPinchRef = React.useRef(onPinch);
+  React.useEffect(() => {
+    onPinchRef.current = onPinch;
+  });
+  React.useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+    instance.updateZoomInteractionListeners('zoomPinch', {
+      requiredKeys
+    });
+  }, [enabled, requiredKeys, instance]);
+  React.useEffect(() => {
+    const element = chartsLayerContainerRef.current;
+    if (element === null || !enabled) {
+      return () => {};
+    }
+    const latest = {
+      point: {
+        x: 0,
+        y: 0
+      },
+      deltaScale: 0,
+      direction: 0,
+      valid: false
+    };
+    const flush = (0, _rafThrottle.rafThrottle)(() => {
+      if (latest.valid) {
+        onPinchRef.current(latest.point, latest.deltaScale, latest.direction);
+        latest.valid = false;
+      }
+    });
+    const handler = instance.addInteractionListener('zoomPinch', event => {
+      // A direction of 0 means the pinch gesture is not yet meaningful.
+      if (event.detail.direction === 0) {
+        return;
+      }
+      latest.point = (0, _internals.getChartPoint)(element, {
+        clientX: event.detail.centroid.x,
+        clientY: event.detail.centroid.y
+      });
+      latest.deltaScale = event.detail.deltaScale;
+      latest.direction = event.detail.direction;
+      latest.valid = true;
+      flush();
+    });
+    return () => {
+      handler.cleanup();
+      flush.clear();
+    };
+  }, [chartsLayerContainerRef, enabled, instance]);
+}

package/internals/plugins/zoomGestures/usePinchGesture.mjs

@@ -0,0 +1,71 @@
+'use client';
+
+import * as React from 'react';
+import { getChartPoint } from '@mui/x-charts/internals';
+import { rafThrottle } from '@mui/x-internals/rafThrottle';
+/**
+ * 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, options) {
+  const {
+    enabled,
+    requiredKeys,
+    onPinch
+  } = options;
+  const {
+    chartsLayerContainerRef
+  } = instance;
+  const onPinchRef = React.useRef(onPinch);
+  React.useEffect(() => {
+    onPinchRef.current = onPinch;
+  });
+  React.useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+    instance.updateZoomInteractionListeners('zoomPinch', {
+      requiredKeys
+    });
+  }, [enabled, requiredKeys, instance]);
+  React.useEffect(() => {
+    const element = chartsLayerContainerRef.current;
+    if (element === null || !enabled) {
+      return () => {};
+    }
+    const latest = {
+      point: {
+        x: 0,
+        y: 0
+      },
+      deltaScale: 0,
+      direction: 0,
+      valid: false
+    };
+    const flush = rafThrottle(() => {
+      if (latest.valid) {
+        onPinchRef.current(latest.point, latest.deltaScale, latest.direction);
+        latest.valid = false;
+      }
+    });
+    const handler = instance.addInteractionListener('zoomPinch', event => {
+      // A direction of 0 means the pinch gesture is not yet meaningful.
+      if (event.detail.direction === 0) {
+        return;
+      }
+      latest.point = getChartPoint(element, {
+        clientX: event.detail.centroid.x,
+        clientY: event.detail.centroid.y
+      });
+      latest.deltaScale = event.detail.deltaScale;
+      latest.direction = event.detail.direction;
+      latest.valid = true;
+      flush();
+    });
+    return () => {
+      handler.cleanup();
+      flush.clear();
+    };
+  }, [chartsLayerContainerRef, enabled, instance]);
+}

package/internals/plugins/zoomGestures/useWheelGesture.d.mts

@@ -0,0 +1,21 @@
+import { type KeyboardKey } from '@mui/x-internal-gestures/core';
+import { type ChartPoint, type GestureInstance } from "./zoomGestures.types.mjs";
+export interface UseWheelGestureOptions {
+  /** Whether the gesture is active. */
+  enabled: boolean;
+  /** Keys that must be held for the wheel to trigger the gesture. */
+  requiredKeys?: KeyboardKey[];
+  /**
+   * Called on each wheel tick inside the drawing area.
+   *
+   * @param {ChartPoint} point The wheel focal point, in SVG coordinates.
+   * @param {WheelEvent} event The `WheelEvent`.
+   */
+  onWheel: (point: ChartPoint, event: WheelEvent) => void;
+}
+/**
+ * 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 declare function useWheelGesture(instance: GestureInstance, options: UseWheelGestureOptions): void;

package/internals/plugins/zoomGestures/useWheelGesture.d.ts

@@ -0,0 +1,21 @@
+import { type KeyboardKey } from '@mui/x-internal-gestures/core';
+import { type ChartPoint, type GestureInstance } from "./zoomGestures.types.js";
+export interface UseWheelGestureOptions {
+  /** Whether the gesture is active. */
+  enabled: boolean;
+  /** Keys that must be held for the wheel to trigger the gesture. */
+  requiredKeys?: KeyboardKey[];
+  /**
+   * Called on each wheel tick inside the drawing area.
+   *
+   * @param {ChartPoint} point The wheel focal point, in SVG coordinates.
+   * @param {WheelEvent} event The `WheelEvent`.
+   */
+  onWheel: (point: ChartPoint, event: WheelEvent) => void;
+}
+/**
+ * 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 declare function useWheelGesture(instance: GestureInstance, options: UseWheelGestureOptions): void;

package/internals/plugins/zoomGestures/useWheelGesture.js

@@ -0,0 +1,78 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useWheelGesture = useWheelGesture;
+var React = _interopRequireWildcard(require("react"));
+var _rafThrottle = require("@mui/x-internals/rafThrottle");
+var _internals = require("@mui/x-charts/internals");
+/**
+ * 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`.
+ */
+function useWheelGesture(instance, options) {
+  const {
+    enabled,
+    requiredKeys,
+    onWheel
+  } = options;
+  const {
+    chartsLayerContainerRef
+  } = instance;
+  const startedOutsideRef = React.useRef(false);
+  const startedOutsideTimeoutRef = React.useRef(null);
+  const onWheelRef = React.useRef(onWheel);
+  React.useEffect(() => {
+    onWheelRef.current = onWheel;
+  });
+  React.useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+    instance.updateZoomInteractionListeners('zoomTurnWheel', {
+      requiredKeys
+    });
+  }, [enabled, requiredKeys, instance]);
+  React.useEffect(() => {
+    const element = chartsLayerContainerRef.current;
+    if (element === null || !enabled) {
+      return () => {};
+    }
+    const rafThrottledOnWheel = (0, _rafThrottle.rafThrottle)(onWheelRef.current);
+    const handler = instance.addInteractionListener('zoomTurnWheel', event => {
+      const point = (0, _internals.getChartPoint)(element, {
+        clientX: event.detail.centroid.x,
+        clientY: event.detail.centroid.y
+      });
+
+      // Ignore wheel events that started outside the chart area (e.g. while page-scrolling
+      // over the chart). The timeout debounces re-entry caused by the scroll itself.
+      if (startedOutsideRef.current || !instance.isPointInside(point.x, point.y)) {
+        startedOutsideRef.current = true;
+        if (startedOutsideTimeoutRef.current) {
+          clearTimeout(startedOutsideTimeoutRef.current);
+        }
+        startedOutsideTimeoutRef.current = setTimeout(() => {
+          startedOutsideRef.current = false;
+          startedOutsideTimeoutRef.current = null;
+        }, 100);
+        return;
+      }
+      event.detail.srcEvent.preventDefault();
+      rafThrottledOnWheel(point, event.detail.srcEvent);
+    });
+    return () => {
+      handler.cleanup();
+      if (startedOutsideTimeoutRef.current) {
+        clearTimeout(startedOutsideTimeoutRef.current);
+        startedOutsideTimeoutRef.current = null;
+      }
+      startedOutsideRef.current = false;
+      rafThrottledOnWheel.clear();
+    };
+  }, [chartsLayerContainerRef, enabled, instance]);
+}