stream-charts 1.2.1 → 2.0.0

package/src/app/charts/plots/plot.ts

@@ -1,57 +1,141 @@
-import {Dimensions} from "../styling/margins";
-import * as d3 from "d3";
-import {GSelection} from "../d3types";
+import type {Dimensions} from "../styling/margins";
+import type {CanvasContext, DrawFn, DrawHandle} from "../d3types";
+import type {FastShiftArray} from "fast-shift-array";
+import type {BaseAxisRange} from "../axes/BaseAxisRange";
+import type {AxisInterval} from "../axes/AxisInterval";
 
-export type Series<D> = Array<D>
+/**
+ * A series' data: a plain array, or the `FastShiftArray` that backs a {@link BaseSeries}
+ */
+export type Series<D> = Array<D> | FastShiftArray<D>
+
+// a draw function registered with the canvas context, and where it falls in the drawing order
+interface RegisteredDraw {
+    draw: DrawFn
+    zIndex: number
+}
 
 /**
- * Creates the main SVG for holding the plot.
+ * Creates the {@link CanvasContext} for the chart -- the drawing context plus the redraw
+ * registration/scheduling API that axes, plots, and the tracker use to (re)paint themselves.
+ * Replaces the old `createPlotContainer`, which appended the root SVG `<g>`.
+ * Each redraw clears the canvas, and then calls every registered draw function in z-index order
+ * (lowest first); a draw function that throws is logged and skipped, so it doesn't blank the rest.
+ * The canvas isn't sized here: call {@link resizeCanvasTo} immediately after this with the actual
+ * container dimensions.
  * @param chartId A unique value identifying the chart.
- * @param container The SVG element interface
- * @param plotDimensions The dimensions of the plot
- * @param color The SVG `color` attribute used for the axis
+ * @param canvas The `<canvas>` DOM element backing the chart.
+ * @param color The default `color` used for text/strokes when nothing more specific is set.
+ * @return The canvas context
+ * @throws Error when the canvas has no 2D rendering context
  */
-export function createPlotContainer(
+export function createCanvasContext(
     chartId: number,
-    container: SVGSVGElement,
-    plotDimensions: Dimensions,
+    canvas: HTMLCanvasElement,
     color: string
-): GSelection {
-    const {width, height} = plotDimensions
-    return d3.select<SVGSVGElement, any>(container)
-        .attr('width', Math.max(0, width))
-        .attr('height', Math.max(0, height))
-        .attr('color', color)
-        .append<SVGGElement>('g')
-        .attr('id', `main-container-${chartId}`)
+): CanvasContext {
+    const context = canvas.getContext('2d')
+    if (!context) {
+        throw new Error(`Unable to acquire a 2D rendering context for chart ${chartId}`)
+    }
+
+    const dpr = window.devicePixelRatio || 1
+    context.textBaseline = 'alphabetic'
+    context.strokeStyle = color
+    context.fillStyle = color
+
+    const drawFns = new Map<DrawHandle, RegisteredDraw>()
+    let animationFrameId: number | null = null
+
+    const redrawNow = (): void => {
+        animationFrameId = null
+
+        // clear the full backing-store (not just the CSS-pixel size, since the backing store is
+        // scaled by devicePixelRatio and the current transform includes that scale)
+        context.save()
+        context.setTransform(1, 0, 0, 1, 0, 0)
+        context.clearRect(0, 0, canvas.width, canvas.height)
+        context.restore()
+
+        Array.from(drawFns.entries())
+            .sort(([, a], [, b]) => a.zIndex - b.zIndex)
+            .forEach(([id, {draw}]) => {
+                try {
+                    draw(canvasContext)
+                } catch (error) {
+                    // one registrant's draw failure (e.g. a misconfigured axis assignment) must not
+                    // blank every other plot/axis/tracker sharing this canvas for the frame -- and
+                    // since this runs on every subsequent data tick too, an uncaught throw here would
+                    // otherwise wedge the chart's rendering permanently rather than just once
+                    console.error(`Error while drawing "${id}"; chart_id: ${chartId}`, error)
+                }
+            })
+    }
+
+    const canvasContext: CanvasContext = {
+        chartId,
+        canvas,
+        context2D: context,
+        dpr,
+        register: (id, draw, zIndex = 0) => {
+            drawFns.set(id, {draw, zIndex})
+            canvasContext.requestRedraw()
+        },
+        unregister: (id) => {
+            drawFns.delete(id)
+            canvasContext.requestRedraw()
+        },
+        requestRedraw: () => {
+            if (animationFrameId === null) {
+                animationFrameId = window.requestAnimationFrame(redrawNow)
+            }
+        }
+    }
+
+    return canvasContext
+}
+
+/**
+ * Resizes the canvas's backing store to match `dimensions` at the current devicePixelRatio, so
+ * that drawing stays crisp on high-DPI displays, and re-applies the dpr scale to the drawing
+ * context so that one drawing-unit equals one CSS pixel. Replaces the old SVG `width`/`height`
+ * attribute updates. Call this whenever the container's pixel dimensions change, before the next
+ * redraw.
+ * @param context The canvas context
+ * @param dimensions The new overall (plot + margin) dimensions, in CSS pixels
+ */
+export function resizeCanvasTo(context: CanvasContext, dimensions: Dimensions): void {
+    const {canvas, context2D, dpr} = context
+    const width = Math.max(0, dimensions.width)
+    const height = Math.max(0, dimensions.height)
+
+    canvas.style.width = `${width}px`
+    canvas.style.height = `${height}px`
+    canvas.width = Math.round(width * dpr)
+    canvas.height = Math.round(height * dpr)
+
+    context2D.setTransform(dpr, 0, 0, dpr, 0, 0)
 }
 
 /**
- * Adds a clip area for the chart to the specified SVG element. The clip-area is given
- * an `id` of `clip-series-<chart_id>`, which because the chart ID should be unique, makes
- * this unique as well.
- * @param chartId The ID of the chart to which the clip area is to be added.
- * @param plotGroup The SVG group element to which the clip area is to be added.
- * @param plotDimensions The dimensions of the plot.
- * @return The ID of the clip-path.
+ * Clips subsequent drawing to a rectangular area. Replaces the old SVG `<clipPath>`/
+ * `setClipPathG`/`setClipPath`. Canvas clip regions are stack-based: callers must `ctx.save()`
+ * before calling this and `ctx.restore()` once the clipped drawing is done, or the clip will leak
+ * into unrelated draw calls later in the same frame.
+ * @param context The canvas context
+ * @param dimensions The dimensions of the area to clip to
+ * @param origin The top-left corner of the clip area, in canvas drawing coordinates (defaults to
+ * `(0, 0)`; pass the margin's `(left, top)` when clipping to the plot area, which is offset from
+ * the canvas origin)
  */
-export function setClipPathG(chartId: number, plotGroup: GSelection, plotDimensions: Dimensions): string {
-    const clipPathId = `chart-clip-path-${chartId}`
-
-    // remove the old clipping region and add a new one with the updated plot dimensions
-    plotGroup.select(`#${clipPathId}-defs`).remove();
-    plotGroup
-        .append('defs')
-            .attr('id', `${clipPathId}-defs`)
-        .append("clipPath")
-            .attr("id", clipPathId)
-        .append("rect")
-            .attr("x", 0)
-            .attr("y", 0)
-            .attr("width", Math.max(0, plotDimensions.width))
-            .attr("height", Math.max(0, plotDimensions.height))
-
-    return clipPathId
+export function clipToArea(
+    context: CanvasContext,
+    dimensions: Dimensions,
+    origin: {x: number, y: number} = {x: 0, y: 0}
+): void {
+    context.context2D.beginPath()
+    context.context2D.rect(origin.x, origin.y, Math.max(0, dimensions.width), Math.max(0, dimensions.height))
+    context.context2D.clip()
 }
 
 /**
@@ -72,4 +156,14 @@ export interface AxesAssignment {
  */
 export const assignAxes = (xAxis: string, yAxis: string): AxesAssignment => ({xAxis, yAxis})
 
-
+/**
+ * Converts a map holding the axes' ranges into a map holding the axes' current intervals. Used
+ * when reporting the axes' bounds to the code using the chart (see the plots' `onUpdateAxesInterval`).
+ * @param ranges A map associating an axis ID with that axis' range
+ * @return A map associating an axis ID with that axis' current interval
+ */
+export function currentIntervalsFrom(ranges: Map<string, BaseAxisRange>): Map<string, AxisInterval> {
+    const intervals = new Map<string, AxisInterval>()
+    ranges.forEach((range, axisId) => intervals.set(axisId, range.current))
+    return intervals
+}

package/src/app/charts/plots/useCanvasZoomPan.ts

@@ -0,0 +1,240 @@
+import {useCallback, useEffect, useRef} from "react";
+import * as d3 from "d3";
+import type {D3ZoomEvent} from "d3";
+import type {CanvasContext} from "../d3types";
+
+/**
+ * A zoom gesture's step, as the plot's zoom handler gets it
+ */
+export interface ZoomStep {
+    /**
+     * The zoom factor of this step alone, relative to the previous step (d3-zoom's own scale is
+     * cumulative; the zoom math in `axes.ts` is incremental -- see `ContinuousAxisRange.scale`)
+     */
+    factor: number
+    /**
+     * d3-zoom's cumulative scale (e.g. for ordinal axes, whose zoom snaps back to the original
+     * range exactly at 1 -- see `OrdinalAxisRange.scale`)
+     */
+    k: number
+    /**
+     * Where the mouse is, relative to the canvas
+     */
+    x: number
+    y: number
+}
+
+/**
+ * The options for {@link useCanvasZoomPan}
+ */
+export interface CanvasZoomPanOptions {
+    /**
+     * Whether dragging pans the plot
+     */
+    panEnabled: boolean
+    /**
+     * Whether the mouse wheel zooms the plot
+     */
+    zoomEnabled: boolean
+    /**
+     * Whether zooming requires the shift (or ctrl) key to be held down
+     */
+    keyModifiersRequired: boolean
+    /**
+     * The smallest and largest (cumulative) zoom scales
+     */
+    scaleExtent: [min: number, max: number]
+    /**
+     * Whether the wheel changes d3-zoom's scale the opposite way to d3-zoom's default, so that all
+     * the plots zoom the same way for the same gesture. Plots differ in which way their axes move
+     * with the scale: a continuous axis's range *widens* as the scale goes up (an incremental factor
+     * above 1 grows it), while an ordinal axis's (pixel) range widens its bands as the scale goes
+     * up. So the continuous-axis plots use d3-zoom's default, and the bar plot (with its ordinal
+     * axis) inverts the wheel to match them. Defaults to `false`.
+     */
+    invertWheel?: boolean
+    /**
+     * The plot's margin and dimensions, which bound the zoom's translation
+     */
+    translateExtent: [[left: number, top: number], [right: number, bottom: number]]
+    /**
+     * Called when a pan (drag) starts (e.g. to suppress tooltips while panning)
+     */
+    onPanStart?: () => void
+    /**
+     * Called for each step of a pan
+     * @param dx The horizontal distance (px) moved since the previous step
+     * @param dy The vertical distance (px) moved since the previous step
+     */
+    onPan: (dx: number, dy: number) => void
+    /**
+     * Called when a pan ends
+     */
+    onPanEnd?: () => void
+    /**
+     * Called for each step of a zoom gesture (a real one: programmatic changes to d3-zoom's
+     * transform, e.g. a reset, aren't reported)
+     * @param step The step's zoom factor, d3-zoom's cumulative scale, and the mouse position
+     */
+    onZoom: (step: ZoomStep) => void
+    /**
+     * The plot's `onZoomReset` property: called (whenever zooming is set up) with a function that
+     * resets the zoom -- d3-zoom's own transform, and then the plot's view (see `resetView`)
+     */
+    onZoomReset?: (resetZoom: () => void) => void
+    /**
+     * Restores the plot's view (its axes' original ranges) when the zoom is reset (see `onZoomReset`)
+     */
+    resetView?: () => void
+}
+
+/**
+ * The zoom controls a plot gets back from {@link useCanvasZoomPan}
+ */
+export interface CanvasZoomPanControls {
+    /**
+     * Resets d3-zoom's own (cumulative) transform to identity, e.g. when the plot's axes are reset
+     * to their original ranges -- otherwise the next zoom gesture would continue from the stale,
+     * accumulated scale
+     */
+    resetZoomTransform: () => void
+    /**
+     * Sets d3-zoom's own (cumulative) scale, e.g. when restoring a saved zoom state. Sets it
+     * directly (where d3-zoom keeps it), without dispatching a "zoom" event.
+     * @param k The scale
+     */
+    setZoomScale: (k: number) => void
+}
+
+/**
+ * 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: WheelEvent): number {
+    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: CanvasContext | null, options: CanvasZoomPanOptions): CanvasZoomPanControls {
+    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<number>(1)
+    // the attached zoom behavior (undefined while zooming isn't set up)
+    const zoomRef = useRef<d3.ZoomBehavior<HTMLCanvasElement, unknown>>(undefined)
+
+    const resetZoomTransform = useCallback(
+        (): void => {
+            if (canvasContext !== null && zoomRef.current !== undefined) {
+                d3.select<HTMLCanvasElement, unknown>(canvasContext.canvas).call(zoomRef.current.transform, d3.zoomIdentity)
+            }
+            lastKRef.current = 1
+        },
+        [canvasContext]
+    )
+
+    const setZoomScale = useCallback(
+        (k: number): void => {
+            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<HTMLCanvasElement, unknown>(canvasContext.canvas)
+
+            if (panEnabled) {
+                const drag = d3.drag<HTMLCanvasElement, unknown>()
+                    .on("start", () => {
+                        canvasSelection.style("cursor", "move")
+                        handlersRef.current.onPanStart?.()
+                    })
+                    .on("drag", event => handlersRef.current.onPan(event.dx, event.dy))
+                    .on("end", () => {
+                        canvasSelection.style("cursor", "auto")
+                        handlersRef.current.onPanEnd?.()
+                    })
+                canvasSelection.call(drag)
+            }
+
+            if (zoomEnabled) {
+                const zoom = d3.zoom<HTMLCanvasElement, unknown>()
+                    // 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: D3ZoomEvent<HTMLCanvasElement, unknown>) => {
+                        // 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 as MouseEvent
+                        handlersRef.current.onZoom({factor, k, x: offsetX, y: offsetY})
+                    })
+                canvasSelection.call(zoom)
+                zoomRef.current = zoom
+
+                onZoomReset?.(() => {
+                    resetZoomTransform()
+                    handlersRef.current.resetView?.()
+                })
+            }
+
+            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}
+}