@mui/x-charts 9.4.0 → 9.5.0

package/internals/plugins/featurePlugins/useProgressiveRendering/useProgressiveRendering.selectors.js

@@ -0,0 +1,166 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.sameSeriesIds = sameSeriesIds;
+exports.selectorShouldUseProgressiveRenderer = exports.selectorProgressiveTotalRounds = exports.selectorProgressiveSeriesRevealedBatches = exports.selectorProgressiveRevealedRounds = exports.selectorProgressivePlans = exports.selectorProgressiveBatchSize = exports.selectorProgressiveAggregate = void 0;
+var _store = require("@mui/x-internals/store");
+var _useChartSeries = require("../../corePlugins/useChartSeries");
+var _useChartExperimentalFeature = require("../../corePlugins/useChartExperimentalFeature");
+/**
+ * Total point count above which the auto (`renderer` unset) mode switches to
+ * the progressive renderer. Below it the synchronous renderer is used, since
+ * the progressive paint's overhead is not worth it for small datasets.
+ */
+const PROGRESSIVE_POINT_THRESHOLD = 20000;
+
+/**
+ * Target number of reveal commits. Each commit repaints every already-painted
+ * circle, so the total progressive wall time is roughly `(C + 1) / 2` times a
+ * single synchronous render (where `C` is the number of commits). Targeting
+ * `5` commits keeps the progressive paint at roughly 2–3× the sync render time.
+ */
+const TARGET_PROGRESSIVE_COMMITS = 5;
+
+/**
+ * Lower bound for the per-tick reveal budget (total points across every
+ * series). Prevents tiny commits whose React overhead would dominate.
+ */
+const MIN_BATCH_TOTAL = 1000;
+
+/**
+ * Upper bound for the per-tick reveal budget (total points across every
+ * series). Prevents a single commit from blocking the main thread for too
+ * long; very large datasets simply use more commits.
+ */
+const MAX_BATCH_TOTAL = 10000;
+
+/**
+ * Per-series points revealed per tick, derived from the total point count
+ * across visible series and the number of visible series. The total per-tick
+ * budget aims for {@link TARGET_PROGRESSIVE_COMMITS} commits, clamped by
+ * {@link MIN_BATCH_TOTAL} / {@link MAX_BATCH_TOTAL}, then split evenly across
+ * the visible series so every series progresses together.
+ */
+const getEffectiveBatchSize = (nSeries, totalPoints) => {
+  const safeSeries = Math.max(1, nSeries);
+  const safePoints = Math.max(1, totalPoints);
+  const totalPerTick = Math.min(MAX_BATCH_TOTAL, Math.max(MIN_BATCH_TOTAL, Math.ceil(safePoints / TARGET_PROGRESSIVE_COMMITS)));
+  return Math.max(1, Math.floor(totalPerTick / safeSeries));
+};
+const selectorProgressiveState = state => state.progressiveRendering;
+
+/** Map of registered plots → their set of series ids. */
+const selectorProgressivePlans = exports.selectorProgressivePlans = (0, _store.createSelector)(selectorProgressiveState, s => s?.plans);
+
+/** Total number of rounds revealed across all plots so far. */
+const selectorProgressiveRevealedRounds = exports.selectorProgressiveRevealedRounds = (0, _store.createSelector)(selectorProgressiveState, s => s?.revealedRounds ?? 0);
+
+/** Point count of a series, looked up across every processed series type. */
+function getSeriesPointCount(processedSeries, seriesId) {
+  for (const type in processedSeries) {
+    if (!Object.hasOwn(processedSeries, type)) {
+      continue;
+    }
+    const item = processedSeries[type]?.series[seriesId];
+    if (item) {
+      return Array.isArray(item.data) ? item.data.length : 0;
+    }
+  }
+  return 0;
+}
+
+/**
+ * Aggregated view of every registered plan: the per-series batch counts, the
+ * total number of rounds, and the per-series batch size (so every consumer
+ * sizes its batches the same way). Point counts are read straight from the
+ * processed series rather than carried by the registration.
+ */
+const selectorProgressiveAggregate = exports.selectorProgressiveAggregate = (0, _store.createSelectorMemoized)(selectorProgressivePlans, _useChartSeries.selectorChartSeriesProcessed, function selectorProgressiveAggregate(plans, processedSeries) {
+  const nBatchesBySeries = new Map();
+  if (!plans || plans.size === 0) {
+    return {
+      nBatchesBySeries,
+      totalRounds: 0,
+      batchSize: MIN_BATCH_TOTAL
+    };
+  }
+  let nSeries = 0;
+  let totalPoints = 0;
+  const pointCounts = new Map();
+  plans.forEach(seriesIds => {
+    seriesIds.forEach(seriesId => {
+      const nPoints = getSeriesPointCount(processedSeries, seriesId);
+      pointCounts.set(seriesId, nPoints);
+      nSeries += 1;
+      totalPoints += nPoints;
+    });
+  });
+  const batchSize = getEffectiveBatchSize(nSeries, totalPoints);
+  let totalRounds = 0;
+  pointCounts.forEach((nPoints, seriesId) => {
+    const n = Math.max(1, Math.ceil(nPoints / batchSize));
+    nBatchesBySeries.set(seriesId, n);
+    if (n > totalRounds) {
+      totalRounds = n;
+    }
+  });
+  return {
+    nBatchesBySeries,
+    totalRounds,
+    batchSize
+  };
+});
+const selectorProgressiveBatchSize = exports.selectorProgressiveBatchSize = (0, _store.createSelector)(selectorProgressiveAggregate, a => a.batchSize);
+const selectorProgressiveTotalRounds = exports.selectorProgressiveTotalRounds = (0, _store.createSelector)(selectorProgressiveAggregate, a => a.totalRounds);
+
+/**
+ * How many of `seriesId`'s own batches are revealed so far. Capped at that
+ * series' total batch count, so series with fewer batches simply stop
+ * progressing while longer ones keep filling in.
+ */
+const selectorProgressiveSeriesRevealedBatches = exports.selectorProgressiveSeriesRevealedBatches = (0, _store.createSelector)(selectorProgressiveAggregate, selectorProgressiveRevealedRounds, function selectorProgressiveSeriesRevealedBatches(agg, revealed, seriesId) {
+  return Math.min(revealed, agg.nBatchesBySeries.get(seriesId) ?? 0);
+});
+
+/**
+ * Whether `seriesIds` should be rendered progressively given the requested
+ * `renderer`:
+ * - `svg-single` / `svg-batch`: never (those are non-progressive renderers).
+ * - `svg-progressive`: always.
+ * - unset (auto): only when the `progressiveRendering` experimental feature is
+ *   enabled and the total point count is above
+ *   {@link PROGRESSIVE_POINT_THRESHOLD}. The flag keeps the auto behavior
+ *   opt-in so the default (`svg-single`) stays non-breaking.
+ */
+const selectorProgressiveRenderingEnabled = state => (0, _useChartExperimentalFeature.selectorChartExperimentalFeaturesState)(state, 'progressiveRendering');
+const selectorShouldUseProgressiveRenderer = exports.selectorShouldUseProgressiveRenderer = (0, _store.createSelector)(_useChartSeries.selectorChartSeriesProcessed, selectorProgressiveRenderingEnabled, (processedSeries, progressiveRenderingEnabled, seriesIds, renderer) => {
+  if (renderer === 'svg-single' || renderer === 'svg-batch') {
+    return false;
+  }
+  if (renderer === 'svg-progressive') {
+    return true;
+  }
+  if (!progressiveRenderingEnabled) {
+    return false;
+  }
+  let totalPoints = 0;
+  for (const seriesId of seriesIds) {
+    totalPoints += getSeriesPointCount(processedSeries, seriesId);
+  }
+  return totalPoints > PROGRESSIVE_POINT_THRESHOLD;
+});
+
+/** Order-sensitive equality between two registered series-id sets. */
+function sameSeriesIds(a, b) {
+  if (!a || a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+  return true;
+}

package/internals/plugins/featurePlugins/useProgressiveRendering/useProgressiveRendering.selectors.mjs

@@ -0,0 +1,159 @@
+import { createSelector, createSelectorMemoized } from '@mui/x-internals/store';
+import { selectorChartSeriesProcessed } from "../../corePlugins/useChartSeries/index.mjs";
+import { selectorChartExperimentalFeaturesState } from "../../corePlugins/useChartExperimentalFeature/index.mjs";
+/**
+ * Total point count above which the auto (`renderer` unset) mode switches to
+ * the progressive renderer. Below it the synchronous renderer is used, since
+ * the progressive paint's overhead is not worth it for small datasets.
+ */
+const PROGRESSIVE_POINT_THRESHOLD = 20000;
+
+/**
+ * Target number of reveal commits. Each commit repaints every already-painted
+ * circle, so the total progressive wall time is roughly `(C + 1) / 2` times a
+ * single synchronous render (where `C` is the number of commits). Targeting
+ * `5` commits keeps the progressive paint at roughly 2–3× the sync render time.
+ */
+const TARGET_PROGRESSIVE_COMMITS = 5;
+
+/**
+ * Lower bound for the per-tick reveal budget (total points across every
+ * series). Prevents tiny commits whose React overhead would dominate.
+ */
+const MIN_BATCH_TOTAL = 1000;
+
+/**
+ * Upper bound for the per-tick reveal budget (total points across every
+ * series). Prevents a single commit from blocking the main thread for too
+ * long; very large datasets simply use more commits.
+ */
+const MAX_BATCH_TOTAL = 10000;
+
+/**
+ * Per-series points revealed per tick, derived from the total point count
+ * across visible series and the number of visible series. The total per-tick
+ * budget aims for {@link TARGET_PROGRESSIVE_COMMITS} commits, clamped by
+ * {@link MIN_BATCH_TOTAL} / {@link MAX_BATCH_TOTAL}, then split evenly across
+ * the visible series so every series progresses together.
+ */
+const getEffectiveBatchSize = (nSeries, totalPoints) => {
+  const safeSeries = Math.max(1, nSeries);
+  const safePoints = Math.max(1, totalPoints);
+  const totalPerTick = Math.min(MAX_BATCH_TOTAL, Math.max(MIN_BATCH_TOTAL, Math.ceil(safePoints / TARGET_PROGRESSIVE_COMMITS)));
+  return Math.max(1, Math.floor(totalPerTick / safeSeries));
+};
+const selectorProgressiveState = state => state.progressiveRendering;
+
+/** Map of registered plots → their set of series ids. */
+export const selectorProgressivePlans = createSelector(selectorProgressiveState, s => s?.plans);
+
+/** Total number of rounds revealed across all plots so far. */
+export const selectorProgressiveRevealedRounds = createSelector(selectorProgressiveState, s => s?.revealedRounds ?? 0);
+
+/** Point count of a series, looked up across every processed series type. */
+function getSeriesPointCount(processedSeries, seriesId) {
+  for (const type in processedSeries) {
+    if (!Object.hasOwn(processedSeries, type)) {
+      continue;
+    }
+    const item = processedSeries[type]?.series[seriesId];
+    if (item) {
+      return Array.isArray(item.data) ? item.data.length : 0;
+    }
+  }
+  return 0;
+}
+
+/**
+ * Aggregated view of every registered plan: the per-series batch counts, the
+ * total number of rounds, and the per-series batch size (so every consumer
+ * sizes its batches the same way). Point counts are read straight from the
+ * processed series rather than carried by the registration.
+ */
+export const selectorProgressiveAggregate = createSelectorMemoized(selectorProgressivePlans, selectorChartSeriesProcessed, function selectorProgressiveAggregate(plans, processedSeries) {
+  const nBatchesBySeries = new Map();
+  if (!plans || plans.size === 0) {
+    return {
+      nBatchesBySeries,
+      totalRounds: 0,
+      batchSize: MIN_BATCH_TOTAL
+    };
+  }
+  let nSeries = 0;
+  let totalPoints = 0;
+  const pointCounts = new Map();
+  plans.forEach(seriesIds => {
+    seriesIds.forEach(seriesId => {
+      const nPoints = getSeriesPointCount(processedSeries, seriesId);
+      pointCounts.set(seriesId, nPoints);
+      nSeries += 1;
+      totalPoints += nPoints;
+    });
+  });
+  const batchSize = getEffectiveBatchSize(nSeries, totalPoints);
+  let totalRounds = 0;
+  pointCounts.forEach((nPoints, seriesId) => {
+    const n = Math.max(1, Math.ceil(nPoints / batchSize));
+    nBatchesBySeries.set(seriesId, n);
+    if (n > totalRounds) {
+      totalRounds = n;
+    }
+  });
+  return {
+    nBatchesBySeries,
+    totalRounds,
+    batchSize
+  };
+});
+export const selectorProgressiveBatchSize = createSelector(selectorProgressiveAggregate, a => a.batchSize);
+export const selectorProgressiveTotalRounds = createSelector(selectorProgressiveAggregate, a => a.totalRounds);
+
+/**
+ * How many of `seriesId`'s own batches are revealed so far. Capped at that
+ * series' total batch count, so series with fewer batches simply stop
+ * progressing while longer ones keep filling in.
+ */
+export const selectorProgressiveSeriesRevealedBatches = createSelector(selectorProgressiveAggregate, selectorProgressiveRevealedRounds, function selectorProgressiveSeriesRevealedBatches(agg, revealed, seriesId) {
+  return Math.min(revealed, agg.nBatchesBySeries.get(seriesId) ?? 0);
+});
+
+/**
+ * Whether `seriesIds` should be rendered progressively given the requested
+ * `renderer`:
+ * - `svg-single` / `svg-batch`: never (those are non-progressive renderers).
+ * - `svg-progressive`: always.
+ * - unset (auto): only when the `progressiveRendering` experimental feature is
+ *   enabled and the total point count is above
+ *   {@link PROGRESSIVE_POINT_THRESHOLD}. The flag keeps the auto behavior
+ *   opt-in so the default (`svg-single`) stays non-breaking.
+ */
+const selectorProgressiveRenderingEnabled = state => selectorChartExperimentalFeaturesState(state, 'progressiveRendering');
+export const selectorShouldUseProgressiveRenderer = createSelector(selectorChartSeriesProcessed, selectorProgressiveRenderingEnabled, (processedSeries, progressiveRenderingEnabled, seriesIds, renderer) => {
+  if (renderer === 'svg-single' || renderer === 'svg-batch') {
+    return false;
+  }
+  if (renderer === 'svg-progressive') {
+    return true;
+  }
+  if (!progressiveRenderingEnabled) {
+    return false;
+  }
+  let totalPoints = 0;
+  for (const seriesId of seriesIds) {
+    totalPoints += getSeriesPointCount(processedSeries, seriesId);
+  }
+  return totalPoints > PROGRESSIVE_POINT_THRESHOLD;
+});
+
+/** Order-sensitive equality between two registered series-id sets. */
+export function sameSeriesIds(a, b) {
+  if (!a || a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+  return true;
+}

package/internals/plugins/featurePlugins/useProgressiveRendering/useProgressiveRendering.types.d.mts

@@ -0,0 +1,34 @@
+import { type SeriesId } from "../../../../models/seriesType/common.mjs";
+import type { RendererType } from "../../../../ScatterChart/index.mjs";
+import { type ChartPluginSignature } from "../../models/index.mjs";
+export interface UseProgressiveRenderingState {
+  progressiveRendering: {
+    /**
+     * Per-plot sets of series ids that should be progressively revealed, keyed
+     * by an opaque plot id. Each plot (e.g. a separate `ScatterPlot` composed
+     * into the same chart) registers its own set. The scheduler aggregates
+     * them and reads point counts straight from the processed series.
+     */
+    plans: ReadonlyMap<string, readonly SeriesId[]>;
+    /**
+     * Number of *rounds* revealed so far. A round adds one batch in every
+     * registered series simultaneously, so every series progresses together.
+     */
+    revealedRounds: number;
+  };
+}
+export interface UseProgressiveRenderingInstance {
+  /**
+   * Register the set of series ids that `plotId` wants progressively revealed,
+   * and return a cleanup function that unregisters them. Designed to be called
+   * from a `React.useEffect`: returning the unregister function makes the
+   * effect's cleanup tear the registration down on unmount or before the next
+   * call. Re-calling with the same `plotId` replaces the previous set; a no-op
+   * when the set is unchanged.
+   */
+  registerProgressivePlan(plotId: string, seriesIds: readonly SeriesId[], renderer: RendererType | 'svg-progressive' | undefined): (() => void) | undefined;
+}
+export type UseProgressiveRenderingSignature = ChartPluginSignature<{
+  state: UseProgressiveRenderingState;
+  instance: UseProgressiveRenderingInstance;
+}>;

package/internals/plugins/featurePlugins/useProgressiveRendering/useProgressiveRendering.types.d.ts

@@ -0,0 +1,34 @@
+import { type SeriesId } from "../../../../models/seriesType/common.js";
+import type { RendererType } from "../../../../ScatterChart/index.js";
+import { type ChartPluginSignature } from "../../models/index.js";
+export interface UseProgressiveRenderingState {
+  progressiveRendering: {
+    /**
+     * Per-plot sets of series ids that should be progressively revealed, keyed
+     * by an opaque plot id. Each plot (e.g. a separate `ScatterPlot` composed
+     * into the same chart) registers its own set. The scheduler aggregates
+     * them and reads point counts straight from the processed series.
+     */
+    plans: ReadonlyMap<string, readonly SeriesId[]>;
+    /**
+     * Number of *rounds* revealed so far. A round adds one batch in every
+     * registered series simultaneously, so every series progresses together.
+     */
+    revealedRounds: number;
+  };
+}
+export interface UseProgressiveRenderingInstance {
+  /**
+   * Register the set of series ids that `plotId` wants progressively revealed,
+   * and return a cleanup function that unregisters them. Designed to be called
+   * from a `React.useEffect`: returning the unregister function makes the
+   * effect's cleanup tear the registration down on unmount or before the next
+   * call. Re-calling with the same `plotId` replaces the previous set; a no-op
+   * when the set is unchanged.
+   */
+  registerProgressivePlan(plotId: string, seriesIds: readonly SeriesId[], renderer: RendererType | 'svg-progressive' | undefined): (() => void) | undefined;
+}
+export type UseProgressiveRenderingSignature = ChartPluginSignature<{
+  state: UseProgressiveRenderingState;
+  instance: UseProgressiveRenderingInstance;
+}>;

package/internals/plugins/featurePlugins/useProgressiveRendering/useProgressiveRendering.types.js

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

package/internals/plugins/featurePlugins/useProgressiveRendering/useProgressiveRendering.types.mjs

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

package/internals/scales/scaleBand.js

@@ -21,60 +21,57 @@ function keyof(value) {
 }
 
 /**
- * Constructs a new band scale with the specified range, no padding, no rounding and center alignment.
- * The domain defaults to the empty domain.
- * If range is not specified, it defaults to the unit range [0, 1].
- *
- * The generic corresponds to the data type of domain elements.
- *
- * @param range A two-element array of numeric values.
- */
-
-/**
- * Constructs a new band scale with the specified domain and range, no padding, no rounding and center alignment.
- *
- * The generic corresponds to the data type of domain elements.
- *
- * @param domain Array of domain values.
- * @param range A two-element array of numeric values.
+ * The internal state shared when copying a scale. The domain index (`InternMap`) is the expensive
+ * part to build — `O(domain)` — and is immutable once set (the domain setter replaces it rather than
+ * mutating it), so a copy can share the same reference instead of rebuilding it. This makes `copy()`
+ * `O(1)`, which matters because zooming copies the scale on every frame to apply a new range.
  */
 
-function scaleBand(...args) {
+function createScaleBand(seed) {
   // @ts-expect-error, InternMap accepts two arguments, but its types are set as Map, which doesn't.
-  let index = new _d3Array.InternMap(undefined, keyof);
-  let domain = [];
-  let ordinalRange = [];
-  let r0 = 0;
-  let r1 = 1;
+  let index = seed ? seed.index : new _d3Array.InternMap(undefined, keyof);
+  let domain = seed ? seed.domain : [];
+  let r0 = seed ? seed.r0 : 0;
+  let r1 = seed ? seed.r1 : 1;
+  let isRound = seed ? seed.isRound : false;
+  let paddingInner = seed ? seed.paddingInner : 0;
+  let paddingOuter = seed ? seed.paddingOuter : 0;
+  let align = seed ? seed.align : 0.5;
+
+  // Derived on every rescale. Positions are affine in the index, so they are computed on demand in
+  // `scale()` rather than materialized into an array — keeping rescale `O(1)` instead of `O(domain)`.
   let step;
   let bandwidth;
-  let isRound = false;
-  let paddingInner = 0;
-  let paddingOuter = 0;
-  let align = 0.5;
+  let reverse = false;
+  let start = 0;
   const scale = d => {
     const i = index.get(d);
     if (i === undefined) {
       return undefined;
     }
-    return ordinalRange[i % ordinalRange.length];
+    const n = domain.length;
+    if (n === 0) {
+      return undefined;
+    }
+    const k = reverse ? n - 1 - i % n : i % n;
+    return start + step * k;
   };
   const rescale = () => {
     const n = domain.length;
-    const reverse = r1 < r0;
-    const start = reverse ? r1 : r0;
-    const stop = reverse ? r0 : r1;
-    step = (stop - start) / Math.max(1, n - paddingInner + paddingOuter * 2);
+    reverse = r1 < r0;
+    const lo = reverse ? r1 : r0;
+    const hi = reverse ? r0 : r1;
+    step = (hi - lo) / Math.max(1, n - paddingInner + paddingOuter * 2);
     if (isRound) {
       step = Math.floor(step);
     }
-    const adjustedStart = start + (stop - start - step * (n - paddingInner)) * align;
+    let adjustedStart = lo + (hi - lo - step * (n - paddingInner)) * align;
     bandwidth = step * (1 - paddingInner);
-    const finalStart = isRound ? Math.round(adjustedStart) : adjustedStart;
-    const finalBandwidth = isRound ? Math.round(bandwidth) : bandwidth;
-    bandwidth = finalBandwidth;
-    const values = (0, _d3Array.range)(n).map(i => finalStart + step * i);
-    ordinalRange = reverse ? values.reverse() : values;
+    if (isRound) {
+      adjustedStart = Math.round(adjustedStart);
+      bandwidth = Math.round(bandwidth);
+    }
+    start = adjustedStart;
     return scale;
   };
   scale.domain = function (_) {
@@ -149,19 +146,49 @@ function scaleBand(...args) {
     align = Math.max(0, Math.min(1, _));
     return rescale();
   };
-  scale.copy = () => {
-    return scaleBand(domain, [r0, r1]).round(isRound).paddingInner(paddingInner).paddingOuter(paddingOuter).align(align);
-  };
 
-  // Initialize from arguments
+  // Shares the immutable domain index with the copy, so copying does not rebuild it.
+  scale.copy = () => createScaleBand({
+    index,
+    domain,
+    r0,
+    r1,
+    isRound,
+    paddingInner,
+    paddingOuter,
+    align
+  });
+  rescale();
+  return scale;
+}
+
+/**
+ * Constructs a new band scale with the specified range, no padding, no rounding and center alignment.
+ * The domain defaults to the empty domain.
+ * If range is not specified, it defaults to the unit range [0, 1].
+ *
+ * The generic corresponds to the data type of domain elements.
+ *
+ * @param range A two-element array of numeric values.
+ */
+
+/**
+ * Constructs a new band scale with the specified domain and range, no padding, no rounding and center alignment.
+ *
+ * The generic corresponds to the data type of domain elements.
+ *
+ * @param domain Array of domain values.
+ * @param range A two-element array of numeric values.
+ */
+
+function scaleBand(...args) {
+  const scale = createScaleBand();
   const [arg0, arg1] = args;
   if (args.length > 1) {
     scale.domain(arg0);
     scale.range(arg1);
   } else if (arg0) {
     scale.range(arg0);
-  } else {
-    rescale();
   }
   return scale;
 }