stream-charts 1.0.0 → 1.1.0

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

@@ -0,0 +1,175 @@
+import {createContext, JSX, useContext} from "react";
+import {concat, from, Observable, Subscription} from "rxjs";
+import {ChartData} from "../observables/ChartData";
+import {useInitialData} from "./useInitialData";
+import {BaseSeries} from "../series/baseSeries";
+// import {noop} from "../utils";
+
+/**
+ * No operation function for use when a default function is needed
+ */
+const noop = () => {
+    /* empty on purpose */
+}
+
+// type SeriesObservable = Observable<TimeSeriesChartData> | Observable<IterateChartData>
+// type Data = Array<Datum> | Array<IterateDatum>
+
+/**
+ * The values exposed through the {@link useDataObservable} react hook
+ */
+interface UseObservableValues<CD extends ChartData, D> {
+    /**
+     * An observable source for chart data
+     */
+    // seriesObservable?: SeriesObservable
+    seriesObservable?: Observable<CD>
+    /**
+     * When `true` the chart will subscribe to the observable, or if already subscribed, will remain
+     * subscribed. When `false` the chart will unsubscribe to the observable if subscribed, or will
+     * remain unsubscribed if not already subscribed.
+     */
+    shouldSubscribe?: boolean
+    /**
+     * The windowing time for aggregating chart-data events. Defines the update rate of the chart.
+     * For example if chart-data events occur every 1 ms, and the windowing time is set to 10 ms,
+     * then events will be aggregated for 10 ms, and then the chart will be updated. In this example,
+     * the chart would be updated only once per 10 ms.
+     */
+    windowingTime?: number
+
+    /*
+     | USER CALLBACK FUNCTIONS
+     */
+    /**
+     * Callback function that is called when the chart subscribes to the observable
+     * @param subscription The subscription resulting form the subscribe action
+     */
+    onSubscribe: (subscription: Subscription) => void
+    /**
+     * Callback function that is called when new data arrives to the chart.
+     * @param seriesName The name of the series for which new data arrived
+     * @param data The new data that arrived in the windowing tine
+     * @see UseChartValues.windowingTime
+     */
+    onUpdateData?: (seriesName: string, data: Array<D>) => void
+    /**
+     * todo
+     * @param time
+     */
+    onUpdateChartTime?: (time: number) => void
+}
+
+const defaultObservableValues: UseObservableValues<any, any> = {
+    windowingTime: NaN,
+    shouldSubscribe: false,
+
+    // user callbacks
+    onSubscribe: noop,
+}
+
+const DataObservableContext = createContext<UseObservableValues<any, any>>(defaultObservableValues)
+
+interface Props<CD extends ChartData, D> {
+    // live data
+    seriesObservable?: Observable<CD>
+    windowingTime?: number
+    shouldSubscribe?: boolean
+
+    /*
+     | USER CALLBACK FUNCTIONS
+     */
+    /**
+     * Callback function that is called when the chart subscribes to the observable
+     * @param subscription The subscription resulting form the subscribe action
+     */
+    onSubscribe?: (subscription: Subscription) => void
+    /**
+     * Callback function that is called when new data arrives to the chart.
+     * @param seriesName The name of the series for which new data arrived
+     * @param data The new data that arrived in the windowing tine
+     * @see UseChartValues.windowingTime
+     */
+    onUpdateData?: (seriesName: string, data: Array<D>) => void
+    onUpdateChartTime?: (time: number) => void
+
+    children: JSX.Element | Array<JSX.Element>
+}
+
+/**
+ * The react context provider for the {@link UseObservableValues}
+ * @param props The properties
+ * @return The children wrapped in this provider
+ * @constructor
+ */
+export default function DataObservableProvider<CD extends ChartData, D>(props: Props<CD, D>): JSX.Element {
+
+    const {
+        seriesObservable,
+        windowingTime = defaultObservableValues.windowingTime || 100,
+        shouldSubscribe,
+
+        onSubscribe = noop,
+        onUpdateData = noop,
+        onUpdateChartTime = noop,
+    } = props
+
+    // when initial data is provided, and importantly, when a function is provided that converts
+    // the initial data into an object of type ChartData, and when there is a defined series
+    // observable, then the initial data is prepended to the data observable.
+    const {initialData, asChartData} = useInitialData<CD, D>()
+    const observable = dataObservable<CD, D>(seriesObservable, initialData, asChartData)
+
+    return <DataObservableContext.Provider
+        value={{
+            seriesObservable: observable,
+            windowingTime,
+            shouldSubscribe,
+
+            onSubscribe,
+            onUpdateData,
+            onUpdateChartTime,
+        }}
+    >
+        {props.children}
+    </DataObservableContext.Provider>
+}
+
+/**
+ * When initial data is provided, and importantly, when a function is provided that converts
+ * the initial data into an object of type ChartData, and when there is a defined series
+ * observable, then the initial data is prepended to the data observable. When only initial data
+ * is provided and a conversion function, then a creates an observable from the initial data.
+ * And, when only a defined series observable is specified, then that is used (this is the default,
+ * and backward compatible behavior).
+ * @param seriesObservable An optional series observable
+ * @param initialData An array of initial data series
+ * @param asChartData A function that converts the initial data series into chart data
+ * @return An {@link Observable} of {@link ChartData}, or an `undefined`
+ */
+function dataObservable<CD extends ChartData, D>(
+    seriesObservable?: Observable<CD>,
+    initialData?: Array<BaseSeries<D>>,
+    asChartData?: (seriesList: Array<BaseSeries<D>>) => CD
+): Observable<CD> | undefined {
+    if (seriesObservable !== undefined && initialData !== undefined && initialData.length > 0 && asChartData !== undefined) {
+        return concat(from([asChartData(initialData)]), seriesObservable)
+    } else if (initialData !== undefined && initialData.length > 0 && asChartData !== undefined) {
+        return from([asChartData(initialData)])
+    } else {
+        return seriesObservable
+    }
+}
+
+/**
+ * React hook that sets up the React context for the chart values.
+ * @return The {@link UseObservableValues} held in the React context.
+ */
+export function useDataObservable<CD extends ChartData, D>(): UseObservableValues<CD, D> {
+    const context = useContext<UseObservableValues<CD, D>>(DataObservableContext)
+    const {onSubscribe} = context
+    if (onSubscribe === undefined) {
+        throw new Error("useDataObservable can only be used when the parent is a <DataObservableProvider/>")
+    }
+    return context
+}

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

@@ -0,0 +1,65 @@
+import {createContext, JSX, useContext} from "react";
+import {BaseSeries} from "../series/baseSeries";
+import {ChartData} from "../observables/ChartData";
+
+
+/**
+ * The values exposed through the {@link useInitialData} react hook
+ */
+type UseInitialDataValues<CD extends ChartData, D> = {
+    /**
+     * An array of series representing the initial data for the chart (i.e. static data
+     * before streaming starts) where D is a datum, whose type must be the same as that
+     * used for the Observable on the chart data
+     */
+    initialData: Array<BaseSeries<D>>
+
+    /**
+     * Function that takes an array of series (which has elements of type D) and converts
+     * it into a chart data type, CD
+     * @param seriesList
+     */
+    asChartData?: (seriesList: Array<BaseSeries<D>>) => CD
+}
+
+const defaultInitialDataValues: UseInitialDataValues<any, any> = {
+    initialData: new Array<BaseSeries<any>>()
+}
+
+const InitialDataContext = createContext<UseInitialDataValues<any, any>>(defaultInitialDataValues)
+
+interface Props<CD extends ChartData, D> {
+    initialData: Array<BaseSeries<D>>
+    asChartData?: (seriesList: Array<BaseSeries<D>>) => CD
+    children: JSX.Element | Array<JSX.Element>
+}
+
+/**
+ * The React context provider for the {@link UseInitialDataValues}
+ * @param props The properties
+ * @return The children wrapped in this provider
+ * @constructor
+ */
+export default function InitialDataProvider<CD extends ChartData, D>(props: Props<CD, D>): JSX.Element {
+    const {
+        initialData,
+        asChartData
+    } = props
+
+    return <InitialDataContext.Provider value={{initialData, asChartData}}>
+        {props.children}
+    </InitialDataContext.Provider>
+}
+
+/**
+ * React hook that sets up the React context for the initial data values.
+ * @return The {@link UseInitialDataValues} held in the React context.
+ */
+export function useInitialData<CD extends ChartData, D>(): UseInitialDataValues<CD, D> {
+    const context = useContext<UseInitialDataValues<CD, D>>(InitialDataContext)
+    const {initialData} = context
+    if (initialData === undefined) {
+        throw new Error("useInitialData can only be used when the parent is a <InitialDataProvider/>")
+    }
+    return context
+}

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

@@ -0,0 +1,125 @@
+import {createContext, JSX, useContext, useRef} from "react";
+import {TooltipData} from "./useTooltip";
+
+/**
+ * No operation function for use when a default function is needed
+ */
+const noop = () => {
+    /* empty on purpose */
+}
+
+export type UseMouseValues<D, TM> = {
+    /**
+     * Adds a mouse-over-series handler with the specified ID and handler function
+     * @param handlerId The handler ID
+     * @param handler The handler function called when a mouse-over-series event occurs.
+     * The handler function is handed the series name, the time (x-value), the actual
+     * series, and the mouse coordinates over which the mouse has moved over.
+     * @return The handler ID.
+     */
+    registerMouseOverHandler: (
+        handlerId: string,
+        handler: (seriesName: string, time: number, tooltipData: TooltipData<D, TM>, mouseCoords: [x: number, y: number]) => void
+    ) => string
+    /**
+     * Removes the mouse-over-series handler with the specified ID
+     * @param handlerId The ID of the handler to remove
+     */
+    unregisterMouseOverHandler: (handlerId: string) => void
+    /**
+     * Attempts to retrieve the mouse-over-series handler for the specified ID
+     * @param handlerId The ID of the handler
+     * @return The mouse-over-series handler for the ID, or `undefined` if not found
+     */
+    mouseOverHandlerFor: (handlerId: string, providerId?: string) =>
+        ((seriesName: string, time: number, tooltipData: TooltipData<D, TM>, mouseCoords: [x: number, y: number], providerId?: string) => void) | undefined
+    /**
+     * Adds a mouse-leave-series handler with the specified ID and handler function
+     * @param handlerId The handler ID
+     * @param handler The handler function called when a mouse-leave-series event occurs
+     * @return The handler ID
+     */
+    registerMouseLeaveHandler: (handlerId: string, handler: (seriesName: string) => void) => string
+    /**
+     * Removes the mouse-leave-series handler with the specified ID
+     * @param handlerId The ID of the handler to remove
+     */
+    unregisterMouseLeaveHandler: (handlerId: string) => void
+    /**
+     * Attempts to retrieve the mouse-leave-series handler for the specified ID
+     * @param handlerId The ID of the handler
+     * @return The mouse-leave-series handler for the ID, or `undefined` if not found
+     */
+    mouseLeaveHandlerFor: (handlerId: string, providerId?: string) => ((seriesName: string, providerId?: string) => void) | undefined
+}
+
+export const defaultMouseValues = (): UseMouseValues<any, any> => ({
+    registerMouseOverHandler: () => '',
+    unregisterMouseOverHandler: noop,
+    mouseOverHandlerFor: () => undefined,
+    registerMouseLeaveHandler: () => '',
+    unregisterMouseLeaveHandler: noop,
+    mouseLeaveHandlerFor: () => undefined,
+})
+
+const MouseContext = createContext<UseMouseValues<any, any>>(defaultMouseValues())
+
+type Props = {
+    children: JSX.Element | Array<JSX.Element>
+}
+
+export default function MouseProvider<D, TM>(props: Props): JSX.Element {
+    const {children} = props
+
+    const mouseOverHandlersRef = useRef<Map<string, (seriesName: string, time: number, tooltipData: TooltipData<D, TM>, mouseCoords: [x: number, y: number], providerId?: string) => void>>(new Map())
+    const mouseLeaveHandlersRef = useRef<Map<string, (seriesName: string, providerId?: string) => void>>(new Map())
+
+    return <MouseContext.Provider
+        value={{
+            registerMouseOverHandler: (handlerId, handler) => {
+                mouseOverHandlersRef.current.set(handlerId, handler)
+                return handlerId
+            },
+            unregisterMouseOverHandler: handlerId => mouseOverHandlersRef.current.delete(handlerId),
+            mouseOverHandlerFor: (handlerId, providerId) => {
+                const handlerHoc = mouseOverHandlersRef.current.get(handlerId)
+                if (handlerHoc !== undefined) {
+                    return (seriesName: string, time: number, tooltipData: TooltipData<D, TM>, mouseCoords: [x: number, y: number])=> {
+                        handlerHoc(seriesName, time, tooltipData, mouseCoords, providerId)
+                    }
+                }
+                return undefined
+            },
+
+            registerMouseLeaveHandler: (handlerId, handler) => {
+                mouseLeaveHandlersRef.current.set(handlerId, handler)
+                return handlerId
+            },
+            unregisterMouseLeaveHandler: handlerId => mouseLeaveHandlersRef.current.delete(handlerId),
+            mouseLeaveHandlerFor: (handlerId, providerId) => {
+                const handlerHoc = mouseLeaveHandlersRef.current.get(handlerId)
+                if (handlerHoc !== undefined) {
+                    return (seriesName: string)=> {
+                        handlerHoc(seriesName, providerId)
+                    }
+                }
+                return undefined
+            },
+        }}
+    >
+        {children}
+    </MouseContext.Provider>
+}
+
+/**
+ * React hook that sets up the React context for the mouse values.
+ * @return The {@link UseMouseValues} held in the React context.
+ */
+export function useMouse<D, TM>(): UseMouseValues<D, TM> {
+    const context = useContext<UseMouseValues<D, TM>>(MouseContext)
+    const {mouseOverHandlerFor} = context
+    if (mouseOverHandlerFor === undefined || mouseOverHandlerFor === null) {
+        throw new Error("useMouse can only be used when the parent is a <MouseProvider/>")
+    }
+    return context
+}

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

@@ -0,0 +1,120 @@
+import {Dimensions, dimensionsNotEqual, Margin, plotDimensionsFrom} from "../styling/margins";
+import {createContext, JSX, useContext, useEffect, useRef, useState} from "react";
+
+/**
+ * No operation function for use when a default function is needed
+ */
+const noop = () => {
+    /* empty on purpose */
+}
+
+export const defaultMargin: Margin = {top: 30, right: 20, bottom: 30, left: 50}
+
+export type PlotDimensionChangeHandler = (previousDimensions: Dimensions, newDimensions: Dimensions) => void
+
+export type UsePlotDimensionsValues = {
+    /**
+     * The width and height (in pixels) of this chart
+     */
+    plotDimensions: Dimensions
+    /**
+     * The plot margins for the border of main G
+     */
+    margin: Margin
+    /**
+     * Update the plot dimensions (for example, on a window resize)
+     * @param dimensions the new dimensions of the plot
+     */
+    updateDimensions: (dimensions: Dimensions) => void
+    registerPlotDimensionChangeHandler: (handler: PlotDimensionChangeHandler) => string
+    unregisterPlotDimensionChangeHandler: (handlerId: string) => void
+}
+
+export const defaultPlotDimensions = (): UsePlotDimensionsValues => ({
+    plotDimensions: {width: 0, height: 0},
+    margin: defaultMargin,
+    updateDimensions: noop,
+    registerPlotDimensionChangeHandler: () => "",
+    unregisterPlotDimensionChangeHandler: noop
+})
+
+const PlotDimensionsContext = createContext<UsePlotDimensionsValues>(defaultPlotDimensions())
+
+type Props = {
+    containerDimensions: Dimensions
+    margin: Margin
+    children: JSX.Element | Array<JSX.Element>
+}
+
+export default function PlotDimensionsProvider(props: Props): JSX.Element {
+    const {
+        containerDimensions,
+        margin,
+        children
+    } = props
+
+    const [dimensions, setDimensions] = useState<Dimensions>(defaultPlotDimensions().plotDimensions)
+    const plotDimensionChangeHandersRef = 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)
+            setDimensions(prevDimensions => {
+                if (dimensionsNotEqual(prevDimensions, newDimensions)) {
+                    for(const handler of plotDimensionChangeHandersRef.current.values()) {
+                        handler(prevDimensions, newDimensions)
+                    }
+                    return newDimensions
+                }
+                return prevDimensions
+            })
+        },
+        [containerDimensions, margin]
+    )
+
+    function updateDimensions(newDimensions: Dimensions) {
+        setDimensions(prevState => {
+            for(const handler of plotDimensionChangeHandersRef.current.values()) {
+                handler(prevState, newDimensions)
+            }
+            return newDimensions
+        })
+    }
+
+    function registerPlotDimensionChangeHandler(handler: PlotDimensionChangeHandler) {
+        const handlerId = crypto.randomUUID()
+        plotDimensionChangeHandersRef.current.set(handlerId, handler)
+        return handlerId
+    }
+
+    function unregisterPlotDimensionChangeHandler(handlerId: string): boolean {
+        return plotDimensionChangeHandersRef.current.delete(handlerId)
+    }
+
+    return <PlotDimensionsContext.Provider
+        value={{
+            plotDimensions: dimensions,
+            margin,
+            updateDimensions,
+            // updateDimensions: dimensions => setDimensions(dimensions),
+            registerPlotDimensionChangeHandler,
+            unregisterPlotDimensionChangeHandler
+        }}
+    >
+        {children}
+    </PlotDimensionsContext.Provider>
+}
+
+/**
+ * React hook that sets up the React context for the plot-dimension values.
+ * @return The {@link UsePlotDimensionsValues} held in the React context.
+ */
+export function usePlotDimensions(): UsePlotDimensionsValues {
+    const context = useContext<UsePlotDimensionsValues>(PlotDimensionsContext)
+    const {plotDimensions} = context
+    if (plotDimensions === undefined || plotDimensions === null) {
+        throw new Error("usePlotDimensions can only be used when the parent is a <PlotDimensionsProvider/>")
+    }
+    return context
+}

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

@@ -0,0 +1,112 @@
+import {Series} from "../plots/plot";
+import {TooltipDimensions} from "../tooltips/tooltipUtils";
+import {createContext, JSX, useContext, useRef} from "react";
+
+/**
+ * No operation function for use when a default function is needed
+ */
+const noop = () => {
+    /* empty on purpose */
+}
+
+/**
+ * Base interface for tooltip data that is passed through to the tooltip content provider
+ */
+export interface TooltipData<D, M> {
+    series: Series<D>
+    metadata: M
+}
+
+/**
+ * A higher-order function that returns a function that provides the tooltip content or
+ * `undefined` if no tooltip content is available.
+ * @return The tooltip content, or `undefined` if no tooltip content is available.
+ * @param seriesName The name of the series for which the tooltip content is being provided
+ * @param time The time (x-value) for which the tooltip content is being provided
+ * @param tooltipData The tooltip data
+ * @param mouseCoords The mouse coordinates over which the mouse is hovering
+ * @param providerId An optional ID of the tooltip content provider.
+ */
+type TooltipContentProvider<D, M> =
+    (seriesName: string, time: number, tooltipData: TooltipData<D, M>, mouseCoords: [x: number, y: number], providerId?: string) => TooltipDimensions
+// type TooltipContentProvider<D, M> =
+//     (seriesName: string, time: number, tooltipData: TooltipData<D, M>, mouseCoords: [x: number, y: number]) => TooltipDimensions
+
+/**
+ * The functions and values exposed through the {@link useTooltip} react hook
+ */
+export type UseTooltipValues<D, M> = {
+    /**
+     * Registers the provider of the tooltip content (generally the plot will register this).
+     * When this function is called again, overwrites the previously registered provider with the
+     * one specified. This function can be called repeatedly.
+     * @param provider The function that provides the content when called.
+     */
+    registerTooltipContentProvider: (provider: TooltipContentProvider<D, M>) => void
+
+    /**
+     * @return The registered function that provides the tooltip content. If no function has been
+     * registered, then returns `undefined`.
+     */
+    tooltipContentProvider: () => (TooltipContentProvider<D, M> | undefined)
+
+    setVisibilityState: (visible: boolean) => void
+    visibilityState: boolean
+}
+
+/**
+ * The default values for the {@link UseTooltipValues}
+ */
+export const defaultTooltipValues = (): UseTooltipValues<any, any> => ({
+    registerTooltipContentProvider: noop,
+    tooltipContentProvider: () => undefined,
+    setVisibilityState: noop,
+    visibilityState: false,
+})
+
+const TooltipContext = createContext<UseTooltipValues<any, any>>(defaultTooltipValues())
+
+type Props = {
+    children: JSX.Element | Array<JSX.Element>
+}
+
+/**
+ * The tooltip context provider allows registering and retrieving tooltip content providers. When
+ * a tooltip content provider is registered with a provider ID, then it must be retrieved with that
+ * same provider ID. This allows a chart to have multiple tooltip content providers, depending on
+ * the context or types of objects being moused over. When a tooltip content provider is registered
+ * without a provider ID, then the default provider ID is used.
+ * @param props The properties holding the children
+ * @constructor
+ * @return A JSX element containing the children
+ */
+export default function TooltipProvider<D, M>(props: Props): JSX.Element {
+    const {children} = props
+
+    const tooltipContentProviderRef = useRef<TooltipContentProvider<D, M>>(undefined)
+    const visibilityStateRef = useRef<boolean>(false)
+
+    return <TooltipContext.Provider
+        value={{
+            registerTooltipContentProvider: provider => tooltipContentProviderRef.current = provider,
+            tooltipContentProvider: () => tooltipContentProviderRef.current,
+            setVisibilityState: (visible: boolean) => visibilityStateRef.current = visible,
+            visibilityState: visibilityStateRef.current
+        }}
+    >
+        {children}
+    </TooltipContext.Provider>
+}
+
+/**
+ * React hook that sets up the React context for the mouse values.
+ * @return The {@link UseTooltipValues} held in the React context.
+ */
+export function useTooltip<D, M>(): UseTooltipValues<D, M> {
+    const context = useContext<UseTooltipValues<D, M>>(TooltipContext)
+    const {registerTooltipContentProvider} = context
+    if (registerTooltipContentProvider === undefined || registerTooltipContentProvider === null) {
+        throw new Error("useTooltip can only be used when the parent is a <TooltipProvider/>")
+    }
+    return context
+}

package/src/app/charts/observables/ChartData.ts

@@ -0,0 +1,31 @@
+/**
+ * Intended base interface for chart data. All chart data need to hold
+ * a {@link Set} of series names.
+ * @see TimeSeriesChartData
+ * @see IterateChartData
+ * @see OrdinalChartData
+ */
+export interface ChartData {
+    seriesNames: Set<string>
+}
+
+/**
+ * @return A default {@link ChartData} object with an empty set of series
+ * names
+ */
+export function defaultChartData(): ChartData {
+    return {
+        seriesNames: new Set<string>()
+    }
+}
+
+/**
+ * Creates and returns a deep copy of the {@link ChartData}
+ * @param data The chart data to copy
+ * @return A deep copy of the chart data
+ */
+export function copyChartData(data: ChartData) {
+    return {
+        seriesNames: new Set(data.seriesNames.values()),
+    }
+}