stream-charts 1.2.0 → 2.0.0

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

@@ -0,0 +1,102 @@
+import {useEffect, useRef} from "react";
+import type {Optional} from "result-fn";
+import type {BaseAxis, ContinuousNumericAxis} from "../axes/axes";
+import type {BaseAxisRange} from "../axes/BaseAxisRange";
+import {ContinuousAxisRange} from "../axes/ContinuousAxisRange";
+import {grownDomain} from "../axes/autoScale";
+
+/**
+ * What a plot needs from its chart's axes to auto-scale its y-axes (see `ContinuousAxis`'s
+ * `autoScale` prop)
+ */
+export type AutoScaleAxes = {
+    /**
+     * The plot's y-axes, by their IDs
+     */
+    yAxes: Map<string, BaseAxis>
+    /**
+     * The (current and original) range of the specified axis
+     */
+    axisRangeFor: (axisId: string) => Optional<BaseAxisRange>
+    /**
+     * Updates the specified axes' ranges (which updates the axes)
+     */
+    updateAxisRanges: (ranges: Map<string, ContinuousAxisRange>) => void
+}
+
+/**
+ * The axis' range, updated to the specified domain (or a new range for it, when the axis has none)
+ * @param axisId The axis' ID
+ * @param domain The domain
+ * @param axisRangeFor The (current and original) range of the specified axis
+ * @return The updated range
+ */
+function rangeFor(
+    axisId: string,
+    [min, max]: [min: number, max: number],
+    axisRangeFor: AutoScaleAxes['axisRangeFor']
+): ContinuousAxisRange {
+    return axisRangeFor(axisId)
+        .map(range => range.update(min, max) as ContinuousAxisRange)
+        .getOrElse(ContinuousAxisRange.from(min, max))
+}
+
+/**
+ * Grows the auto-scaling y-axes to fit the specified extents of the data plotted against them
+ * (within their limits, and with their padding -- see `grownDomain`). Meant to be called from a
+ * draw function registered to run before the axes draw (they're at z-index 0), so that the axes
+ * and the data are drawn with the grown domain in the same frame.
+ * @param extents The extent of the (visible) data plotted against each y-axis, by axis ID
+ * @param axes The plot's y-axes, and their ranges
+ */
+export function growAutoScaledYAxes(
+    extents: Map<string, [min: number, max: number]>,
+    axes: AutoScaleAxes
+): void {
+    const {yAxes, axisRangeFor, updateAxisRanges} = axes
+    const updates = new Map<string, ContinuousAxisRange>()
+    extents.forEach((extent, axisId) => {
+        const axis = yAxes.get(axisId) as ContinuousNumericAxis | undefined
+        if (axis?.autoScale === undefined) return
+        const [currentMin, currentMax] = axis.scale.domain()
+        const [min, max] = grownDomain([currentMin, currentMax], extent, axis.autoScale, axis.scale)
+        if (min !== currentMin || max !== currentMax) {
+            updates.set(axisId, rangeFor(axisId, [min, max], axisRangeFor))
+        }
+    })
+    if (updates.size > 0) updateAxisRanges(updates)
+}
+
+/**
+ * New data, new scale: when the plot's data source is replaced (e.g. on a reset, or a change to
+ * the number of series), restarts the auto-scaling y-axes from their starts (and they then grow
+ * to fit the new data). Only on a *change* of data source -- not when the plot mounts with its
+ * data source, which would throw away an axis' kept growth (see `ContinuousAxis`'s
+ * `autoScaledDomain`). The axes are read through a ref, so that this only acts when the data
+ * source changes -- not, say, when an axis is added.
+ * @param dataSource The plot's data source
+ * @param axes The plot's y-axes, and their ranges
+ */
+export function useAutoScaleRestart(dataSource: unknown, axes: AutoScaleAxes): void {
+    const axesRef = useRef(axes)
+    useEffect(() => {
+        axesRef.current = axes
+    })
+
+    const dataSourceRef = useRef(dataSource)
+    useEffect(
+        () => {
+            if (dataSourceRef.current === dataSource) return
+            dataSourceRef.current = dataSource
+
+            const {yAxes, axisRangeFor, updateAxisRanges} = axesRef.current
+            const updates = new Map<string, ContinuousAxisRange>()
+            yAxes.forEach((axis, axisId) => {
+                const {autoScale} = axis as ContinuousNumericAxis
+                if (autoScale !== undefined) updates.set(axisId, rangeFor(axisId, autoScale.domain, axisRangeFor))
+            })
+            if (updates.size > 0) updateAxisRanges(updates)
+        },
+        [dataSource]
+    )
+}

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

@@ -0,0 +1,185 @@
+import * as d3 from "d3";
+import type {CurveFactory} from "d3";
+
+/**
+ * The default color of a colorized line's start (its oldest point): a blue
+ */
+export const DEFAULT_LINE_START_COLOR = '#2f6cf6'
+/**
+ * The default color of a colorized line's end (its newest point): a red
+ */
+export const DEFAULT_LINE_END_COLOR = '#e8423f'
+
+/**
+ * The default number of points it takes a colorized line's color to sweep from its start color to
+ * its end color (see `sweepFraction`)
+ */
+export const DEFAULT_LINE_COLOR_STEPS = 1000
+
+// a piece of a line, as d3's line generator traced it: where it starts and ends, and how to draw
+// it (from its start) onto a canvas path
+type LinePiece = {
+    start: [x: number, y: number]
+    end: [x: number, y: number]
+    draw: (context: CanvasPath) => void
+}
+
+/**
+ * Records the pieces of the line that d3's line generator traces (one per drawing command:
+ * `lineTo`, `bezierCurveTo`, ...), rather than drawing them, so that each piece can be stroked in
+ * its own color while keeping the curve's exact shape
+ */
+class LineRecorder {
+    readonly pieces: Array<LinePiece> = []
+    private current: [x: number, y: number] = [0, 0]
+    private subpathStart: [x: number, y: number] = [0, 0]
+
+    moveTo(x: number, y: number): void {
+        this.current = [x, y]
+        this.subpathStart = [x, y]
+    }
+
+    lineTo(x: number, y: number): void {
+        this.add([x, y], context => context.lineTo(x, y))
+    }
+
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void {
+        this.add([x, y], context => context.bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y))
+    }
+
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void {
+        this.add([x, y], context => context.quadraticCurveTo(cpx, cpy, x, y))
+    }
+
+    arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void {
+        this.add([x2, y2], context => context.arcTo(x1, y1, x2, y2, radius))
+    }
+
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void {
+        const end: [number, number] = [x + radius * Math.cos(endAngle), y + radius * Math.sin(endAngle)]
+        this.add(end, context => context.arc(x, y, radius, startAngle, endAngle, counterclockwise))
+    }
+
+    closePath(): void {
+        const [x, y] = this.subpathStart
+        this.add([x, y], context => context.lineTo(x, y))
+    }
+
+    rect(x: number, y: number, width: number, height: number): void {
+        this.moveTo(x, y)
+        this.lineTo(x + width, y)
+        this.lineTo(x + width, y + height)
+        this.lineTo(x, y + height)
+        this.closePath()
+    }
+
+    private add(end: [x: number, y: number], draw: (context: CanvasPath) => void): void {
+        this.pieces.push({start: this.current, end, draw})
+        this.current = end
+    }
+}
+
+/**
+ * Creates the function that gives the color at a fraction of the way along a colorized line:
+ * from the start color (at 0) to the end color (at 1), sweeping the long way around the hue
+ * circle, so that the line passes through the colors of the spectrum in between (e.g. from blue,
+ * through cyan, green, and yellow, to red)
+ * @param startColor The color at the line's start
+ * @param endColor The color at the line's end
+ * @return The color at a fraction (from 0 to 1) of the way along the line
+ */
+export function lineColorScale(startColor: string, endColor: string): (fraction: number) => string {
+    return d3.interpolateHslLong(startColor, endColor)
+}
+
+/**
+ * Where a point is in the color sweep of a colorized line: the line's color advances one step per
+ * point, sweeping from the start color (0) to the end color (1) over `steps` points, then back to
+ * the start color over the next `steps` points, and so on -- so the color never jumps
+ * @param pointNumber The point's overall sequence number in its series (from 0)
+ * @param steps The number of points (steps) a sweep from the start color to the end color takes
+ * @return The fraction (from 0, the start color, to 1, the end color) of the way through the sweep
+ */
+export function sweepFraction(pointNumber: number, steps: number): number {
+    const span = Math.max(1, steps)
+    const phase = (Math.max(0, pointNumber) / span) % 2
+    return phase <= 1 ? phase : 2 - phase
+}
+
+/**
+ * Creates the function that gives the color of a colorized line at a point: from the start color,
+ * one step per point, to the end color, and back (see {@link sweepFraction}), sweeping the spectrum
+ * in between (see {@link lineColorScale})
+ * @param startColor The color the sweep starts at
+ * @param endColor The color the sweep ends at
+ * @param steps The number of points (steps) a sweep from the start color to the end color takes
+ * @return The color at a point, given its overall sequence number in its series
+ */
+export function pointColorScale(startColor: string, endColor: string, steps: number): (pointNumber: number) => string {
+    const colorAt = lineColorScale(startColor, endColor)
+    return pointNumber => colorAt(sweepFraction(pointNumber, steps))
+}
+
+/**
+ * Strokes a line through the specified points, with the specified curve, whose color changes
+ * along it: each piece of the line, as the curve traces it (e.g. the segment between two points),
+ * gets the color of the point it's at (pieces are matched to points by their position along the
+ * line, since some curves trace more, or fewer, pieces than there are segments). Consecutive
+ * pieces of the same color are stroked together. The curve's shape is exactly the same as
+ * stroking the whole line at once. The context's current line width (and other stroke settings)
+ * are used.
+ * @param context The canvas 2D context to stroke onto
+ * @param points The points, in order
+ * @param x The x-coordinate (in the context's space) of a point
+ * @param y The y-coordinate (in the context's space) of a point
+ * @param curve The curve (interpolation) between the points
+ * @param colorOf The color of the line at the point with the specified index (in `points`)
+ * @template P The type of the points
+ */
+export function strokeColorizedLine<P>(
+    context: CanvasRenderingContext2D,
+    points: Array<P>,
+    x: (point: P) => number,
+    y: (point: P) => number,
+    curve: CurveFactory,
+    colorOf: (index: number) => string
+): void {
+    // (with a single point, there's no line to draw -- d3 would close the path back on itself)
+    if (points.length < 2) return
+
+    const recorder = new LineRecorder()
+    d3.line<P>().x(x).y(y).curve(curve).context(recorder as unknown as CanvasRenderingContext2D)(points)
+    const {pieces} = recorder
+    if (pieces.length === 0) return
+
+    // the index of the point a piece is at (for e.g. a linear curve, a segment's starting point)
+    const pointIndexOf = (pieceIndex: number) => pieces.length === 1 ?
+        0 :
+        Math.round(pieceIndex / (pieces.length - 1) * (points.length - 2))
+    const sameSpot = (a: [number, number], b: [number, number]) => a[0] === b[0] && a[1] === b[1]
+
+    context.save()
+    // (round joins and caps, so that consecutive runs of different colors meet without a notch)
+    context.lineJoin = 'round'
+    context.lineCap = 'round'
+    let color: string | undefined = undefined
+    let previousEnd: [number, number] | undefined = undefined
+    pieces.forEach((piece, index) => {
+        const pieceColor = colorOf(pointIndexOf(index))
+        if (pieceColor !== color) {
+            // a new color: stroke the run so far, and start a new one at this piece
+            if (color !== undefined) context.stroke()
+            color = pieceColor
+            context.strokeStyle = color
+            context.beginPath()
+            context.moveTo(piece.start[0], piece.start[1])
+        } else if (previousEnd === undefined || !sameSpot(previousEnd, piece.start)) {
+            // (a gap in the line, e.g. a new subpath)
+            context.moveTo(piece.start[0], piece.start[1])
+        }
+        piece.draw(context)
+        previousEnd = piece.end
+    })
+    context.stroke()
+    context.restore()
+}

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

@@ -0,0 +1,16 @@
+// A sentinel that represents that no curve factory is to be used, which means
+// that no line will be drawn between the iterates (kinda gross)
+import type {CurveFactory} from "d3";
+import type {BarChartElementId} from "./BarPlot";
+
+export const NoCurveFactory: CurveFactory = undefined as unknown as CurveFactory; // constants identifying the bar-chart elements for which mouse-over/mouse-leave events are defined
+
+export const STREAM_CHARTS_BAR_CHART_ID = 'stream-charts-bar-chart'
+export const TOOLTIP_PROVIDER_ID = STREAM_CHARTS_BAR_CHART_ID + '-tooltip-provider'
+export const BAR_CHART_TOOLTIP_PROVIDER_IDS: BarChartElementId = {
+    currentValue: TOOLTIP_PROVIDER_ID + '-current-value',
+    meanValue: TOOLTIP_PROVIDER_ID + '-mean-value',
+    minMax: TOOLTIP_PROVIDER_ID + '-min-max',
+    windowedMeanValue: TOOLTIP_PROVIDER_ID + '-windowed-min-max',
+    windowedMinMax: TOOLTIP_PROVIDER_ID + '-windowed-mean'
+}

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

@@ -0,0 +1,198 @@
+// Canvas has no per-shape mouse events (no SVG `.on("mouseover", ...)` equivalent) -- everything is
+// just pixels on a bitmap. So instead of attaching a handler to each `<path>`/`<circle>`, plots
+// register their drawn geometry (in canvas/pixel coordinates) here, and a single `mousemove`
+// listener on the shared canvas element hit-tests the mouse position against that geometry to
+// figure out which series (if any) the mouse is over.
+
+/** A single (x, y) point in canvas drawing coordinates (i.e. already includes the plot's margin offset). */
+export type Point = [x: number, y: number]
+
+/** An axis-aligned rectangle, in canvas coordinates. */
+export interface Rect {
+    x: number
+    y: number
+    width: number
+    height: number
+}
+
+/**
+ * The screen-space geometry for one series, as last drawn, used for hit-testing on `mousemove`.
+ * Points/segments/rects are in the same canvas coordinate space the series was drawn in
+ * (margin-offset already applied).
+ */
+export interface SeriesGeometry {
+    /** the points that make up the series, in drawing order (ignored when `segments`/`rects` is set) */
+    points: Array<Point>
+    /**
+     * When set, `points` is hit-tested as a single *connected* polyline (mouse must be within
+     * `hitRadius` pixels of a line segment between consecutive points). When unset and
+     * `segments`/`rects` is also unset, `points` are hit-tested individually as circles of radius
+     * `hitRadius` (e.g. for marker/bar-style plots where there's no connecting line).
+     */
+    asLine?: boolean
+    /**
+     * A set of *disjoint* line segments (e.g. one per raster spike) that are hit-tested
+     * independently -- unlike `asLine`, consecutive entries are NOT assumed to connect to each
+     * other. Takes precedence over `points`/`asLine` when set.
+     */
+    segments?: Array<[Point, Point]>
+    /**
+     * A set of axis-aligned rectangles (e.g. bar-chart bars), hit-tested as filled regions (exact
+     * containment, not a `hitRadius` proximity test). Takes precedence over `segments`/`points`.
+     */
+    rects?: Array<Rect>
+    /** how close (in pixels) the mouse must be to register a hit (ignored when `rects` is set) */
+    hitRadius: number
+}
+
+/**
+ * Squared distance from a point to a line segment (avoids a sqrt when just comparing distances).
+ * @param px The point's x-coordinate
+ * @param py The point's y-coordinate
+ * @param x1 The x-coordinate of the segment's start
+ * @param y1 The y-coordinate of the segment's start
+ * @param x2 The x-coordinate of the segment's end
+ * @param y2 The y-coordinate of the segment's end
+ * @return The squared distance from the point to the nearest point on the segment
+ */
+function distanceSquaredToSegment(px: number, py: number, x1: number, y1: number, x2: number, y2: number): number {
+    const dx = x2 - x1
+    const dy = y2 - y1
+    const lengthSquared = dx * dx + dy * dy
+    if (lengthSquared === 0) {
+        const ddx = px - x1
+        const ddy = py - y1
+        return ddx * ddx + ddy * ddy
+    }
+    // project point onto the segment, clamped to the segment's extent
+    let t = ((px - x1) * dx + (py - y1) * dy) / lengthSquared
+    t = Math.max(0, Math.min(1, t))
+    const closestX = x1 + t * dx
+    const closestY = y1 + t * dy
+    const ddx = px - closestX
+    const ddy = py - closestY
+    return ddx * ddx + ddy * ddy
+}
+
+/**
+ * The result of a hit-test: which series was hit, and the index of the specific point (for
+ * point/polyline geometry) or segment (for disjoint-segment geometry) that matched -- so callers
+ * can look up the specific datum involved (e.g. for a tooltip) rather than just the series name.
+ */
+export interface SeriesHit {
+    /** the name of the series that was hit */
+    name: string
+    /**
+     * the index of the point (for point or polyline geometry -- for a polyline, whichever end of
+     * the hit segment is nearer the mouse), segment, or rect that was hit
+     */
+    index: number
+}
+
+/**
+ * Finds the series (and specific point/segment within it) hit by the given mouse position.
+ * Entries are checked in *reverse* insertion order -- i.e. most-recently-added first -- and the
+ * first entry with any qualifying match wins, matching normal DOM/SVG hit-testing (the topmost
+ * element captures the pointer) rather than picking whichever entry happens to report the smallest
+ * geometric distance across all entries.
+ *
+ * This distinction matters whenever two entries visually overlap: e.g. a bar-chart's value-line
+ * segment is drawn on top of (and can extend slightly beyond) its min/max bar's rect. A rect is a
+ * containment test -- any point inside it is unambiguously "hit," with no notion of "how close" --
+ * so comparing it against a segment's proximity-based distance would let the rect win everywhere
+ * the two overlap, even dead-center on the line, since 0 distance beats any nonzero one. Since
+ * plots insert geometry in the same order they draw it, checking entries topmost-first resolves
+ * this the way it looks on screen: whichever shape is drawn last (visually on top) claims the
+ * pointer first, and only falls through to earlier (lower) entries where it doesn't match at all.
+ *
+ * Within a single entry (e.g. Scatter's many polyline segments, or Raster's many disjoint spikes)
+ * the closest qualifying point/segment still wins, since there's no z-order to speak of among
+ * pieces of the same drawn shape.
+ * @param mouseX The mouse's x-coordinate, in the same canvas coordinate space the geometry was recorded in
+ * @param mouseY The mouse's y-coordinate, in the same canvas coordinate space the geometry was recorded in
+ * @param geometry A `map(series_name -> SeriesGeometry)` as last drawn, in draw order
+ * @return The hit series and matched index, or `undefined` if the mouse isn't over any series
+ */
+export function seriesAt(mouseX: number, mouseY: number, geometry: Map<string, SeriesGeometry>): SeriesHit | undefined {
+    const entries = Array.from(geometry.entries()).reverse()
+
+    for (const [name, {points, asLine, segments, rects, hitRadius}] of entries) {
+        const hitRadiusSquared = hitRadius * hitRadius
+
+        if (rects !== undefined) {
+            const index = rects.findIndex(rect =>
+                mouseX >= rect.x && mouseX <= rect.x + rect.width &&
+                mouseY >= rect.y && mouseY <= rect.y + rect.height
+            )
+            if (index >= 0) return {name, index}
+            continue
+        }
+
+        if (segments !== undefined) {
+            let bestIndex = -1
+            let bestDistanceSquared = Infinity
+            segments.forEach(([[x1, y1], [x2, y2]], index) => {
+                const distanceSquared = distanceSquaredToSegment(mouseX, mouseY, x1, y1, x2, y2)
+                if (distanceSquared <= hitRadiusSquared && distanceSquared < bestDistanceSquared) {
+                    bestDistanceSquared = distanceSquared
+                    bestIndex = index
+                }
+            })
+            if (bestIndex >= 0) return {name, index: bestIndex}
+            continue
+        }
+
+        if (points.length === 0) continue
+
+        if (asLine) {
+            let bestIndex = -1
+            let bestDistanceSquared = Infinity
+            for (let i = 0; i < points.length - 1; i++) {
+                const [x1, y1] = points[i]
+                const [x2, y2] = points[i + 1]
+                const distanceSquared = distanceSquaredToSegment(mouseX, mouseY, x1, y1, x2, y2)
+                if (distanceSquared <= hitRadiusSquared && distanceSquared < bestDistanceSquared) {
+                    bestDistanceSquared = distanceSquared
+                    // attribute the hit to whichever endpoint of the segment is nearer
+                    const toStart = (mouseX - x1) ** 2 + (mouseY - y1) ** 2
+                    const toEnd = (mouseX - x2) ** 2 + (mouseY - y2) ** 2
+                    bestIndex = toStart <= toEnd ? i : i + 1
+                }
+            }
+            if (bestIndex >= 0) return {name, index: bestIndex}
+            continue
+        }
+
+        let bestIndex = -1
+        let bestDistanceSquared = Infinity
+        points.forEach(([x, y], index) => {
+            const distanceSquared = (mouseX - x) ** 2 + (mouseY - y) ** 2
+            if (distanceSquared <= hitRadiusSquared && distanceSquared < bestDistanceSquared) {
+                bestDistanceSquared = distanceSquared
+                bestIndex = index
+            }
+        })
+        if (bestIndex >= 0) return {name, index: bestIndex}
+    }
+
+    return undefined
+}
+
+/**
+ * Converts a `MouseEvent` (as received by a `canvas.addEventListener('mousemove', ...)` handler)
+ * into canvas-local coordinates, accounting for the canvas's on-page position and any CSS scaling
+ * between the canvas's backing-store size and its displayed size.
+ * @param event The mouse event
+ * @param canvas The canvas element the event was dispatched to
+ * @return The `[x, y]` position of the event, in the canvas's own CSS-pixel coordinate space
+ * (i.e. the same space `ctx` drawing calls use once the devicePixelRatio transform is applied)
+ */
+export function canvasLocalPoint(event: MouseEvent, canvas: HTMLCanvasElement): Point {
+    const rect = canvas.getBoundingClientRect()
+    const scaleX = rect.width > 0 ? canvas.clientWidth / rect.width : 1
+    const scaleY = rect.height > 0 ? canvas.clientHeight / rect.height : 1
+    return [
+        (event.clientX - rect.left) * scaleX,
+        (event.clientY - rect.top) * scaleY
+    ]
+}