stream-charts 1.2.1 → 2.0.0

package/src/app/charts/hooks/CanvasSurfaceProvider.tsx

@@ -0,0 +1,117 @@
+import {type JSX, useCallback, useEffect, useMemo, useRef, useState} from "react";
+import {usePlotDimensions} from "./usePlotDimensions";
+import {createCanvasContext, resizeCanvasTo} from "../plots/plot";
+import type {CanvasContext} from "../d3types";
+import {CanvasSurfaceContext} from "./useCanvasSurface";
+import {initialSvgStyle, type SvgStyle} from "../styling/svgStyle";
+
+const defaultBackground = '#202020';
+
+export type Props = {
+    chartId: number
+    color: string
+    backgroundColor: string
+    svgStyle?: Partial<SvgStyle>
+    children: JSX.Element | Array<JSX.Element>
+}
+
+/**
+ * Creates and sizes the chart's `<canvas>` element, and provides the resulting canvas element and
+ * drawing context (via {@link useCanvasSurface}) to descendants -- most notably {@link ChartProvider}.
+ *
+ * Must be rendered as a descendant of {@link PlotDimensionsProvider}. The canvas's size is derived
+ * entirely from {@link usePlotDimensions}'s `plotDimensions`/`margin` -- the single source of truth
+ * for the chart's dimensions -- rather than from static width/height props. This matters because
+ * `usePlotDimensions` also exposes `updateDimensions(...)`, an escape hatch for updating
+ * dimensions independent of any prop (e.g. from a `ResizeObserver`-driven descendant); sourcing
+ * the canvas's size from the same place those updates land keeps the canvas from ever drifting out
+ * of sync with what the axes/plots believe the plot dimensions to be.
+ * @param props The properties
+ * @return The children, wrapped in the canvas-surface context provider
+ */
+export default function CanvasSurfaceProvider(props: Props): JSX.Element {
+    const {
+        chartId,
+        color,
+        backgroundColor,
+        children
+    } = props
+
+    // the container (canvas) size is the plot area plus its margins -- i.e. the inverse of what
+    // plotDimensionsFrom(width, height, margin) computes -- reconstructed from usePlotDimensions'
+    // state rather than from props, so this stays correct even when dimensions are updated via
+    // updateDimensions(...) rather than a containerDimensions prop change.
+    const {plotDimensions, margin} = usePlotDimensions()
+    const width = plotDimensions.width + margin.left + margin.right
+    const height = plotDimensions.height + margin.top + margin.bottom
+
+    const svgStyle = useMemo<SvgStyle>(
+        () => ({...initialSvgStyle, ...props.svgStyle}),
+        [props.svgStyle]
+    )
+
+    const [canvas, setCanvas] = useState<HTMLCanvasElement | null>(null)
+    const [canvasContext, setCanvasContext] = useState<CanvasContext | null>(null)
+
+    // captures the dimensions active at the exact moment this component first renders
+    const initialDimensionsRef = useRef({width, height})
+
+    // a plain ref latch, not `canvasContext` state, guards the one-time canvas-context creation
+    // below
+    const hasCreatedCanvasContext = useRef(false)
+
+    // keep the canvas's backing store in sync with the plot dimensions, however they change
+    // (prop-driven container resize, or a direct updateDimensions(...) call)
+    useEffect(
+        () => {
+            if (canvasContext) {
+                resizeCanvasTo(canvasContext, {width, height})
+                canvasContext.requestRedraw()
+            }
+        },
+        [canvasContext, width, height]
+    )
+
+    const setCanvasCallback = useCallback(
+        /**
+         * Callback for setting the canvas element and updating its CSS style.
+         * @param canvasElement - The canvas element, or null if not available (e.g. unmounting).
+         */
+        (canvasElement: HTMLCanvasElement | null) => {
+            if (canvasElement) {
+                setCanvas(canvasElement)
+
+                // create the canvas context (and do its initial sizing) exactly once, the moment
+                // the canvas element first attaches.
+                if (!hasCreatedCanvasContext.current) {
+                    hasCreatedCanvasContext.current = true
+                    const cc = createCanvasContext(chartId, canvasElement, color)
+                    resizeCanvasTo(cc, initialDimensionsRef.current)
+                    setCanvasContext(cc)
+                }
+
+                // apply the style/background/color from the defaults and any style object passed
+                // in as properties, one property at a time, rather than overwriting the whole
+                // `style` attribute
+                Object.getOwnPropertyNames(svgStyle)
+                    .filter(name => name !== 'width' && name !== 'height')
+                    .forEach(name => canvasElement.style.setProperty(name, String(svgStyle[name])))
+
+                canvasElement.style.backgroundColor = backgroundColor !== defaultBackground ? backgroundColor : ''
+                canvasElement.style.color = color
+            }
+        },
+        [backgroundColor, chartId, color, svgStyle]
+    )
+
+    const value = useMemo(() => ({canvas, canvasContext}), [canvas, canvasContext])
+
+    return (
+        <CanvasSurfaceContext.Provider value={value}>
+            <div style={{position: 'relative', width, height}}>
+                <canvas ref={setCanvasCallback}/>
+            </div>
+            {children}
+        </CanvasSurfaceContext.Provider>
+    )
+}

package/src/app/charts/hooks/ChartProvider.tsx

@@ -0,0 +1,79 @@
+import type {BaseAxis, SeriesStyle} from "../axes/axes";
+import {BaseAxisRange} from "../axes/BaseAxisRange";
+import {type JSX, useMemo} from "react";
+import {defaultUseChartValues} from "./defaultUseChartValues";
+import {useAxes} from "./useAxes";
+import {useMouse} from "./useMouse";
+import {useTooltip} from "./useTooltip";
+import {useCanvasSurface} from "./useCanvasSurface";
+import {ChartContext} from "./useChart";
+
+// the defaults (constants, so that their identity doesn't change from one render to the next)
+const DEFAULT_SERIES_FILTER = defaultUseChartValues().seriesFilter
+const NO_SERIES_STYLES = new Map<string, SeriesStyle>()
+
+/**
+ * The properties for the {@link ChartProvider}
+ * @template S The type of the series style
+ */
+export interface Props<S extends SeriesStyle> {
+    /**
+     * The unique ID for the chart
+     */
+    chartId: number
+    /**
+     * Base color
+     */
+    color: string
+    /**
+     * The base/default background color
+     */
+    backgroundColor: string
+    /**
+     * A `map(series_name -> series_line_style)` holding the style for each series
+     */
+    seriesStyles?: Map<string, S>
+    /**
+     * An optional regular expression used against the series names to determine which series to show in the chart
+     */
+    seriesFilter?: RegExp
+
+    children: JSX.Element | Array<JSX.Element>
+}
+
+/**
+ * The React context provider for the {@link UseChartValues}
+ * @param props The properties
+ * @return The children wrapped in this provider
+ * @template S The type of the series style
+ * @template AR The type of the axis range
+ * @template A The type of the axis
+ */
+export default function ChartProvider<S extends SeriesStyle, AR extends BaseAxisRange, A extends BaseAxis>(props: Props<S>): JSX.Element {
+    const {
+        chartId,
+        color,
+        backgroundColor,
+        seriesFilter = DEFAULT_SERIES_FILTER,
+        seriesStyles = NO_SERIES_STYLES as Map<string, S>,
+    } = props
+
+    // canvas/canvasContext come from CanvasSurfaceProvider (a shared ancestor -- see Chart.tsx),
+    // which sizes the canvas from usePlotDimensions() rather than from props, so this always
+    // reflects the same dimensions the axes/plots are using.
+    const {canvas, canvasContext} = useCanvasSurface()
+
+    const axes = useAxes<AR, A>()
+    const mouse = useMouse()
+    const tooltip = useTooltip()
+
+    // (memoized, so that the chart's components only re-render when something in it changes)
+    const value = useMemo(
+        () => ({chartId, color, backgroundColor, seriesStyles, seriesFilter, canvasContext, canvas, axes, mouse, tooltip}),
+        [chartId, color, backgroundColor, seriesStyles, seriesFilter, canvasContext, canvas, axes, mouse, tooltip]
+    )
+
+    return <ChartContext.Provider value={value}>
+        {props.children}
+    </ChartContext.Provider>
+}

package/src/app/charts/hooks/InteractionProvider.tsx

@@ -0,0 +1,88 @@
+import {type JSX, useMemo, useRef, useState} from "react";
+import {MouseContext, type TooltipMouseLeaveHandlerFn, type TooltipMouseOverHandlerFn, type UseMouseValues} from "./useMouse";
+import {type TooltipContentProvider, TooltipContext, type UseTooltipValues} from "./useTooltip";
+import {HoveredSeriesContext, type HoveredSeriesValues} from "./useHoveredSeries";
+
+type Props = {
+    children: JSX.Element | Array<JSX.Element>
+}
+
+/**
+ * Provides the chart's interactions: the mouse-over and mouse-leave handlers (see {@link useMouse}),
+ * the tooltip's content provider and visibility (see {@link useTooltip}), and the hovered series
+ * (see {@link useHoveredSeries}).
+ *
+ * The plots hit-test the mouse, and call the mouse handlers: a mouse-over sets the hovered series,
+ * and then calls every registered mouse-over handler (e.g. the tooltip's); a mouse-leave clears the
+ * hovered series, and calls every registered mouse-leave handler.
+ *
+ * The handler registries live in refs, so the mouse and tooltip values never change identity (the
+ * tooltip's changes only with its visibility), and registering a handler never re-renders anything.
+ * @param props The children
+ * @return The children, wrapped in the interaction contexts
+ * @template D The type of the data object for the series
+ * @template TM The type of the metadata object for the series
+ */
+export default function InteractionProvider<D, TM>(props: Props): JSX.Element {
+    const {children} = props
+
+    const mouseOverHandlersRef = useRef<Map<string, TooltipMouseOverHandlerFn<D, TM>>>(new Map())
+    const mouseLeaveHandlersRef = useRef<Map<string, (seriesName: string, providerId?: string) => void>>(new Map())
+    const tooltipContentProviderRef = useRef<TooltipContentProvider<D, TM>>(undefined)
+
+    const [hoveredSeriesName, setHoveredSeriesName] = useState<string | null>(null)
+    const [tooltipVisible, setTooltipVisible] = useState<boolean>(false)
+
+    const mouse = useMemo<UseMouseValues<D, TM>>(
+        () => ({
+            registerMouseOverHandler: (handlerId, handler) => {
+                mouseOverHandlersRef.current.set(handlerId, handler)
+                return handlerId
+            },
+            unregisterMouseOverHandler: handlerId => mouseOverHandlersRef.current.delete(handlerId),
+            mouseOverHandlerFor: (_handlerId, providerId) =>
+                (seriesName, time, tooltipData, mouseCoords) => {
+                    setHoveredSeriesName(seriesName)
+                    mouseOverHandlersRef.current.forEach(handler => handler(seriesName, time, tooltipData, mouseCoords, providerId))
+                },
+            registerMouseLeaveHandler: (handlerId, handler: TooltipMouseLeaveHandlerFn) => {
+                mouseLeaveHandlersRef.current.set(handlerId, handler)
+                return handlerId
+            },
+            unregisterMouseLeaveHandler: handlerId => mouseLeaveHandlersRef.current.delete(handlerId),
+            mouseLeaveHandlerFor: (_handlerId, providerId) =>
+                seriesName => {
+                    setHoveredSeriesName(null)
+                    mouseLeaveHandlersRef.current.forEach(handler => handler(seriesName, providerId))
+                },
+        }),
+        []
+    )
+
+    const tooltip = useMemo<UseTooltipValues<D, TM>>(
+        () => ({
+            registerTooltipContentProvider: provider => {
+                tooltipContentProviderRef.current = provider
+            },
+            tooltipContentProvider: () => tooltipContentProviderRef.current,
+            setVisibilityState: setTooltipVisible,
+            visibilityState: tooltipVisible,
+        }),
+        [tooltipVisible]
+    )
+
+    const hovered = useMemo<HoveredSeriesValues>(
+        () => ({hoveredSeriesName, setHoveredSeriesName}),
+        [hoveredSeriesName]
+    )
+
+    return (
+        <MouseContext.Provider value={mouse}>
+            <TooltipContext.Provider value={tooltip}>
+                <HoveredSeriesContext.Provider value={hovered}>
+                    {children}
+                </HoveredSeriesContext.Provider>
+            </TooltipContext.Provider>
+        </MouseContext.Provider>
+    )
+}

package/src/app/charts/hooks/PlotDimensionsProvider.tsx

@@ -0,0 +1,109 @@
+import {type JSX, useCallback, useEffect, useMemo, useRef, useState} from "react";
+import {type Dimensions, dimensionsNotEqual, type Margin, plotDimensionsFrom} from "../styling/margins";
+import {defaultPlotDimensions} from "./defaultPlotDimensions";
+import {type PlotDimensionChangeHandler, PlotDimensionsContext} from "./usePlotDimensions";
+
+export type Props = {
+    containerDimensions: Dimensions
+    margin: Margin
+    children: JSX.Element | Array<JSX.Element>
+}
+
+/**
+ * Provides the plot's dimensions and margins (see {@link usePlotDimensions}): the plot dimensions
+ * are the container's dimensions less the margins, and are updated (and the registered change
+ * handlers called) when the container's dimensions or the margins change.
+ * @param props The properties
+ * @return The children wrapped in this provider
+ */
+export default function PlotDimensionsProvider(props: Props): JSX.Element {
+    const {
+        containerDimensions,
+        margin,
+        children
+    } = props
+
+    const [dimensions, setDimensions] = useState<Dimensions>(defaultPlotDimensions().plotDimensions)
+    // holds the latest committed dimensions so the change handlers can be fired from the effect body
+    const dimensionsRef = useRef<Dimensions>(dimensions)
+    const plotDimensionChangeHandlersRef = useRef<Map<string, PlotDimensionChangeHandler>>(new Map())
+
+    // update the plot dimensions when the container size or margin change
+    useEffect(
+        () => {
+            const newDimensions = plotDimensionsFrom(containerDimensions.width, containerDimensions.height, margin)
+            if (dimensionsNotEqual(dimensionsRef.current, newDimensions)) {
+                for (const handler of plotDimensionChangeHandlersRef.current.values()) {
+                    handler(dimensionsRef.current, newDimensions)
+                }
+                dimensionsRef.current = newDimensions
+                setDimensions(newDimensions)
+            }
+        },
+        [containerDimensions, margin]
+    )
+
+    /**
+     * Updates the plot dimensions and fires any registered change handlers. Wrapped in
+     * `useCallback` (empty deps -- closes only over refs and the stable `setDimensions` setter) so
+     * its identity is stable across renders, which in turn lets the context `value` below be
+     * memoized instead of being a fresh object on every render.
+     * @param newDimensions The new plot dimensions.
+     */
+    const updateDimensions = useCallback(
+        (newDimensions: Dimensions) => {
+            if (dimensionsNotEqual(dimensionsRef.current, newDimensions)) {
+                for (const handler of plotDimensionChangeHandlersRef.current.values()) {
+                    handler(dimensionsRef.current, newDimensions)
+                }
+                dimensionsRef.current = newDimensions
+                setDimensions(newDimensions)
+            }
+        },
+        []
+    )
+
+    /**
+     * Registers a plot dimension change handler.
+     * @param handler The handler to register.
+     * @returns The handler ID.
+     */
+    const registerPlotDimensionChangeHandler = useCallback(
+        (handler: PlotDimensionChangeHandler) => {
+            const handlerId = crypto.randomUUID()
+            plotDimensionChangeHandlersRef.current.set(handlerId, handler)
+            return handlerId
+        },
+        []
+    )
+
+    /**
+     * Unregisters a plot dimension change handler.
+     * @param handlerId The handler ID.
+     * @returns True if the handler was unregistered, false if it was not found.
+     */
+    const unregisterPlotDimensionChangeHandler = useCallback(
+        (handlerId: string): boolean => plotDimensionChangeHandlersRef.current.delete(handlerId),
+        []
+    )
+
+    // memoized so consumers relying on context value identity (e.g. a useMemo/effect keyed on this
+    // context's value) don't re-run on every render of anything above this provider -- previously
+    // a fresh object literal every render, which is exactly the same class of bug already
+    // documented/worked-around for AxesProvider's context value (see e.g. ScatterPlot.tsx's note
+    // on `axesRanges` never being memoized there).
+    const value = useMemo(
+        () => ({
+            plotDimensions: dimensions,
+            margin,
+            updateDimensions,
+            registerPlotDimensionChangeHandler,
+            unregisterPlotDimensionChangeHandler
+        }),
+        [dimensions, margin, updateDimensions, registerPlotDimensionChangeHandler, unregisterPlotDimensionChangeHandler]
+    )
+
+    return <PlotDimensionsContext.Provider value={value}>
+        {children}
+    </PlotDimensionsContext.Provider>
+}

package/src/app/charts/hooks/defaultAxesValues.ts

@@ -0,0 +1,40 @@
+import {BaseAxisRange} from "../axes/BaseAxisRange";
+import type {BaseAxis} from "../axes/axes";
+import {AxesState} from "../axes/AxesState";
+import {Optional} from "result-fn";
+import type {UseAxesValues} from "./useAxes";
+
+/**
+ * No operation function for use when a default function is needed
+ */
+const noop = () => {
+    /* empty on purpose */
+}
+
+/**
+ * Default axes value
+ * @return The default values for the {@link UseAxesValues}
+ * @template AR The type of the axis range (e.g. {@link ContinuousAxisRange} or {@link OrdinalAxisRange})
+ * @template A The axis type
+ */
+export function defaultAxesValues<AR extends BaseAxisRange, A extends BaseAxis>(): UseAxesValues<AR, A> {
+    return ({
+        xAxesState: AxesState.empty(),
+        yAxesState: AxesState.empty(),
+        addXAxis: noop,
+        addYAxis: noop,
+        setAxisAssignments: noop,
+        axisAssignmentsFor: () => ({xAxis: "", yAxis: ""}),
+        updateAxisRanges: noop,
+        axesRanges: () => new Map<string, AR>(),
+        axisRangeFor: () => Optional.empty(),
+        setAxesRanges: noop,
+        setAxisRangeFor: noop,
+        setAxisIntervalFor: noop,
+        setOriginalAxisIntervalFor: noop,
+        resetAxisIntervalFor: noop,
+        resetAxesRanges: noop,
+        addAxesRangesUpdateHandler: () => noop,
+        removeAxesRangesUpdateHandler: () => noop,
+    })
+}

package/src/app/charts/hooks/defaultMouseValues.ts

@@ -0,0 +1,24 @@
+import type {UseMouseValues} from "./useMouse";
+
+/**
+ * No operation function for use when a default function is needed
+ */
+const noop = () => {
+    /* empty on purpose */
+}
+/**
+ * The default values for the {@link UseMouseValues}
+ * @return The default values for the {@link UseMouseValues}
+ * @template D The type of the data object for the series
+ * @template TM The type of the metadata object for the series
+ */
+export function defaultMouseValues<D, TM>(): UseMouseValues<D, TM> {
+    return {
+        registerMouseOverHandler: () => '',
+        unregisterMouseOverHandler: noop,
+        mouseOverHandlerFor: () => noop,
+        registerMouseLeaveHandler: () => '',
+        unregisterMouseLeaveHandler: noop,
+        mouseLeaveHandlerFor: () => noop,
+    }
+}

package/src/app/charts/hooks/defaultPlotDimensions.ts

@@ -0,0 +1,27 @@
+import type {Margin} from "../styling/margins";
+import type {UsePlotDimensionsValues} from "./usePlotDimensions";
+
+/**
+ * No operation function for use when a default function is needed
+ */
+const noop = () => {
+    /* empty on purpose */
+}
+
+/**
+ * The default values for the {@link UsePlotDimensionsValues}: zero-sized plot dimensions, the
+ * {@link defaultMargin}, and no-op functions
+ * @return The default plot-dimension values
+ */
+export const defaultPlotDimensions = (): UsePlotDimensionsValues => ({
+    plotDimensions: {width: 0, height: 0},
+    margin: defaultMargin,
+    updateDimensions: noop,
+    registerPlotDimensionChangeHandler: () => "",
+    unregisterPlotDimensionChangeHandler: noop
+})
+
+/**
+ * The default margins between the edges of the chart and the plot area
+ */
+export const defaultMargin: Margin = {top: 30, right: 20, bottom: 30, left: 50}

package/src/app/charts/hooks/defaultTooltipValues.tsx

@@ -0,0 +1,23 @@
+import type {UseTooltipValues} from "./useTooltip";
+
+/**
+ * No operation function for use when a default function is needed
+ */
+const noop = () => {
+    /* empty on purpose */
+}
+
+/**
+ * The default values for the {@link UseTooltipValues}
+ * @return The default values for the {@link UseTooltipValues}
+ * @template D The type of the data object for the series
+ * @template M The type of the metadata object for the series
+ */
+export function defaultTooltipValues<D, M>(): UseTooltipValues<D, M> {
+    return {
+        registerTooltipContentProvider: noop,
+        tooltipContentProvider: () => undefined,
+        setVisibilityState: noop,
+        visibilityState: false,
+    }
+}

package/src/app/charts/hooks/defaultUseChartValues.tsx

@@ -0,0 +1,36 @@
+import type {BaseAxis, SeriesStyle} from "../axes/axes";
+import {BaseAxisRange} from "../axes/BaseAxisRange";
+import {defaultAxesValues} from "./defaultAxesValues";
+import {defaultMouseValues} from "./defaultMouseValues";
+import {defaultTooltipValues} from "./defaultTooltipValues";
+import type {UseChartValues} from "./useChart";
+
+/**
+ * The default values for the {@link UseChartValues}
+ * @return The default values for the {@link UseChartValues}
+ * @template D The type of the series' datum
+ * @template S The type of the series style
+ * @template TM The type of the tooltip's metadata (data about the series data)
+ * @template AR The type of the axis range
+ * @template A The type of the axis
+ */
+export function defaultUseChartValues<D, S extends SeriesStyle, TM, AR extends BaseAxisRange, A extends BaseAxis>(): UseChartValues<D, S, TM, AR, A> {
+    return {
+        chartId: NaN,
+        canvas: null,
+        canvasContext: null,
+        color: '#d2933f',
+        backgroundColor: '#EEE',
+        seriesStyles: new Map<string, S>(),
+
+        // axes
+        axes: defaultAxesValues(),
+
+        // data
+        seriesFilter: /./,
+
+        // internal chart-interaction event handlers
+        mouse: defaultMouseValues(),
+        tooltip: defaultTooltipValues(),
+    }
+}