stream-charts 1.2.0 → 2.0.0

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

@@ -1,16 +1,20 @@
-import {BaseAxis} from "./axes";
+import type {BaseAxis} from "./axes";
 import {Optional} from "result-fn";
 
 /**
- * Holds the information to allow mapping axes names to the underlying axes objects.
- * These objects hold the axis ID, its location on the chart (i.e. left, right, bottom, upper)
- * and the underlying d3 selection objects for managing the axes. Axis objects that extend
- * the `BaseAxis` class may have additional properties.
+ * Holds the information to allow mapping axes IDs to the underlying axes objects (of either the
+ * x-axes or the y-axes). These objects hold the axis ID, its location on the chart (i.e. left,
+ * right, bottom, top), its type, and (for the axis types that extend `BaseAxis`) its scale and the
+ * functions for updating and drawing it.
  * @typeParam A The type of the axes (must extend `BaseAxis`)
  */
 export class AxesState<A extends BaseAxis> {
     readonly axes: Map<string, A>
 
+    /**
+     * Use {@link from} or {@link empty} to create an axes state
+     * @param axes Mapping of the axes IDs to the axes
+     */
     private constructor(axes: Map<string, A>) {
         this.axes = axes
     }
@@ -40,19 +44,8 @@ export class AxesState<A extends BaseAxis> {
     }
 
     /**
-     * Creates a deep copy of the current axes state.
-     * @return A deep copy of the current axes state.
-     */
-    copy(): AxesState<A> {
-        return new AxesState<A>(
-            new Map<string, A>(Array.from(this.axes.entries())
-                .map(([id, axis]) => [id, {...axis}])
-            )
-        )
-    }
-
-    /**
-     * Adds an axis to the current axis state and returns a new axis state. This is an internal state
+     * Adds an axis to this axes state's map of axes (in place), and returns a new axes state holding
+     * that same map (a new object, so that React sees the change). This is an internal state
      * management function. This should generally not be used. Instead, use the {@link UseAxesValues.addXAxis}
      * and {@link UseAxesValues.addYAxis} functions to add axes.
      * @param axis The axis to add
@@ -67,23 +60,27 @@ export class AxesState<A extends BaseAxis> {
     }
 
     /**
-     * Attempts to retrieve the x-axis for the specified ID
-     * @param axisId The unique ID of the axis
-     * @return The axis, or undefined if no axis with the specified ID is found
+     * Attempts to retrieve the axis for the specified ID.
+     * @param axisId The unique ID of the axis, or `""` to request the default axis (the
+     * convention used throughout this library wherever a series has no explicit axis
+     * assignment -- see e.g. each plot component's own `axesFor` helper).
+     * @return The axis matching `axisId`; the default axis (see {@link defaultAxis}) if
+     * `axisId` is `""` and at least one axis exists; otherwise an empty `Optional`. A non-empty
+     * `axisId` that doesn't match any axis is deliberately treated as "not found" rather than
+     * silently substituting an unrelated axis -- that used to happen for *any* unmatched ID,
+     * which masked stale/mistyped axis IDs as if they'd resolved correctly.
      */
     axisFor(axisId: string): Optional<A> {
         const axis = this.axes.get(axisId)
-        // when there is no axis for the specified ID and there is at least
-        // one axis, then just use that...it is the default axis
-        if (axis === undefined && this.axes.size >= 1) {
-            return Optional.of(Array.from(this.axes.values())[0])
+        if (axis === undefined && axisId === "" && this.axes.size >= 1) {
+            return this.defaultAxis()
         }
         return Optional.ofNullable(axis)
     }
 
     /**
-     * Returns the default axis
-     * @return The default axis
+     * Returns the default axis: the first axis added
+     * @return The default axis, or an empty `Optional` when there are no axes
      * @see axisDefaultId
      */
     defaultAxis(): Optional<A> {
@@ -94,14 +91,15 @@ export class AxesState<A extends BaseAxis> {
     }
 
     /**
-     * @return An array holding all existing the x-axis IDs
+     * @return An array holding the IDs of all the axes
      */
     axisIds(): Array<string> {
         return Array.from(this.axes.keys())
     }
 
     /**
-     * @return The default name of the x-axis (in case only on default axis was added)
+     * @return The ID of the default axis (the first axis added), or an empty `Optional` when there
+     * are no axes
      */
     axisDefaultId(): Optional<string> {
         const ids = Array.from(this.axes.keys())

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

@@ -1,18 +1,48 @@
 /**
- * The range of an axis is the physical (start, end) pixels on the screen for the axis.
- * This is the pixel-space of the axis (where as the domain is the data-space of the axis,
- * for example, the tick values).
+ * An immutable (start, end) interval, with `start <= end`, used both for an axis' domain (its
+ * data-space, for example, the range of the tick values) and for an axis' range (its pixel-space,
+ * the physical start and end pixels on the screen). An interval whose start or end is `NaN` is
+ * empty.
  */
 export class AxisInterval {
-    private constructor(readonly start: number, readonly end: number) {}
+    readonly start: number
+    readonly end: number
 
     /**
-     * Creates an axis interval from the specified start and end values
+     * Use {@link from}, {@link as}, or {@link empty} to create an axis interval
+     * @param start The interval's start
+     * @param end The interval's end
+     */
+    private constructor(start: number, end: number) {
+        this.start = start
+        this.end = end
+    }
+
+    /**
+     * Creates an axis interval from the specified start and end values. The values are normalized
+     * so that `start <= end` regardless of the order they're passed in -- callers never need to
+     * worry about which endpoint ended up larger (e.g. after a pan/zoom delta pushes one endpoint
+     * past the other).
+     *
+     * If exactly one of `start`/`end` is `NaN`, both endpoints of the result collapse to `NaN`
+     * (`Math.min`/`Math.max` propagate `NaN` unconditionally) -- the same representation as an
+     * intentionally-empty interval (see {@link empty}). That's indistinguishable from genuinely
+     * wanting an empty interval, and silently discards which of the two inputs was actually bad,
+     * so this logs a warning for that specific mixed case (one real number, one `NaN`) to surface
+     * what's almost always an upstream computation error -- `from(NaN, NaN)` (a deliberate empty
+     * interval) is not warned about.
      * @param start The axis-range start value
      * @param end The axis-range end value
      * @return The axis-interval
      */
     static from(start: number, end: number): AxisInterval {
+        if ((isNaN(start) || isNaN(end)) && !(isNaN(start) && isNaN(end))) {
+            console.warn(
+                `AxisInterval.from received exactly one NaN endpoint -- this usually indicates an ` +
+                `upstream computation error, not an intentional empty interval (use AxisInterval.empty() ` +
+                `for that); start: ${start}, end: ${end}`
+            )
+        }
         return new AxisInterval(Math.min(start, end), Math.max(start, end))
     }
 
@@ -48,7 +78,11 @@ export class AxisInterval {
     }
 
     /**
-     * @return `true` if the specified axis interval is equal to this one, `false` otherwise
+     * Determines whether this axis interval's start and end are the specified ones (two empty
+     * intervals are equal)
+     * @param start The start to compare to
+     * @param end The end to compare to
+     * @return `true` if this axis interval's start and end are the specified ones, `false` otherwise
      */
     equalsInterval(start: number, end: number): boolean {
         return (this.start === start && this.end === end) || (this.isEmpty() && isNaN(start) && isNaN(end))
@@ -64,8 +98,8 @@ export class AxisInterval {
     }
 
     /**
-     * Creates a copy of the specified axis interval
-     * @return A copy of the specified axis interval
+     * Creates a copy of this axis interval
+     * @return A copy of this axis interval
      */
     copy(): AxisInterval {
         return AxisInterval.from(this.start, this.end)
@@ -80,9 +114,10 @@ export class AxisInterval {
     }
 
     /**
-     * Applies the specified function to the axis interval and returns the result
-     * @param fn The function to apply to the axis interval
-     * @return The result of the function application
+     * Applies the specified function to this axis interval's start and end, and returns the
+     * resulting interval
+     * @param fn The function to apply to the axis interval's start and end
+     * @return A new axis interval holding the function's result
      */
     map(fn: (start: number, end: number) => [start: number, end: number]): AxisInterval {
         const [start, end] = fn(this.start, this.end)
@@ -90,50 +125,40 @@ export class AxisInterval {
     }
 
     /**
-     * Calculates the measure (end - start) of the specified axis interval.
+     * Calculates the measure (end - start) of this axis interval.
      * The measure of an empty axis interval is 0.
-     * @return The measure (end - start) of the specified axis interval
+     * @return The measure (end - start) of this axis interval
      */
     measure(): number {
         return this.isNotEmpty() ? this.end - this.start : 0
     }
 
     /**
-     * Updates the start value of the specified axis interval
-     * @param delta The amount by which to update the start value
-     * @return A new axis interval
+     * Creates an axis interval whose start is moved by the specified amount (and whose end isn't)
+     * @param delta The amount by which to move the start
+     * @return A new axis interval (empty when this one is)
      */
     translateStart(delta: number): AxisInterval {
         return this.isNotEmpty() ? AxisInterval.from(this.start + delta, this.end) : AxisInterval.empty()
     }
 
     /**
-     * Updates the end value of the specified axis interval
-     * @param delta The amount by which to update the end value
-     * @return The new axis interval
+     * Creates an axis interval whose end is moved by the specified amount (and whose start isn't)
+     * @param delta The amount by which to move the end
+     * @return A new axis interval (empty when this one is)
      */
     translateEnd(delta: number): AxisInterval {
         return this.isNotEmpty() ? AxisInterval.from(this.start, this.end + delta) : AxisInterval.empty()
     }
 
     /**
-     * Translates the specified axis interval by the specified delta.
+     * Creates an axis interval that's this one translated (both its start and its end moved) by the
+     * specified amount
      * @param delta The amount by which to translate the axis interval
-     * @return The new axis interval
+     * @return A new axis interval (empty when this one is)
      */
     translate(delta: number): AxisInterval {
         return this.isNotEmpty() ? AxisInterval.from(this.start + delta, this.end + delta) : AxisInterval.empty()
     }
 }
 
-/**
- * Creates a copy of the specified map(axis_id, (start, end))
- * @param ranges The ranges map to copy
- * @return A copy of the specified map(axis_id, (start, end))
- */
-export function copyRangeMap(ranges: Map<string, AxisInterval>): Map<string, AxisInterval> {
-    return new Map(Array.from(ranges.entries())
-        .map(([id, range]) => [id, range.copy()])
-    )
-}
-

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

@@ -31,67 +31,87 @@ export abstract class BaseAxisRange {
     }
 
     /**
-     * Returns the current distance between the start and end of the range.
+     * The current distance between the start and end of the range
+     * @return The current range's measure (0 when it's empty)
      */
     get currentDistance(): number {
         return this.current.measure()
     }
 
     /**
-     * Returns the original (e.g. before any zooming or panning) distance between the start and end of the range.
+     * The original (e.g. before any zooming or panning) distance between the start and end of the range
+     * @return The original range's measure (0 when it's empty)
      */
     get originalDistance(): number {
         return this.original.measure()
     }
 
     /**
-     * The ratio between the current and original distance.
-     */
-    get scaleFactor(): number {
-        return this.currentDistance / this.originalDistance
-    }
-
-    /**
-     * Scales the range using the current scale-factor (closure on `scaleFactor`)
-     * @param factor The factor used to update the range
+     * Scales the range by the specified *incremental* factor -- i.e. relative to `.current`, not
+     * relative to `.original`. d3-zoom's own `transform.k` is cumulative from wherever `__zoom` was
+     * last reset to identity, so callers must first convert it to an incremental factor (this
+     * event's `k` divided by the previously-applied `k`, tracked in a ref that survives across
+     * zoom events -- see `useCanvasZoomPan`) before calling this. Scaling relative
+     * to `.current` this way means `.original` no longer needs to be preserved/shifted for the
+     * zoom math to stay correct -- unlike the previous design, where `factor` was the *cumulative*
+     * `transform.k` applied against `.original`, which broke the moment anything (e.g. a fresh
+     * subscription on Run) rebuilt `.original` to match a since-zoomed `.current` mid-session.
+     * @param factor The incremental scale factor (this event's change in scale, not the cumulative
+     * scale since the axis was last at identity)
      * @param value The current value being scaled
      * @return The new range, represented by an array holding the start and end value
      */
     protected scaledRange(factor: number, value: number): AxisInterval {
         const dtStart = value - this.current.start
         const dtEnd = this.current.end - value
-        const start = value - dtStart * factor / this.scaleFactor
-        const end = value + dtEnd * factor / this.scaleFactor
+        const start = value - dtStart * factor
+        const end = value + dtEnd * factor
         return AxisInterval.from(start, end)
     }
 
     /**
-     *
-     * Scales the axis-range by the specified scale factor from the specified {@link value}. The equations
-     * are written so that the zooming (scaling) occurs at the specified {@link value}, and expands/contracts equally
-     * from that {@link value}.
-     * @param factor The scale factor
-     * @param value The time from which to scale the interval
-     * @return A new continuous-axis range with updated values
+     * Scales the axis-range by the specified factor from the specified `value` (see
+     * {@link scaledRange} for what "incremental" means for a continuous axis range). 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 -- incremental for a {@link ContinuousAxisRange}, but cumulative
+     * for an {@link OrdinalAxisRange} (see its {@link OrdinalAxisRange.scale})
+     * @param value The value from which to scale the interval
+     * @return A new axis range with updated values
      */
     abstract scale(factor: number, value: number): BaseAxisRange
 
     /**
-     * Scales the axis-range by the specified scale factor, but constrains the range to the specified
-     * {@link constraint} min and max. The equations are written so that the zooming (scaling) occurs
-     * at the specified {@link value}, and expands/contracts equally from that {@link value}.
-     * @param factor The scale factor
+     * Scales the axis-range from the specified `value`, honoring the specified
+     * `constraint` min and max. The equations are written so that the zooming (scaling)
+     * occurs at the specified `value`, and expands/contracts equally from that
+     * `value`.
+     *
+     * IMPORTANT: the two concrete subclasses give `constraint` opposite meanings, and neither
+     * uses the same kind of `factor` -- this base signature is shared for convenience, not
+     * because the implementations are interchangeable:
+     * - {@link ContinuousAxisRange.constrainedScale} takes an *incremental* factor and *clamps*
+     *   the result to stay inside `constraint` -- `constraint` is a hard viewport edge the range
+     *   is not allowed to scroll/zoom past.
+     * - {@link OrdinalAxisRange.constrainedScale} takes a *cumulative* factor and *widens* the
+     *   result to guarantee it fully covers `constraint` -- `constraint` is the domain that must
+     *   be entirely visible once zoomed all the way out, and widening (rather than clamping) is
+     *   what fixes the pivot-drift bug documented on `OrdinalAxisRange.scaledCumulative`.
+     * Do not port logic between the two without re-reading both subclasses' own doc comments.
+     * @param factor The scale factor -- incremental or cumulative, depending on the concrete subclass
      * @param value The value at which the zoom is initiated
      * @param constraint The min and max range
-     * @return A new continuous-axis range with updated values
+     * @return A new axis range with updated values
      */
     abstract constrainedScale(factor: number, value: number, constraint: [min: number, max: number]): 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
      * @param amount The amount by which to translate the axis-range
      * @param [constraints] Optional constraint interval in which the axis range must be within
-     * @return An updated {@link ContinuousAxisRange} that has been translated by the specified amount
+     * @return An updated axis range that has been translated by the specified amount (or an
+     * unchanged copy, when the translation would leave the constraint interval)
      */
     abstract translate(amount: number, constraints?: [start: number, end: number]): BaseAxisRange