stream-charts 1.2.1 → 2.0.0

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

@@ -1,148 +1,82 @@
-import {cloneElement, useEffect, useMemo, JSX} from "react";
-import {defaultTooltipStyle, removeTooltip, TooltipStyle} from "./tooltipUtils";
-import * as d3 from "d3";
+import {type JSX, useEffect, useMemo} from "react";
+import {defaultTooltipStyle, type TooltipStyle} from "./tooltipUtils";
 import {useChart} from "../hooks/useChart";
-import {usePlotDimensions} from "../hooks/usePlotDimensions";
-import {BaseAxis, SeriesStyle} from "../axes/axes";
-import {TooltipData} from "../hooks/useTooltip";
+import type {BaseAxis, SeriesStyle} from "../axes/axes";
+import type {TooltipData} from "../hooks/useTooltip";
 import {BaseAxisRange} from "../axes/BaseAxisRange";
+import {TooltipStyleContext} from "./useTooltipStyle";
 
+/**
+ * The properties of the {@link Tooltip}
+ */
 export interface Props {
+    /** whether the tooltip is shown when the mouse is over one of the plot's elements */
     visible: boolean
+    /** the style of the tooltip (its box and text); its content can override parts of it */
     style?: Partial<TooltipStyle>
+    /** the tooltip's content (e.g. a `<ScatterPlotTooltipContent>`, or your own, built on `<TooltipContent>`) */
     children: JSX.Element
 }
 
 /**
- * Tooltip component triggered by mouse-over-series events. When mounted, the tooltip component
- * registers a mouse-over handler with the {@link useMouse} hook using the
- * {@link UseMouseValues.registerMouseOverHandler} function. The handler renders the tooltip
- * by adding it to the SVG plot container. However, to remain general, this {@link Tooltip} also
- * uses the {@link useTooltip}'s {@link UseTooltipValues.tooltipContentProvider} to render the actual
- * content of the tooltip. The content provider is given the series' name on which the mouse-over
- * event occurred, the plot time associated with mouse-over event, and the {@link TimeSeries}
- * associated with the mouse-over event. The plot (for example {@link ScatterPlot}) is responsible
- * for rendering the tooltip, and it registers this tooltip-content provider with the {@link useTooltip}
- * hook.
- *
- * The {@link useChart} hook allows the plots and this tooltip to register methods needed its siblings.
- *
- * ## on mount
- * 1. The plot (for example {@link ScatterPlot}) adds a d3 mouse-enter and mouse-leave event handlers
- *    to each series. The mouse-enter event handler performs a few tasks and then calls the
- *    mouse-over event handler registered by the {@link Tooltip} via the {@link useMouse} hook.
- * 2. The plot (for example {@link ScatterPlot}) registers the tooltip-content provider with the {@link useTooltip}
- *    hook using the {@link UseTooltipValues.registerTooltipContentProvider} function.
- * 3. {@link Tooltip} registers the handler for mouse-over events. The handler accepts the series
- *    name, plot time, and time-series associated with the mouse-over event, and returns the tooltip
- *    dimensions. In order to create/render the tooltip, it uses the {@link UseTooltipValues.tooltipContentProvider}
- *    function that was registered via the {@link useTooltip} hook.
+ * Shows a tooltip when the mouse is over one of the plot's elements (a series, a point, a spike, a
+ * bar, a band, and so on), while `visible` is `true`. What the tooltip shows is up to its content
+ * (its child -- for example, a `<ScatterPlotTooltipContent>`), which is built on
+ * {@link TooltipContent}.
  *
- * ## on mouse-over event
- * When the plot's (for example {@link ScatterPlot}) d3 mouse-enter event handler fires, the plot calls this
- * {@link Tooltip}'s mouse-over handler, which creates the tooltip, and calls the {@link UseTooltipValues.tooltipContentProvider}
- * registered by the plot to render the tooltip content, and get the tooltip size.
+ * The plot hit-tests the mouse against what it drew, and calls the mouse-over handler this
+ * component registers (see `useMouse`), which hands what the plot knows about the element
+ * under the mouse to the content's tooltip-content provider (see `useTooltip`). The content
+ * shows itself, and hides itself again when the mouse leaves the element.
  *
- * @param props The properties of the tooltip (i.e. visibility and style)
- * @return null
+ * The content gets this tooltip's style (its `style` over the default tooltip style) through
+ * {@link useTooltipStyle}, and can override parts of it.
+ * @param props Whether the tooltip is shown, its style, and its content
+ * @return The content, while the tooltip is shown
+ * @template D The type of the series' datum
+ * @template S The type of the series style
+ * @template TM The type of the tooltip metadata
+ * @template AR The type of the axis range
+ * @template A The type of the axis
  */
 export function Tooltip<D, S extends SeriesStyle, TM, AR extends BaseAxisRange, A extends BaseAxis>(props: Props): JSX.Element {
-    const {
-        chartId,
-        container,
-        tooltip,
-        mouse
-    } = useChart<D, S, TM, AR, A>()
-
-    const {
-        tooltipContentProvider,
-        setVisibilityState,
-    } = tooltip
-
-    const {margin, plotDimensions} = usePlotDimensions()
-
-    const {
-        visible,
-        style,
-        children
-    } = props
+    const {visible, style, children} = props
 
-    const {
-        registerMouseOverHandler,
-        unregisterMouseOverHandler,
-        registerMouseLeaveHandler,
-        unregisterMouseLeaveHandler
-    } = mouse
+    const {chartId, tooltip, mouse} = useChart<D, S, TM, AR, A>()
+    const {tooltipContentProvider, setVisibilityState} = tooltip
+    const {registerMouseOverHandler, unregisterMouseOverHandler} = mouse
 
-    const tooltipStyle = useMemo(() => ({...defaultTooltipStyle, ...style}), [style])
-
-    // let the tooltip context know whether the tooltip is visible
-    setVisibilityState(visible)
+    const tooltipStyle = useMemo<TooltipStyle>(() => ({...defaultTooltipStyle, ...style}), [style])
 
     useEffect(
         () => {
-            const handlerId = `tooltip-${chartId}`
-            if (visible && container) {
-                const contentProvider = tooltipContentProvider()
-                if (contentProvider) {
-                    // register this tooltip's mouse-over event handler with the useCharts hook
-                    // so that the plots can call it when mouse-enter events are triggered (for
-                    // example, a mouse-over a time-series in the plot).
-                    registerMouseOverHandler(
-                        handlerId,
-                        (
-                            (
-                                seriesName: string,
-                                time: number,
-                                tooltipData: TooltipData<D, TM>,
-                                mouseCoords: [x: number, y: number],
-                                providerId?: string
-                            ) => {
-                                // create the rounded rectangle for the tooltip's background
-                                const rect = d3.select<SVGSVGElement | null, any>(container)
-                                    .append<SVGRectElement>('rect')
-                                    .attr('id', `r${time}-${seriesName}-${chartId}`)
-                                    .attr('class', 'tooltip')
-                                    .attr('rx', tooltipStyle.borderRadius)
-                                    .attr('fill', tooltipStyle.backgroundColor)
-                                    .attr('fill-opacity', tooltipStyle.backgroundOpacity)
-                                    .attr('stroke', tooltipStyle.borderColor)
-                                    .attr('stroke-width', tooltipStyle.borderWidth)
-                                    .attr('stroke-opacity', tooltipStyle.borderOpacity)
-
-                                // call the callback to add the content
-                                const {
-                                    x,
-                                    y,
-                                    contentWidth,
-                                    contentHeight
-                                } = contentProvider(seriesName, time, tooltipData, mouseCoords, providerId)
-
-                                // set the position, width, and height of the tooltip rect based on the text height and width and the padding
-                                rect.attr('x', () => x)
-                                    .attr('y', () => y)
-                                    .attr('width', contentWidth + tooltipStyle.paddingLeft + tooltipStyle.paddingRight)
-                                    .attr('height', contentHeight + tooltipStyle.paddingTop + tooltipStyle.paddingBottom)
+            // let the tooltip context know whether the tooltip is visible
+            setVisibilityState(visible)
+            if (!visible) return
 
-                            }
-                        )
-                    )
-
-                    registerMouseLeaveHandler(handlerId, () => removeTooltip())
-                }
-            }
-            return () => {
-                unregisterMouseOverHandler(handlerId)
-                unregisterMouseLeaveHandler(handlerId)
-            }
+            // hands the element under the mouse to the content's provider (looked up on each call,
+            // so it's always the one the content registered most recently)
+            const handlerId = `tooltip-${chartId}`
+            registerMouseOverHandler(
+                handlerId,
+                (
+                    seriesName: string,
+                    time: number,
+                    tooltipData: TooltipData<D, TM>,
+                    mouseCoords: [x: number, y: number],
+                    providerId?: string
+                ) => tooltipContentProvider()?.(seriesName, time, tooltipData, mouseCoords, providerId)
+            )
+            return () => unregisterMouseOverHandler(handlerId)
         },
-        [
-            chartId, container, margin, plotDimensions,
-            registerMouseOverHandler, tooltipContentProvider, tooltipStyle,
-            unregisterMouseOverHandler, visible, registerMouseLeaveHandler,
-            unregisterMouseLeaveHandler
-        ]
+        [chartId, visible, tooltipContentProvider, setVisibilityState, registerMouseOverHandler, unregisterMouseOverHandler]
     )
 
-    return <>{cloneElement(children, props)}</>
+    // (the content is only mounted while the tooltip is visible, so hiding the tooltip also hides
+    // any content that's showing)
+    return (
+        <TooltipStyleContext.Provider value={tooltipStyle}>
+            {visible ? children : null}
+        </TooltipStyleContext.Provider>
+    )
 }

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

@@ -0,0 +1,177 @@
+import {type CSSProperties, type ReactElement, type ReactNode, useEffect, useMemo, useRef, useState} from "react";
+import {createPortal} from "react-dom";
+import {useChart} from "../hooks/useChart";
+import {usePlotDimensions} from "../hooks/usePlotDimensions";
+import type {TooltipData} from "../hooks/useTooltip";
+import type {BaseAxis, SeriesStyle} from "../axes/axes";
+import type {BaseAxisRange} from "../axes/BaseAxisRange";
+import {withAlpha} from "../styling/canvasStyle";
+import type {TooltipStyle} from "./tooltipUtils";
+import {tooltipAnchorFor, type TooltipAnchor, useTooltipPlacement} from "./useTooltipPlacement";
+import {useTooltipStyle} from "./useTooltipStyle";
+
+/**
+ * Turns what the plot hands the tooltip about the element under the mouse into the content to show
+ * (any value you like), or `undefined` to show nothing.
+ * @param seriesName The name of the series under the mouse
+ * @param time A value that depends on the plot: usually the time under the mouse (see the plot's
+ * documentation)
+ * @param tooltipData The series' data, and the plot's metadata about the element under the mouse
+ * @param providerId Which kind of element is under the mouse, for a plot that has several (e.g. the
+ * bar plot)
+ * @return The tooltip's content, or `undefined` to show no tooltip
+ * @template D The type of the series' datum
+ * @template M The type of the plot's tooltip metadata
+ * @template C The type of the tooltip's content
+ */
+export type TooltipCapture<D, M, C> = (
+    seriesName: string,
+    time: number,
+    tooltipData: TooltipData<D, M>,
+    providerId?: string
+) => C | undefined
+
+/**
+ * The properties of the {@link TooltipContent}
+ * @template D The type of the series' datum
+ * @template M The type of the plot's tooltip metadata
+ * @template C The type of the tooltip's content
+ */
+export interface TooltipContentProps<D, M, C> {
+    /**
+     * Turns what the plot hands the tooltip into the tooltip's content. Called on every mouse move
+     * over an element, so keep it quick -- and copy what you need out of the series, which the data
+     * source keeps changing.
+     */
+    capture: TooltipCapture<D, M, C>
+    /**
+     * Renders the content (inside the tooltip's box)
+     * @param content The content returned by `capture`
+     * @param style The tooltip's style
+     * @return What to show in the tooltip's box
+     */
+    children: (content: C, style: TooltipStyle) => ReactNode
+    /**
+     * Overrides of the style of the enclosing {@link Tooltip}
+     */
+    style?: Partial<TooltipStyle>
+    /**
+     * Additional CSS for the tooltip's box (e.g. its line height)
+     */
+    boxStyle?: CSSProperties
+    /**
+     * Where the tooltip's top goes (relative to the chart), given its content and its rendered
+     * height -- for a tooltip that isn't placed below the mouse (e.g. one centered on a raster
+     * plot's row). By default, the tooltip goes just below the mouse.
+     */
+    topFor?: (content: C, height: number) => number
+}
+
+/**
+ * The building block of every tooltip's content. Put a component built on it inside a
+ * {@link Tooltip}, and when the mouse moves over one of the plot's elements, it calls `capture` with
+ * what the plot knows about that element, and shows what `children` renders, in a box next to the
+ * mouse (styled like the enclosing `<Tooltip>`). It hides again when the mouse leaves the element.
+ *
+ * Under the hood, it registers the chart's tooltip-content provider (one per chart: registering
+ * replaces the previous one), and a mouse-leave handler, and renders its box as a React portal on
+ * the page's `body`, which `useTooltipPlacement` places next to the mouse once it's rendered
+ * (and so its size is known).
+ * @example
+ * function MyScatterTooltip(): JSX.Element {
+ *     return (
+ *         <TooltipContent<Datum, ScatterTooltipMetadata, {seriesName: string, count: number}>
+ *             capture={(seriesName, _time, {series}) => ({seriesName, count: series.length})}
+ *         >
+ *             {({seriesName, count}) => <div>{seriesName}: {count} points</div>}
+ *         </TooltipContent>
+ *     )
+ * }
+ * @param props The capture and render functions, and the style
+ * @return The tooltip's box (a portal), or `null` when nothing is hovered
+ * @template D The type of the series' datum
+ * @template M The type of the plot's tooltip metadata
+ * @template C The type of the tooltip's content
+ */
+export function TooltipContent<D, M, C>(props: TooltipContentProps<D, M, C>): ReactElement | null {
+    const {capture, children, style, boxStyle, topFor} = props
+
+    const {chartId, canvas, tooltip, mouse} = useChart<D, SeriesStyle, M, BaseAxisRange, BaseAxis>()
+    const {registerTooltipContentProvider} = tooltip
+    const {registerMouseLeaveHandler, unregisterMouseLeaveHandler} = mouse
+    const {margin, plotDimensions} = usePlotDimensions()
+
+    const enclosingStyle = useTooltipStyle()
+    const tooltipStyle = useMemo<TooltipStyle>(() => ({...enclosingStyle, ...style}), [enclosingStyle, style])
+
+    // what's shown, and where (null when nothing is hovered)
+    const [shown, setShown] = useState<{ content: C, anchor: TooltipAnchor } | null>(null)
+    const tooltipRef = useRef<HTMLDivElement>(null)
+
+    // the latest capture and placement functions, so that the registered provider always uses the
+    // current ones without having to be registered again whenever they change
+    const captureRef = useRef(capture)
+    const topForRef = useRef(topFor)
+    useEffect(() => {
+        captureRef.current = capture
+        topForRef.current = topFor
+    })
+
+    // the plot calls the provider whenever the mouse is over one of its elements
+    useEffect(
+        () => {
+            if (canvas === null) return
+            registerTooltipContentProvider((seriesName, time, tooltipData, mouseCoords, providerId) => {
+                const content = captureRef.current(seriesName, time, tooltipData, providerId)
+                if (content === undefined) {
+                    setShown(null)
+                    return
+                }
+                const placeTop = topForRef.current
+                const anchor = tooltipAnchorFor(
+                    mouseCoords, canvas,
+                    placeTop !== undefined ? height => placeTop(content, height) : undefined
+                )
+                setShown({content, anchor})
+            })
+        },
+        [canvas, registerTooltipContentProvider]
+    )
+
+    // hides the tooltip when the mouse leaves the element
+    useEffect(
+        () => {
+            const handlerId = `tooltip-content-leave-${chartId}`
+            registerMouseLeaveHandler(handlerId, () => setShown(null))
+            return () => unregisterMouseLeaveHandler(handlerId)
+        },
+        [chartId, registerMouseLeaveHandler, unregisterMouseLeaveHandler]
+    )
+
+    // places the tooltip next to the mouse, once it's rendered (and so its size is known)
+    useTooltipPlacement(tooltipRef, shown?.anchor ?? null, plotDimensions, margin, tooltipStyle)
+
+    if (shown === null) return null
+
+    const tooltipBoxStyle: CSSProperties = {
+        position: 'fixed',
+        // (placed next to the mouse, from its rendered size, by `useTooltipPlacement`, before it's
+        // painted)
+        left: 0,
+        top: 0,
+        backgroundColor: withAlpha(tooltipStyle.backgroundColor, tooltipStyle.backgroundOpacity),
+        border: `${tooltipStyle.borderWidth}px solid ${withAlpha(tooltipStyle.borderColor, tooltipStyle.borderOpacity)}`,
+        borderRadius: tooltipStyle.borderRadius,
+        padding: `${tooltipStyle.paddingTop}px ${tooltipStyle.paddingRight}px ${tooltipStyle.paddingBottom}px ${tooltipStyle.paddingLeft}px`,
+        fontFamily: tooltipStyle.fontFamily,
+        fontSize: tooltipStyle.fontSize,
+        color: tooltipStyle.fontColor,
+        pointerEvents: 'none',
+        zIndex: 9999,
+        ...boxStyle,
+    }
+    return createPortal(
+        <div ref={tooltipRef} style={tooltipBoxStyle}>{children(shown.content, tooltipStyle)}</div>,
+        document.body
+    )
+}