stream-charts 1.2.1 → 2.0.0

package/src/app/charts/axes/OrdinalAxis.tsx

@@ -1,21 +1,21 @@
 import {
-    addOrdinalStringAxis,
-    AxesFont,
+    type AxesFont,
     AxisLocation,
-    AxisTickStyle, ContinuousNumericAxis,
-    defaultAxesFont,
+    type AxisTickStyle, defaultAxesFont,
     defaultAxisTickStyle,
-    labelIdFor,
-    OrdinalStringAxis
+    addOrdinalStringAxis,
+    removeOrdinalXAxis,
+    removeOrdinalYAxis,
+    type OrdinalStringAxis,
+    type SeriesStyle
 } from "./axes"
-import * as d3 from "d3";
-import {ScaleBand} from "d3";
-import {useChart} from "../hooks/useChart";
+import type {ScaleBand} from "d3";
+import {type NoTooltipMetadata, useChart} from "../hooks/useChart";
 import {useEffect, useRef} from "react";
-import {Dimensions} from "../styling/margins";
+import type {Dimensions} from "../styling/margins";
 import {usePlotDimensions} from "../hooks/usePlotDimensions";
 import {OrdinalAxisRange} from "./OrdinalAxisRange";
-import {Datum} from "../series/timeSeries";
+import type {Datum} from "../series/timeSeries";
 import {AxisInterval} from "./AxisInterval";
 
 export interface Props {
@@ -56,17 +56,18 @@ export interface Props {
  * Category axis that represents the x-axis when its location is either on the bottom or the top.
  * When the axis location is left or right, then the category axis represents the y-axis. The category
  * axis requires a set of categories that will form the axis. Generally, these categories should
- * be the name of the series used to represent each category.
+ * be the name of the series used to represent each category. This component returns null, meaning
+ * React won't render it because we are drawing directly onto the chart's shared canvas.
  * @param props The properties for the component
  * @return null
  */
 export function OrdinalAxis(props: Props): null {
     const {
         chartId,
-        container,
+        canvasContext,
         axes,
         color,
-    } = useChart<Datum, any, any, OrdinalAxisRange, OrdinalStringAxis>()
+    } = useChart<Datum, SeriesStyle, NoTooltipMetadata, OrdinalAxisRange, OrdinalStringAxis>()
 
     const {
         xAxesState,
@@ -103,18 +104,16 @@ export function OrdinalAxis(props: Props): null {
     // handles plot size changes by updating the range of the axis and the original range of the axis
     useEffect(
         () => {
-            if (container) {
-                const svg = d3.select<SVGSVGElement, any>(container)
+            if (canvasContext) {
                 const font: AxesFont = {...defaultAxesFont(), color, ...props.font}
                 const axisTickStyle = {...defaultAxisTickStyle(), ...props.axisTickStyle}
 
-
                 // lambda that gets called when the axes need to be updated
                 const handleRangeUpdates = (updates: Map<string, OrdinalAxisRange>, plotDim: Dimensions): void => {
                     if (rangeUpdateHandlerIdRef.current && axis) {
                         const range = updates.get(axisId)
                         if (range) {
-                            axis.update(range.current, range.original, plotDim, margin)
+                            axis.update(categories, range.current, range.original, plotDim, margin)
                         }
                     }
                 }
@@ -126,13 +125,13 @@ export function OrdinalAxis(props: Props): null {
                         case AxisLocation.Top:
                         case AxisLocation.Bottom: {
                             const xAxis = addOrdinalStringAxis(
-                                chartId, axisId, svg, location, categories,
+                                canvasContext, axisId, location, categories,
                                 label, font, axisTickStyle, plotDimensions, margin,
                                 setAxisIntervalFor, setOriginalAxisIntervalFor
                             )
 
                             // add the x-axis to the chart context
-                            const [start, end] = AxisInterval.as(xAxis.scale.range()).asTuple()
+                            const [start, end] = AxisInterval.as(xAxis.scale.range() as [number, number]).asTuple()
                             addXAxis(xAxis, axisId, OrdinalAxisRange.from(start, end))
 
                             // add an update handler
@@ -144,12 +143,12 @@ export function OrdinalAxis(props: Props): null {
                         case AxisLocation.Left:
                         case AxisLocation.Right: {
                             const yAxis = addOrdinalStringAxis(
-                                chartId, axisId, svg, location, categories,
+                                canvasContext, axisId, location, categories,
                                 label, font, axisTickStyle, plotDimensions, margin,
                                 setAxisIntervalFor, setOriginalAxisIntervalFor
                             )
                             // add the y-axis to the chart context
-                            const [start, end] = AxisInterval.as(yAxis.scale.range()).asTuple()
+                            const [start, end] = AxisInterval.as(yAxis.scale.range() as [number, number]).asTuple()
                             addYAxis(yAxis, axisId, OrdinalAxisRange.from(start, end))
                             // add an update handler
                             rangeUpdateHandlerIdRef.current = `y-axis-${chartId}-${axisId}-${location.valueOf()}`
@@ -161,15 +160,20 @@ export function OrdinalAxis(props: Props): null {
                         .map(range => ([range.current, range.original]))
                         .getOrElse([AxisInterval.empty(), AxisInterval.empty()])
                     if (range && originalRange) {
-                        axis.update(range, originalRange, plotDimensions, margin)
+                        axis.update(categories, range, originalRange, plotDimensions, margin)
                     }
 
-                    svg.select(`#${labelIdFor(chartId, location)}`).attr('fill', color)
+                    // keep the axis *label's* color in sync with the chart's color (e.g. on theme
+                    // change), without recreating the axis or touching its domain. Note: tick label
+                    // color is intentionally NOT touched here -- it stays fixed at whatever
+                    // axisTickStyle.font was at creation, matching the original SVG version, which
+                    // only ever updated the label's `fill`, not the ticks'.
+                    axis.updateFont(font)
                 }
             }
         },
         [
-            container,
+            canvasContext,
             axis,
             addXAxis, addYAxis,
             addAxesRangesUpdateHandler,
@@ -193,7 +197,10 @@ export function OrdinalAxis(props: Props): null {
                         const {current, original} = OrdinalAxisRange
                             .from(start, end, 0, oldDimension.width)
                             .zoom(oldDimension.width, newDimension.width)
-                        axis.update(current, original, plotDimensions, margin)
+                        // a resize never changes the set of categories -- read the axis's own
+                        // current domain rather than `categories` from props, since `categories`
+                        // isn't in this effect's dependency array and so may be stale here
+                        axis.update(axis.scale.domain(), current, original, plotDimensions, margin)
                     }
                     if (location === AxisLocation.Left || location === AxisLocation.Right) {
                         const [start, end] = axisRangeFor(axisId)
@@ -202,7 +209,7 @@ export function OrdinalAxis(props: Props): null {
                         const {current, original} = OrdinalAxisRange
                             .from(start, end, 0, oldDimension.height)
                             .zoom(oldDimension.height, newDimension.height)
-                        axis.update(current, original, plotDimensions, margin)
+                        axis.update(axis.scale.domain(), current, original, plotDimensions, margin)
                     }
                 }
             })
@@ -229,6 +236,25 @@ export function OrdinalAxis(props: Props): null {
         [removeAxesRangesUpdateHandler]
     )
 
+    // unregister the axis' draw function when the axis unmounts
+    useEffect(
+        () => {
+            return () => {
+                if (canvasContext) {
+                    switch (location) {
+                        case AxisLocation.Top:
+                        case AxisLocation.Bottom:
+                            removeOrdinalXAxis(canvasContext, axisId)
+                            break
+                        case AxisLocation.Left:
+                        case AxisLocation.Right:
+                            removeOrdinalYAxis(canvasContext, axisId)
+                    }
+                }
+            }
+        },
+        [canvasContext, axisId, location]
+    )
+
     return null
 }
-

package/src/app/charts/axes/OrdinalAxisRange.ts

@@ -6,6 +6,13 @@ import {BaseAxisRange} from "./BaseAxisRange";
  */
 export class OrdinalAxisRange extends BaseAxisRange {
 
+    /**
+     * Use {@link OrdinalAxisRange.from} to create an instance
+     * @param start The start of the axis-range
+     * @param end The end of the axis-range
+     * @param [originalStart=start] The original start of the axis-range
+     * @param [originalEnd=end] The original end of the axis-range
+     */
     private constructor(start: number, end: number, originalStart: number = start, originalEnd: number = end) {
         super(start, end, originalStart, originalEnd)
     }
@@ -18,36 +25,100 @@ export class OrdinalAxisRange extends BaseAxisRange {
      * Defaults to the start value if not specified.)
      * @param [originalEnd=end] The optional original end of the axis-range (e.g. before any zooming or panning.
      * Defaults to the end value if not specified.)
-     * @return A new continuous-axis range instance.
+     * @return A new ordinal-axis range instance.
      */
     static from(start: number, end: number, originalStart: number = start, originalEnd: number = end): OrdinalAxisRange {
         return new OrdinalAxisRange(start, end, originalStart, originalEnd)
     }
 
     /**
-     * Scales the axis-range by the specified scale factor from the specified value. The equations
-     * are written so that the zooming (scaling) occurs at the specified value, and expands/contracts equally
-     * from that value. This operation does not modify the original range.
-     * @param factor The scale factor
+     * Scales the axis-range by the specified *cumulative* scale factor (d3-zoom's own
+     * `event.transform.k`, taken as-is -- NOT converted to an incremental, relative-to-the-
+     * previous-event factor), pivoting on `value`.
+     *
+     * Two cases, because neither a purely incremental nor a purely cumulative-from-`.original`
+     * formula is correct on its own for a bounded ordinal domain:
+     *
+     * - `factor === 1` (fully zoomed out): returns `.original` directly, bypassing the pivot math
+     *   entirely. An ordinal axis's domain (the fixed set of categories) is bounded, so "zoomed all
+     *   the way back out" has exactly one correct answer -- `.current` must equal `.original`
+     *   *exactly*, regardless of how many different pivots were used to get there. d3-zoom's own
+     *   `.scaleExtent` clamps `k` to *exactly* 1 at the zoom floor (not just asymptotically close),
+     *   so this equality check reliably detects that boundary.
+     * - Otherwise: scales from `.current` using the *incremental* step implied by the cumulative
+     *   factor (`factor` divided by the range's own current/original width ratio) -- the same
+     *   pivot-preserving composition `ContinuousAxisRange` uses (see `BaseAxisRange.scaledRange`).
+     *   This composes correctly across any sequence of differing pivots without jumping.
+     *
+     * Why not just always scale from `.original` by the cumulative factor (a prior version of this
+     * method did exactly that)? Composing pivot-preserving zooms at *different* pivots is not
+     * itself position-preserving -- zooming in at one spot and back out at another nets a
+     * translation, same as any pinch-zoom or map UI, verified live: zoom in at pivot A to k=5, then
+     * zoom out at a different pivot B to k=1, lands `.current` at `[400, 1400]` instead of
+     * `[0, 1000]` even under the mathematically-correct incremental composition. Scaling
+     * `.original` directly by the raw cumulative factor "fixes" that only by recomputing the
+     * *entire* zoom from scratch at the current pivot on every single event -- which is correct
+     * only when the pivot never changes since the last identity reset, and otherwise discards all
+     * zoom history, producing a visible jump the moment the pivot changes at any *non-identity* zoom
+     * level (confirmed live: continuing to zoom in from k=5 at pivot A to k=6 at a different pivot B
+     * jumped from the correct, continuous `[-1600, 4400]` to `[-4000, 2000]`). The `factor === 1`
+     * special case gets the position-preserving guarantee only where it's actually needed -- the
+     * one canonical "fully zoomed out" state -- without sacrificing composability everywhere else.
+     * A continuous/scrolling axis (`ContinuousAxisRange`) never needs the equivalent of this special
+     * case, since it has no fixed domain edge for translational drift to visibly clip against.
+     * @param factor The cumulative scale factor (`event.transform.k`, unmodified)
      * @param value The value from which to scale the interval
-     * @return A new continuous-axis range with updated values
+     * @return The new range, as a plain {start, end} pair
+     */
+    private scaledCumulative(factor: number, value: number): {start: number, end: number} {
+        // when the factor is 1 or the original measure is 0, return the original range
+        if (factor === 1 || this.original.measure() === 0) {
+            return {start: this.original.start, end: this.original.end}
+        }
+        const scaleFactor = this.current.measure() / this.original.measure()
+        const incrementalFactor = factor / scaleFactor
+        const dtStart = value - this.current.start
+        const dtEnd = this.current.end - value
+        return {start: value - dtStart * incrementalFactor, end: value + dtEnd * incrementalFactor}
+    }
+
+    /**
+     * Scales the axis-range by the specified *cumulative* scale factor (see
+     * `scaledCumulative` for why this must be cumulative, not incremental) from the
+     * specified value. The equations are written so that the zooming (scaling) occurs at the
+     * specified value, and expands/contracts equally from that value. This operation does not
+     * modify the original range.
+     * @param factor The cumulative scale factor
+     * @param value The value from which to scale the interval
+     * @return A new ordinal-axis range with updated values
      */
     scale(factor: number, value: number): OrdinalAxisRange {
-        const scaledInterval = this.scaledRange(factor, value)
+        const scaledInterval = this.scaledCumulative(factor, value)
         return new OrdinalAxisRange(scaledInterval.start, scaledInterval.end, this.original.start, this.original.end)
     }
 
     /**
-     * Scales the axis-range by the specified scale factor from the specified value, while keeping
-     * the range within the constraints (start, end). The equations are written so that the zooming
-     * (scaling) occurs at the specified value, and expands/contracts equally from that value.
-     * @param factor The scale factor
+     * Scales the axis-range by the specified *cumulative* scale factor (see
+     * `scaledCumulative` for why this must be cumulative, not incremental) from the
+     * specified value, while keeping the range within the constraints (start, end). The equations
+     * are written so that the zooming (scaling) occurs at the specified value, and
+     * expands/contracts equally from that value.
+     *
+     * Widens the scaled result to *cover* `constraint` (never narrower than it) -- `constraint`
+     * is the domain that must be fully visible once zoomed all the way out, and widening rather
+     * than clamping is exactly what fixes the pivot-drift bug described on
+     * `scaledCumulative` (zooming in at one pivot and back out at another must never leave
+     * part of the domain clipped). This is the opposite direction from
+     * {@link ContinuousAxisRange.constrainedScale}, which *clamps* its result inside `constraint`
+     * instead -- see that method's doc comment for why a continuous axis needs the opposite
+     * behavior. Do not "fix" this difference without reading both.
+     * @param factor The cumulative scale factor
      * @param value The value from which to scale the interval
      * @param constraint The minimum and maximum values that range bounds can be
-     * @return A new continuous-axis range with updated values
+     * @return A new ordinal-axis range with updated values
      */
     constrainedScale(factor: number, value: number, constraint: [min: number, max: number]): OrdinalAxisRange {
-        const scaledInterval = this.scaledRange(factor, value)
+        const scaledInterval = this.scaledCumulative(factor, value)
         const [min, max] = constraint
         return new OrdinalAxisRange(
             Math.min(min, scaledInterval.start),
@@ -57,14 +128,16 @@ export class OrdinalAxisRange extends BaseAxisRange {
         )
     }
     /**
-     * Translates the axis-range by the specified amount
+     * Translates the axis-range by the specified amount, unless that would take it outside the
+     * constraint interval (when both ends of the constraint are infinite, there's no constraint)
      * @param amount The amount by which to translate the axis-range
      * @param [constraint=[-Infinity, Infinity]] Optional constraint interval in which the axis range must be within
-     * @return An updated {@link OrdinalAxisRange} that has been translated by the specified amount
+     * @return An updated {@link OrdinalAxisRange} that has been translated by the specified amount (or an
+     * unchanged copy, when the translation would leave the constraint interval)
      */
     translate(amount: number, constraint: [start: number, end: number] = [-Infinity, Infinity]): OrdinalAxisRange {
         const [cs, ce] = constraint
-        // when either of the constraints is infinite, or the pan keeps the new axis range
+        // when both of the constraints are infinite, or the pan keeps the new axis range
         // within the origin axis range (i.e. zoomed in and the panned), then allow the pan,
         // otherwise don't update
         if ((!isFinite(cs) && !isFinite(ce)) || (this.current.start + amount >= cs && this.current.end + amount <= ce)) {
@@ -83,6 +156,13 @@ export class OrdinalAxisRange extends BaseAxisRange {
      * the dimensions.
      */
     zoom(beforeDimension: number, afterDimension: number): OrdinalAxisRange {
+        // a zero `beforeDimension` (e.g. a chart mounted inside a collapsed/hidden container that
+        // later becomes visible) would otherwise divide by zero below, producing a NaN/Infinity
+        // range that corrupts this axis until remount. There's no proportional "before" range to
+        // scale from in that case, so just take the new dimension as the fresh, un-zoomed range.
+        if (beforeDimension === 0) {
+            return new OrdinalAxisRange(0, afterDimension, 0, afterDimension)
+        }
         const [start, end] = this.current.asTuple()
         const delta = (end - start ) * (afterDimension - beforeDimension) / beforeDimension
         const lowerBound = start / (end - start) * delta + start

package/src/app/charts/axes/autoScale.ts

@@ -0,0 +1,244 @@
+import type {ScaleContinuousNumeric} from "d3";
+import {firstIndexAtOrAfter} from "../utils";
+
+/**
+ * The auto-scaling settings of a (y-) axis whose domain grows to fit the data plotted against it
+ * (see `ContinuousAxis`'s `autoScale`, `autoScaleMin`, `autoScaleMax`, and `autoScalePadding` props)
+ */
+export type AutoScale = {
+    /**
+     * Where the axis' domain starts out: its `domain` prop, clamped to the limits. It's what the
+     * domain is restored to when its plot's data is replaced (e.g. on a reset).
+     */
+    domain: [min: number, max: number]
+    /**
+     * The smallest value the axis' domain may reach
+     */
+    min: number
+    /**
+     * The largest value the axis' domain may reach
+     */
+    max: number
+    /**
+     * The fraction of the axis' length left beyond the data's extreme on a side that grows (so
+     * the extreme point isn't drawn right on the edge), from 0 to 0.45
+     */
+    padding: number
+}
+
+/**
+ * Clamps a domain to the auto-scaling limits, so that an auto-scaling axis never starts out past
+ * them. (When the domain lies entirely beyond a limit, it collapses onto that limit.)
+ * @param domain The domain
+ * @param min The smallest value the domain may reach
+ * @param max The largest value the domain may reach
+ * @return The domain, clamped to the limits
+ */
+export function clampedDomain(
+    domain: [min: number, max: number],
+    min: number,
+    max: number
+): [min: number, max: number] {
+    const clamp = (value: number) => Math.min(max, Math.max(min, value))
+    return [clamp(domain[0]), clamp(domain[1])]
+}
+
+/**
+ * Whether two auto-scaling settings are the same (`undefined` means "not auto-scaling")
+ * @param a The first settings
+ * @param b The second settings
+ * @return `true` when they're the same; `false` otherwise
+ */
+export function sameAutoScale(a: AutoScale | undefined, b: AutoScale | undefined): boolean {
+    if (a === undefined || b === undefined) return a === b
+    return a.domain[0] === b.domain[0] && a.domain[1] === b.domain[1] &&
+        a.min === b.min && a.max === b.max && a.padding === b.padding
+}
+
+/**
+ * Grows an axis' domain to include the specified extent of the data, with the padding beyond it,
+ * without going past the auto-scaling limits. A side grows when the data reaches into its padding
+ * (not only when the data goes past the edge), so that the data always has the padding's room to
+ * spare (until a limit is reached), and it grows so that the data's extreme sits exactly the
+ * padding from the edge. The domain only ever grows: an extent that's within the domain, and
+ * clear of its padding, leaves the domain as it is.
+ *
+ * The padding is applied in the scale's own space (e.g. logarithmically, for a log scale), as a
+ * fraction of the axis' length.
+ * @param domain The axis' current domain
+ * @param extent The [min, max] of the data plotted against the axis, or `undefined` when there's
+ * no data
+ * @param autoScale The auto-scaling settings (the limits, and the padding)
+ * @param scale The axis' scale (only its kind matters: linear, log, ...)
+ * @return The grown domain (or the current domain, when there's nothing to grow for)
+ */
+export function grownDomain(
+    domain: [min: number, max: number],
+    extent: [min: number, max: number] | undefined,
+    autoScale: Pick<AutoScale, 'min' | 'max' | 'padding'>,
+    scale: ScaleContinuousNumeric<number, number>
+): [min: number, max: number] {
+    if (extent === undefined) return domain
+    const [domainMin, domainMax] = domain
+    const padding = Math.min(0.45, Math.max(0, autoScale.padding))
+
+    // a side grows when the data reaches into its padding (or past its edge). Where the data sits
+    // within the current domain is measured in the scale's own space, with a little tolerance, so
+    // that an extreme that sits exactly the padding from the edge (as growing leaves it) doesn't
+    // grow the domain again by rounding errors on every frame.
+    const tolerance = 1e-9
+    const current = scale.copy().domain([domainMin, domainMax]).range([0, 1])
+    const growsDown = extent[0] < domainMin || current(extent[0]) < padding - tolerance
+    const growsUp = extent[1] > domainMax || current(extent[1]) > 1 - padding + tolerance
+    if (!growsDown && !growsUp) return domain
+
+    let min = growsDown ? extent[0] : domainMin
+    let max = growsUp ? extent[1] : domainMax
+    if (padding > 0 && min < max) {
+        // the normalized scale over the grown domain, extended on each growing side so that the
+        // extreme sits `padding` of the (extended) axis' length from that edge: with n growing
+        // sides, each extension e satisfies e / (1 + n e) = padding
+        const normalized = scale.copy().domain([min, max]).range([0, 1])
+        const growingSides = (growsDown ? 1 : 0) + (growsUp ? 1 : 0)
+        const extension = padding / (1 - growingSides * padding)
+        if (growsDown) min = normalized.invert(-extension)
+        if (growsUp) max = normalized.invert(1 + extension)
+    }
+    // (never past the limits -- and never shrinking a side, should the domain already be past one)
+    return [
+        growsDown ? Math.min(domainMin, Math.max(autoScale.min, min)) : domainMin,
+        growsUp ? Math.max(domainMax, Math.min(autoScale.max, max)) : domainMax,
+    ]
+}
+
+/**
+ * Extends an extent to include the specified value
+ * @param extent The extent so far, or `undefined` when there's none yet
+ * @param value The value to include
+ * @return The extent, including the value
+ */
+export function extentWith(
+    extent: [min: number, max: number] | undefined,
+    value: number
+): [min: number, max: number] {
+    if (extent === undefined) return [value, value]
+    return [Math.min(extent[0], value), Math.max(extent[1], value)]
+}
+
+/**
+ * Calculates the extent (the [min, max]) of the specified values, skipping those the y-scale
+ * can't show (e.g. values <= 0 on a log scale, or NaN)
+ * @param values The values
+ * @param yScale The y-axis' scale
+ * @return The extent of the values, or `undefined` when there are none (that can be shown)
+ */
+export function extentOf(
+    values: Iterable<number>,
+    yScale: ScaleContinuousNumeric<number, number>
+): [min: number, max: number] | undefined {
+    let extent: [min: number, max: number] | undefined = undefined
+    for (const value of values) {
+        if (Number.isFinite(yScale(value))) extent = extentWith(extent, value)
+    }
+    return extent
+}
+
+/**
+ * Calculates the extent (the [min, max] of the y-values) of a series' data that's visible within
+ * the x-axis' window: the values of the points within the window, and -- when the series is drawn
+ * with lines -- the lines' heights where they cross the window's left and right edges (a line from
+ * a point just off screen can reach higher, or lower, within the window than any point that's on
+ * screen). Values the y-scale can't show (e.g. values <= 0 on a log scale) are skipped.
+ *
+ * A point can have several values, each drawn as its own line across the points (e.g. an outlier
+ * series' value, and its bands' lower and upper bounds), so the crossings are calculated for each.
+ * They're calculated in the y-scale's own space (as the lines are drawn), so they're exact for
+ * straight lines, on any kind of scale.
+ * @param data The series' data, ordered by x
+ * @param window The x-axis' [start, end]
+ * @param yScale The y-axis' scale
+ * @param withLines Whether the series is drawn with lines (rather than just points)
+ * @param xOf The point's x-value (defaults to its `x`)
+ * @param valuesOf The point's y-values, each drawn as its own line (defaults to its `y`)
+ * @return The extent of the visible data, or `undefined` when nothing is visible
+ * @template P The type of the data's points
+ */
+export function visibleExtent<P>(
+    data: { length: number, [index: number]: P },
+    window: [start: number, end: number],
+    yScale: ScaleContinuousNumeric<number, number>,
+    withLines: boolean,
+    xOf: (point: P) => number = point => (point as { x: number }).x,
+    valuesOf: (point: P) => Array<number> = point => [(point as { y: number }).y],
+): [min: number, max: number] | undefined {
+    const [start, end] = window
+    const showable = (value: number) => Number.isFinite(yScale(value))
+    // includes the heights where the lines between the two points cross x
+    const withCrossings = (
+        extent: [min: number, max: number] | undefined,
+        from: P,
+        to: P,
+        x: number
+    ): [min: number, max: number] | undefined => {
+        const fromValues = valuesOf(from)
+        const toValues = valuesOf(to)
+        const fraction = xOf(to) === xOf(from) ? 1 : (x - xOf(from)) / (xOf(to) - xOf(from))
+        fromValues.forEach((fromValue, index) => {
+            const toValue = toValues[index]
+            if (toValue === undefined || !showable(fromValue) || !showable(toValue)) return
+            const fromY = yScale(fromValue)
+            extent = extentWith(extent, yScale.invert(fromY + (yScale(toValue) - fromY) * fraction))
+        })
+        return extent
+    }
+
+    let extent: [min: number, max: number] | undefined = undefined
+    let index = firstIndexAtOrAfter(data, start, xOf)
+
+    // the lines entering through the window's left edge
+    if (withLines && index > 0 && index < data.length && xOf(data[index]) <= end) {
+        extent = withCrossings(extent, data[index - 1], data[index], start)
+    }
+
+    // the points within the window
+    for (; index < data.length && xOf(data[index]) <= end; index++) {
+        valuesOf(data[index]).forEach(value => {
+            if (showable(value)) extent = extentWith(extent, value)
+        })
+    }
+
+    // the lines leaving through the window's right edge (or, when no point is within the window,
+    // passing straight across it)
+    if (withLines && index > 0 && index < data.length && xOf(data[index - 1]) < end) {
+        extent = withCrossings(extent, data[index - 1], data[index], end)
+        if (xOf(data[index - 1]) < start) extent = withCrossings(extent, data[index - 1], data[index], start)
+    }
+    return extent
+}
+
+// the warnings already issued (each is only issued once)
+const issuedWarnings = new Set<string>()
+
+/**
+ * Issues a warning to the console, once (e.g. about auto-scaling settings that are ignored)
+ * @param message The warning
+ */
+export function warnOnce(message: string): void {
+    if (issuedWarnings.has(message)) return
+    issuedWarnings.add(message)
+    console.warn(message)
+}
+
+/**
+ * Warns (once per axis) about the auto-scaling y-axes of a plot that doesn't support auto-scaling,
+ * whose `autoScale` setting is therefore ignored
+ * @param plotName The name of the plot (e.g. "BarPlot")
+ * @param yAxes The plot's y-axes, by their IDs
+ */
+export function warnAboutIgnoredAutoScale(plotName: string, yAxes: Map<string, object>): void {
+    yAxes.forEach((axis, axisId) => {
+        if ((axis as { autoScale?: AutoScale }).autoScale !== undefined) {
+            warnOnce(`The ${plotName} doesn't support auto-scaling y-axes, so the "autoScale" setting of y-axis "${axisId}" is ignored`)
+        }
+    })
+}