stream-charts 1.2.0 → 2.0.0

package/src/app/charts/tooltips/RasterPlotTooltipContent.tsx

@@ -1,70 +1,22 @@
-import {Dimensions, Margin} from "../styling/margins";
-import {categoryTooltipY, defaultTooltipStyle, TooltipDimensions, TooltipStyle, tooltipX} from "./tooltipUtils";
-import * as d3 from "d3";
-import {formatTime, formatValue} from "../utils";
-import {useEffect, useMemo} from "react";
-import {NoTooltipMetadata, useChart} from "../hooks/useChart";
-import {OrdinalStringAxis, SeriesLineStyle} from "../axes/axes";
+import type {ReactElement} from "react";
+import {
+    categoryTooltipY,
+    type RasterTooltipMetadata,
+    type Sparkline,
+    sparklineFor,
+    type SeriesStatistics,
+    seriesStatistics,
+    type TooltipStyle,
+    valueOrMissing
+} from "./tooltipUtils";
+import {TooltipContent} from "./TooltipContent";
+import {formatNumber, formatTime, formatValue} from "../utils";
+import {useChart} from "../hooks/useChart";
+import type {OrdinalStringAxis, SeriesLineStyle} from "../axes/axes";
 import {usePlotDimensions} from "../hooks/usePlotDimensions";
-import {Datum} from "../series/timeSeries";
-import {TooltipData} from "../hooks/useTooltip";
+import type {Datum} from "../series/timeSeries";
 import {ContinuousAxisRange} from "../axes/ContinuousAxisRange";
-
-/**
- # Want to write your own tooltip-content component?
-
- Here's how to write your own tooltip-content component.
-
- To create your own tooltip content `<MyTooltipContent/>` you must do the following:
- 1. Create a react component for your tooltip content (see for example, {@link ScatterPlotTooltipContent}
- as a reference.
- 2. Use the {@link useChart} hook to get the {@link registerTooltipContentProvider} registration function.
- 3. When your tooltip content component (`<MyTooltipContent/>`) mounts, use the {@link registerTooltipContentProvider}
- function to register your tooltip content provider.
- 4. When the chart dimensions, margin, container, etc, change, register your tooltip content provider
- again (you can register as many times as you like because it only uses the last content provider
- registered).
-
- That's it! A bit more details below.
-
- The {@link registerTooltipContentProvider} function from the {@link useChart} hook allows you to register
- one tooltip content provider. A second call to this function will cause the {@link useChart} hook to drop
- the first one in favor of the second one.
-
- The {@link registerTooltipContentProvider} function from the {@link useChart} hook accepts a higher-order
- function that allowing a closure on content/chart-specific data. Specifically, you must hand the
- {@link registerTooltipContentProvider} a function of the form:
-
- `(seriesName: string, time: number, series: TimeSeries, mouseCoords: [x: number, y: number]) => TooltipDimensions`
-
- Your function to add that actual content will be what this function calls whenever d3 fires a mouse-over
- event on one you the time-series in the chart.
-
- The code snippet below is from the `useEffect` call in the {@link ScatterPlotTooltipContent}.
- Note that the first four arguments to the {@link addTooltipContent} function are those provided by the {@link useChart} hook
- when a d3 mouse-over event occurs on one of your series. The additional six arguments are from the closure formed
- on the variables in your component. The `chartId`, `container`, `margin`, and `plotDimensions` are from the
- {@link useChart} hook called by the {@link ScatterPlotTooltipContent} component. The last two
- arguments, `defaultTooltipStyle` and `options` are specific to the {@link ScatterPlotTooltipContent}.
- For example, the `options` property is set by the caller of the {@link ScatterPlotTooltipContent}
- component.
-
- ```ts
- // register the tooltip content provider function with the chart hook (useChart) so that
- // it is visible to all children of the Chart (i.e. the <Tooltip>).
- registerTooltipContentProvider(
-     (seriesName: string, time: number, series: TimeSeries, mouseCoords: [x: number, y: number]) =>
-         addTooltipContent(
-         seriesName, time, series, mouseCoords,
-         chartId, container, margin, plotDimensions,
-         defaultTooltipStyle, options
-     )
- )
- ```
-
- This pattern allows you to supplement that `useChart` mouse-over callback with information specific to you component.
-
- */
+import type {Series} from "../plots/plot";
 
 /**
  * Options for displaying the tooltip content. These options are specific to this
@@ -75,12 +27,12 @@ import {ContinuousAxisRange} from "../axes/ContinuousAxisRange";
  * formatters.x(x), formatters.y(y)
  * ```
  */
-interface TooltipOptions {
-    formatters: {
-        x: (value: number) => string,
-        y: (value: number) => string,
-    }
-}
+// interface TooltipOptions {
+//     formatters: {
+//         x: (value: number) => string,
+//         y: (value: number) => string,
+//     }
+// }
 
 /**
  * Properties for rendering the tooltip content. The properties are applied as
@@ -89,185 +41,180 @@ interface TooltipOptions {
  * series name
  * xFormatter, yFormatter
  * ```
+ * Below that, the spikes' statistics: the mean value and standard deviation (formatted by
+ * `yFormatter`), and the mean time between spikes (formatted by `intervalFormatter`).
  */
 export interface Props {
+    /** formats the spike's time */
     xFormatter?: (value: number) => string
+    /** formats the values (the spike's value, and the mean and standard deviation of the values) */
     yFormatter?: (value: number) => string
+    /**
+     * formats the mean time between spikes (a duration, in the times' units). Defaults to the
+     * `xFormatter`, so give it its own formatter when the times are formatted as something that isn't
+     * a duration, such as the time of day
+     */
+    intervalFormatter?: (interval: number) => string
+    /** the style of the tooltip */
     style?: Partial<TooltipStyle>
 }
 
+// the size of the tooltip's sparkline (of the spikes' values over the window)
+const SPARKLINE_WIDTH = 180
+const SPARKLINE_HEIGHT = 36
+
+/**
+ * The data needed to render the tooltip's content, captured when the mouse moves over an element
+ */
+interface RasterTooltipContent {
+    seriesName: string
+    spikeTime: number
+    value: number
+    // statistics of the series' spikes in the window (the data the chart holds)
+    statistics: SeriesStatistics | undefined
+    // the spikes' values over the window, when there are enough of them to draw
+    sparkline: Sparkline | undefined
+    // the spike's row's axis (the tooltip is centered on the row)
+    axis: OrdinalStringAxis
+}
+
 /**
- * Adds tooltip content that shows the series name and the (time, value) of the selected point.
+ * Adds tooltip content that shows the series name, the (time, value) of the selected spike, the
+ * statistics of the series' spikes in the window of data the chart holds (their count, the mean
+ * and standard deviation of their values, and the mean time between them), and a sparkline of
+ * their values over the window, with the selected spike marked.
  * ```
  * series name
  * time, value
+ * statistics
+ * sparkline
  * ```
  *
- * Registers the tooltip-content provider with the `ChartContext` so that when d3 fires a mouse-over
- * event on a series. The content provider is returns the {@link addTooltipContent} function
- * when called. And when called the {@link addTooltipContent} function adds the actual tooltip
- * content to the SVG element.
+ * Built on {@link TooltipContent}; put it inside a {@link Tooltip}.
  * @param props The properties describing the tooltip content
- * @return null
+ * @return The tooltip's portal, or `null` when nothing is being hovered
  */
-export function RasterPlotTooltipContent(props: Props): null {
-    const {
-        chartId,
-        container,
-        tooltip,
-        axes
-    } = useChart<Datum, SeriesLineStyle, NoTooltipMetadata, ContinuousAxisRange, OrdinalStringAxis>()
-
-    const {registerTooltipContentProvider} = tooltip
-
-    const {
-        yAxesState,
-        axisAssignmentsFor
-    } = axes
-
+export function RasterPlotTooltipContent(props: Props): ReactElement | null {
+    const {axes} = useChart<Datum, SeriesLineStyle, Partial<RasterTooltipMetadata>, ContinuousAxisRange, OrdinalStringAxis>()
+    const {yAxesState, axisAssignmentsFor} = axes
     const {margin, plotDimensions} = usePlotDimensions()
 
     const {
         xFormatter = formatTime,
         yFormatter = formatValue,
+        intervalFormatter = xFormatter,
         style,
     } = props
 
-    const tooltipStyle = useMemo(() => ({...defaultTooltipStyle, ...style}), [style])
-
-    // register the tooltip content provider, which when called on mouse-enter-series events
-    // will render the tooltip container and then the tooltip content. recall that that the
-    // tooltip content is generated in this plot (because this is the plot that holds all the
-    // information needed to render it), and the container for the content is rendered by
-    // the <Tooltip>, which this know nothing about.
-    //
-    // the 'registration function accepts a function of the form (seriesName, time, series) => TooltipDimensions.
-    // and that function has a closure on the content-specific information needed to add the
-    // actual content
-    useEffect(
-        () => {
-            if (container) {
-                // assemble the options for adding the tooltip
-                const options: TooltipOptions = {
-                    formatters: {
-                        x: xFormatter,
-                        y: yFormatter,
+    return (
+        <TooltipContent<Datum, Partial<RasterTooltipMetadata>, RasterTooltipContent>
+            style={style}
+            capture={(seriesName, _time, tooltipData) => {
+                const yAxisId = axisAssignmentsFor(seriesName).yAxis
+                const axis = yAxesState
+                    .axisFor(yAxisId)
+                    .getOrThrow(() => new Error(`No assigned y-axis exists; axis_id: ${yAxisId}`))
+                return captureTooltipContent(seriesName, tooltipData.series[0], tooltipData.metadata.spikes, axis)
+            }}
+            // (vertically, the tooltip is centered on the spike's row, rather than placed below the mouse)
+            topFor={(content, height) =>
+                categoryTooltipY(content.seriesName, height, content.axis, margin, content.axis.scale.bandwidth(), plotDimensions)
+            }
+        >
+            {(tooltipContent, tooltipStyle) => <>
+                    <div style={{fontSize: tooltipStyle.fontSize, fontWeight: tooltipStyle.fontWeight}}>
+                        {tooltipContent.seriesName}
+                    </div>
+                    <div style={{fontSize: tooltipStyle.fontSize + 2, fontWeight: tooltipStyle.fontWeight + 150}}>
+                        {xFormatter(tooltipContent.spikeTime)}, {yFormatter(tooltipContent.value)}
+                    </div>
+                    {/* the series' spikes over the window (the data the chart holds) */}
+                    {tooltipContent.statistics !== undefined && tooltipContent.statistics.count > 0 &&
+                        // (sized to its content, rather than the app's default full-width tables, so that
+                        // the values sit next to their labels)
+                        <table style={{fontSize: tooltipStyle.fontSize, borderCollapse: 'collapse', border: 'none', marginTop: 6, width: 'auto'}}>
+                            <tbody>
+                            {[
+                                ['Spikes', formatNumber(tooltipContent.statistics.count, " ,.0f")],
+                                ['Mean value', valueOrMissing(tooltipContent.statistics.meanValue, yFormatter)],
+                                ['Std. deviation', valueOrMissing(tooltipContent.statistics.valueStandardDeviation, yFormatter)],
+                                ['Mean interval', valueOrMissing(tooltipContent.statistics.meanInterval, intervalFormatter)],
+                            ].map(([label, value]) => (
+                                <tr key={label}>
+                                    <td style={{padding: '1px 12px 1px 0', textAlign: 'left', border: 'none'}}>{label}</td>
+                                    <td style={{padding: '1px 0', textAlign: 'right', border: 'none'}}>{value}</td>
+                                </tr>
+                            ))}
+                            </tbody>
+                        </table>
                     }
-                }
-
-                // register the tooltip content provider function with the chart hook (useChart) so that
-                // it is visible to all children of the Chart (i.e. the <Tooltip>).
-                registerTooltipContentProvider(
-                    /**
-                     *
-                     * @param seriesName The name of the series
-                     * @param time The mouse time
-                     * @param tooltipData The tooltip data holding the series and metadata (data about the series)
-                     * @param mouseCoords The coordinates of the mouse
-                     * @return The tooltip contents
-                     */
-                    (seriesName: string, time: number, tooltipData: TooltipData<Datum, NoTooltipMetadata>, mouseCoords: [x: number, y: number]) => {
-                        const yAxisId = axisAssignmentsFor(seriesName).yAxis
-                        const assignedAxis = yAxesState
-                            .axisFor(yAxisId)
-                            // .getOrElse(undefined as unknown as OrdinalStringAxis)
-                            .getOrThrow(() => new Error(`No assigned y-axis exists; axis_id: ${yAxisId}`))
-                        return addTooltipContent(
-                            seriesName, time, tooltipData.series[0], mouseCoords,
-                            chartId, container, margin, plotDimensions, tooltipStyle,
-                            assignedAxis,
-                            options
-                        )
+                    {/* the spikes' values over the window, with the hovered spike marked (the dot) */}
+                    {tooltipContent.sparkline !== undefined &&
+                        <svg
+                            width={SPARKLINE_WIDTH}
+                            height={SPARKLINE_HEIGHT}
+                            style={{display: 'block', marginTop: 8}}
+                            aria-hidden="true"
+                        >
+                            <path
+                                d={tooltipContent.sparkline.path}
+                                fill="none"
+                                stroke={tooltipStyle.fontColor}
+                                strokeWidth={1.25}
+                                strokeLinejoin="round"
+                                strokeLinecap="round"
+                            />
+                            {tooltipContent.sparkline.mark !== undefined &&
+                                <circle
+                                    cx={tooltipContent.sparkline.mark[0]}
+                                    cy={tooltipContent.sparkline.mark[1]}
+                                    r={2.5}
+                                    fill={tooltipStyle.fontColor}
+                                />
+                            }
+                        </svg>
                     }
-                )
-            }
-        },
-        [
-            chartId, container, margin, plotDimensions, registerTooltipContentProvider,
-            xFormatter,
-            yFormatter,
-            tooltipStyle,
-            yAxesState, axisAssignmentsFor
-        ]
+            </>}
+        </TooltipContent>
     )
-
-    return null
 }
 
 /**
- * Callback function that adds tooltip content and returns the tooltip width and text height
+ * Captures the data needed to render the tooltip content: the selected spike, and the statistics
+ * and sparkline of the series' spikes
  * @param seriesName The name of the series (i.e. the neuron ID)
- * @param time The time (x-coordinate value) corresponding to the mouse location
- * @param selected The selected datum (time, value)
- * @param mouseCoords The coordinates of the mouse when the event was fired (relative to the plot container)
- * @param chartId The ID of this chart
- * @param container The plot container (SVGSVGElement)
- * @param margin The plot margins
- * @param tooltipStyle The style properties for the tooltip
+ * @param selected The selected datum (time, value), or `undefined` (in which case there's no tooltip)
+ * @param spikes All the series' spikes in the window (for the statistics and the sparkline), when known
  * @param axis The category axis to which the time-series is associated
- * @param plotDimensions The dimensions of the plot
- * @param options The options passed through the the function that adds the tooltip content
- * @return The width and text height of the tooltip content
+ * @return The tooltip's content, or `undefined` when there's no selected spike
  */
-function addTooltipContent(
+function captureTooltipContent(
     seriesName: string,
-    time: number,
-    selected: Datum,
-    mouseCoords: [x: number, y: number],
-    chartId: number,
-    container: SVGSVGElement,
-    margin: Margin,
-    plotDimensions: Dimensions,
-    tooltipStyle: TooltipStyle,
+    selected: Datum | undefined,
+    spikes: Series<Datum> | undefined,
     axis: OrdinalStringAxis,
-    options: TooltipOptions
-): TooltipDimensions {
-    const {formatters} = options
-    const [x, ] = mouseCoords
-    const {time: spikeTime, value} = selected
-
-    // display the neuron ID in the tooltip
-    const header = d3.select<SVGSVGElement | null, any>(container)
-        .append<SVGTextElement>("text")
-        .attr('id', `tn${spikeTime}-${seriesName}-${chartId}`)
-        .attr('class', 'tooltip')
-        .attr('fill', tooltipStyle.fontColor)
-        .attr('font-family', 'sans-serif')
-        .attr('font-size', tooltipStyle.fontSize)
-        .attr('font-weight', tooltipStyle.fontWeight)
-        .text(() => seriesName)
-
-    // display the time (ms) and spike strength (mV) in the tooltip
-    const text = d3.select<SVGSVGElement | null, any>(container)
-        .append<SVGTextElement>("text")
-        .attr('id', `t${spikeTime}-${seriesName}-${chartId}`)
-        .attr('class', 'tooltip')
-        .attr('fill', tooltipStyle.fontColor)
-        .attr('font-family', 'sans-serif')
-        .attr('font-size', tooltipStyle.fontSize + 2)
-        .attr('font-weight', tooltipStyle.fontWeight + 150)
-        .text(() => `${formatters.x(spikeTime)}, ${formatters.y(value)}`)
-
-    // calculate the max width and height of the text
-    const tooltipWidth = Math.max(header.node()?.getBBox()?.width || 0, text.node()?.getBBox()?.width || 0);
-    const headerTextHeight = header.node()?.getBBox()?.height || 0;
-    const idHeight = text.node()?.getBBox()?.height || 0;
-    const textHeight = headerTextHeight + idHeight;
-
-    // set the header text location
-    // const spikeHeight = plotDimensions.height / liveDataRef.current.size
-    const xCoord = tooltipX(x, tooltipWidth, plotDimensions, tooltipStyle, margin)
-    const yCoord = categoryTooltipY(seriesName, textHeight, axis, tooltipStyle, margin, axis.scale.bandwidth(), plotDimensions)
-    const xTooltip = xCoord + tooltipStyle.paddingLeft
-    const yTooltip = yCoord + tooltipStyle.paddingTop
-    header
-        .attr('x', () => xTooltip)
-        .attr('y', () => yTooltip - idHeight + textHeight)
-
-    // set the tooltip text (i.e. neuron ID) location
-    text
-        .attr('x', () => xTooltip)
-        .attr('y', () => yTooltip + textHeight)
+): RasterTooltipContent | undefined {
+    // `selected` comes from the caller's `tooltipData.series[0]` -- this component is a public,
+    // independently-usable tooltip-content provider, and `TooltipData.series: Series<D>` permits
+    // an empty array, so guard here rather than relying on every caller to have already checked
+    // (RasterPlot.tsx's own mousemove handler does today, but that shouldn't be the only thing
+    // standing between an empty series and a destructuring crash below)
+    if (selected === undefined) return undefined
+
+    const {x: spikeTime, y} = selected
+
+    // the spikes' statistics, and their values over time, over the window (the data the chart holds)
+    const spikeValues: Array<{ time: number, value: number }> = []
+    if (spikes !== undefined) {
+        for (let i = 0; i < spikes.length; i++) spikeValues.push({time: spikes[i].x, value: spikes[i].y})
+    }
 
-    return {x: xCoord, y: yCoord, contentWidth: tooltipWidth, contentHeight: textHeight}
+    return {
+        seriesName,
+        spikeTime,
+        value: y,
+        statistics: spikes !== undefined ? seriesStatistics(spikes) : undefined,
+        sparkline: sparklineFor(spikeValues, SPARKLINE_WIDTH, SPARKLINE_HEIGHT, 2, undefined, spikeTime),
+        axis,
+    }
 }