@mui/x-charts-pro 9.3.0 → 9.5.0

package/internals/plugins/useChartProZoom/useChartProZoom.types.d.ts

@@ -1,11 +1,38 @@
 import { type UseChartSeriesSignature, type ChartPluginSignature, type UseChartCartesianAxisSignature, type UseChartCartesianAxisDefaultizedParameters, type ZoomData, type AxisId, type UseChartBrushSignature } from '@mui/x-charts/internals';
 import { type ZoomInteractionConfig, type DefaultizedZoomInteractionConfig } from "./ZoomInteractionConfig.types.js";
+import { type RangeButtonValue } from "../../../ChartsToolbarPro/rangeButtonValueToZoom.js";
+/**
+ * Initializes the zoom of an axis with a range value instead of zoom percentages.
+ */
+export interface InitialZoomRange {
+  /**
+   * The id of the axis to apply the zoom to.
+   */
+  axisId: AxisId;
+  /**
+   * The range to zoom to. Accepts the same values as a range button:
+   *
+   * - `{ unit, step }` — A calendar interval from the end of the data.
+   * - `[start, end]` — An absolute date range, or a range between two ordinal axis values.
+   * - `(params) => { start, end }` — A function returning zoom percentages (0-100).
+   * - `null` — Shows all data.
+   */
+  value: RangeButtonValue;
+}
+/**
+ * An entry of the `initialZoom` prop. Either explicit zoom percentages ({@link ZoomData})
+ * or a range value resolved against the axis ({@link InitialZoomRange}).
+ */
+export type InitialZoom = ZoomData | InitialZoomRange;
 export interface UseChartProZoomParameters {
   /**
    * The list of zoom data related to each axis.
    * Used to initialize the zoom in a specific configuration without controlling it.
+   *
+   * Each entry is either explicit zoom percentages (`{ axisId, start, end }`) or a
+   * range value (`{ axisId, value }`) resolved against the axis domain.
    */
-  initialZoom?: readonly ZoomData[];
+  initialZoom?: readonly InitialZoom[];
   /**
    * Callback fired when the zoom has changed.
    *
@@ -41,11 +68,6 @@ export interface UseChartProZoomState {
      * Configuration for zoom interactions.
      */
     zoomInteractionConfig: DefaultizedZoomInteractionConfig;
-    /**
-     * The key of the currently active range button, or `null` if no range button is active.
-     * Cleared when the user manually zooms or pans the chart.
-     */
-    activeRangeButtonKey: string | null;
   };
 }
 export interface UseChartProZoomPublicApi {
@@ -78,11 +100,6 @@ export interface UseChartProZoomInstance extends UseChartProZoomPublicApi {
    * Zoom out the chart.
    */
   zoomOut: () => void;
-  /**
-   * Set the active range button key. Pass `null` to clear.
-   * @param {string | null} key The key of the active range button.
-   */
-  setActiveRangeButtonKey: (key: string | null) => void;
 }
 export type UseChartProZoomSignature = ChartPluginSignature<{
   params: UseChartProZoomParameters;

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

@@ -0,0 +1,5 @@
+export { useDragGesture, type UseDragGestureOptions } from "./useDragGesture.mjs";
+export { useDragOnPressGesture, type UseDragOnPressGestureOptions } from "./useDragOnPressGesture.mjs";
+export { useWheelGesture, type UseWheelGestureOptions } from "./useWheelGesture.mjs";
+export { usePinchGesture, type UsePinchGestureOptions } from "./usePinchGesture.mjs";
+export type { GestureInstance, PanGestureConfig, ChartPoint } from "./zoomGestures.types.mjs";

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

@@ -0,0 +1,5 @@
+export { useDragGesture, type UseDragGestureOptions } from "./useDragGesture.js";
+export { useDragOnPressGesture, type UseDragOnPressGestureOptions } from "./useDragOnPressGesture.js";
+export { useWheelGesture, type UseWheelGestureOptions } from "./useWheelGesture.js";
+export { usePinchGesture, type UsePinchGestureOptions } from "./usePinchGesture.js";
+export type { GestureInstance, PanGestureConfig, ChartPoint } from "./zoomGestures.types.js";

package/internals/plugins/zoomGestures/index.js

@@ -0,0 +1,33 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "useDragGesture", {
+  enumerable: true,
+  get: function () {
+    return _useDragGesture.useDragGesture;
+  }
+});
+Object.defineProperty(exports, "useDragOnPressGesture", {
+  enumerable: true,
+  get: function () {
+    return _useDragOnPressGesture.useDragOnPressGesture;
+  }
+});
+Object.defineProperty(exports, "usePinchGesture", {
+  enumerable: true,
+  get: function () {
+    return _usePinchGesture.usePinchGesture;
+  }
+});
+Object.defineProperty(exports, "useWheelGesture", {
+  enumerable: true,
+  get: function () {
+    return _useWheelGesture.useWheelGesture;
+  }
+});
+var _useDragGesture = require("./useDragGesture");
+var _useDragOnPressGesture = require("./useDragOnPressGesture");
+var _useWheelGesture = require("./useWheelGesture");
+var _usePinchGesture = require("./usePinchGesture");

package/internals/plugins/zoomGestures/index.mjs

@@ -0,0 +1,4 @@
+export { useDragGesture } from "./useDragGesture.mjs";
+export { useDragOnPressGesture } from "./useDragOnPressGesture.mjs";
+export { useWheelGesture } from "./useWheelGesture.mjs";
+export { usePinchGesture } from "./usePinchGesture.mjs";

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

@@ -0,0 +1,30 @@
+import { type PanEvent } from '@mui/x-internal-gestures/core';
+import { type ChartPoint, type GestureInstance, type PanGestureConfig } from "./zoomGestures.types.mjs";
+export interface UseDragGestureOptions {
+  /** 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 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 useDragGesture(instance: GestureInstance, options: UseDragGestureOptions): void;

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

@@ -0,0 +1,30 @@
+import { type PanEvent } from '@mui/x-internal-gestures/core';
+import { type ChartPoint, type GestureInstance, type PanGestureConfig } from "./zoomGestures.types.js";
+export interface UseDragGestureOptions {
+  /** 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 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 useDragGesture(instance: GestureInstance, options: UseDragGestureOptions): void;

package/internals/plugins/zoomGestures/useDragGesture.js

@@ -0,0 +1,105 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useDragGesture = useDragGesture;
+var React = _interopRequireWildcard(require("react"));
+var _rafThrottle = require("@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.
+ */
+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 = (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('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/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;