@mui/x-charts-pro 9.8.0 → 9.9.0

package/internals/plugins/useChartProSampling/sampling.line.js

@@ -0,0 +1,172 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.largestTriangleThreeBuckets = largestTriangleThreeBuckets;
+exports.sample = sample;
+exports.sampleBuckets = sampleBuckets;
+var _sampling = require("./sampling");
+/** Points the `minmax` envelope renders per bucket (min, max). Used to align the `lttb` budget. */
+const ENVELOPE_POINTS_PER_BUCKET = 2;
+
+/**
+ * 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.
+ */
+function sampleBuckets(pyramid, currentSpan, availableSizePx, minSpan, algorithm = 'minmax', getValues) {
+  const level = (0, _sampling.selectSamplingLevel)(pyramid, currentSpan, availableSizePx, minSpan);
+  if (!level) {
+    return null;
+  }
+  const {
+    bucketSize,
+    start,
+    end
+  } = level;
+  const {
+    nullIndices
+  } = pyramid;
+  const maxIndex = pyramid.dataLength - 1;
+  const nullLength = nullIndices?.length ?? 0;
+
+  // Builds one bucket's render indices: the ascending `candidates` (extrema/ends or the lttb points)
+  // with this bucket's null indices merged in, deduped, so the line breaks at gaps. `nullCursor`
+  // advances monotonically since buckets partition `[0, maxIndex]` left to right.
+  let nullCursor = 0;
+  const mergeBucket = (candidates, endIndex) => {
+    const indices = [];
+    let c = 0;
+    while (c < candidates.length || nullCursor < nullLength && nullIndices[nullCursor] <= endIndex) {
+      const nextCandidate = c < candidates.length ? candidates[c] : Infinity;
+      const nextNull = nullCursor < nullLength && nullIndices[nullCursor] <= endIndex ? nullIndices[nullCursor] : Infinity;
+      const next = Math.min(nextCandidate, nextNull);
+      if (indices[indices.length - 1] !== next) {
+        indices.push(next);
+      }
+      if (next === nextCandidate) {
+        c += 1;
+      }
+      if (next === nextNull) {
+        nullCursor += 1;
+      }
+    }
+    return Int32Array.from(indices);
+  };
+  if (algorithm === 'lttb') {
+    // LTTB emits one point per bucket, vs `ENVELOPE_POINTS_PER_BUCKET` for the min/max methods.
+    // Scale the budget by that factor so LTTB isn't sparser than them at the same zoom.
+    const indices = largestTriangleThreeBuckets(getValues(), Math.ceil(ENVELOPE_POINTS_PER_BUCKET * pyramid.dataLength / bucketSize));
+    return [{
+      startIndex: 0,
+      endIndex: maxIndex,
+      indices: mergeBucket(indices, maxIndex)
+    }];
+  }
+  const {
+    argMin,
+    argMax
+  } = pyramid;
+  const withEnds = algorithm === 'm4';
+  const buckets = [];
+  for (let j = start; j < end; j += 1) {
+    const bucket = j - start;
+    const startIndex = bucket * bucketSize;
+    const endIndex = Math.min(startIndex + bucketSize - 1, maxIndex);
+    // Extrema in ascending index order; `m4` also brackets them with the bucket's first/last.
+    const extremaFirst = Math.min(argMin[j], argMax[j]);
+    const extremaLast = Math.max(argMin[j], argMax[j]);
+    const candidates = withEnds ? [startIndex, extremaFirst, extremaLast, endIndex] : [extremaFirst, extremaLast];
+    buckets.push({
+      startIndex,
+      endIndex,
+      indices: mergeBucket(candidates, endIndex)
+    });
+  }
+  return buckets;
+}
+
+/** Shared `sample` for every series type; the per-type build feeds the channels into the pyramid. */
+function sample(context) {
+  const {
+    zoom
+  } = context;
+  if (!zoom) {
+    return null;
+  }
+  return sampleBuckets(context.built, zoom.end - zoom.start, context.availableSize, context.minSpan, context.algorithm, context.getValues);
+}
+
+/**
+ * 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)
+ */
+function largestTriangleThreeBuckets(values, threshold) {
+  const dataLength = values.length;
+  if (threshold >= dataLength) {
+    return Int32Array.from({
+      length: dataLength
+    }, (_, i) => i);
+  }
+  if (threshold <= 2) {
+    // Keep just the endpoints; returning every index here would bypass the rendered-point cap.
+    return Int32Array.from([0, dataLength - 1]);
+  }
+  const sampled = new Int32Array(threshold);
+  let sampledIndex = 0;
+  sampled[sampledIndex] = 0; // always keep the first point
+  sampledIndex += 1;
+
+  // Middle buckets span indices [1, dataLength - 1); the last point is fixed separately.
+  const bucketSize = (dataLength - 2) / (threshold - 2);
+  let a = 0; // index of the previously selected point
+
+  for (let i = 0; i < threshold - 2; i += 1) {
+    // Average point of the next bucket (the third triangle vertex).
+    const avgStart = Math.floor((i + 1) * bucketSize) + 1;
+    let avgEnd = Math.floor((i + 2) * bucketSize) + 1;
+    if (avgEnd > dataLength) {
+      avgEnd = dataLength;
+    }
+    let avgX = 0;
+    let avgY = 0;
+    const avgCount = avgEnd - avgStart;
+    for (let k = avgStart; k < avgEnd; k += 1) {
+      avgX += k;
+      avgY += values[k];
+    }
+    if (avgCount > 0) {
+      avgX /= avgCount;
+      avgY /= avgCount;
+    } else {
+      avgX = dataLength - 1;
+      avgY = values[dataLength - 1];
+    }
+    const rangeStart = Math.floor(i * bucketSize) + 1;
+    const rangeEnd = Math.floor((i + 1) * bucketSize) + 1;
+    const ax = a;
+    const ay = values[a];
+    let maxArea = -1;
+    let chosen = rangeStart;
+    for (let k = rangeStart; k < rangeEnd; k += 1) {
+      const area = Math.abs((ax - avgX) * (values[k] - ay) - (ax - k) * (avgY - ay));
+      if (area > maxArea) {
+        maxArea = area;
+        chosen = k;
+      }
+    }
+    sampled[sampledIndex] = chosen;
+    sampledIndex += 1;
+    a = chosen;
+  }
+  sampled[sampledIndex] = dataLength - 1; // always keep the last point
+  return sampled;
+}

package/internals/plugins/useChartProSampling/sampling.line.mjs

@@ -0,0 +1,164 @@
+import { selectSamplingLevel } from "./sampling.mjs";
+/** Points the `minmax` envelope renders per bucket (min, max). Used to align the `lttb` budget. */
+const ENVELOPE_POINTS_PER_BUCKET = 2;
+
+/**
+ * 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 function sampleBuckets(pyramid, currentSpan, availableSizePx, minSpan, algorithm = 'minmax', getValues) {
+  const level = selectSamplingLevel(pyramid, currentSpan, availableSizePx, minSpan);
+  if (!level) {
+    return null;
+  }
+  const {
+    bucketSize,
+    start,
+    end
+  } = level;
+  const {
+    nullIndices
+  } = pyramid;
+  const maxIndex = pyramid.dataLength - 1;
+  const nullLength = nullIndices?.length ?? 0;
+
+  // Builds one bucket's render indices: the ascending `candidates` (extrema/ends or the lttb points)
+  // with this bucket's null indices merged in, deduped, so the line breaks at gaps. `nullCursor`
+  // advances monotonically since buckets partition `[0, maxIndex]` left to right.
+  let nullCursor = 0;
+  const mergeBucket = (candidates, endIndex) => {
+    const indices = [];
+    let c = 0;
+    while (c < candidates.length || nullCursor < nullLength && nullIndices[nullCursor] <= endIndex) {
+      const nextCandidate = c < candidates.length ? candidates[c] : Infinity;
+      const nextNull = nullCursor < nullLength && nullIndices[nullCursor] <= endIndex ? nullIndices[nullCursor] : Infinity;
+      const next = Math.min(nextCandidate, nextNull);
+      if (indices[indices.length - 1] !== next) {
+        indices.push(next);
+      }
+      if (next === nextCandidate) {
+        c += 1;
+      }
+      if (next === nextNull) {
+        nullCursor += 1;
+      }
+    }
+    return Int32Array.from(indices);
+  };
+  if (algorithm === 'lttb') {
+    // LTTB emits one point per bucket, vs `ENVELOPE_POINTS_PER_BUCKET` for the min/max methods.
+    // Scale the budget by that factor so LTTB isn't sparser than them at the same zoom.
+    const indices = largestTriangleThreeBuckets(getValues(), Math.ceil(ENVELOPE_POINTS_PER_BUCKET * pyramid.dataLength / bucketSize));
+    return [{
+      startIndex: 0,
+      endIndex: maxIndex,
+      indices: mergeBucket(indices, maxIndex)
+    }];
+  }
+  const {
+    argMin,
+    argMax
+  } = pyramid;
+  const withEnds = algorithm === 'm4';
+  const buckets = [];
+  for (let j = start; j < end; j += 1) {
+    const bucket = j - start;
+    const startIndex = bucket * bucketSize;
+    const endIndex = Math.min(startIndex + bucketSize - 1, maxIndex);
+    // Extrema in ascending index order; `m4` also brackets them with the bucket's first/last.
+    const extremaFirst = Math.min(argMin[j], argMax[j]);
+    const extremaLast = Math.max(argMin[j], argMax[j]);
+    const candidates = withEnds ? [startIndex, extremaFirst, extremaLast, endIndex] : [extremaFirst, extremaLast];
+    buckets.push({
+      startIndex,
+      endIndex,
+      indices: mergeBucket(candidates, endIndex)
+    });
+  }
+  return buckets;
+}
+
+/** Shared `sample` for every series type; the per-type build feeds the channels into the pyramid. */
+export function sample(context) {
+  const {
+    zoom
+  } = context;
+  if (!zoom) {
+    return null;
+  }
+  return sampleBuckets(context.built, zoom.end - zoom.start, context.availableSize, context.minSpan, context.algorithm, context.getValues);
+}
+
+/**
+ * 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 function largestTriangleThreeBuckets(values, threshold) {
+  const dataLength = values.length;
+  if (threshold >= dataLength) {
+    return Int32Array.from({
+      length: dataLength
+    }, (_, i) => i);
+  }
+  if (threshold <= 2) {
+    // Keep just the endpoints; returning every index here would bypass the rendered-point cap.
+    return Int32Array.from([0, dataLength - 1]);
+  }
+  const sampled = new Int32Array(threshold);
+  let sampledIndex = 0;
+  sampled[sampledIndex] = 0; // always keep the first point
+  sampledIndex += 1;
+
+  // Middle buckets span indices [1, dataLength - 1); the last point is fixed separately.
+  const bucketSize = (dataLength - 2) / (threshold - 2);
+  let a = 0; // index of the previously selected point
+
+  for (let i = 0; i < threshold - 2; i += 1) {
+    // Average point of the next bucket (the third triangle vertex).
+    const avgStart = Math.floor((i + 1) * bucketSize) + 1;
+    let avgEnd = Math.floor((i + 2) * bucketSize) + 1;
+    if (avgEnd > dataLength) {
+      avgEnd = dataLength;
+    }
+    let avgX = 0;
+    let avgY = 0;
+    const avgCount = avgEnd - avgStart;
+    for (let k = avgStart; k < avgEnd; k += 1) {
+      avgX += k;
+      avgY += values[k];
+    }
+    if (avgCount > 0) {
+      avgX /= avgCount;
+      avgY /= avgCount;
+    } else {
+      avgX = dataLength - 1;
+      avgY = values[dataLength - 1];
+    }
+    const rangeStart = Math.floor(i * bucketSize) + 1;
+    const rangeEnd = Math.floor((i + 1) * bucketSize) + 1;
+    const ax = a;
+    const ay = values[a];
+    let maxArea = -1;
+    let chosen = rangeStart;
+    for (let k = rangeStart; k < rangeEnd; k += 1) {
+      const area = Math.abs((ax - avgX) * (values[k] - ay) - (ax - k) * (avgY - ay));
+      if (area > maxArea) {
+        maxArea = area;
+        chosen = k;
+      }
+    }
+    sampled[sampledIndex] = chosen;
+    sampledIndex += 1;
+    a = chosen;
+  }
+  sampled[sampledIndex] = dataLength - 1; // always keep the last point
+  return sampled;
+}

package/internals/plugins/useChartProSampling/sampling.mjs

@@ -0,0 +1,164 @@
+/** Smallest element size (px) allowed before sampling kicks in. */
+export 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 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.
+ */
+export const 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`).
+ */
+export 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). */
+export 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]`.
+ */
+export 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`.
+ */
+export 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.pyramid.types.d.mts

@@ -0,0 +1,33 @@
+/**
+ * The active level of detail for the current zoom: the slice `[start, end)` of the pyramid's
+ * `argMin`/`argMax` arrays plus its bucket size. Bucket `j` (`j` from `0`) covers indices
+ * `[j * bucketSize, min((j + 1) * bucketSize - 1, dataLength - 1)]`.
+ */
+export interface ActiveSamplingLevel {
+  /** Elements merged per bucket (power of two, `>= 2`). */
+  bucketSize: number;
+  /** Start offset into `argMin`/`argMax`. */
+  start: number;
+  /** End offset (exclusive) into `argMin`/`argMax`. */
+  end: number;
+}
+/**
+ * Precomputed LOD pyramid for one series, shared by every chart type and sampling method.
+ * Stored as flat typed arrays (no per-level or per-bucket objects): for each bucket it keeps the
+ * original index of the minimum (`argMin`, over the low channel) and the maximum (`argMax`, over
+ * the high channel). Consumers read the values back from their own series data by index.
+ *
+ * All levels are concatenated finest (`bucketSize 2`) to coarsest; `offsets[i]..offsets[i + 1]` is
+ * level `i` (bucketSize `2 ** (i + 1)`), and there are `offsets.length - 1` levels.
+ */
+export interface SamplingPyramid {
+  dataLength: number;
+  /** Index of the per-bucket minimum (low channel), concatenated finest to coarsest. */
+  argMin: Int32Array;
+  /** Index of the per-bucket maximum (high channel), same order. */
+  argMax: Int32Array;
+  /** Level start offsets into `argMin`/`argMax`; length `levelCount + 1`. */
+  offsets: Int32Array;
+  /** Ascending null-point indices, merged back into the output as line breaks. Absent without nulls. */
+  nullIndices?: Int32Array;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * The active level of detail for the current zoom: the slice `[start, end)` of the pyramid's
+ * `argMin`/`argMax` arrays plus its bucket size. Bucket `j` (`j` from `0`) covers indices
+ * `[j * bucketSize, min((j + 1) * bucketSize - 1, dataLength - 1)]`.
+ */
+export interface ActiveSamplingLevel {
+  /** Elements merged per bucket (power of two, `>= 2`). */
+  bucketSize: number;
+  /** Start offset into `argMin`/`argMax`. */
+  start: number;
+  /** End offset (exclusive) into `argMin`/`argMax`. */
+  end: number;
+}
+/**
+ * Precomputed LOD pyramid for one series, shared by every chart type and sampling method.
+ * Stored as flat typed arrays (no per-level or per-bucket objects): for each bucket it keeps the
+ * original index of the minimum (`argMin`, over the low channel) and the maximum (`argMax`, over
+ * the high channel). Consumers read the values back from their own series data by index.
+ *
+ * All levels are concatenated finest (`bucketSize 2`) to coarsest; `offsets[i]..offsets[i + 1]` is
+ * level `i` (bucketSize `2 ** (i + 1)`), and there are `offsets.length - 1` levels.
+ */
+export interface SamplingPyramid {
+  dataLength: number;
+  /** Index of the per-bucket minimum (low channel), concatenated finest to coarsest. */
+  argMin: Int32Array;
+  /** Index of the per-bucket maximum (high channel), same order. */
+  argMax: Int32Array;
+  /** Level start offsets into `argMin`/`argMax`; length `levelCount + 1`. */
+  offsets: Int32Array;
+  /** Ascending null-point indices, merged back into the output as line breaks. Absent without nulls. */
+  nullIndices?: Int32Array;
+}

package/internals/plugins/useChartProSampling/sampling.pyramid.types.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/internals/plugins/useChartProSampling/sampling.pyramid.types.mjs

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,4 @@
+import type { ChartPlugin } from '@mui/x-charts/internals';
+import type { UseChartProSamplingSignature } from "./useChartProSampling.types.mjs";
+/** Toggles sampling. Pyramids and level selection live in community selectors. */
+export declare const useChartProSampling: ChartPlugin<UseChartProSamplingSignature>;

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

@@ -0,0 +1,4 @@
+import type { ChartPlugin } from '@mui/x-charts/internals';
+import type { UseChartProSamplingSignature } from "./useChartProSampling.types.js";
+/** Toggles sampling. Pyramids and level selection live in community selectors. */
+export declare const useChartProSampling: ChartPlugin<UseChartProSamplingSignature>;

package/internals/plugins/useChartProSampling/useChartProSampling.js

@@ -0,0 +1,59 @@
+"use strict";
+'use client';
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useChartProSampling = void 0;
+var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
+var _useEffectAfterFirstRender = require("@mui/x-internals/useEffectAfterFirstRender");
+var _isDeepEqual = require("@mui/x-internals/isDeepEqual");
+/** Toggles sampling. Pyramids and level selection live in community selectors. */
+const useChartProSampling = ({
+  params,
+  store
+}) => {
+  const {
+    sampling
+  } = params;
+  (0, _useEffectAfterFirstRender.useEffectAfterFirstRender)(() => {
+    // Skip the update when unchanged so an inlined `sampling` config (a new object each render, e.g.
+    // in composition) doesn't replace the state and force the pyramids to recompute every render.
+    const next = toSamplingState(sampling);
+    if (!(0, _isDeepEqual.isDeepEqual)(store.state.sampling, next)) {
+      store.set('sampling', next);
+    }
+  }, [sampling, store]);
+  return {};
+};
+
+/** Maps the per-series-type `sampling` config to the internal state (enabled methods per type). */
+exports.useChartProSampling = useChartProSampling;
+function toSamplingState(sampling = {}) {
+  const methods = {};
+  // Iterate generically so a new series type only needs its `sampling` config entry, no edit here.
+  Object.keys(sampling).forEach(seriesType => {
+    const method = sampling[seriesType];
+    if (method && method !== 'none') {
+      methods[seriesType] = method;
+    }
+  });
+  return {
+    enabled: Object.keys(methods).length > 0,
+    methods
+  };
+}
+useChartProSampling.params = {
+  sampling: true
+};
+useChartProSampling.getDefaultizedParams = ({
+  params
+}) => (0, _extends2.default)({}, params, {
+  sampling: params.sampling ?? {}
+});
+useChartProSampling.getInitialState = ({
+  sampling
+}) => ({
+  sampling: toSamplingState(sampling)
+});