stream-charts 1.2.0 → 2.0.0

package/src/app/charts/tooltips/tooltipUtils.ts

@@ -1,8 +1,9 @@
-import {Series} from "../plots/plot";
-import * as d3 from "d3";
-import {Datum} from "../series/timeSeries";
-import {Dimensions, Margin} from "../styling/margins";
-import {OrdinalStringAxis} from "../axes/axes";
+import type {Series} from "../plots/plot";
+import type {Dimensions, Margin} from "../styling/margins";
+import type {OrdinalStringAxis} from "../axes/axes";
+import type {ScaleContinuousNumeric} from "d3";
+import type {Datum} from "../series/timeSeries";
+import {firstIndexAtOrAfter} from "../utils";
 
 /**
  * Properties for rendering the tooltip. This is the style for the container
@@ -48,6 +49,9 @@ export interface TooltipStyle {
     paddingBottom: number;
 }
 
+/**
+ * The default tooltip style
+ */
 export const defaultTooltipStyle: TooltipStyle = {
     visible: false,
 
@@ -72,91 +76,76 @@ export const defaultTooltipStyle: TooltipStyle = {
     paddingBottom: 10,
 };
 
-export interface TooltipDimensions {
-    x: number,
-    y: number,
-    contentWidth: number,
-    contentHeight: number
-}
-
 /**
- * Removes the tooltip when the mouse has moved away from the spike
- */
-export function removeTooltip() {
-    d3.selectAll<SVGPathElement, Datum>('.tooltip').remove()
-}
-
-/**
- * Calculates the x-coordinate of the upper left-hand side of the tooltip rectangle (obviously without
- * "rounded corners"). Adjusts the x-coordinate so that tooltip is visible on the edges of the plot.
- * @param x The current x-coordinate of the mouse
- * @param textWidth The width of the tooltip text
+ * Calculates the x-coordinate of the left side of the tooltip. The tooltip goes to the right of the
+ * mouse, unless it would run past the right edge of the plot, in which case it goes to the left of
+ * the mouse (and never past the left edge of the chart).
+ * @param x The x-coordinate of the mouse, relative to the chart
+ * @param width The tooltip's (rendered) width, including its padding and border
  * @param plotDimensions The dimensions of the plot
- * @param tooltipStyle The tooltip style information
+ * @param tooltipStyle The tooltip style information (its left padding is used as the gap between
+ * the mouse and the tooltip)
  * @param margin The plot margin
- * @return The x-coordinate of the lower left-hand side of the tooltip rectangle
+ * @return The x-coordinate of the tooltip's left side, relative to the chart
  */
-export function tooltipX(x: number, textWidth: number, plotDimensions: Dimensions, tooltipStyle: TooltipStyle, margin: Margin): number {
-    if (x > plotDimensions.width + margin.left - (textWidth + tooltipStyle.paddingLeft + tooltipStyle.paddingRight)) {
-        return x - textWidth - margin.right + tooltipStyle.paddingRight + tooltipStyle.paddingLeft
+export function tooltipX(x: number, width: number, plotDimensions: Dimensions, tooltipStyle: TooltipStyle, margin: Margin): number {
+    const gap = tooltipStyle.paddingLeft
+    if (x + gap + width <= margin.left + plotDimensions.width) {
+        return x + gap
     }
-    return x + tooltipStyle.paddingLeft
+    return Math.max(0, x - gap - width)
 }
 
 /**
- * Calculates the y-coordinate of the upper-left-hand corner of the tooltip rectangle. Adjusts the y-coordinate
- * so that the tooltip is visible on the upper edge of the plot
- * @param y The y-coordinate of the mouse
- * @param textHeight The height of the header and neuron ID text
+ * Calculates the y-coordinate of the top of the tooltip. The tooltip goes below the mouse, unless it
+ * would run past the bottom of the plot, in which case it's moved up so that its bottom lines up
+ * with the plot's bottom (and never past the top edge of the chart).
+ * @param y The y-coordinate of the mouse, relative to the chart
+ * @param height The tooltip's (rendered) height, including its padding and border
  * @param plotDimensions The dimensions of the plot
- * @param tooltipStyle The tooltip style information
+ * @param tooltipStyle The tooltip style information (its top padding is used as the gap between
+ * the mouse and the tooltip)
  * @param margin The plot margin
- * @return The y-coordinate of the lower-left-hand corner of the tooltip rectangle
+ * @return The y-coordinate of the tooltip's top, relative to the chart
  */
-export function tooltipY(y: number, textHeight: number, plotDimensions: Dimensions, tooltipStyle: TooltipStyle, margin: Margin): number {
-    if (y > plotDimensions.height + margin.top - (textHeight + tooltipStyle.paddingTop + tooltipStyle.paddingBottom)) {
-        return plotDimensions.height + margin.top - (textHeight + tooltipStyle.paddingTop + tooltipStyle.paddingBottom)
+export function tooltipY(y: number, height: number, plotDimensions: Dimensions, tooltipStyle: TooltipStyle, margin: Margin): number {
+    const gap = tooltipStyle.paddingTop
+    if (y + gap + height <= margin.top + plotDimensions.height) {
+        return y + gap
     }
-    return y + tooltipStyle.paddingTop
+    return Math.max(0, margin.top + plotDimensions.height - height)
 }
 
 /**
- * Calculates the y-coordinate for the upper-left-hand the tooltip rectangle. Adjusts the y-coordinate so
- * that the tooltip is visible on the upper and lower edges of the plot
- * @param seriesName The name of the series
- * @param textHeight The height of the header and neuron ID text
+ * Calculates the y-coordinate of the top of a tooltip for a category (e.g. a raster plot's row):
+ * the tooltip is centered on the category, but kept within the plot's top and bottom edges.
+ * @param seriesName The name of the series (the category)
+ * @param height The tooltip's (rendered) height, including its padding and border
  * @param axis The category axis for determining the y-value of the tooltip
- * @param tooltipStyle The tooltip style
  * @param margin The plot margin
  * @param categoryHeight The height (in pixels) of the category
  * @param plotDimensions The dimensions of the plot
- * @return The y-coordinate of the lower-left-hand corner of the tooltip rectangle
+ * @return The y-coordinate of the tooltip's top, relative to the chart
  */
 export function categoryTooltipY(
     seriesName: string,
-    textHeight: number,
+    height: number,
     axis: OrdinalStringAxis,
-    tooltipStyle: TooltipStyle,
     margin: Margin,
     categoryHeight: number,
     plotDimensions: Dimensions
 ): number {
-    const y = axis.scale(seriesName) || 0
-    const halfHeight = (tooltipStyle.paddingBottom + textHeight + tooltipStyle.paddingTop) / 2
-    if (y < halfHeight) {
-        return margin.top
-    }
-    if (y > plotDimensions.height + margin.top - halfHeight) {
-        return plotDimensions.height + margin.top - textHeight
-    }
-    return y + margin.top - halfHeight + categoryHeight / 2
+    const categoryCenter = margin.top + (axis.scale(seriesName) || 0) + categoryHeight / 2
+    const top = categoryCenter - height / 2
+    const lowest = margin.top + plotDimensions.height - height
+    return Math.max(margin.top, Math.min(top, lowest))
 }
 
 /**
  * Returns the index of the data point whose time is the upper boundary on the specified
- * time. If the specified time is larger than any time in the specified data, the returns
+ * time. If the specified time is larger than any time in the specified data, then returns
  * the length of the data array. If the specified time is smaller than all the values in
- * the specified array, then returns -1.
+ * the specified array, then returns 0. The data must not be empty.
  * @param data The array of points from which to select the
  * boundary.
  * @param value The time for which to find the bounding points
@@ -185,11 +174,17 @@ function boundingPointsIndex<D>(data: Series<D>, value: number, xFrom: (value: D
  * @param xFrom A function that extracts the x-value from the datum
  * @param emptyDatum A function that returns an empty datum
  * @template D The type of the datum in the data-series
- * @return {[[number, number], [number, number]]} the (time, value) point that comes just before
- * the mouse and just after the mouse. If the mouse is after the last point, then the "after" point
- * is `[NaN, NaN]`. If the mouse is before the first point, then the "before" point is `[NaN, NaN]`.
+ * @return The point that comes just before the mouse and just after the mouse. If the mouse is
+ * after the last point, then the "after" point is the empty datum. If the mouse is before the
+ * first point, then the "before" point is the empty datum. (Both are, for an empty series.)
  */
 export function boundingPoints<D>(data: Series<D>, value: number, xFrom: (value: D) => number, emptyDatum: () => D): [D, D] {
+    // an empty series has no bounding points at all -- guard here (not just inside
+    // boundingPointsIndex) since this function's own upperIndex<=0/>=data.length fallbacks below
+    // also read data[0]/data[data.length-1], which are just as undefined on an empty array
+    if (data.length === 0) {
+        return [emptyDatum(), emptyDatum()]
+    }
     const upperIndex = boundingPointsIndex<D>(data, value, xFrom)
     if (upperIndex <= 0) {
         return [emptyDatum(), data[0]]
@@ -200,6 +195,19 @@ export function boundingPoints<D>(data: Series<D>, value: number, xFrom: (value:
     return [data[upperIndex - 1], data[upperIndex]]
 }
 
+/**
+ * Finds the first point whose x-value is within the tolerance of the specified value, along with
+ * the points before and after it
+ * @param data The series' data
+ * @param value The x-value to look for
+ * @param tolerance How far (in the x-value's units) a point's x-value may be from the value
+ * @param xFrom A function that extracts the x-value from the datum
+ * @param emptyDatum A function that returns an empty datum (for a point that doesn't exist)
+ * @return The point before, the point, the point after, and the point's index (-1 when no point
+ * is within the tolerance, in which case the point and the point before are empty, and the point
+ * after is the series' first point)
+ * @template D The type of the datum in the data-series
+ */
 export function findPointAndNeighbors<D>(
     data: Series<D>,
     value: number,
@@ -214,3 +222,293 @@ export function findPointAndNeighbors<D>(
     const upper = (index < data.length - 1) ? data[index+1] : emptyDatum()
     return [lower, point, upper, index]
 }
+
+/**
+ * The points of a scatter series that a tooltip shows (and the plot highlights), depending on
+ * where the mouse is over the series:
+ * - directly over a data point: that `point`, along with the points `before` and `after` it
+ * - over a line segment between two points: the points `before` and `after` the mouse
+ *
+ * `before` and `after` are undefined when there's no such point (e.g. before the first point).
+ */
+export type ScatterTooltipPoints =
+    | { kind: 'point', before?: Datum, point: Datum, after?: Datum }
+    | { kind: 'segment', before?: Datum, after?: Datum }
+
+/**
+ * The scatter plot's tooltip metadata: the points the tooltip shows
+ */
+export interface ScatterTooltipMetadata {
+    points: ScatterTooltipPoints
+}
+
+/**
+ * Determines which of a scatter series' points a tooltip shows, from where the mouse is: when the
+ * mouse is over a data point, that point (and its neighbors); otherwise the points on either side
+ * of the mouse (the segment it's over).
+ *
+ * The mouse is over a point when it's within `pointRadius` pixels of it -- or, when the point's
+ * nearest neighbor is closer than three times that, within a third of the way to that neighbor.
+ * Otherwise, with dense data (points a few pixels apart), the mouse would almost always be within
+ * the radius of some point, and the segments between them could hardly be hovered at all.
+ * @param data The series' data, ordered by x
+ * @param mouse The mouse's coordinates, within the plot area (i.e. in the axes' ranges)
+ * @param xScale The series' x-axis scale
+ * @param yScale The series' y-axis scale
+ * @param pointRadius How close (in pixels) the mouse must be to a data point to be over it
+ * @return The points the tooltip shows
+ */
+export function scatterTooltipPoints(
+    data: { length: number, [index: number]: Datum },
+    mouse: [x: number, y: number],
+    xScale: ScaleContinuousNumeric<number, number>,
+    yScale: ScaleContinuousNumeric<number, number>,
+    pointRadius: number
+): ScatterTooltipPoints {
+    const [mouseX, mouseY] = mouse
+    const pointAt = (index: number): Datum | undefined => index >= 0 && index < data.length ? data[index] : undefined
+    // the first point at, or after, the mouse's x-value
+    const index = firstIndexAtOrAfter(data, xScale.invert(mouseX), datum => datum.x)
+
+    // the on-screen distance between two points
+    const distanceBetween = (a: Datum, b: Datum): number => Math.hypot(xScale(a.x) - xScale(b.x), yScale(a.y) - yScale(b.y))
+    // how close the mouse must be to the point (see above)
+    const radiusFor = (candidate: number): number => {
+        const neighborDistances = [pointAt(candidate - 1), pointAt(candidate + 1)]
+            .filter((neighbor): neighbor is Datum => neighbor !== undefined)
+            .map(neighbor => distanceBetween(data[candidate], neighbor))
+        return Math.min(pointRadius, ...neighborDistances.map(distance => distance / 3))
+    }
+
+    // the nearest point (on screen) that the mouse is over, among those around the mouse's x-value
+    let nearest: number | undefined = undefined
+    let nearestDistance = Infinity
+    for (let candidate = index - 2; candidate <= index + 1; candidate++) {
+        const datum = pointAt(candidate)
+        if (datum === undefined) continue
+        const distance = Math.hypot(xScale(datum.x) - mouseX, yScale(datum.y) - mouseY)
+        if (distance <= radiusFor(candidate) && distance < nearestDistance) {
+            nearestDistance = distance
+            nearest = candidate
+        }
+    }
+
+    if (nearest !== undefined) {
+        return {kind: 'point', before: pointAt(nearest - 1), point: data[nearest], after: pointAt(nearest + 1)}
+    }
+    return {kind: 'segment', before: pointAt(index - 1), after: pointAt(index)}
+}
+
+/**
+ * The points a scatter tooltip shows, as a list (e.g. for highlighting them)
+ * @param points The points the tooltip shows
+ * @return The points, in order
+ */
+export function scatterTooltipPointList(points: ScatterTooltipPoints): Array<Datum> {
+    const list = points.kind === 'point' ?
+        [points.before, points.point, points.after] :
+        [points.before, points.after]
+    return list.filter((datum): datum is Datum => datum !== undefined)
+}
+
+/**
+ * A sparkline: a small line chart of a series' values over time (e.g. for a tooltip), as an SVG
+ * path, and where its last point is
+ */
+export interface Sparkline {
+    // the SVG path of the line, within the sparkline's width and height
+    path: string
+    // where the line ends (the latest value)
+    end: [x: number, y: number]
+    // where the marked point is (see `sparklineFor`'s `markedTime`), when one was asked for, and found
+    mark?: [x: number, y: number]
+}
+
+/**
+ * Creates a sparkline of the specified (time-ordered) values: time runs left to right across the
+ * width, and the values are scaled to fill the height (the highest at the top). Values that
+ * aren't finite are skipped.
+ *
+ * A long series is reduced to (at most) four points per pixel column -- the column's first,
+ * lowest, highest, and last values, in the order they occurred -- so that the path stays small,
+ * while still tracing the line's true shape, spikes included.
+ * @param data The values, ordered by time
+ * @param width The sparkline's width (in pixels)
+ * @param height The sparkline's height (in pixels)
+ * @param padding The space (in pixels) to leave around the line, within the width and height
+ * @param valueRange The (fixed) range of values the height spans (values outside it are drawn at
+ * its edge) -- by default, the range of the values themselves
+ * @param markedTime The time of a point to mark (e.g. the hovered point), whose position is
+ * returned as the sparkline's `mark` -- by default, none
+ * @return The sparkline, or `undefined` when there are fewer than two values to draw
+ */
+export function sparklineFor(
+    data: { length: number, [index: number]: { time: number, value: number } },
+    width: number,
+    height: number,
+    padding: number = 2,
+    valueRange?: [min: number, max: number],
+    markedTime?: number
+): Sparkline | undefined {
+    const points: Array<{ time: number, value: number }> = []
+    for (let i = 0; i < data.length; i++) {
+        if (Number.isFinite(data[i].time) && Number.isFinite(data[i].value)) points.push(data[i])
+    }
+    if (points.length < 2) return undefined
+
+    const startTime = points[0].time
+    const timeSpan = points[points.length - 1].time - startTime
+    let minValue = Infinity
+    let maxValue = -Infinity
+    if (valueRange !== undefined) {
+        [minValue, maxValue] = valueRange
+    } else {
+        points.forEach(({value}) => {
+            minValue = Math.min(minValue, value)
+            maxValue = Math.max(maxValue, value)
+        })
+    }
+    const innerWidth = width - 2 * padding
+    const innerHeight = height - 2 * padding
+    const xOf = (time: number) => padding + (timeSpan > 0 ? (time - startTime) / timeSpan * innerWidth : innerWidth / 2)
+    // (a flat line sits in the middle)
+    const yOf = (value: number) => padding + (maxValue > minValue ?
+        (maxValue - Math.min(maxValue, Math.max(minValue, value))) / (maxValue - minValue) * innerHeight :
+        innerHeight / 2)
+
+    // each pixel column's first, lowest, highest, and last values, in the order they occurred
+    const reduced: Array<{ time: number, value: number }> = []
+    let column: Array<{ index: number, point: { time: number, value: number } }> = []
+    let columnX = Math.floor(xOf(points[0].time))
+    const flushColumn = () => {
+        if (column.length === 0) return
+        const lowest = column.reduce((low, entry) => entry.point.value < low.point.value ? entry : low)
+        const highest = column.reduce((high, entry) => entry.point.value > high.point.value ? entry : high)
+        const kept = new Map([column[0], lowest, highest, column[column.length - 1]].map(entry => [entry.index, entry.point]))
+        Array.from(kept.entries()).sort(([a], [b]) => a - b).forEach(([, point]) => reduced.push(point))
+        column = []
+    }
+    points.forEach((point, index) => {
+        const x = Math.floor(xOf(point.time))
+        if (x !== columnX) {
+            flushColumn()
+            columnX = x
+        }
+        column.push({index, point})
+    })
+    flushColumn()
+
+    const coordinates = reduced.map(({time, value}) => [xOf(time), yOf(value)] as [number, number])
+    const round = (value: number) => Math.round(value * 100) / 100
+    const marked = markedTime === undefined ? undefined : points.find(point => point.time === markedTime)
+    return {
+        path: coordinates.map(([x, y], index) => `${index === 0 ? 'M' : 'L'}${round(x)},${round(y)}`).join(' '),
+        end: coordinates[coordinates.length - 1],
+        ...(marked !== undefined ? {mark: [xOf(marked.time), yOf(marked.value)] as [number, number]} : {}),
+    }
+}
+
+/**
+ * The raster plot's tooltip metadata: all of the hovered series' spikes that the chart holds (the
+ * tooltip data's `series` holds just the hovered spike)
+ */
+export interface RasterTooltipMetadata {
+    spikes: Series<Datum>
+}
+
+/**
+ * Statistics of a series' (time, value) points -- e.g. a raster chart's spikes, or a scatter
+ * chart's points -- over the window of data that the chart holds. Those that need at least two
+ * points are undefined when there's only one.
+ */
+export interface SeriesStatistics {
+    // the number of points
+    count: number
+    // the mean of the points' values
+    meanValue: number | undefined
+    // the (sample) standard deviation of the points' values
+    valueStandardDeviation: number | undefined
+    // the mean time between consecutive points
+    meanInterval: number | undefined
+}
+
+/**
+ * Calculates the statistics of a series' (time, value) points: their count, the mean and the
+ * (sample) standard deviation of their values, and the mean time between consecutive points.
+ * Points whose value or time isn't finite are skipped.
+ * @param spikes The points (e.g. spikes), ordered by time
+ * @return The statistics
+ */
+export function seriesStatistics(spikes: { length: number, [index: number]: Datum }): SeriesStatistics {
+    const valid: Array<Datum> = []
+    for (let i = 0; i < spikes.length; i++) {
+        if (Number.isFinite(spikes[i].x) && Number.isFinite(spikes[i].y)) valid.push(spikes[i])
+    }
+    const count = valid.length
+    if (count === 0) return {count, meanValue: undefined, valueStandardDeviation: undefined, meanInterval: undefined}
+
+    const meanValue = valid.reduce((sum, spike) => sum + spike.y, 0) / count
+    if (count < 2) return {count, meanValue, valueStandardDeviation: undefined, meanInterval: undefined}
+
+    const sumOfSquares = valid.reduce((sum, spike) => sum + (spike.y - meanValue) ** 2, 0)
+    return {
+        count,
+        meanValue,
+        valueStandardDeviation: Math.sqrt(sumOfSquares / (count - 1)),
+        // the intervals between consecutive spikes sum to the span from the first to the last
+        meanInterval: (valid[count - 1].x - valid[0].x) / (count - 1),
+    }
+}
+
+/**
+ * Formats a value, or shows a dash when there isn't one (e.g. the standard deviation of a single
+ * point)
+ * @param value The value, if there is one
+ * @param formatter Formats the value
+ * @return The formatted value, or a dash
+ */
+export function valueOrMissing(value: number | undefined, formatter: (value: number) => string): string {
+    return value === undefined ? '–' : formatter(value)
+}
+
+// the largest lag (in points) for which the autocorrelation is calculated by default
+const MAX_AUTOCORRELATION_LAG = 50
+
+/**
+ * Calculates the (sample) autocorrelation of a series' values, by lag: for each lag `k` (in
+ * points, not time -- a series' points needn't be evenly spaced in time), the correlation between
+ * the values and the values `k` points later,
+ * <p>`r[k] = sum[t](x[t] - mean) * (x[t+k] - mean) / sum[t](x[t] - mean)^2`</p>
+ * so `r[0]` is 1, and the values are between -1 and 1. Points whose value or time isn't finite are
+ * skipped.
+ * @param points The series' points, ordered by time
+ * @param maxLag The largest lag -- by default, a quarter of the number of points (the usual rule
+ * of thumb, since the estimates for larger lags rest on too few pairs of points), but no more than 50
+ * @return The autocorrelation for each lag, from 0 to the largest lag, or `undefined` when there
+ * are fewer than four points (so no lag beyond 0), or the values don't vary
+ */
+export function autocorrelation(
+    points: { length: number, [index: number]: Datum },
+    maxLag?: number
+): Array<number> | undefined {
+    const values: Array<number> = []
+    for (let i = 0; i < points.length; i++) {
+        if (Number.isFinite(points[i].x) && Number.isFinite(points[i].y)) values.push(points[i].y)
+    }
+    const count = values.length
+    const largestLag = Math.min(count - 1, maxLag ?? Math.min(MAX_AUTOCORRELATION_LAG, Math.floor(count / 4)))
+    if (largestLag < 1) return undefined
+
+    const mean = values.reduce((sum, value) => sum + value, 0) / count
+    const deviations = values.map(value => value - mean)
+    const variance = deviations.reduce((sum, deviation) => sum + deviation * deviation, 0)
+    if (variance === 0) return undefined
+
+    const correlations: Array<number> = []
+    for (let lag = 0; lag <= largestLag; lag++) {
+        let sum = 0
+        for (let t = 0; t + lag < count; t++) sum += deviations[t] * deviations[t + lag]
+        correlations.push(sum / variance)
+    }
+    return correlations
+}

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

@@ -0,0 +1,68 @@
+import {type JSX, createContext, useContext} from "react"
+import type {OutlierBandTooltipMetadata} from "../plots/OutlierPlot"
+import type {TooltipStyle} from "./tooltipUtils"
+
+/**
+ * What the outlier tooltip shows: the name of the series, and the band (and, for an outlier, the
+ * datum) under the mouse
+ */
+export type OutlierTooltipData<M extends readonly number[] = readonly number[]> =
+    {seriesName: string} & OutlierBandTooltipMetadata<M>
+
+/**
+ * The (optional) formatters for the outlier tooltip's content
+ */
+export type OutlierTooltipContentFormatters = {
+    /**
+     * Formatter for the datum
+     * @param x X-coordinate of the datum
+     * @param y Y-coordinate of the datum
+     * @return a human-readable description of the datum
+     */
+    datumFormatter?: (x: number, y: number) => string | JSX.Element
+    /**
+     * Formatter for the band (it's handed the band's measures, not its bounds)
+     * @param lower The measure of the band's inner edge (the measure of the next tighter band, or
+     * 0 for the tightest band)
+     * @param upper The measure of the band's outer edge (the hovered band's own measure)
+     * @return a human-readable description of the band
+     */
+    bandFormatter?: (lower: number, upper: number) => string | JSX.Element
+    /**
+     * Formatter for the description of the band's measure: the probabilities of a point being in,
+     * and outside, the band
+     * @param innerProb Probability of points being within this band
+     * @param outerProb Probability of points being outside this band
+     * @return a human-readable description of the band: text, JSX, or an array of lines (shown
+     * one per line)
+     */
+    measureFormatter?: (innerProb: number, outerProb: number) => string | JSX.Element | Array<string>
+}
+
+/**
+ * The outlier tooltip's context: what it shows, its style, and its formatters (the
+ * `measureFormatter`'s lines, when it returns an array of them, already laid out one per line)
+ */
+export type OutlierTooltipContextValue = {
+    tooltipContent: OutlierTooltipData
+    tooltipStyle: TooltipStyle
+    datumFormatter: (x: number, y: number) => string | JSX.Element
+    bandFormatter: (lower: number, upper: number) => string | JSX.Element
+    measureFormatter: (innerProb: number, outerProb: number) => string | JSX.Element
+}
+
+export const UseOutlierTooltip = createContext<OutlierTooltipContextValue | null>(null)
+
+/**
+ * Hook for consuming the outlier tooltip context inside a child of
+ * {@link OutlierPlotTooltipContent} (for writing your own content for the outlier tooltip)
+ * @return What the tooltip shows, its style, and its formatters
+ * @throws Error when used outside an `<OutlierPlotTooltipContent>`
+ */
+export function useOutlierTooltip(): OutlierTooltipContextValue {
+    const context = useContext(UseOutlierTooltip)
+    if (context === null) {
+        throw new Error('useOutlierTooltip must be used inside OutlierPlotTooltipContent')
+    }
+    return context
+}

package/src/app/charts/tooltips/useTooltipPlacement.ts

@@ -0,0 +1,86 @@
+import {type RefObject, useLayoutEffect} from "react";
+import type {Dimensions, Margin} from "../styling/margins";
+import {type TooltipStyle, tooltipX, tooltipY} from "./tooltipUtils";
+
+/**
+ * Where a tooltip is anchored: the mouse, when the tooltip's content was captured
+ */
+export type TooltipAnchor = {
+    /**
+     * The mouse's coordinates, relative to the chart (its canvas)
+     */
+    mouse: [x: number, y: number]
+    /**
+     * The chart's (canvas') position in the viewport, when the content was captured
+     */
+    canvasLeft: number
+    canvasTop: number
+    /**
+     * Optional: the y-coordinate (relative to the chart) of the tooltip's top, given its rendered
+     * height, for a tooltip that isn't placed below the mouse (e.g. one centered on a raster
+     * plot's category). Defaults to `tooltipY`.
+     */
+    topFor?: (height: number) => number
+}
+
+/**
+ * Positions a tooltip (a `position: fixed` element, e.g. a tooltip content's portal) next to the
+ * mouse, based on its *rendered* size: after each render, measures the tooltip and sets its
+ * `left` and `top` directly, before the browser paints (so the tooltip never shows in the wrong
+ * place). The tooltip goes to the right of the mouse, or to the left when it would run past the
+ * plot's right edge (see `tooltipX` and `tooltipY`).
+ *
+ * A tooltip's size depends on its content, so it can only be known once the content has been
+ * rendered -- positioning it from an estimate of its size put a narrower-than-estimated tooltip
+ * far from the mouse when it flipped to the mouse's left.
+ * @param tooltipRef The tooltip's element
+ * @param anchor Where the tooltip is anchored (the mouse), or `null` when no tooltip is shown
+ * @param plotDimensions The dimensions of the plot
+ * @param margin The plot margin
+ * @param tooltipStyle The tooltip's style
+ */
+export function useTooltipPlacement(
+    tooltipRef: RefObject<HTMLElement | null>,
+    anchor: TooltipAnchor | null,
+    plotDimensions: Dimensions,
+    margin: Margin,
+    tooltipStyle: TooltipStyle,
+): void {
+    useLayoutEffect(
+        () => {
+            const tooltip = tooltipRef.current
+            if (tooltip === null || anchor === null) return
+            // measured at the viewport's top-left corner, where nothing limits its width: a
+            // `position: fixed` element near the viewport's right edge only gets the width left to
+            // the edge, so its content could wrap, and it would measure narrower than it really is
+            tooltip.style.left = '0px'
+            tooltip.style.top = '0px'
+            const {width, height} = tooltip.getBoundingClientRect()
+            const [x, y] = anchor.mouse
+            const left = tooltipX(x, width, plotDimensions, tooltipStyle, margin)
+            const top = anchor.topFor !== undefined ?
+                anchor.topFor(height) :
+                tooltipY(y, height, plotDimensions, tooltipStyle, margin)
+            tooltip.style.left = `${anchor.canvasLeft + left}px`
+            tooltip.style.top = `${anchor.canvasTop + top}px`
+        }
+    )
+}
+
+/**
+ * Creates a tooltip's anchor: the mouse, relative to the chart, and the chart's position in the
+ * viewport
+ * @param mouseCoords The mouse's coordinates, relative to the chart (its canvas)
+ * @param canvas The chart's canvas
+ * @param topFor Optional: the y-coordinate of the tooltip's top for its rendered height (see
+ * {@link TooltipAnchor.topFor})
+ * @return The anchor
+ */
+export function tooltipAnchorFor(
+    mouseCoords: [x: number, y: number],
+    canvas: HTMLCanvasElement,
+    topFor?: (height: number) => number
+): TooltipAnchor {
+    const canvasRect = canvas.getBoundingClientRect()
+    return {mouse: mouseCoords, canvasLeft: canvasRect.left, canvasTop: canvasRect.top, topFor}
+}

package/src/app/charts/tooltips/useTooltipStyle.ts

@@ -0,0 +1,15 @@
+import {createContext, useContext} from "react";
+import {defaultTooltipStyle, type TooltipStyle} from "./tooltipUtils";
+
+/**
+ * The style of the enclosing {@link Tooltip} (its `style`, over the default tooltip style)
+ */
+export const TooltipStyleContext = createContext<TooltipStyle>(defaultTooltipStyle)
+
+/**
+ * @return The style of the enclosing {@link Tooltip}: its `style` property over the default tooltip
+ * style (or just the default style, outside a tooltip)
+ */
+export function useTooltipStyle(): TooltipStyle {
+    return useContext(TooltipStyleContext)
+}