@mui/x-charts-pro 9.7.0 → 9.9.0

package/internals/ChartsWatermark.d.mts

@@ -1,6 +1,7 @@
+import * as React from 'react';
 import type { CommercialPackageInfo } from '@mui/x-license/internals';
 interface ChartsWatermarkProps {
   packageInfo: CommercialPackageInfo;
 }
-export declare function ChartsWatermark(props: ChartsWatermarkProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartsWatermark(props: ChartsWatermarkProps): React.JSX.Element;
 export {};

package/internals/ChartsWatermark.d.ts

@@ -1,6 +1,7 @@
+import * as React from 'react';
 import type { CommercialPackageInfo } from '@mui/x-license/internals';
 interface ChartsWatermarkProps {
   packageInfo: CommercialPackageInfo;
 }
-export declare function ChartsWatermark(props: ChartsWatermarkProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartsWatermark(props: ChartsWatermarkProps): React.JSX.Element;
 export {};

package/internals/index.d.mts

@@ -3,6 +3,8 @@ export type { UseChartsContainerProPropsReturnValue } from "../ChartsContainerPr
 export type { ChartsSlotsPro, ChartsSlotPropsPro } from "./material/index.mjs";
 export { seriesPreviewPlotMap } from "../ChartsZoomSlider/internals/seriesPreviewPlotMap.mjs";
 export type { PreviewPlotProps } from "../ChartsZoomSlider/internals/previews/PreviewPlot.types.mjs";
+export { useDragGesture, useWheelGesture, usePinchGesture, type UseDragGestureOptions, type UseWheelGestureOptions, type UsePinchGestureOptions, type GestureInstance, type PanGestureConfig } from "./plugins/zoomGestures/index.mjs";
+export { useRegisterZoomGestures } from "./plugins/useChartProZoom/gestureHooks/useRegisterZoomGestures.mjs";
 export { defaultSeriesConfigPro } from "../ChartsDataProviderPro/ChartsDataProviderPro.mjs";
 export type { ProPluginsPerSeriesType } from "../context/ChartProApi.mjs";
 export { useHeatmapProps } from "../Heatmap/useHeatmapProps.mjs";

package/internals/index.d.ts

@@ -3,6 +3,8 @@ export type { UseChartsContainerProPropsReturnValue } from "../ChartsContainerPr
 export type { ChartsSlotsPro, ChartsSlotPropsPro } from "./material/index.js";
 export { seriesPreviewPlotMap } from "../ChartsZoomSlider/internals/seriesPreviewPlotMap.js";
 export type { PreviewPlotProps } from "../ChartsZoomSlider/internals/previews/PreviewPlot.types.js";
+export { useDragGesture, useWheelGesture, usePinchGesture, type UseDragGestureOptions, type UseWheelGestureOptions, type UsePinchGestureOptions, type GestureInstance, type PanGestureConfig } from "./plugins/zoomGestures/index.js";
+export { useRegisterZoomGestures } from "./plugins/useChartProZoom/gestureHooks/useRegisterZoomGestures.js";
 export { defaultSeriesConfigPro } from "../ChartsDataProviderPro/ChartsDataProviderPro.js";
 export type { ProPluginsPerSeriesType } from "../context/ChartProApi.js";
 export { useHeatmapProps } from "../Heatmap/useHeatmapProps.js";

package/internals/index.js

@@ -6,6 +6,10 @@ Object.defineProperty(exports, "__esModule", {
 var _exportNames = {
   useChartsContainerProProps: true,
   seriesPreviewPlotMap: true,
+  useDragGesture: true,
+  useWheelGesture: true,
+  usePinchGesture: true,
+  useRegisterZoomGestures: true,
   defaultSeriesConfigPro: true,
   useHeatmapProps: true,
   defaultSlotsMaterial: true,
@@ -41,14 +45,40 @@ Object.defineProperty(exports, "useChartsContainerProProps", {
     return _useChartsContainerProProps.useChartsContainerProProps;
   }
 });
+Object.defineProperty(exports, "useDragGesture", {
+  enumerable: true,
+  get: function () {
+    return _zoomGestures.useDragGesture;
+  }
+});
 Object.defineProperty(exports, "useHeatmapProps", {
   enumerable: true,
   get: function () {
     return _useHeatmapProps.useHeatmapProps;
   }
 });
+Object.defineProperty(exports, "usePinchGesture", {
+  enumerable: true,
+  get: function () {
+    return _zoomGestures.usePinchGesture;
+  }
+});
+Object.defineProperty(exports, "useRegisterZoomGestures", {
+  enumerable: true,
+  get: function () {
+    return _useRegisterZoomGestures.useRegisterZoomGestures;
+  }
+});
+Object.defineProperty(exports, "useWheelGesture", {
+  enumerable: true,
+  get: function () {
+    return _zoomGestures.useWheelGesture;
+  }
+});
 var _useChartsContainerProProps = require("../ChartsContainerPro/useChartsContainerProProps");
 var _seriesPreviewPlotMap = require("../ChartsZoomSlider/internals/seriesPreviewPlotMap");
+var _zoomGestures = require("./plugins/zoomGestures");
+var _useRegisterZoomGestures = require("./plugins/useChartProZoom/gestureHooks/useRegisterZoomGestures");
 var _ChartsDataProviderPro = require("../ChartsDataProviderPro/ChartsDataProviderPro");
 var _useHeatmapProps = require("../Heatmap/useHeatmapProps");
 var _material = require("./material");

package/internals/index.mjs

@@ -1,5 +1,7 @@
 export { useChartsContainerProProps } from "../ChartsContainerPro/useChartsContainerProProps.mjs";
 export { seriesPreviewPlotMap } from "../ChartsZoomSlider/internals/seriesPreviewPlotMap.mjs";
+export { useDragGesture, useWheelGesture, usePinchGesture } from "./plugins/zoomGestures/index.mjs";
+export { useRegisterZoomGestures } from "./plugins/useChartProZoom/gestureHooks/useRegisterZoomGestures.mjs";
 export { defaultSeriesConfigPro } from "../ChartsDataProviderPro/ChartsDataProviderPro.mjs";
 export { useHeatmapProps } from "../Heatmap/useHeatmapProps.mjs";
 export { defaultSlotsMaterial } from "./material/index.mjs";

package/internals/material/components/BaseMenuItem.d.mts

@@ -1,2 +1,2 @@
 import type { ChartBaseMenuItemProps } from "../../slots/chartBaseSlotProps.mjs";
-export declare function BaseMenuItem(props: ChartBaseMenuItemProps): import("react/jsx-runtime").JSX.Element;
+export declare function BaseMenuItem(props: ChartBaseMenuItemProps): import("react").JSX.Element;

package/internals/material/components/BaseMenuItem.d.ts

@@ -1,2 +1,2 @@
 import type { ChartBaseMenuItemProps } from "../../slots/chartBaseSlotProps.js";
-export declare function BaseMenuItem(props: ChartBaseMenuItemProps): import("react/jsx-runtime").JSX.Element;
+export declare function BaseMenuItem(props: ChartBaseMenuItemProps): import("react").JSX.Element;

package/internals/material/components/BasePopper.d.mts

@@ -1,2 +1,3 @@
+import * as React from 'react';
 import type { ChartBasePopperProps } from "../../slots/chartBaseSlotProps.mjs";
-export declare function BasePopper(props: ChartBasePopperProps): import("react/jsx-runtime").JSX.Element;
+export declare function BasePopper(props: ChartBasePopperProps): React.JSX.Element;

package/internals/material/components/BasePopper.d.ts

@@ -1,2 +1,3 @@
+import * as React from 'react';
 import type { ChartBasePopperProps } from "../../slots/chartBaseSlotProps.js";
-export declare function BasePopper(props: ChartBasePopperProps): import("react/jsx-runtime").JSX.Element;
+export declare function BasePopper(props: ChartBasePopperProps): React.JSX.Element;

package/internals/plugins/useChartProSampling/barSampler.d.mts

@@ -0,0 +1,8 @@
+import type { SamplingStrategy } from '@mui/x-charts/internals';
+import type { SamplingPyramid } from "./sampling.pyramid.types.mjs";
+/**
+ * Min/max LOD pyramid over the bar's stacked envelope. Uses `min(base, top)`/`max(base, top)` per
+ * point rather than base/top directly, so diverging/negative bars (where the stack emits `[0, -5]`,
+ * i.e. base > top) keep their full extent instead of being truncated.
+ */
+export declare const barSampler: SamplingStrategy<'bar', SamplingPyramid>;

package/internals/plugins/useChartProSampling/barSampler.d.ts

@@ -0,0 +1,8 @@
+import type { SamplingStrategy } from '@mui/x-charts/internals';
+import type { SamplingPyramid } from "./sampling.pyramid.types.js";
+/**
+ * Min/max LOD pyramid over the bar's stacked envelope. Uses `min(base, top)`/`max(base, top)` per
+ * point rather than base/top directly, so diverging/negative bars (where the stack emits `[0, -5]`,
+ * i.e. base > top) keep their full extent instead of being truncated.
+ */
+export declare const barSampler: SamplingStrategy<'bar', SamplingPyramid>;

package/internals/plugins/useChartProSampling/barSampler.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.barSampler = void 0;
+var _sampling = require("./sampling");
+var _sampling2 = require("./sampling.line");
+/**
+ * Min/max LOD pyramid over the bar's stacked envelope. Uses `min(base, top)`/`max(base, top)` per
+ * point rather than base/top directly, so diverging/negative bars (where the stack emits `[0, -5]`,
+ * i.e. base > top) keep their full extent instead of being truncated.
+ */
+const barSampler = exports.barSampler = {
+  build: series => (0, _sampling.buildSamplingPyramid)(Float64Array.from(series.visibleStackedData, point => Math.min(point[0], point[1])), Float64Array.from(series.visibleStackedData, point => Math.max(point[0], point[1]))),
+  sample: _sampling2.sample,
+  bucketSizeAt: (span, context) => (0, _sampling.getSamplingBucketSize)(span, context.dataLength, context.availableSize, context.minSpan)
+};

package/internals/plugins/useChartProSampling/barSampler.mjs

@@ -0,0 +1,12 @@
+import { buildSamplingPyramid, getSamplingBucketSize } from "./sampling.mjs";
+import { sample } from "./sampling.line.mjs";
+/**
+ * Min/max LOD pyramid over the bar's stacked envelope. Uses `min(base, top)`/`max(base, top)` per
+ * point rather than base/top directly, so diverging/negative bars (where the stack emits `[0, -5]`,
+ * i.e. base > top) keep their full extent instead of being truncated.
+ */
+export const barSampler = {
+  build: series => buildSamplingPyramid(Float64Array.from(series.visibleStackedData, point => Math.min(point[0], point[1])), Float64Array.from(series.visibleStackedData, point => Math.max(point[0], point[1]))),
+  sample,
+  bucketSizeAt: (span, context) => getSamplingBucketSize(span, context.dataLength, context.availableSize, context.minSpan)
+};

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

@@ -0,0 +1,2 @@
+export { useChartProSampling } from "./useChartProSampling.mjs";
+export type * from "./useChartProSampling.types.mjs";

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

@@ -0,0 +1,2 @@
+export { useChartProSampling } from "./useChartProSampling.js";
+export type * from "./useChartProSampling.types.js";

package/internals/plugins/useChartProSampling/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "useChartProSampling", {
+  enumerable: true,
+  get: function () {
+    return _useChartProSampling.useChartProSampling;
+  }
+});
+var _useChartProSampling = require("./useChartProSampling");

package/internals/plugins/useChartProSampling/index.mjs

@@ -0,0 +1 @@
+export { useChartProSampling } from "./useChartProSampling.mjs";

package/internals/plugins/useChartProSampling/lineSampler.d.mts

@@ -0,0 +1,8 @@
+import type { SamplingStrategy } from '@mui/x-charts/internals';
+import type { SamplingPyramid } from "./sampling.pyramid.types.mjs";
+/**
+ * Min/max LOD pyramid over the line's y values (single channel when null-free). Nulls get `+Inf`
+ * low / `-Inf` high so they never win an extremum, and go into `nullIndices` for the sampler to
+ * re-insert as line breaks.
+ */
+export declare const lineSampler: SamplingStrategy<'line', SamplingPyramid>;

package/internals/plugins/useChartProSampling/lineSampler.d.ts

@@ -0,0 +1,8 @@
+import type { SamplingStrategy } from '@mui/x-charts/internals';
+import type { SamplingPyramid } from "./sampling.pyramid.types.js";
+/**
+ * Min/max LOD pyramid over the line's y values (single channel when null-free). Nulls get `+Inf`
+ * low / `-Inf` high so they never win an extremum, and go into `nullIndices` for the sampler to
+ * re-insert as line breaks.
+ */
+export declare const lineSampler: SamplingStrategy<'line', SamplingPyramid>;

package/internals/plugins/useChartProSampling/lineSampler.js

@@ -0,0 +1,47 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.lineSampler = void 0;
+var _sampling = require("./sampling");
+var _sampling2 = require("./sampling.line");
+/**
+ * Min/max LOD pyramid over the line's y values (single channel when null-free). Nulls get `+Inf`
+ * low / `-Inf` high so they never win an extremum, and go into `nullIndices` for the sampler to
+ * re-insert as line breaks.
+ */
+const lineSampler = exports.lineSampler = {
+  build: series => {
+    const {
+      data,
+      visibleStackedData
+    } = series;
+    const length = visibleStackedData.length;
+    const values = new Float64Array(length);
+    let nullIndices = null;
+    for (let i = 0; i < length; i += 1) {
+      if (data[i] == null) {
+        (nullIndices ?? (nullIndices = [])).push(i);
+      } else {
+        values[i] = visibleStackedData[i][1];
+      }
+    }
+    if (!nullIndices) {
+      return (0, _sampling.buildSamplingPyramid)(values, values);
+    }
+
+    // Two channels only when gaps exist: nulls lose both extrema comparisons.
+    const low = values;
+    const high = Float64Array.from(values);
+    for (let i = 0; i < nullIndices.length; i += 1) {
+      low[nullIndices[i]] = Infinity;
+      high[nullIndices[i]] = -Infinity;
+    }
+    const pyramid = (0, _sampling.buildSamplingPyramid)(low, high);
+    pyramid.nullIndices = Int32Array.from(nullIndices);
+    return pyramid;
+  },
+  sample: _sampling2.sample,
+  bucketSizeAt: (span, context) => (0, _sampling.getSamplingBucketSize)(span, context.dataLength, context.availableSize, context.minSpan)
+};

package/internals/plugins/useChartProSampling/lineSampler.mjs

@@ -0,0 +1,41 @@
+import { buildSamplingPyramid, getSamplingBucketSize } from "./sampling.mjs";
+import { sample } from "./sampling.line.mjs";
+/**
+ * Min/max LOD pyramid over the line's y values (single channel when null-free). Nulls get `+Inf`
+ * low / `-Inf` high so they never win an extremum, and go into `nullIndices` for the sampler to
+ * re-insert as line breaks.
+ */
+export const lineSampler = {
+  build: series => {
+    const {
+      data,
+      visibleStackedData
+    } = series;
+    const length = visibleStackedData.length;
+    const values = new Float64Array(length);
+    let nullIndices = null;
+    for (let i = 0; i < length; i += 1) {
+      if (data[i] == null) {
+        (nullIndices ??= []).push(i);
+      } else {
+        values[i] = visibleStackedData[i][1];
+      }
+    }
+    if (!nullIndices) {
+      return buildSamplingPyramid(values, values);
+    }
+
+    // Two channels only when gaps exist: nulls lose both extrema comparisons.
+    const low = values;
+    const high = Float64Array.from(values);
+    for (let i = 0; i < nullIndices.length; i += 1) {
+      low[nullIndices[i]] = Infinity;
+      high[nullIndices[i]] = -Infinity;
+    }
+    const pyramid = buildSamplingPyramid(low, high);
+    pyramid.nullIndices = Int32Array.from(nullIndices);
+    return pyramid;
+  },
+  sample,
+  bucketSizeAt: (span, context) => getSamplingBucketSize(span, context.dataLength, context.availableSize, context.minSpan)
+};

package/internals/plugins/useChartProSampling/sampling.d.mts

@@ -0,0 +1,38 @@
+import type { ActiveSamplingLevel, SamplingPyramid } from "./sampling.pyramid.types.mjs";
+/** Smallest element size (px) allowed before sampling kicks in. */
+export declare const MIN_ELEMENT_SIZE_PX = 6;
+/**
+ * Min zoom span (%) at which the data fills the view with `MIN_ELEMENT_SIZE_PX`-wide elements.
+ * Screen-derived, so elements never get thinner and the level count adapts to screen + data.
+ */
+export declare function getSamplingMinSpan(dataLength: number, availableSizePx: number): number;
+/**
+ * Hard ceiling on rendered elements, independent of zoom. Even at the deepest zoom (where elements
+ * would be wide enough to skip screen sampling), a view with more than this many points is still
+ * sampled enough levels to get under the cap — too many elements hurts performance whatever the size.
+ */
+export declare const MAX_RENDERED_POINTS = 2000;
+/**
+ * Builds the LOD pyramid for one series from its low/high value channels (for bars: the stacked
+ * `[base, top]` channels; for lines: the displayed `y` for both). Each bucket keeps the original
+ * index of its min (over `low`) and max (over `high`) — a min/max envelope, so spikes and troughs
+ * survive. Consumers read the values back from their own series data by index.
+ *
+ * Stored flat: all levels concatenated into `argMin`/`argMax`, with `offsets` marking level
+ * boundaries. Level 0 (no merge) is implicit; bucket indices are derived (`j * bucketSize`).
+ */
+export declare function buildSamplingPyramid(low: ArrayLike<number>, high: ArrayLike<number>): SamplingPyramid;
+/** Number of stored levels (finest `bucketSize 2` to coarsest). */
+export declare function getSamplingLevelCount(pyramid: SamplingPyramid): number;
+/**
+ * Picks the active level from the zoom span: level 0 (deepest zoom, `span <= minSpan`, or elements
+ * still wide enough) → no sampling (`null`, raw 1:1); each level up → bucket size ×2, chosen so
+ * sampled elements stay at least `MIN_ELEMENT_SIZE_PX` wide. Clamped to the pyramid depth.
+ * `bucketSize === 2 ** clampedLevel`, level buckets `offsets[clampedLevel - 1 .. clampedLevel]`.
+ */
+export declare function selectSamplingLevel(pyramid: SamplingPyramid, currentSpan: number, availableSizePx: number, minSpan: number): ActiveSamplingLevel | null;
+/**
+ * Active bucket size (`1` = no sampling) for an axis with no built pyramid (the axis highlight).
+ * Matches `selectSamplingLevel`'s `bucketSize`, derived from `dataLength` + screen + `minSpan`.
+ */
+export declare function getSamplingBucketSize(currentSpan: number, dataLength: number, availableSizePx: number, minSpan: number): number;

package/internals/plugins/useChartProSampling/sampling.d.ts

@@ -0,0 +1,38 @@
+import type { ActiveSamplingLevel, SamplingPyramid } from "./sampling.pyramid.types.js";
+/** Smallest element size (px) allowed before sampling kicks in. */
+export declare const MIN_ELEMENT_SIZE_PX = 6;
+/**
+ * Min zoom span (%) at which the data fills the view with `MIN_ELEMENT_SIZE_PX`-wide elements.
+ * Screen-derived, so elements never get thinner and the level count adapts to screen + data.
+ */
+export declare function getSamplingMinSpan(dataLength: number, availableSizePx: number): number;
+/**
+ * Hard ceiling on rendered elements, independent of zoom. Even at the deepest zoom (where elements
+ * would be wide enough to skip screen sampling), a view with more than this many points is still
+ * sampled enough levels to get under the cap — too many elements hurts performance whatever the size.
+ */
+export declare const MAX_RENDERED_POINTS = 2000;
+/**
+ * Builds the LOD pyramid for one series from its low/high value channels (for bars: the stacked
+ * `[base, top]` channels; for lines: the displayed `y` for both). Each bucket keeps the original
+ * index of its min (over `low`) and max (over `high`) — a min/max envelope, so spikes and troughs
+ * survive. Consumers read the values back from their own series data by index.
+ *
+ * Stored flat: all levels concatenated into `argMin`/`argMax`, with `offsets` marking level
+ * boundaries. Level 0 (no merge) is implicit; bucket indices are derived (`j * bucketSize`).
+ */
+export declare function buildSamplingPyramid(low: ArrayLike<number>, high: ArrayLike<number>): SamplingPyramid;
+/** Number of stored levels (finest `bucketSize 2` to coarsest). */
+export declare function getSamplingLevelCount(pyramid: SamplingPyramid): number;
+/**
+ * Picks the active level from the zoom span: level 0 (deepest zoom, `span <= minSpan`, or elements
+ * still wide enough) → no sampling (`null`, raw 1:1); each level up → bucket size ×2, chosen so
+ * sampled elements stay at least `MIN_ELEMENT_SIZE_PX` wide. Clamped to the pyramid depth.
+ * `bucketSize === 2 ** clampedLevel`, level buckets `offsets[clampedLevel - 1 .. clampedLevel]`.
+ */
+export declare function selectSamplingLevel(pyramid: SamplingPyramid, currentSpan: number, availableSizePx: number, minSpan: number): ActiveSamplingLevel | null;
+/**
+ * Active bucket size (`1` = no sampling) for an axis with no built pyramid (the axis highlight).
+ * Matches `selectSamplingLevel`'s `bucketSize`, derived from `dataLength` + screen + `minSpan`.
+ */
+export declare function getSamplingBucketSize(currentSpan: number, dataLength: number, availableSizePx: number, minSpan: number): number;

package/internals/plugins/useChartProSampling/sampling.js

@@ -0,0 +1,175 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MIN_ELEMENT_SIZE_PX = exports.MAX_RENDERED_POINTS = void 0;
+exports.buildSamplingPyramid = buildSamplingPyramid;
+exports.getSamplingBucketSize = getSamplingBucketSize;
+exports.getSamplingLevelCount = getSamplingLevelCount;
+exports.getSamplingMinSpan = getSamplingMinSpan;
+exports.selectSamplingLevel = selectSamplingLevel;
+/** Smallest element size (px) allowed before sampling kicks in. */
+const MIN_ELEMENT_SIZE_PX = exports.MIN_ELEMENT_SIZE_PX = 6;
+
+/**
+ * Min zoom span (%) at which the data fills the view with `MIN_ELEMENT_SIZE_PX`-wide elements.
+ * Screen-derived, so elements never get thinner and the level count adapts to screen + data.
+ */
+function getSamplingMinSpan(dataLength, availableSizePx) {
+  return 100 * availableSizePx / (MIN_ELEMENT_SIZE_PX * dataLength);
+}
+const EMPTY_PYRAMID_OFFSETS = new Int32Array(1);
+
+/**
+ * Level 0 (raw) extends this factor above `minSpan` before the first sampled level kicks in — a
+ * half-octave of wiggle room so the deepest zoom stays unsampled without a knife-edge transition.
+ */
+const RAW_LEVEL_SPAN_FACTOR = Math.SQRT2;
+
+/**
+ * Hard ceiling on rendered elements, independent of zoom. Even at the deepest zoom (where elements
+ * would be wide enough to skip screen sampling), a view with more than this many points is still
+ * sampled enough levels to get under the cap — too many elements hurts performance whatever the size.
+ */
+const MAX_RENDERED_POINTS = exports.MAX_RENDERED_POINTS = 2000;
+
+/** Levels of sampling needed to bring `visiblePoints` under `MAX_RENDERED_POINTS` (0 if under). */
+function pointCapLevel(visiblePoints) {
+  return visiblePoints > MAX_RENDERED_POINTS ? Math.ceil(Math.log2(visiblePoints / MAX_RENDERED_POINTS)) : 0;
+}
+
+/**
+ * Builds the LOD pyramid for one series from its low/high value channels (for bars: the stacked
+ * `[base, top]` channels; for lines: the displayed `y` for both). Each bucket keeps the original
+ * index of its min (over `low`) and max (over `high`) — a min/max envelope, so spikes and troughs
+ * survive. Consumers read the values back from their own series data by index.
+ *
+ * Stored flat: all levels concatenated into `argMin`/`argMax`, with `offsets` marking level
+ * boundaries. Level 0 (no merge) is implicit; bucket indices are derived (`j * bucketSize`).
+ */
+function buildSamplingPyramid(low, high) {
+  const dataLength = low.length;
+  if (dataLength <= 1) {
+    return {
+      dataLength,
+      argMin: new Int32Array(0),
+      argMax: new Int32Array(0),
+      offsets: EMPTY_PYRAMID_OFFSETS
+    };
+  }
+  const levelCount = Math.ceil(Math.log2(dataLength));
+
+  // Level start offsets into the shared buffers; each level halves the previous count (round up).
+  const offsets = new Int32Array(levelCount + 1);
+  for (let levelIndex = 0, count = dataLength; levelIndex < levelCount; levelIndex += 1) {
+    count = Math.ceil(count / 2);
+    offsets[levelIndex + 1] = offsets[levelIndex] + count;
+  }
+  const argMin = new Int32Array(offsets[levelCount]);
+  const argMax = new Int32Array(offsets[levelCount]);
+
+  // Level 0 (bucketSize 2) merges adjacent raw points; the only level that scans raw data.
+  for (let j = 0, i = 0; i < dataLength; j += 1, i += 2) {
+    const next = i + 1;
+    let lo = i;
+    let hi = i;
+    if (next < dataLength) {
+      if (low[next] < low[i]) {
+        lo = next;
+      }
+      if (high[next] > high[i]) {
+        hi = next;
+      }
+    }
+    argMin[j] = lo;
+    argMax[j] = hi;
+  }
+
+  // Higher levels merge pairs of buckets from the level below (argMin/argMax are associative via
+  // value compare, so the result equals re-scanning raw data). n/2 + n/4 + ... → O(n) build.
+  for (let levelIndex = 1; levelIndex < levelCount; levelIndex += 1) {
+    const prevStart = offsets[levelIndex - 1];
+    const prevCount = offsets[levelIndex] - prevStart;
+    const start = offsets[levelIndex];
+    for (let i = 0, j = 0; i < prevCount; i += 2, j += 1) {
+      const a = prevStart + i;
+      const w = start + j;
+      if (i + 1 >= prevCount) {
+        argMin[w] = argMin[a];
+        argMax[w] = argMax[a];
+      } else {
+        const b = a + 1;
+        argMin[w] = low[argMin[a]] <= low[argMin[b]] ? argMin[a] : argMin[b];
+        argMax[w] = high[argMax[a]] >= high[argMax[b]] ? argMax[a] : argMax[b];
+      }
+    }
+  }
+  return {
+    dataLength,
+    argMin,
+    argMax,
+    offsets
+  };
+}
+
+/** Number of stored levels (finest `bucketSize 2` to coarsest). */
+function getSamplingLevelCount(pyramid) {
+  return pyramid.offsets.length - 1;
+}
+
+/**
+ * Level-of-detail index for the current zoom:
+ * - Level 0 (no sampling, raw) at the deepest zoom (`currentSpan <= minSpan * RAW_LEVEL_SPAN_FACTOR`),
+ *   whatever the bar size — fully zoomed in shows every point, up to `MAX_RENDERED_POINTS`.
+ * - Above that, the level is screen-defined: bucket size keeps elements at least
+ *   `MIN_ELEMENT_SIZE_PX` wide (+1 per span doubling past that pixel threshold).
+ * - The `MAX_RENDERED_POINTS` cap applies at every zoom: a view with too many points is always
+ *   sampled, even in the raw zone where the screen rule alone would render it untouched.
+ */
+function levelIndexFor(currentSpan, dataLength, availableSizePx, minSpan) {
+  if (!(currentSpan > 0)) {
+    return 0;
+  }
+  const capLevel = pointCapLevel(dataLength * Math.min(currentSpan, 100) / 100);
+  if (currentSpan <= minSpan * RAW_LEVEL_SPAN_FACTOR) {
+    return capLevel; // raw zone, but still bounded by the point cap
+  }
+  const screenMinSpan = getSamplingMinSpan(dataLength, availableSizePx);
+  if (!(screenMinSpan > 0)) {
+    return capLevel;
+  }
+  return Math.max(capLevel, Math.round(Math.log2(currentSpan / screenMinSpan)));
+}
+
+/**
+ * Picks the active level from the zoom span: level 0 (deepest zoom, `span <= minSpan`, or elements
+ * still wide enough) → no sampling (`null`, raw 1:1); each level up → bucket size ×2, chosen so
+ * sampled elements stay at least `MIN_ELEMENT_SIZE_PX` wide. Clamped to the pyramid depth.
+ * `bucketSize === 2 ** clampedLevel`, level buckets `offsets[clampedLevel - 1 .. clampedLevel]`.
+ */
+function selectSamplingLevel(pyramid, currentSpan, availableSizePx, minSpan) {
+  const levelCount = pyramid.offsets.length - 1;
+  const levelIndex = levelIndexFor(currentSpan, pyramid.dataLength, availableSizePx, minSpan);
+  if (levelIndex <= 0 || levelCount === 0) {
+    return null;
+  }
+  const clampedLevel = Math.min(levelIndex, levelCount);
+  return {
+    bucketSize: 2 ** clampedLevel,
+    start: pyramid.offsets[clampedLevel - 1],
+    end: pyramid.offsets[clampedLevel]
+  };
+}
+
+/**
+ * Active bucket size (`1` = no sampling) for an axis with no built pyramid (the axis highlight).
+ * Matches `selectSamplingLevel`'s `bucketSize`, derived from `dataLength` + screen + `minSpan`.
+ */
+function getSamplingBucketSize(currentSpan, dataLength, availableSizePx, minSpan) {
+  const levelIndex = levelIndexFor(currentSpan, dataLength, availableSizePx, minSpan);
+  if (levelIndex <= 0 || dataLength <= 1) {
+    return 1;
+  }
+  return 2 ** Math.min(levelIndex, Math.ceil(Math.log2(dataLength)));
+}

package/internals/plugins/useChartProSampling/sampling.line.d.mts

@@ -0,0 +1,22 @@
+import type { LineSamplingAlgorithm, SampleContext, SampledBucket } from '@mui/x-charts/internals';
+import type { SamplingPyramid } from "./sampling.pyramid.types.mjs";
+/**
+ * The active level of detail as buckets for the current zoom, or `null` for no sampling. Each bucket
+ * carries its original-index span plus the ascending indices to render. The same output feeds both
+ * series types: lines flatten the indices into a polyline, bars draw one merged rect per bucket.
+ *
+ * `minmax` (default; bars use it) keeps {min, max} per bucket; `m4` also brackets them with the
+ * bucket's first/last (pixel-accurate); both read the shared `SamplingPyramid`. `lttb` ignores
+ * the pyramid and reduces on demand, reading raw values from `getValues` (called only for `lttb`)
+ * as a single whole-range bucket. Its budget matches the envelope methods' point density so it
+ * isn't visually sparser at the same zoom.
+ */
+export declare function sampleBuckets(pyramid: SamplingPyramid, currentSpan: number, availableSizePx: number, minSpan: number, algorithm?: LineSamplingAlgorithm, getValues?: () => ArrayLike<number>): SampledBucket[] | null;
+/** Shared `sample` for every series type; the per-type build feeds the channels into the pyramid. */
+export declare function sample(context: SampleContext): SampledBucket[] | null;
+/**
+ * Largest-Triangle-Three-Buckets downsampling. Returns `threshold` original indices (including the
+ * first and last) chosen to preserve the line's visual shape. Uses the data index as the x channel.
+ * @see https://skemman.is/handle/1946/15343 (Sveinn Steinarsson, 2013)
+ */
+export declare function largestTriangleThreeBuckets(values: ArrayLike<number>, threshold: number): Int32Array;

package/internals/plugins/useChartProSampling/sampling.line.d.ts

@@ -0,0 +1,22 @@
+import type { LineSamplingAlgorithm, SampleContext, SampledBucket } from '@mui/x-charts/internals';
+import type { SamplingPyramid } from "./sampling.pyramid.types.js";
+/**
+ * The active level of detail as buckets for the current zoom, or `null` for no sampling. Each bucket
+ * carries its original-index span plus the ascending indices to render. The same output feeds both
+ * series types: lines flatten the indices into a polyline, bars draw one merged rect per bucket.
+ *
+ * `minmax` (default; bars use it) keeps {min, max} per bucket; `m4` also brackets them with the
+ * bucket's first/last (pixel-accurate); both read the shared `SamplingPyramid`. `lttb` ignores
+ * the pyramid and reduces on demand, reading raw values from `getValues` (called only for `lttb`)
+ * as a single whole-range bucket. Its budget matches the envelope methods' point density so it
+ * isn't visually sparser at the same zoom.
+ */
+export declare function sampleBuckets(pyramid: SamplingPyramid, currentSpan: number, availableSizePx: number, minSpan: number, algorithm?: LineSamplingAlgorithm, getValues?: () => ArrayLike<number>): SampledBucket[] | null;
+/** Shared `sample` for every series type; the per-type build feeds the channels into the pyramid. */
+export declare function sample(context: SampleContext): SampledBucket[] | null;
+/**
+ * Largest-Triangle-Three-Buckets downsampling. Returns `threshold` original indices (including the
+ * first and last) chosen to preserve the line's visual shape. Uses the data index as the x channel.
+ * @see https://skemman.is/handle/1946/15343 (Sveinn Steinarsson, 2013)
+ */
+export declare function largestTriangleThreeBuckets(values: ArrayLike<number>, threshold: number): Int32Array;