stream-charts 1.2.0 → 2.0.0

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

@@ -1,22 +1,33 @@
-import { setClipPathG } from "./plot";
-import * as d3 from "d3";
+import { clipToArea } from "./plot";
+import { useStreamingTimeAxes } from "./useStreamingTimeAxes";
+import { useHoveredSeries } from "../hooks/useHoveredSeries";
 import { noop } from "../utils";
 import { useChart } from "../hooks/useChart";
-import { useCallback, useEffect, useMemo, useRef } from "react";
-import { axesForSeriesGen, continuousAxisIntervals, continuousAxisRanges, continuousAxisZoomHandler, defaultLineStyle, panHandler } from "../axes/axes";
-import { subscriptionTimeSeriesFor, subscriptionTimeSeriesWithCadenceFor } from "../subscriptions/subscriptions";
-import { useDataObservable } from "../hooks/useDataObservable";
+import { useCallback, useEffect, useRef } from "react";
+import { AxisType, checkAxisType, defaultLineStyle } from "../axes/axes";
+import { seriesAt, canvasLocalPoint } from "./hitTesting";
+import { timeSeriesAxisTimes } from "../subscriptions/viewDrivers";
+import { useDataSource, useDataSourceRunning, useInitialData } from "../hooks/useDataSource";
 import { usePlotDimensions } from "../hooks/usePlotDimensions";
-import { useInitialData } from "../hooks/useInitialData";
-import { Optional } from "result-fn";
-import { ContinuousAxisRange } from "../axes/ContinuousAxisRange";
+import { FastShiftArray } from "fast-shift-array";
 /**
- * Renders a streaming neuron raster plot for the series in the initial data and those sourced by the
- * observable specified as a property in the {@link Chart}. This component uses the {@link useChart}
+ * Renders a streaming neuron raster plot for the series held by the {@link StreamingDataSource}
+ * handed to the {@link Chart} (its `dataSource` prop). This component uses the {@link useChart}
  * hook, and therefore must be a child of the {@link Chart} in order to be plugged in to the
  * chart ecosystem (axes, tracker, tooltip).
  *
+ * The plot never subscribes to the data stream itself -- see {@link ScatterPlot} for how the
+ * application-owned data source and this plot's mount-scoped view driver divide the work.
+ *
+ * Internally, this no longer creates/updates SVG `<line>` elements. Instead, it registers a single
+ * draw function with the chart's {@link CanvasContext} that redraws every series' spikes from
+ * scratch each time the canvas repaints. Mouse hover (for the tooltip) is handled by hit-testing
+ * the mouse position against the last-drawn spike geometry -- as *disjoint* segments, since unlike
+ * a scatter series, consecutive spikes are not connected by a line (see `hitTesting.ts`). When
+ * the data source is paused, hovering over a spike shows the tooltip (when there's one).
+ *
  * @param props The properties associated with the raster plot
+ * @return `null` (the plot draws onto the chart's canvas)
  * @example
  <RasterPlot
      axisAssignments={new Map([
@@ -24,92 +35,50 @@ import { ContinuousAxisRange } from "../axes/ContinuousAxisRange";
         ['neuron2', assignAxes("x-axis-2", "y-axis-2")],
      ])}
      spikeMargin={1}
-     dropDataAfter={5000}
      panEnabled={true}
      zoomEnabled={true}
      zoomKeyModifiersRequired={true}
  />
  */
 export function RasterPlot(props) {
-    const { chartId, container, mainG, axes, color, seriesStyles, seriesFilter, mouse, hoveredSeriesRef, } = useChart();
-    const { xAxesState, yAxesState, setAxisAssignments, setAxisIntervalFor, updateAxisRanges = noop, onUpdateAxesInterval, } = axes;
+    var _a;
+    const { chartId, canvasContext, axes, seriesStyles, seriesFilter, mouse, } = useChart();
+    const { hoveredSeriesName } = useHoveredSeries();
+    const { xAxesState, yAxesState, setAxisAssignments, } = axes;
     const { mouseOverHandlerFor, mouseLeaveHandlerFor } = mouse;
     const { plotDimensions, margin } = usePlotDimensions();
-    const { seriesObservable, windowingTime = 100, shouldSubscribe, onSubscribe = noop, onUpdateData, } = useDataObservable();
+    // the application-owned source of the data, and whether it's running (streaming)
+    const dataSource = useDataSource();
+    const running = useDataSourceRunning(dataSource);
     const { initialData } = useInitialData();
-    const { axisAssignments = new Map(), dropDataAfter = Infinity, panEnabled = false, zoomEnabled = false, zoomKeyModifiersRequired = true, withCadenceOf, spikeMargin = 2, } = props;
+    const { axisAssignments = new Map(), panEnabled = false, zoomEnabled = false, zoomKeyModifiersRequired = true, withCadenceOf, spikeMargin = 2, highlightAxesOnMouseOver = false, onZoomReset = noop, } = props;
     // why do "dataRef" and "seriesRef" both hold on to the same underlying data? for performance.
     //
     // the "dataRef" and "seriesRef" both point to the same underlying data, a collection
-    // of series. The series in "dataRef" are bound to the DOM elements through d3. The "seriesRef" series
-    // are the ones that are updated as new data is streamed in.
+    // of series (held, and updated as new data is streamed in, by the data source). The series in
+    // "dataRef" are read by the canvas draw function, and the "seriesRef" map is for looking a
+    // series up by its name.
     //
     // the "dataRef" object holds on to a copy of the initial data (which is an array of
-    // time-series, e.i. an array of BaseSeries<OrdinalDatum> objects). The slice just creates a copy of
+    // time-series, e.i. an array of BaseSeries<Datum> objects). The slice just creates a copy of
     // the array, but the references to the BaseSeries objects are the same and still point to the same
     // data as the "initialData" array.
     //
-    // the "seriesRef" object is a reference to a map (series_name -> BaseSeries<OrdinalDatum>) which is
-    // used to update the data in the series. When new data enters, it is appended to one or more series.
+    // the "seriesRef" object is a reference to a map (series_name -> BaseSeries<Datum>), used to find
+    // the series under the mouse (for the tooltip).
     //
-    // the series in the "dataRef" object are the ones bound to the DOM elements in d3, and so as these
-    // are updated, d3 will update the DOM elements (the elements in this plot).
+    // the series in the "dataRef" object are the ones read by the next redraw, so as these are
+    // updated, the next canvas repaint picks up the new data.
     const dataRef = useRef(initialData.slice());
     const seriesRef = useRef(new Map(initialData.map(series => [series.name, series])));
-    // map(axis_id -> current_time) -- maps the axis ID to the current time for that axis
-    const currentTimeRef = useRef(new Map());
-    const subscriptionRef = useRef(undefined);
-    const isSubscriptionClosed = () => subscriptionRef.current === undefined || subscriptionRef.current.closed;
-    const allowTooltipRef = useRef(isSubscriptionClosed());
-    useEffect(() => {
-        currentTimeRef.current = new Map(Array.from(xAxesState.axes.keys()).map(id => [id, 0]));
-    }, [xAxesState]);
-    // set the axis assignments needed if a tooltip is being used
-    useEffect(() => {
-        setAxisAssignments(axisAssignments);
-    }, [axisAssignments, setAxisAssignments]);
-    // calculates the distinct series IDs that cover all the series in the plot
-    const axesForSeries = useMemo(() => axesForSeriesGen(initialData, axisAssignments, xAxesState), [initialData, axisAssignments, xAxesState]);
-    // updates the timing using the onUpdateTime and updatePlot references. This and the references
-    // defined above allow the axes' times to be update properly by avoid stale reference to these
-    // functions.
-    const updateTimingAndPlot = useCallback((ranges) => {
-        if (mainG !== null) {
-            onUpdateTimeRef.current(ranges);
-            updatePlotRef.current(ranges, mainG);
-            if (onUpdateAxesInterval) {
-                setTimeout(() => {
-                    const times = new Map();
-                    ranges.forEach((range, name) => times.set(name, range.current));
-                    onUpdateAxesInterval(times);
-                }, 0);
-            }
-        }
-    }, [mainG, onUpdateAxesInterval]);
-    // todo find better way
-    // when the initial data changes, then reset the plot. note that the initial data doesn't change
-    // during the normal course of updates from the observable, only when the plot is restarted.
-    useEffect(() => {
-        dataRef.current = initialData.slice();
-        seriesRef.current = new Map(initialData.map(series => [series.name, series]));
-        currentTimeRef.current = new Map(Array.from(xAxesState.axes.keys()).map(id => [id, 0]));
-        updateTimingAndPlot(new Map(Array.from(continuousAxisRanges(xAxesState.axes).entries())
-            .map(([id, range]) => {
-            // grab the current range, then calculate the minimum time from the initial data, and
-            // set that as the start, and then add the range to it for the end time
-            const [start, end] = range.original.asTuple();
-            const minTime = initialData
-                .filter(srs => { var _a; return ((_a = axisAssignments.get(srs.name)) === null || _a === void 0 ? void 0 : _a.xAxis) === id; })
-                .reduce((tMin, series) => Math.min(tMin, !series.isEmpty() ? series.data[0].time : tMin), Infinity);
-            const startTime = minTime === Infinity ? 0 : minTime;
-            return [id, ContinuousAxisRange.from(startTime, startTime + end - start)];
-        })));
-    }, 
-    // ** not happy about this **
-    // only want this effect to run when the initial data is changed, which mean all the
-    // other dependencies are recalculated anyway.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [initialData]);
+    // the last-drawn geometry for each series' spikes, in canvas coordinates, used for
+    // hit-testing mouse hover on `mousemove` (see the effect below that wires up the listener)
+    const geometryRef = useRef(new Map());
+    // the name of the series the mouse was over on the previous `mousemove`, so we know when to
+    // fire a "leave" for the old series before firing an "over" for the new one
+    const lastHoveredRef = useRef(undefined);
+    // tooltips are only shown while the data source is paused (and not while panning)
+    const allowTooltipRef = useRef(!((_a = dataSource === null || dataSource === void 0 ? void 0 : dataSource.running) !== null && _a !== void 0 ? _a : false));
     /**
      * Calculates the upper and lower y-coordinate for the spike line
      * @param categorySize The size of the category (i.e. plot_height / num_series)
@@ -130,227 +99,159 @@ export function RasterPlot(props) {
         };
     }
     /**
-     * Adjusts the time-range and updates the plot when the plot is dragged to the left or right
-     * @param deltaX The amount that the plot is dragged
-     * @param plotDimensions The dimensions of the plot
-     * @param series An array of series names
-     * @param ranges A map holding the axis ID and its associated time range
-     */
-    const onPan = useCallback((x, plotDimensions, ranges) => panHandler(axesForSeries, margin, setAxisIntervalFor, xAxesState)(x, plotDimensions, ranges), [axesForSeries, margin, setAxisIntervalFor, xAxesState]);
-    /**
-     * Called when the user uses the scroll wheel (or scroll gesture) to zoom in or out. Zooms in/out
-     * at the location of the mouse when the scroll wheel or gesture was applied.
-     * @param transform The d3 zoom transformation information
-     * @param x The x-position of the mouse when the scroll wheel or gesture is used
-     * @param plotDimensions The dimensions of the plot
-     * @param series An array of series names
-     * @param ranges A map holding the axis ID and its associated time-range
+     * (Re-)registers this plot's draw function with the canvas context and requests a redraw.
+     * Replaces the old version, which directly mutated SVG `<line>` elements bound via d3's
+     * enter/update/exit join. Canvas has no persistent elements to join against, so the draw
+     * function just redraws every spike from current data/scale state each time it's invoked.
+     *
+     * Pan/zoom behavior setup lives in a separate effect (see below), not here -- this function
+     * runs on every data tick (each `windowingTime` interval), and recreating/reattaching a
+     * `d3.drag()`/`d3.zoom()` behavior that often is pure overhead unrelated to drawing the new
+     * data.
+     * @param cc The canvas context to register the draw function with
      */
-    const onZoom = useCallback((transform, x, plotDimensions, ranges) => continuousAxisZoomHandler(axesForSeries, margin, setAxisIntervalFor, xAxesState)(transform, x, plotDimensions, ranges), [axesForSeries, margin, setAxisIntervalFor, xAxesState]);
-    /**
-     * @param timeRanges
-     * @param mainGElem
-     */
-    const updatePlot = useCallback((timeRanges, mainGElem) => {
-        if (container) {
-            // select the svg element bind the data to them
-            const svg = d3.select(container);
-            // set up panning
-            if (panEnabled) {
-                const drag = d3.drag()
-                    .on("start", () => {
-                    d3.select(container).style("cursor", "move");
-                    allowTooltipRef.current = false;
-                })
-                    .on("drag", (event) => {
-                    onPan(event.dx, plotDimensions, timeRanges);
-                    // need to update the plot with the new time-ranges
-                    updatePlotRef.current(timeRanges, mainGElem);
-                })
-                    .on("end", () => {
-                    d3.select(container).style("cursor", "auto");
-                    allowTooltipRef.current = isSubscriptionClosed();
-                });
-                svg.call(drag);
-            }
-            // set up for zooming
-            if (zoomEnabled) {
-                const zoom = d3.zoom()
-                    .filter((event) => !zoomKeyModifiersRequired || event.shiftKey || event.ctrlKey)
-                    .scaleExtent([0, 10])
-                    .translateExtent([[margin.left, margin.top], [plotDimensions.width, plotDimensions.height]])
-                    .on("zoom", (event) => {
-                    onZoom(event.transform, event.sourceEvent.offsetX - margin.left, plotDimensions, timeRanges);
-                    updatePlotRef.current(timeRanges, mainGElem);
-                });
-                svg.call(zoom);
-            }
+    const updatePlot = useCallback((cc) => {
+        const draw = (context) => {
+            const { context2D } = context;
+            context2D.save();
+            clipToArea(context, plotDimensions, { x: margin.left, y: margin.top });
+            context2D.translate(margin.left, margin.top);
+            const newGeometry = new Map();
             // enter, update, delete the raster data
             dataRef.current.forEach(series => {
                 const [xAxis, yAxis] = axesFor(series.name, axisAssignments, axisId => xAxesState.axisFor(axisId).getOrUndefined(), axisId => yAxesState.axisFor(axisId).getOrUndefined());
+                if (xAxis === undefined || yAxis === undefined)
+                    return;
                 // grab the series styles, or the defaults if none exist
-                const { color, lineWidth, highlightColor, highlightWidth, margin: spikeLineMargin = spikeMargin } = seriesStyles.get(series.name) || Object.assign(Object.assign({}, defaultLineStyle()), { highlightColor: defaultLineStyle().color });
-                const isHovered = hoveredSeriesRef.current === series.name;
-                const strokeColor = isHovered ? highlightColor : color;
+                const { color: seriesColor, lineWidth, highlightColor, highlightWidth, margin: spikeLineMargin = spikeMargin } = seriesStyles.get(series.name) || {
+                    ...defaultLineStyle(),
+                    highlightColor: defaultLineStyle().color
+                };
+                const isHovered = hoveredSeriesName === series.name;
+                const strokeColor = isHovered ? highlightColor : seriesColor;
                 const strokeWidth = isHovered ? (highlightWidth || lineWidth) : lineWidth;
                 // only show the data for which the regex filter matches
-                const plotData = (series.name.match(seriesFilter)) ? series.data : [];
-                const seriesContainer = svg
-                    .select(`#${series.name}-${chartId}-raster`)
-                    .selectAll('line')
-                    .data(plotData);
-                //
-                // enter new elements
+                const plotData = (series.name.match(seriesFilter)) ? series.data : FastShiftArray.empty();
+                // grab the functions that are used to determine the lower and upper coordinates of
+                // the raster line (y1, y2) and then calculate the values (y1, y2) using those functions
                 const { yUpper, yLower } = yCoordsFn(yAxis.scale.bandwidth(), lineWidth, spikeLineMargin);
-                // grab the value (index) associated with the series name (this is a category axis)
                 const y = yAxis.scale(series.name) || 0;
-                // enter
-                seriesContainer
-                    .enter()
-                    .append('line')
-                    .attr('x1', datum => datum.x)
-                    .attr('x2', datum => datum.x)
-                    .attr('y1', _ => yUpper(y))
-                    .attr('y2', _ => yLower(y))
-                    .attr('stroke', strokeColor)
-                    .attr('stroke-width', strokeWidth)
-                    .attr('data-series-name', series.name)
-                    .attr('class', 'spikes-lines')
-                    .on("mouseover", (event, datumArray) => handleMouseOverSeries(container, xAxis, series.name, datumArray, event, margin, seriesStyles, allowTooltipRef.current, mouseOverHandlerFor(`tooltip-${chartId}`)))
-                    .on("mouseleave", event => handleMouseLeaveSeries(series.name, event.currentTarget, seriesStyles, mouseLeaveHandlerFor(`tooltip-${chartId}`)))
-                    .each(datum => datum.x = xAxis.scale(datum.time));
-                // update
-                seriesContainer
-                    .each(datum => datum.x = xAxis.scale(datum.time))
-                    .attr('x1', datum => datum.x)
-                    .attr('x2', datum => datum.x)
-                    .attr('y1', _ => yUpper(y))
-                    .attr('y2', _ => yLower(y))
-                    .attr('stroke', strokeColor)
-                    .attr('stroke-width', strokeWidth);
-                // exit old elements
-                seriesContainer.exit().remove();
+                const y1 = yUpper(y);
+                const y2 = yLower(y);
+                context2D.strokeStyle = strokeColor;
+                context2D.lineWidth = strokeWidth;
+                const segments = [];
+                for (let i = 0; i < plotData.length; i++) {
+                    const x = xAxis.scale(plotData[i].x);
+                    context2D.beginPath();
+                    context2D.moveTo(x, y1);
+                    context2D.lineTo(x, y2);
+                    context2D.stroke();
+                    segments.push([[x + margin.left, y1 + margin.top], [x + margin.left, y2 + margin.top]]);
+                }
+                newGeometry.set(series.name, {
+                    points: [],
+                    segments,
+                    hitRadius: Math.max(4, strokeWidth)
+                });
             });
-        }
+            geometryRef.current = newGeometry;
+            context2D.restore();
+        };
+        cc.register(`raster-plot-${chartId}`, draw, 10);
+        cc.requestRedraw();
     }, [
-        axisAssignments, chartId, container, margin,
-        mouseLeaveHandlerFor, mouseOverHandlerFor, onPan, onZoom,
-        panEnabled,
-        plotDimensions,
-        seriesFilter, seriesStyles,
-        xAxesState, yAxesState,
-        zoomEnabled, zoomKeyModifiersRequired,
-        spikeMargin,
-        hoveredSeriesRef
+        axisAssignments, chartId, plotDimensions, seriesFilter, seriesStyles, xAxesState, yAxesState,
+        spikeMargin, hoveredSeriesName, margin.left, margin.top
     ]);
-    // need to keep the function references for use by the subscription, which forms a closure
-    // on them. without the references, the closures become stale, and resizing during streaming
-    // doesn't work properly
-    const updatePlotRef = useRef(noop);
+    // the time axes: their ranges, the view driver, panning and zooming, highlighting, and
+    // reporting the axes' intervals -- see `useStreamingTimeAxes`
+    useStreamingTimeAxes({
+        canvasContext,
+        dataSource,
+        running,
+        initialData,
+        timeOf: datum => datum.x,
+        axisTimesFor: timeSeriesAxisTimes(axisAssignments, xAxesState),
+        axisAssignments,
+        updatePlot,
+        onDataReset: () => {
+            dataRef.current = initialData.slice();
+            seriesRef.current = new Map(initialData.map(series => [series.name, series]));
+        },
+        allowTooltipRef,
+        panEnabled,
+        zoomEnabled,
+        zoomKeyModifiersRequired,
+        onZoomReset,
+        withCadenceOf,
+        highlightAxesOnMouseOver,
+    });
+    // the series' axis assignments, for the chart (e.g. the tooltip looks up a spike's row's axis)
+    useEffect(() => {
+        setAxisAssignments(axisAssignments);
+    }, [axisAssignments, setAxisAssignments]);
+    // wires up a single mousemove/mouseleave listener on the shared canvas to replace the old
+    // per-element SVG mouseover/mouseleave handlers. Hit-tests the mouse position against the
+    // last-drawn spike geometry (see `geometryRef`, populated by the draw function above).
     useEffect(() => {
-        if (mainG !== null && container !== null) {
-            // when the update plot function doesn't yet exist, then create the container holding the plot
-            const clipPathId = setClipPathG(chartId, mainG, plotDimensions);
-            if (updatePlotRef.current === noop) {
-                mainG
-                    .selectAll('g')
-                    .attr("clip-path", `url(#${clipPathId})`)
-                    .data(dataRef.current)
-                    .enter()
-                    .append('g')
-                    .attr('class', 'spikes-series')
-                    .attr('id', series => `${series.name}-${chartId}-raster`)
-                    .attr('transform', `translate(${margin.left}, ${margin.top})`);
+        if (!canvasContext)
+            return;
+        const canvas = canvasContext.canvas;
+        const handleMove = (event) => {
+            if (!allowTooltipRef.current)
+                return;
+            const [x, y] = canvasLocalPoint(event, canvas);
+            const hit = seriesAt(x, y, geometryRef.current);
+            if ((hit === null || hit === void 0 ? void 0 : hit.name) === lastHoveredRef.current && hit !== undefined) {
+                // still hovering the same series -- no enter/leave to fire, but the specific
+                // spike may have changed, so fall through and re-report below
             }
-            else {
-                mainG
-                    .selectAll('g')
-                    .attr("clip-path", `url(#${clipPathId})`);
+            else if (lastHoveredRef.current !== undefined) {
+                handleMouseLeaveSeries(lastHoveredRef.current, mouseLeaveHandlerFor(`tooltip-${chartId}`));
             }
-            updatePlotRef.current = updatePlot;
-        }
-    }, [chartId, container, mainG, margin, plotDimensions, updatePlot]);
-    // grab a reference to the function used to update the time ranges and update that reference
-    // if the function changes (solve for stale closures)
-    const onUpdateTimeRef = useRef(updateAxisRanges);
-    useEffect(() => {
-        onUpdateTimeRef.current = updateAxisRanges;
-    }, [updateAxisRanges]);
-    // memoized function for subscribing to the chart-data observable
-    const subscribe = useCallback(() => {
-        if (seriesObservable === undefined || mainG === null)
-            return undefined;
-        if (withCadenceOf !== undefined) {
-            return subscriptionTimeSeriesWithCadenceFor(seriesObservable, onSubscribe, windowingTime, axisAssignments, xAxesState, onUpdateData, dropDataAfter, updateTimingAndPlot, 
-            // as new data flows into the subscription, the subscription
-            // updates this map directly (for performance)
-            seriesRef.current, (axisId, end) => currentTimeRef.current.set(axisId, end), withCadenceOf);
-        }
-        return subscriptionTimeSeriesFor(seriesObservable, onSubscribe, windowingTime, axisAssignments, xAxesState, onUpdateData, dropDataAfter, updateTimingAndPlot, 
-        // as new data flows into the subscription, the subscription
-        // updates this map directly (for performance)
-        seriesRef.current, (axisId, end) => currentTimeRef.current.set(axisId, end));
-    }, [
-        axisAssignments, dropDataAfter, mainG,
-        onSubscribe, onUpdateData,
-        seriesObservable, updateTimingAndPlot, windowingTime, xAxesState,
-        withCadenceOf
-    ]);
-    const timeRangesRef = useRef(new Map());
-    useEffect(() => {
-        if (container && mainG) {
-            // so this gets a bit complicated. the time-ranges need to be updated whenever the time-ranges
-            // change. for example, as data is streamed in, the times change, and then we need to update the
-            // time-range. however, we want to keep the time-ranges to reflect their original scale so that
-            // we can zoom properly (so the updates can't fuck with the scale). At the same time, when the
-            // interpolation changes, then the update plot changes, and the time-ranges must maintain their
-            // original scale as well.
-            if (timeRangesRef.current.size === 0) {
-                // when no time-ranges have yet been created, then create them and hold on to a mutable
-                // reference to them
-                timeRangesRef.current = continuousAxisRanges(xAxesState.axes);
+            if (hit !== undefined) {
+                const series = seriesRef.current.get(hit.name);
+                const selectedDatum = series === null || series === void 0 ? void 0 : series.data[hit.index];
+                const xAxis = axesFor(hit.name, axisAssignments, axisId => xAxesState.axisFor(axisId).getOrUndefined(), axisId => yAxesState.axisFor(axisId).getOrUndefined())[0];
+                if (series !== undefined && selectedDatum !== undefined && xAxis !== undefined) {
+                    handleMouseOverSeries(xAxis, hit.name, selectedDatum, series.data, [x, y], margin, mouseOverHandlerFor(`tooltip-${chartId}`));
+                }
             }
-            else {
-                // when the time-ranges already exist, then we want to update the time-ranges for each
-                // existing time-range in a way that maintains the original scale.
-                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}`));
-                    // .getOrElse([NaN, NaN])
-                    if (!isNaN(start) && !isNaN(end)) {
-                        // update the reference map with the new (start, end) portion of the range,
-                        // while keeping the original scale intact
-                        rangesMap.set(id, range.update(start, end));
-                    }
-                });
+            lastHoveredRef.current = hit === null || hit === void 0 ? void 0 : hit.name;
+        };
+        const handleLeaveCanvas = () => {
+            if (lastHoveredRef.current !== undefined) {
+                handleMouseLeaveSeries(lastHoveredRef.current, mouseLeaveHandlerFor(`tooltip-${chartId}`));
+                lastHoveredRef.current = undefined;
             }
-            updatePlot(timeRangesRef.current, mainG);
-        }
-    }, [chartId, color, container, mainG, plotDimensions, updatePlot, xAxesState]);
-    // subscribe/unsubscribe to the observable chart data. when the `shouldSubscribe`
-    // is changed to `true` and we haven't subscribed yet, then subscribe. when the
-    // `shouldSubscribe` is `false` and we had subscribed, then unsubscribe. otherwise,
-    // do nothing.
+        };
+        canvas.addEventListener('mousemove', handleMove);
+        canvas.addEventListener('mouseleave', handleLeaveCanvas);
+        return () => {
+            canvas.removeEventListener('mousemove', handleMove);
+            canvas.removeEventListener('mouseleave', handleLeaveCanvas);
+        };
+    }, [canvasContext, chartId, margin, axisAssignments, xAxesState, yAxesState, mouseOverHandlerFor, mouseLeaveHandlerFor]);
+    // this plot needs a data source (see the `Chart`'s `dataSource` prop)
     useEffect(() => {
-        var _a;
-        if (shouldSubscribe && subscriptionRef.current === undefined) {
-            subscriptionRef.current = subscribe();
-            allowTooltipRef.current = false;
-        }
-        else if (!shouldSubscribe && subscriptionRef.current !== undefined) {
-            (_a = subscriptionRef.current) === null || _a === void 0 ? void 0 : _a.unsubscribe();
-            subscriptionRef.current = undefined;
-            allowTooltipRef.current = true;
+        if (dataSource === undefined) {
+            console.error("RasterPlot requires a data source; set the enclosing Chart's `dataSource` prop");
         }
-    }, [shouldSubscribe, subscribe]);
+    }, [dataSource]);
+    // unregister this plot's draw function on unmount
+    useEffect(() => {
+        return () => {
+            if (canvasContext) {
+                canvasContext.unregister(`raster-plot-${chartId}`);
+            }
+        };
+    }, [canvasContext, chartId]);
     return null;
 }
 /**
- * Attempts to locate the x- and y-axes for the specified series. If no axis is found for the
- * series name, then uses the default returned by the useChart() hook.
+ * Attempts to locate the x- and y-axes for the specified series. If the series has no axis
+ * assignment, then uses the default (first) x- and y-axes.
  * @param seriesName Name of the series for which to retrieve the axis
  * @param axisAssignments A map holding the series name and the associated x- and y-axes assigned
  * to that series. Note that the series in the axis-assignment map is merely a subset of the set
@@ -358,63 +259,54 @@ export function RasterPlot(props) {
  * @param xAxisFor The function that accepts an axis ID and returns the corresponding x-axis
  * @param yAxisFor The function that accepts an axis ID and returns the corresponding y-axis
  * @return A 2d tuple holding the linear x-axis as its first element and the category y-axis as
- * the second element.
+ * the second element (either is actually `undefined` when it isn't found, despite the type).
+ * @throws Error when the x-axis isn't a continuous numeric axis, or the y-axis isn't a category axis
  */
 function axesFor(seriesName, axisAssignments, xAxisFor, yAxisFor) {
     const axes = axisAssignments.get(seriesName);
     const xAxis = xAxisFor((axes === null || axes === void 0 ? void 0 : axes.xAxis) || "");
+    checkAxisType("RasterPlot", "x", xAxis, AxisType.ContinuousNumeric);
     const xAxisLinear = xAxis;
-    if (xAxis && !xAxisLinear) {
-        throw Error("Raster plot requires that x-axis be of type LinearAxis");
-    }
     const yAxis = yAxisFor((axes === null || axes === void 0 ? void 0 : axes.yAxis) || "");
+    checkAxisType("RasterPlot", "y", yAxis, AxisType.OrdinalString);
     const yAxisCategory = yAxis;
-    if (yAxis && !yAxisCategory) {
-        throw Error("Raster plot requires that y-axis be of type CategoryAxis");
-    }
     return [xAxisLinear, yAxisCategory];
 }
 /**
- * Renders a tooltip showing the neuron, spike time, and the spike strength when the mouse hovers over a spike.
- * @param container The chart container
+ * Reports a tooltip showing the neuron, spike time, and the spike's value when the mouse hovers over a spike.
+ * Replaces the old version, which mutated the hovered SVG `<line>`'s stroke directly; highlighting is now
+ * handled by the draw function reading `hoveredSeriesName` from chart state rather than by touching an
+ * element here.
  * @param xAxis The x-axis
  * @param seriesName The name of the series (i.e. the neuron ID)
  * @param selectedDatum The selected datum
- * @param event The mouse-over series event
+ * @param spikes All the series' spikes that the chart holds (for the tooltip's statistics)
+ * @param mouseCoords The `[x, y]` position of the mouse, in canvas coordinates
  * @param margin The plot margin
- * @param seriesStyles The series style information (needed for (un)highlighting)
- * @param allowTooltip When set to `false` won't show tooltip, even if it is visible (used by pan)
  * @param mouseOverHandlerFor The handler for the mouse over (registered by the <Tooltip/>)
  */
-function handleMouseOverSeries(container, xAxis, seriesName, selectedDatum, event, margin, seriesStyles, allowTooltip, mouseOverHandlerFor) {
+function handleMouseOverSeries(xAxis, seriesName, selectedDatum, spikes, mouseCoords, margin, mouseOverHandlerFor) {
     // grab the time needed for the tooltip ID
-    const [x, y] = d3.pointer(event, container);
+    const [x] = mouseCoords;
     const time = Math.round(xAxis.scale.invert(x - margin.left));
-    const { highlightColor, highlightWidth } = seriesStyles.get(seriesName) || defaultLineStyle();
-    // Use d3 to select element, change color and size
-    d3.select(event.currentTarget)
-        .attr('stroke', highlightColor)
-        .attr('stroke-width', highlightWidth);
-    if (mouseOverHandlerFor && allowTooltip) {
+    if (mouseOverHandlerFor) {
         // the contract for the mouse over handler is for a time-series, but here we only
         // need one point, the selected datum, and so we convert it into an array of point
         // (i.e. a time-series). The category tooltip is (and custom ones, must) be
-        // written to expect only the selected point
-        mouseOverHandlerFor(seriesName, time, { series: [selectedDatum], metadata: {} }, [x, y]);
+        // written to expect only the selected point. All the series' spikes (that the chart
+        // holds) come along in the metadata, for the tooltip's statistics
+        mouseOverHandlerFor(seriesName, time, { series: [selectedDatum], metadata: { spikes } }, mouseCoords);
     }
 }
 /**
- * Unselects the time series and calls the mouse-leave-series handler registered for this series.
+ * Calls the mouse-leave-series handler registered for this series. Replaces the old version, which
+ * also reset the hovered SVG element's stroke color/width directly; that reset is now implicit --
+ * once `hoveredSeriesName` is cleared, the next redraw simply paints the spikes in their normal
+ * (non-highlighted) style.
  * @param seriesName The name of the series (i.e. the neuron ID)
- * @param segment The SVG line element representing the spike, over which the mouse is hovering.
- * @param seriesStyles The styles for the series (for (un)highlighting)
  * @param mouseLeaverHandlerFor Registered handler for the series when the mouse leaves
  */
-function handleMouseLeaveSeries(seriesName, segment, seriesStyles, mouseLeaverHandlerFor) {
-    const { color, lineWidth } = seriesStyles.get(seriesName) || defaultLineStyle();
-    d3.select(segment)
-        .attr('stroke', color)
-        .attr('stroke-width', lineWidth);
+function handleMouseLeaveSeries(seriesName, mouseLeaverHandlerFor) {
     if (mouseLeaverHandlerFor) {
         mouseLeaverHandlerFor(seriesName);
     }