stream-charts 1.0.0 → 1.1.0

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

@@ -0,0 +1,112 @@
+import {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.
+ * @typeParam A The type of the axes (must extend `BaseAxis`)
+ */
+export class AxesState<A extends BaseAxis> {
+    readonly axes: Map<string, A>
+
+    private constructor(axes: Map<string, A>) {
+        this.axes = axes
+    }
+
+    /**
+     * Creates a new axes state from the specified map of axes.
+     * @param axes Mapping of the axes ID's to the axes.
+     * @return A new axes-state object.
+     */
+    static from<A extends BaseAxis>(axes: Map<string, A>): AxesState<A> {
+        return new AxesState<A>(axes)
+    }
+
+    /**
+     * Creates an empty axes-state object.
+     * @return A new axes-state object.
+     */
+    static empty<A extends BaseAxis>(): AxesState<A> {
+        return new AxesState<A>(new Map<string, A>())
+    }
+
+    /**
+     * @return `true` if the axes state is empty, `false` otherwise.
+     */
+    isEmpty(): boolean {
+        return this.axes.size === 0
+    }
+
+    /**
+     * 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
+     * management function. This should generally not be used. Instead, use the {@link UseChartValues.addXAxis}
+     * and {@link UseChartValues.addYAxis} functions to add axes.
+     * @param axis The axis to add
+     * @param id The ID of the axis to add
+     * @return An updated axes state that has the new axis
+     * @see UseChartValues.addXAxis
+     * @see UseChartValues.addYAxis
+     */
+    addAxis(axis: A, id: string): AxesState<A> {
+        const updatedAxes = this.axes.set(id, axis)
+        return new AxesState<A>(updatedAxes)
+    }
+
+    /**
+     * 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
+     */
+    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])
+        }
+        return Optional.ofNullable(axis)
+    }
+
+    /**
+     * Returns the default axis
+     * @return The default axis
+     * @see axisDefaultId
+     */
+    defaultAxis(): Optional<A> {
+        const axes = Array.from(this.axes.values())
+        return axes.length > 0 ?
+            Optional.of(axes[0]) :
+            Optional.empty()
+    }
+
+    /**
+     * @return An array holding all existing the x-axis IDs
+     */
+    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)
+     */
+    axisDefaultId(): Optional<string> {
+        const ids = Array.from(this.axes.keys())
+        return ids.length > 0 ?
+            Optional.of(ids[0]) :
+            Optional.empty()
+    }
+}

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

@@ -0,0 +1,143 @@
+import {AxisInterval, copyRangeMap} from "./AxisInterval";
+
+describe('AxisInterval', () => {
+
+    describe('AxisInterval creation', () => {
+        it('should create an AxisInterval with valid start and end values', () => {
+            const interval = AxisInterval.from(1, 5);
+            expect(interval.start).toBe(1);
+            expect(interval.end).toBe(5);
+        });
+
+        it('should create an AxisInterval with correct start and end when the start is greater than the end', () => {
+            const interval = AxisInterval.from(5, 1);
+            expect(interval.start).toBe(1);
+            expect(interval.end).toBe(5);
+        })
+
+        it('should create an AxisInterval from a tuple holding start and end values', () => {
+            const interval = AxisInterval.as([1, 5]);
+            expect(interval.start).toBe(1);
+            expect(interval.end).toBe(5);
+        })
+
+        it('should create an empty AxisInterval', () => {
+            const interval = AxisInterval.empty();
+            expect(interval.start).toBeNaN()
+            expect(interval.end).toBeNaN()
+        })
+
+        it('should create an empty AxisInterval with start and end NaN', () => {
+            const interval = AxisInterval.from(NaN, NaN);
+            expect(interval.start).toBeNaN()
+            expect(interval.end).toBeNaN()
+        })
+
+        it('should create a new copy of an existing AxisInterval', () => {
+            const interval = AxisInterval.from(1, 5);
+            const copy = interval.copy();
+            expect(copy.start).toBe(1);
+            expect(copy.end).toBe(5);
+            expect(copy).not.toBe(interval);
+        })
+    })
+
+    describe('AxisInterval comparison', () => {
+        const interval1 = AxisInterval.from(1, 5);
+        const interval2 = AxisInterval.from(1, 5);
+        const interval3 = AxisInterval.from(2, 5);
+        const emptyInterval = AxisInterval.empty();
+
+        it('should return true when comparing two AxisIntervals with the same start and end values', () => {
+            expect(interval1.equals(interval2)).toBe(true)
+            expect(interval1.equalsInterval(1, 5)).toBe(true)
+        });
+
+        it('should return not-equal when comparing two AxisIntervals with different start and end values', () => {
+            expect(interval1.equals(interval3)).toBe(false)
+            expect(interval1.equalsInterval(1, 3)).toBe(false)
+        })
+
+        it('should return true when comparing two empty intervals', () => {
+            expect(AxisInterval.empty().equals(emptyInterval)).toBe(true)
+        })
+    })
+
+    describe('AxisInterval conversion', () => {
+        it('should convert an AxisInterval to a tuple', () => {
+            const interval = AxisInterval.from(1, 5);
+            const tuple = interval.asTuple();
+            expect(tuple).toEqual([1, 5]);
+        })
+
+        it('should map an AxisInterval to a new AxisInterval', () => {
+            const interval = AxisInterval.from(1, 5)
+            const mappedInterval = interval.map((start, end) => ([start * 2, end * 3]))
+
+            expect(mappedInterval.start).toBe(2);
+            expect(mappedInterval.end).toBe(15);
+            expect(mappedInterval).not.toBe(interval);
+        })
+
+        it('should calculate the measure of an AxisInterval', () => {
+            const interval = AxisInterval.from(1, 5)
+            expect(interval.measure()).toBe(4);
+        })
+
+        it('should calculate the measure of an empty AxisInterval', () => {
+            const interval = AxisInterval.empty()
+            expect(interval.measure()).toBe(0);
+        })
+
+        it('should translate the start of the AxisInterval', () => {
+            const interval = AxisInterval.from(1, 5)
+            const translatedInterval = interval.translateStart(12)
+            expect(translatedInterval.start).toBe(5);
+            expect(translatedInterval.end).toBe(13);
+            expect(translatedInterval).not.toBe(interval);
+        })
+
+        it('should translate the start of an empty interval into an empty interval', () => {
+            expect(AxisInterval.empty().translateStart(12)).toEqual(AxisInterval.empty())
+        })
+
+        it('should translate the end of the AxisInterval', () => {
+            const interval = AxisInterval.from(1, 5)
+            const translatedInterval = interval.translateEnd(-12)
+            expect(translatedInterval.start).toBe(-7);
+            expect(translatedInterval.end).toBe(1);
+            expect(translatedInterval).not.toBe(interval);
+        })
+
+        it('should translate the end of an empty interval into an empty interval', () => {
+            expect(AxisInterval.empty().translateEnd(12)).toEqual(AxisInterval.empty())
+        })
+
+        it('should translate an AxisInterval', () => {
+            const interval = AxisInterval.from(1, 5)
+            const translatedInterval = interval.translate(-12)
+            expect(translatedInterval.start).toBe(-11);
+            expect(translatedInterval.end).toBe(-7);
+            expect(translatedInterval).not.toBe(interval);
+        })
+
+        it('should translate an empty interval into an empty interval', () => {
+            expect(AxisInterval.empty().translate(12)).toEqual(AxisInterval.empty())
+        })
+    })
+
+    describe('Copy a range map', () => {
+        it('should create a copy of a range map', () => {
+            const ranges = new Map<string, AxisInterval>([
+                ['a', AxisInterval.from(1, 5)],
+                ['b', AxisInterval.from(10, 20)]
+            ])
+            const copy = copyRangeMap(ranges)
+
+            expect(copy).not.toBe(ranges)
+            expect(copy.size).toBe(ranges.size)
+            expect(copy.get('a')).toEqual(ranges.get('a'))
+            expect(copy.get('b')).toEqual(ranges.get('b'))
+        })
+    })
+})

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

@@ -0,0 +1,139 @@
+/**
+ * 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).
+ */
+export class AxisInterval {
+    private constructor(readonly start: number, readonly end: number) {}
+
+    /**
+     * Creates an axis interval from the specified start and end values
+     * @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 {
+        return new AxisInterval(Math.min(start, end), Math.max(start, end))
+    }
+
+    /**
+     * Creates an axis interval from the specified tuple
+     * @param tuple The tuple to convert
+     * @return The axis-interval
+     */
+    static as(tuple: [start: number, end: number]): AxisInterval {
+        return AxisInterval.from(tuple[0], tuple[1])
+    }
+
+    /**
+     * Creates an empty axis interval
+     * @return An empty axis interval
+     */
+    static empty(): AxisInterval {
+        return new AxisInterval(NaN, NaN)
+    }
+
+    /**
+     * @return `true` if the axis interval is empty, `false` otherwise
+     */
+    isEmpty(): boolean {
+        return isNaN(this.start) || isNaN(this.end)
+    }
+
+    /**
+     * @return `true` if the axis interval is not empty, `false` otherwise
+     */
+    isNotEmpty(): boolean {
+        return !this.isEmpty()
+    }
+
+    /**
+     * @return `true` if the specified axis interval is equal to this one, `false` otherwise
+     */
+    equalsInterval(start: number, end: number): boolean {
+        return (this.start === start && this.end === end) || (this.isEmpty() && isNaN(start) && isNaN(end))
+    }
+
+    /**
+     * Determines whether the specified axis interval is equal to this one.
+     * @param other The other axis interval to compare to
+     * @return `true` if the specified axis interval is equal to this one, `false` otherwise.
+     */
+    equals(other: AxisInterval): boolean {
+        return this.equalsInterval(other.start, other.end)
+    }
+
+    /**
+     * Creates a copy of the specified axis interval
+     * @return A copy of the specified axis interval
+     */
+    copy(): AxisInterval {
+        return AxisInterval.from(this.start, this.end)
+    }
+
+    /**
+     * Converts the axis interval to a tuple
+     * @return The axis interval as a tuple
+     */
+    asTuple(): [start: number, end: number] {
+        return [this.start, this.end]
+    }
+
+    /**
+     * 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
+     */
+    map(fn: (start: number, end: number) => [start: number, end: number]): AxisInterval {
+        const [start, end] = fn(this.start, this.end)
+        return AxisInterval.from(start, end)
+    }
+
+    /**
+     * Calculates the measure (end - start) of the specified axis interval.
+     * The measure of an empty axis interval is 0.
+     * @return The measure (end - start) of the specified 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
+     */
+    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
+     */
+    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.
+     * @param delta The amount by which to translate the axis interval
+     * @return The new axis interval
+     */
+    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

@@ -0,0 +1,113 @@
+import {AxisInterval} from "./AxisInterval";
+
+/**
+ * An immutable axis range that holds the current range and the original (no zoom) range.
+ */
+export abstract class BaseAxisRange {
+    readonly current: AxisInterval
+    // the range when there is no zoom, which is the interval (0, width | height)
+    readonly original: AxisInterval
+
+    /**
+     * @param start The axis-range start value.
+     * @param end The axis-range end value.
+     * @param [originalStart = start] The optional original axis-range start value. Defaults to the start value if not specified.
+     * @param [originalEnd = end] The optional original axis-range end value. Defaults to the end value if not specified.
+     * @protected
+     */
+    protected constructor(start: number, end: number, originalStart: number = start, originalEnd: number = end) {
+        this.current = AxisInterval.from(start, end)
+        this.original = AxisInterval.from(originalStart, originalEnd)
+    }
+
+    /**
+     * Determines whether the specified (start, end) interval matches the original interval
+     * @param start The start of the interval
+     * @param end The end of the interval
+     * @return `true` if the specified interval matches the original interval; `false` otherwise
+     */
+    matchesOriginal(start: number, end: number): boolean {
+        return this.original.equalsInterval(start, end)
+    }
+
+    /**
+     * Returns the current distance between the start and end of the range.
+     */
+    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.
+     */
+    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
+     * @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
+        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
+     */
+    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
+     * @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
+     */
+    abstract constrainedScale(factor: number, value: number, constraint: [min: number, max: number]): BaseAxisRange
+
+    /**
+     * Translates the axis-range by the specified amount
+     * @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
+     */
+    abstract translate(amount: number, constraints?: [start: number, end: number]): BaseAxisRange
+
+    /**
+     * Updates the axis-range based on the new start and end values
+     * @param start The new start of the axis-range
+     * @param end The new end of the axis range
+     * @return The updated axis-range type, with all other values unchanged
+     */
+    abstract update(start: number, end: number): BaseAxisRange
+
+    /**
+     * Updates the original range with the new start and end values.
+     * @param start The new value for the start of the original range
+     * @param end The new value for the end of the original range
+     * @return The updated original range.
+     */
+    abstract updateOriginal(start: number, end: number): BaseAxisRange
+}