stream-charts 1.2.1 → 2.0.0

package/dist/app/charts/plots/useCanvasZoomPan.js

@@ -0,0 +1,113 @@
+import { useCallback, useEffect, useRef } from "react";
+import * as d3 from "d3";
+/**
+ * How far a wheel event scrolls (positive when scrolling down, toward you), scaled as d3-zoom's
+ * default `wheelDelta` scales it (which negates it, so that scrolling up raises the scale)
+ * @param event The wheel event
+ * @return The scroll amount, in d3-zoom's units
+ */
+function wheelDeltaOf(event) {
+    return event.deltaY * (event.deltaMode === 1 ? 0.05 : event.deltaMode ? 1 : 0.002) * (event.ctrlKey ? 10 : 1);
+}
+/**
+ * Sets up panning (dragging) and zooming (the mouse wheel) on a plot's canvas, with d3's drag and
+ * zoom behaviors, and detaches them when the plot unmounts (or the canvas, or the settings they
+ * depend on, change).
+ *
+ * - Zooming only responds to wheel events (and, when required, only with the shift or ctrl key
+ *   down): d3-zoom also handles mouse drags on its own, which would otherwise fire zoom events for
+ *   the same gesture the dedicated drag behavior pans with.
+ * - d3-zoom's scale is cumulative; each zoom step is also handed to the plot as an incremental
+ *   factor (relative to the previous step), which is reset whenever d3-zoom's transform is.
+ * - The handlers are always the plot's latest ones, so the behaviors needn't be re-attached when
+ *   the handlers change.
+ * @param canvasContext The plot's canvas context (`null` until the canvas exists)
+ * @param options Whether panning and zooming are enabled, their extents, and the handlers
+ * @return The controls for d3-zoom's own transform (reset it, or set its scale)
+ */
+export function useCanvasZoomPan(canvasContext, options) {
+    const { panEnabled, zoomEnabled, keyModifiersRequired, scaleExtent: [minScale, maxScale], invertWheel = false, translateExtent: [[left, top], [right, bottom]], onZoomReset, } = options;
+    // the latest handlers (the behaviors call these, so they needn't be re-attached when they change)
+    const handlersRef = useRef(options);
+    useEffect(() => {
+        handlersRef.current = options;
+    });
+    // d3-zoom's cumulative scale as of the previous zoom step, to turn its next one into an
+    // incremental factor
+    const lastKRef = useRef(1);
+    // the attached zoom behavior (undefined while zooming isn't set up)
+    const zoomRef = useRef(undefined);
+    const resetZoomTransform = useCallback(() => {
+        if (canvasContext !== null && zoomRef.current !== undefined) {
+            d3.select(canvasContext.canvas).call(zoomRef.current.transform, d3.zoomIdentity);
+        }
+        lastKRef.current = 1;
+    }, [canvasContext]);
+    const setZoomScale = useCallback((k) => {
+        if (canvasContext !== null) {
+            // (d3-zoom keeps an element's transform in its `__zoom` property)
+            d3.select(canvasContext.canvas).property("__zoom", d3.zoomIdentity.scale(k));
+        }
+        lastKRef.current = k;
+    }, [canvasContext]);
+    useEffect(() => {
+        if (canvasContext === null)
+            return;
+        const canvasSelection = d3.select(canvasContext.canvas);
+        if (panEnabled) {
+            const drag = d3.drag()
+                .on("start", () => {
+                var _a, _b;
+                canvasSelection.style("cursor", "move");
+                (_b = (_a = handlersRef.current).onPanStart) === null || _b === void 0 ? void 0 : _b.call(_a);
+            })
+                .on("drag", event => handlersRef.current.onPan(event.dx, event.dy))
+                .on("end", () => {
+                var _a, _b;
+                canvasSelection.style("cursor", "auto");
+                (_b = (_a = handlersRef.current).onPanEnd) === null || _b === void 0 ? void 0 : _b.call(_a);
+            });
+            canvasSelection.call(drag);
+        }
+        if (zoomEnabled) {
+            const zoom = d3.zoom()
+                // wheel events only -- see the doc comment above
+                .filter(event => event.type === 'wheel' && (!keyModifiersRequired || event.shiftKey || event.ctrlKey))
+                // (the same gesture zooms every plot the same way -- see `invertWheel`)
+                .wheelDelta(event => (invertWheel ? 1 : -1) * wheelDeltaOf(event))
+                .scaleExtent([minScale, maxScale])
+                .translateExtent([[left, top], [right, bottom]])
+                .on("zoom", (event) => {
+                // a `null` source event means a programmatic change to the transform (e.g. a
+                // reset), not a user's gesture: there's nothing for the plot to do
+                if (event.sourceEvent === null)
+                    return;
+                const k = event.transform.k;
+                const factor = k / lastKRef.current;
+                lastKRef.current = k;
+                const { offsetX, offsetY } = event.sourceEvent;
+                handlersRef.current.onZoom({ factor, k, x: offsetX, y: offsetY });
+            });
+            canvasSelection.call(zoom);
+            zoomRef.current = zoom;
+            onZoomReset === null || onZoomReset === void 0 ? void 0 : onZoomReset(() => {
+                var _a, _b;
+                resetZoomTransform();
+                (_b = (_a = handlersRef.current).resetView) === null || _b === void 0 ? void 0 : _b.call(_a);
+            });
+        }
+        return () => {
+            if (panEnabled)
+                canvasSelection.on(".drag", null);
+            if (zoomEnabled) {
+                canvasSelection.on(".zoom", null);
+                zoomRef.current = undefined;
+            }
+        };
+    }, [
+        canvasContext, panEnabled, zoomEnabled, keyModifiersRequired, invertWheel,
+        minScale, maxScale, left, top, right, bottom, onZoomReset, resetZoomTransform
+    ]);
+    return { resetZoomTransform, setZoomScale };
+}
+//# sourceMappingURL=useCanvasZoomPan.js.map

package/dist/app/charts/plots/useCanvasZoomPan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCanvasZoomPan.js","sourceRoot":"","sources":["../../../../src/app/charts/plots/useCanvasZoomPan.ts"],"names":[],"mappings":"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"}

package/dist/app/charts/plots/useStreamingTimeAxes.d.ts

@@ -0,0 +1,103 @@
+import { type RefObject } from "react";
+import type { CanvasContext } from "../d3types";
+import type { StreamingDataSource } from "../datasources/StreamingDataSource";
+import type { ChartData } from "../observables/ChartData";
+import type { BaseSeries } from "../series/baseSeries";
+import { type AxisTimesFor, TimeWindowBehavior } from "../subscriptions/viewDrivers";
+import { type AxesAssignment } from "./plot";
+/**
+ * The options for {@link useStreamingTimeAxes}
+ * @template CD The type of the chart data
+ * @template D The type of the series' datum
+ */
+export interface StreamingTimeAxesOptions<CD extends ChartData, D> {
+    /**
+     * The plot's canvas context (`null` until the canvas exists)
+     */
+    canvasContext: CanvasContext | null;
+    /**
+     * The data source (and whether it's running)
+     */
+    dataSource: StreamingDataSource<CD, D> | undefined;
+    running: boolean;
+    /**
+     * The series the data source held when it was handed to the chart (see `useInitialData`)
+     */
+    initialData: Array<BaseSeries<D>>;
+    /**
+     * The time of a datum (its x-value)
+     */
+    timeOf: (datum: D) => number;
+    /**
+     * Gives the current time of each x-axis that a chunk of data has new points for (see
+     * `timeSeriesAxisTimes` and `outlierAxisTimes`)
+     */
+    axisTimesFor: AxisTimesFor<CD>;
+    /**
+     * The assignment of the series to their x- and y-axes
+     */
+    axisAssignments: Map<string, AxesAssignment>;
+    /**
+     * Draws the plot (registers its draw function with the canvas context, and requests a redraw)
+     */
+    updatePlot: (canvasContext: CanvasContext) => void;
+    /**
+     * Resets the plot's own references to the data, when the data source is replaced -- called just
+     * before the axes are reset and the plot is redrawn
+     */
+    onDataReset: () => void;
+    /**
+     * Whether the plot may show tooltips: when given, it's cleared while panning and while the data
+     * source is running, and restored afterward
+     */
+    allowTooltipRef?: RefObject<boolean>;
+    /**
+     * Panning and zooming (see {@link useCanvasZoomPan})
+     */
+    panEnabled: boolean;
+    zoomEnabled: boolean;
+    zoomKeyModifiersRequired: boolean;
+    /**
+     * The plot's `onZoomReset` property (see {@link useCanvasZoomPan})
+     */
+    onZoomReset?: (resetZoom: () => void) => void;
+    /**
+     * The time (ms) between cadence ticks (none, when undefined -- see `timeAxisViewDriverFor`)
+     */
+    withCadenceOf?: number;
+    /**
+     * Whether the time axes scroll or squeeze as data passes their ends (defaults to SCROLL)
+     */
+    timeWindowBehavior?: TimeWindowBehavior;
+    /**
+     * When true, the x- and y-axes of the hovered series are highlighted (in the series' own
+     * highlight color and width)
+     */
+    highlightAxesOnMouseOver: boolean;
+}
+/**
+ * The time (x-) axes of a streaming time plot (the scatter, raster, and outlier plots): keeps each
+ * x-axis's range in step with the data, and with the user's panning and zooming, and reports the
+ * ranges.
+ *
+ * - **The ranges.** One map of the x-axes' ranges, built once and mutated in place: the zoom and
+ *   pan handlers, and the view driver, all work on the same map, so that neither undoes the
+ *   other (the view driver hands its map back through `updateTimingAndPlot`, which re-points the
+ *   map at it).
+ * - **The view driver.** While the data source runs, a view driver (see `timeAxisViewDriverFor`)
+ *   advances the ranges as the data arrives (or with cadence), records each axis's current time,
+ *   and redraws the plot. It belongs to this plot alone, and is torn down with it.
+ * - **Panning and zooming.** While running, the zoom pivots on each axis's current time ("now");
+ *   while paused, on the mouse. A zoom reset restores the axes' original ranges (as captured when
+ *   the data source was handed to the plot).
+ * - **Reporting.** The axes' intervals are reported to the chart's `onUpdateAxesBounds` (at most
+ *   once per animation frame, since zooming and panning fire many events).
+ * - **A new data source** (new initial data) resets the plot's data, the axes' ranges (starting at
+ *   the data's first time), and the original ranges a zoom reset restores.
+ * - **Highlighting.** Optionally, highlights the hovered series' axes.
+ * @param options The plot's canvas, data, handlers, and settings
+ * @template CD The type of the chart data
+ * @template D The type of the series' datum
+ */
+export declare function useStreamingTimeAxes<CD extends ChartData, D>(options: StreamingTimeAxesOptions<CD, D>): void;
+//# sourceMappingURL=useStreamingTimeAxes.d.ts.map

package/dist/app/charts/plots/useStreamingTimeAxes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStreamingTimeAxes.d.ts","sourceRoot":"","sources":["../../../../src/app/charts/plots/useStreamingTimeAxes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,KAAK,SAAS,EAA0D,MAAM,OAAO,CAAC;AAc9F,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,oCAAoC,CAAC;AAK5E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAC,KAAK,YAAY,EAAyB,kBAAkB,EAAC,MAAM,8BAA8B,CAAC;AAE1G,OAAO,EAAC,KAAK,cAAc,EAAuB,MAAM,QAAQ,CAAC;AAGjE;;;;GAIG;AACH,MAAM,WAAW,wBAAwB,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC7D;;OAEG;IACH,aAAa,EAAE,aAAa,GAAG,IAAI,CAAA;IACnC;;OAEG;IACH,UAAU,EAAE,mBAAmB,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,SAAS,CAAA;IAClD,OAAO,EAAE,OAAO,CAAA;IAChB;;OAEG;IACH,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;IACjC;;OAEG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAA;IAC5B;;;OAGG;IACH,YAAY,EAAE,YAAY,CAAC,EAAE,CAAC,CAAA;IAC9B;;OAEG;IACH,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IAC5C;;OAEG;IACH,UAAU,EAAE,CAAC,aAAa,EAAE,aAAa,KAAK,IAAI,CAAA;IAClD;;;OAGG;IACH,WAAW,EAAE,MAAM,IAAI,CAAA;IACvB;;;OAGG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IACpC;;OAEG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB,WAAW,EAAE,OAAO,CAAA;IACpB,wBAAwB,EAAE,OAAO,CAAA;IACjC;;OAEG;IACH,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;IAC7C;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;OAEG;IACH,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;IACvC;;;OAGG;IACH,wBAAwB,EAAE,OAAO,CAAA;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,wBAAwB,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAqQ5G"}

package/dist/app/charts/plots/useStreamingTimeAxes.js

@@ -0,0 +1,257 @@
+import { useCallback, useEffect, useEffectEvent, useMemo, useRef } from "react";
+import { Optional } from "result-fn";
+import { axesForSeriesGen, continuousAxisIntervals, continuousAxisRanges, continuousAxisZoomHandler, defaultLineStyle, panHandler, } from "../axes/axes";
+import { AxisInterval } from "../axes/AxisInterval";
+import { ContinuousAxisRange } from "../axes/ContinuousAxisRange";
+import { useChart } from "../hooks/useChart";
+import { useHoveredSeries } from "../hooks/useHoveredSeries";
+import { usePlotDimensions } from "../hooks/usePlotDimensions";
+import { useStreamingSettings } from "../hooks/useDataSource";
+import { timeAxisViewDriverFor, TimeWindowBehavior } from "../subscriptions/viewDrivers";
+import { noop } from "../utils";
+import { currentIntervalsFrom } from "./plot";
+import { useCanvasZoomPan } from "./useCanvasZoomPan";
+/**
+ * The time (x-) axes of a streaming time plot (the scatter, raster, and outlier plots): keeps each
+ * x-axis's range in step with the data, and with the user's panning and zooming, and reports the
+ * ranges.
+ *
+ * - **The ranges.** One map of the x-axes' ranges, built once and mutated in place: the zoom and
+ *   pan handlers, and the view driver, all work on the same map, so that neither undoes the
+ *   other (the view driver hands its map back through `updateTimingAndPlot`, which re-points the
+ *   map at it).
+ * - **The view driver.** While the data source runs, a view driver (see `timeAxisViewDriverFor`)
+ *   advances the ranges as the data arrives (or with cadence), records each axis's current time,
+ *   and redraws the plot. It belongs to this plot alone, and is torn down with it.
+ * - **Panning and zooming.** While running, the zoom pivots on each axis's current time ("now");
+ *   while paused, on the mouse. A zoom reset restores the axes' original ranges (as captured when
+ *   the data source was handed to the plot).
+ * - **Reporting.** The axes' intervals are reported to the chart's `onUpdateAxesBounds` (at most
+ *   once per animation frame, since zooming and panning fire many events).
+ * - **A new data source** (new initial data) resets the plot's data, the axes' ranges (starting at
+ *   the data's first time), and the original ranges a zoom reset restores.
+ * - **Highlighting.** Optionally, highlights the hovered series' axes.
+ * @param options The plot's canvas, data, handlers, and settings
+ * @template CD The type of the chart data
+ * @template D The type of the series' datum
+ */
+export function useStreamingTimeAxes(options) {
+    const { canvasContext, dataSource, running, initialData, timeOf, axisTimesFor, axisAssignments, updatePlot, onDataReset, allowTooltipRef, panEnabled, zoomEnabled, zoomKeyModifiersRequired, onZoomReset, withCadenceOf, timeWindowBehavior = TimeWindowBehavior.SCROLL, highlightAxesOnMouseOver, } = options;
+    const { chartId, color, axes, seriesStyles } = useChart();
+    const { xAxesState, yAxesState, setAxisIntervalFor, updateAxisRanges = noop, onUpdateAxesInterval } = axes;
+    const { plotDimensions, margin } = usePlotDimensions();
+    const { windowingTime, dataUpdatePeriod } = useStreamingSettings();
+    const { hoveredSeriesName } = useHoveredSeries();
+    // the x-axes' ranges: built once, and mutated in place by the zoom and pan handlers (and
+    // re-pointed at the view driver's map by `updateTimingAndPlot`)
+    const timeRangesRef = useRef(new Map());
+    // map(axis_id -> current_time), recorded by the view driver; the zoom pivots on it while
+    // running. Empty (rather than 0 per axis) until the driver records a time, so that the zoom
+    // pivot falls back to the axis' own domain
+    const currentTimeRef = useRef(new Map());
+    // the axes' true original (un-zoomed) bounds, which a zoom reset restores, and each axis' pinned
+    // start time for SQUEEZE -- captured when the data source is handed to the plot (see
+    // `resetForNewData`), rather than via a `useMemo` on the axes context, which re-samples the
+    // ranges' `.original` as auto-scroll moves it
+    const initialAxisIntervalsRef = useRef(new Map());
+    const initialTimesRef = useRef(new Map());
+    // the latest draw and axis-range-update functions (called from the view driver, and the zoom
+    // and pan handlers)
+    const updatePlotRef = useRef(updatePlot);
+    useEffect(() => {
+        updatePlotRef.current = updatePlot;
+    }, [updatePlot]);
+    const updateAxisRangesRef = useRef(updateAxisRanges);
+    useEffect(() => {
+        updateAxisRangesRef.current = updateAxisRanges;
+    }, [updateAxisRanges]);
+    // reports the axes' intervals to the chart's `onUpdateAxesBounds`, at most once per animation
+    // frame (zooming and panning fire many events per gesture, and the callback generally updates
+    // the application's state). Coalescing loses nothing: the deferred notification reports the
+    // *latest* ranges (`pendingRangesRef`), not those of the call that scheduled it -- the ranges
+    // map is sometimes replaced (e.g. on a reset), and reporting a stale map would write stale
+    // intervals into the application's state.
+    const notifyIntervalsRef = useRef(noop);
+    const notifyFrameRef = useRef(0);
+    const pendingRangesRef = useRef(new Map());
+    useEffect(() => {
+        notifyIntervalsRef.current = onUpdateAxesInterval === undefined ?
+            noop :
+            ranges => {
+                pendingRangesRef.current = ranges;
+                if (notifyFrameRef.current !== 0)
+                    return;
+                notifyFrameRef.current = requestAnimationFrame(() => {
+                    notifyFrameRef.current = 0;
+                    onUpdateAxesInterval(currentIntervalsFrom(pendingRangesRef.current));
+                });
+            };
+    }, [onUpdateAxesInterval]);
+    // don't leave a scheduled notification pointing at an unmounted plot
+    useEffect(() => () => {
+        if (notifyFrameRef.current !== 0) {
+            cancelAnimationFrame(notifyFrameRef.current);
+            notifyFrameRef.current = 0;
+        }
+    }, []);
+    // new x-axes: forget the current times (see `currentTimeRef`)
+    useEffect(() => {
+        currentTimeRef.current = new Map();
+    }, [xAxesState]);
+    // highlights the hovered series' x- and y-axes, and un-highlights them (in the effect's
+    // cleanup) when the hover moves to a different series, or ends
+    useEffect(() => {
+        if (!highlightAxesOnMouseOver || hoveredSeriesName === null)
+            return;
+        const assignment = axisAssignments.get(hoveredSeriesName);
+        const xAxis = xAxesState.axisFor((assignment === null || assignment === void 0 ? void 0 : assignment.xAxis) || "").getOrUndefined();
+        const yAxis = yAxesState.axisFor((assignment === null || assignment === void 0 ? void 0 : assignment.yAxis) || "").getOrUndefined();
+        const { highlightColor, highlightWidth } = seriesStyles.get(hoveredSeriesName) || defaultLineStyle();
+        xAxis === null || xAxis === void 0 ? void 0 : xAxis.setHighlighted(true, highlightColor, highlightWidth);
+        yAxis === null || yAxis === void 0 ? void 0 : yAxis.setHighlighted(true, highlightColor, highlightWidth);
+        return () => {
+            xAxis === null || xAxis === void 0 ? void 0 : xAxis.setHighlighted(false);
+            yAxis === null || yAxis === void 0 ? void 0 : yAxis.setHighlighted(false);
+        };
+    }, [highlightAxesOnMouseOver, hoveredSeriesName, axisAssignments, xAxesState, yAxesState, seriesStyles]);
+    // the distinct x-axes that the series use
+    const axesForSeries = useMemo(() => axesForSeriesGen(initialData, axisAssignments, xAxesState), [initialData, axisAssignments, xAxesState]);
+    // hands new ranges to the axes, makes them the plot's ranges (see `timeRangesRef`), redraws the
+    // plot, and reports the axes' intervals
+    const updateTimingAndPlot = useCallback((ranges) => {
+        if (canvasContext === null)
+            return;
+        updateAxisRangesRef.current(ranges);
+        timeRangesRef.current = ranges;
+        updatePlotRef.current(canvasContext);
+        notifyIntervalsRef.current(ranges);
+    }, [canvasContext]);
+    // a new data source (new initial data): resets the plot's data, the current times, and the
+    // original bounds (for a zoom reset), and starts each axis at the data's first time. (An effect
+    // event, so that it runs only when the initial data changes, with the latest everything else.)
+    const resetForNewData = useEffectEvent(() => {
+        onDataReset();
+        currentTimeRef.current = new Map();
+        const freshRanges = continuousAxisRanges(xAxesState.axes);
+        initialAxisIntervalsRef.current = new Map(Array.from(freshRanges.entries()).map(([id, range]) => [id, range.original.asTuple()]));
+        initialTimesRef.current = new Map(Array.from(freshRanges.entries()).map(([id, range]) => [id, range.original.start]));
+        updateTimingAndPlot(new Map(Array.from(freshRanges.entries()).map(([id, range]) => {
+            const [start, end] = range.original.asTuple();
+            const firstTime = initialData
+                .filter(series => { var _a; return ((_a = axisAssignments.get(series.name)) === null || _a === void 0 ? void 0 : _a.xAxis) === id; })
+                .reduce((tMin, series) => Math.min(tMin, !series.isEmpty() ? timeOf(series.data[0]) : tMin), Infinity);
+            const startTime = firstTime === Infinity ? 0 : firstTime;
+            return [id, ContinuousAxisRange.from(startTime, startTime + end - start)];
+        })));
+    });
+    useEffect(() => {
+        resetForNewData();
+    }, [initialData]);
+    // pans the axes (in place) by the dragged amount
+    const onPan = useCallback((x, ranges) => panHandler(axesForSeries, margin, setAxisIntervalFor, xAxesState)(x, plotDimensions, ranges), [axesForSeries, margin, setAxisIntervalFor, xAxesState, plotDimensions]);
+    // zooms the axes (in place) by the incremental zoom factor, around each axis's pivot
+    const onZoom = useCallback((zoomFactor, pivotFor, ranges) => continuousAxisZoomHandler(axesForSeries, margin, setAxisIntervalFor, xAxesState)(zoomFactor, pivotFor, plotDimensions, ranges), [axesForSeries, margin, setAxisIntervalFor, xAxesState, plotDimensions]);
+    // what the zoom pivots on: while running, each axis's "now" (so the newest data stays put,
+    // whether or not the axis has started scrolling yet -- falling back to the axis' right edge
+    // until the view driver records a time); while paused, the mouse
+    const zoomPivotFor = useCallback((offsetX) => running ?
+        (axisId, axis) => { var _a; return (_a = currentTimeRef.current.get(axisId)) !== null && _a !== void 0 ? _a : axis.scale.domain()[1]; } :
+        (_axisId, axis) => axis.scale.invert(offsetX - margin.left), [running, margin]);
+    useCanvasZoomPan(canvasContext, {
+        panEnabled,
+        zoomEnabled,
+        keyModifiersRequired: zoomKeyModifiersRequired,
+        scaleExtent: [0, 10],
+        translateExtent: [[margin.left, margin.top], [plotDimensions.width, plotDimensions.height]],
+        // (tooltips are suppressed while panning, so that one isn't left behind)
+        onPanStart: () => {
+            if (allowTooltipRef !== undefined)
+                allowTooltipRef.current = false;
+        },
+        onPan: dx => {
+            if (canvasContext === null)
+                return;
+            onPan(dx, timeRangesRef.current);
+            updatePlotRef.current(canvasContext);
+            // the pan updated the axes' ranges in place, so report the new intervals
+            notifyIntervalsRef.current(timeRangesRef.current);
+        },
+        onPanEnd: () => {
+            var _a;
+            if (allowTooltipRef !== undefined)
+                allowTooltipRef.current = !((_a = dataSource === null || dataSource === void 0 ? void 0 : dataSource.running) !== null && _a !== void 0 ? _a : false);
+        },
+        onZoom: ({ factor, x }) => {
+            if (canvasContext === null)
+                return;
+            onZoom(factor, zoomPivotFor(x), timeRangesRef.current);
+            updatePlotRef.current(canvasContext);
+            // the zoom updated the axes' ranges in place, so report the new intervals
+            notifyIntervalsRef.current(timeRangesRef.current);
+        },
+        onZoomReset,
+        // restores each axis to its true original bounds (see `initialAxisIntervalsRef`), and does
+        // a full sync (through `updateTimingAndPlot`), so that the AxesProvider's own ranges pick up
+        // the reset `.original` too -- otherwise a reset while paused (with no ticks left to resync
+        // them) would leave them at the zoomed bounds, which a store-backed domain then reads back
+        resetView: () => {
+            initialAxisIntervalsRef.current.forEach(([start, end], axisId) => {
+                timeRangesRef.current.set(axisId, ContinuousAxisRange.from(start, end));
+                xAxesState.axisFor(axisId).ifPresent(axis => axis.update(AxisInterval.from(start, end), plotDimensions, margin));
+            });
+            updateTimingAndPlot(timeRangesRef.current);
+        },
+    });
+    // keeps the ranges in step with the axes when the canvas, the axes, or the plot's dimensions
+    // change (creating them the first time, and afterward updating them in place, so that their
+    // `.original` -- and the map's identity -- survive), and redraws
+    useEffect(() => {
+        if (canvasContext === null)
+            return;
+        if (timeRangesRef.current.size === 0) {
+            continuousAxisRanges(xAxesState.axes).forEach((range, id) => timeRangesRef.current.set(id, range));
+        }
+        else {
+            const intervals = continuousAxisIntervals(xAxesState.axes);
+            timeRangesRef.current.forEach((range, id, rangesMap) => {
+                const [start, end] = Optional.ofNullable(intervals.get(id))
+                    .map(interval => interval.asTuple())
+                    .getOrThrow(() => new Error(`Unable to retrieve interval for axis; axis_id: ${id}`));
+                if (!isNaN(start) && !isNaN(end)) {
+                    rangesMap.set(id, range.update(start, end));
+                }
+            });
+        }
+        updatePlot(canvasContext);
+    }, [chartId, color, canvasContext, plotDimensions, updatePlot, xAxesState]);
+    // the latest `updateTimingAndPlot`, for the view driver (created once per run) to call
+    const updateTimingAndPlotRef = useRef(updateTimingAndPlot);
+    useEffect(() => {
+        updateTimingAndPlotRef.current = updateTimingAndPlot;
+    }, [updateTimingAndPlot]);
+    // creates the view driver, with the current settings (an effect event, so that the driver is
+    // created only when the run starts, with the settings as they are then)
+    const createViewDriver = useEffectEvent((source) => timeAxisViewDriverFor(source, xAxesState, axisTimesFor, ranges => updateTimingAndPlotRef.current(ranges), (axisId, end) => currentTimeRef.current.set(axisId, end), {
+        windowingTime,
+        dataUpdatePeriod,
+        cadencePeriod: withCadenceOf,
+        timeWindowBehavior,
+        initialTimes: initialTimesRef.current,
+    }));
+    // while the data source runs (and the plot has a canvas and x-axes), drives the view from the
+    // data source's updates. The driver belongs to this plot alone, and is always torn down with it.
+    const hasXAxes = xAxesState.axes.size > 0;
+    useEffect(() => {
+        if (dataSource === undefined || !running || canvasContext === null || !hasXAxes)
+            return;
+        if (allowTooltipRef !== undefined)
+            allowTooltipRef.current = false;
+        const driver = createViewDriver(dataSource);
+        return () => {
+            driver.unsubscribe();
+            if (allowTooltipRef !== undefined)
+                allowTooltipRef.current = true;
+        };
+    }, [dataSource, running, canvasContext, hasXAxes, allowTooltipRef]);
+}
+//# sourceMappingURL=useStreamingTimeAxes.js.map

package/dist/app/charts/plots/useStreamingTimeAxes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStreamingTimeAxes.js","sourceRoot":"","sources":["../../../../src/app/charts/plots/useStreamingTimeAxes.ts"],"names":[],"mappings":"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"}

package/dist/app/charts/series/baseSeries.d.ts

@@ -1,38 +1,90 @@
-import { Result } from "result-fn";
+import { type Result } from "result-fn";
+import { FastShiftArray } from "fast-shift-array";
 /**
- * A spike series holding an array of spike (time, value) datum, the name and supplemental information
- * needed by the `RasterChart`
+ * A named series of data, the basis of every chart's series. Its data is held in a
+ * `FastShiftArray`, so that the oldest data can be dropped from its head cheaply as new data
+ * streams in.
+ * @template D The type of the series' datum
  */
 export interface BaseSeries<D> {
+    /**
+     * The name of the series (unique within a chart)
+     */
     readonly name: string;
-    data: Array<D>;
+    /**
+     * The series' data, ordered by time
+     */
+    data: FastShiftArray<D>;
+    /**
+     * @return The last datum, or a failure when the series is empty
+     */
     readonly last: () => Result<D, string>;
+    /**
+     * @return The number of data in the series
+     */
     readonly length: () => number;
+    /**
+     * @return `true` when the series has no data; `false` otherwise
+     */
     readonly isEmpty: () => boolean;
 }
+/**
+ * Default number of shifts a series' backing `FastShiftArray` accumulates before it's compacted,
+ * used whenever a caller doesn't specify one explicitly. This is deliberately much lower than
+ * `FastShiftArray`'s own default of 100,000: compaction is a single, blocking O(n) operation (it
+ * splices out all the accumulated dead slots in one call), so with the default threshold, a
+ * long-running streaming chart hits one large, very perceptible stutter once cumulative shifts
+ * cross 100,000 -- visible as a sudden jump/lag rather than a gradual slowdown. Compacting more
+ * often, on a much smaller batch each time, trades that one large pause for many much smaller
+ * (and much less noticeable) ones spread across the session.
+ *
+ * If a particular use case genuinely prefers fewer, larger pauses (e.g. a non-interactive/batch
+ * context where per-call overhead matters more than pause smoothness), pass a larger
+ * `compactingSize` explicitly to `seriesFrom`/`emptySeries`/`emptySeriesFor`.
+ */
+export declare const DEFAULT_COMPACTING_SIZE = 10000;
 /**
  * Creates a series from the name and the optional array of `Datum`.
+ *
+ * **Ownership warning:** when `data` is a plain array (or already a {@link FastShiftArray}), it is
+ * wrapped **by reference**, not copied -- the returned series' backing storage *is* that same
+ * array/`FastShiftArray`. As the chart streams in new data and ages old data out, the library calls
+ * `shift()` on it (clearing the head slot, and periodically `splice`-ing it during compaction),
+ * mutating it in place. If you keep your own reference to the array you pass in (to reuse,
+ * snapshot, or compare later), you will see it change out from under you. If you need an
+ * independent copy, pass `data.slice()` instead -- see e.g. `StreamingBarChart.tsx`,
+ * `StreamingRasterChart.tsx`, and `StreamingPoincareChart.tsx`, which all do this when re-deriving
+ * initial series from data they still hold a reference to elsewhere.
  * @param name The name of the series (i.e. neuron)
  * @param data The array of datum, which could be `(t, f(t))`, or `(f[n](x), f[n+1](x))`
- * @return A {@link BaseSeries} for object that can be used by in {@link Chart}s
+ * @param compactingSize The number of shifts the series' backing array accumulates before it's
+ * compacted (see {@link DEFAULT_COMPACTING_SIZE}). Only applies when `data` is a plain array (and
+ * so a new `FastShiftArray` is created for it) -- ignored when `data` is already a `FastShiftArray`,
+ * since compaction size is fixed at that instance's own construction time.
+ * @return A {@link BaseSeries} that can be used in {@link Chart}s
  * @see seriesFromTuples
  * @see emptySeries
  */
-export declare function seriesFrom<D>(name: string, data?: Array<D>): BaseSeries<D>;
+export declare function seriesFrom<D>(name: string, data?: Array<D> | FastShiftArray<D>, compactingSize?: number): BaseSeries<D>;
 /**
  * Returns an empty series with the specified name
  * @param name The name of the series
+ * @param compactingSize The number of shifts the series' backing array accumulates before it's
+ * compacted (see {@link DEFAULT_COMPACTING_SIZE})
  * @return The empty series
  * @see seriesFrom
  * @see seriesFromTuples
  */
-export declare const emptySeries: <D>(name: string) => BaseSeries<D>;
+export declare const emptySeries: <D>(name: string, compactingSize?: number) => BaseSeries<D>;
 /**
  * Creates an array of empty series, one for each specified name
  * @param names The names for each of the empty series
+ * @param compactingSize The number of shifts each series' backing array accumulates before it's
+ * compacted (see {@link DEFAULT_COMPACTING_SIZE})
  * @return An array of empty series with the specified names
  * @see emptySeries
  * @see seriesFrom
  * @see seriesFromTuples
  */
-export declare const emptySeriesFor: <D>(names: Array<string>) => Array<BaseSeries<D>>;
+export declare const emptySeriesFor: <D>(names: Array<string>, compactingSize?: number) => Array<BaseSeries<D>>;
+//# sourceMappingURL=baseSeries.d.ts.map

package/dist/app/charts/series/baseSeries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseSeries.d.ts","sourceRoot":"","sources":["../../../../src/app/charts/series/baseSeries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,MAAM,EAAgB,MAAM,WAAW,CAAC;AACpE,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IACzB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IACxB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACvC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAC9B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC;CACnC;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EACxB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,KAAK,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAM,EACvC,cAAc,GAAE,MAAgC,GACjD,UAAU,CAAC,CAAC,CAAC,CAmBf;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,MAAM,MAAM,EAAE,iBAAgB,MAAgC,KAAG,UAAU,CAAC,CAAC,CACpE,CAAC;AAEzC;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC,EAAE,iBAAgB,MAAgC,KAAG,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CACnE,CAAA"}