stream-charts 1.2.1 → 2.0.0

package/src/app/charts/series/ordinalSeries.ts

@@ -1,12 +1,13 @@
-import {BaseSeries, seriesFrom} from "./baseSeries";
+import {type BaseSeries, seriesFrom} from "./baseSeries";
 import {
     initialMaxTimeDatum,
     initialMaxValueDatum, initialMinTimeDatum,
     initialMinValueDatum,
-    OrdinalChartData,
-    OrdinalStats,
-    OrdinalValueStats
+    type OrdinalChartData,
+    type OrdinalStats,
+    type OrdinalValueStats
 } from "../observables/ordinals";
+import type {FastShiftArray} from "fast-shift-array";
 
 /**
  * An immutable datum object for series with a category and value.
@@ -22,7 +23,7 @@ export interface OrdinalDatum {
 
 
 /**
- * Creates an empty ordinal datum
+ * An empty ordinal datum (`NaN` time and value, and an empty ordinal)
  */
 export const emptyOrdinalDatum: OrdinalDatum = {
     time: NaN,
@@ -30,6 +31,11 @@ export const emptyOrdinalDatum: OrdinalDatum = {
     value: NaN,
 }
 
+/**
+ * Copies an ordinal datum
+ * @param datum The datum to copy
+ * @return The copy
+ */
 export const copyOrdinalDatum = (datum: OrdinalDatum): OrdinalDatum => ({
     time: datum.time,
     ordinal: datum.ordinal,
@@ -37,11 +43,11 @@ export const copyOrdinalDatum = (datum: OrdinalDatum): OrdinalDatum => ({
 })
 
 /**
- * Creates an iterate datum
+ * Creates an ordinal datum
  * @param time The datum time, which is mostly informational
  * @param ordinal The category name or identifier
  * @param value The value
- * @return An iterate datum
+ * @return An ordinal datum
  */
 export const ordinalDatumOf = (time: number, ordinal: string, value: number): OrdinalDatum => ({
     time,
@@ -51,11 +57,10 @@ export const ordinalDatumOf = (time: number, ordinal: string, value: number): Or
 
 
 /**
- * Returns whether the ordinal datum is empty. An ordinal datum is considered empty
- * when the time is NaN, the ordinal is blank (empty or only whitespace), and the value
- * is NaN.
- * @param datum The iterate datum to test
- * @return `true` if the iterate datum is empty; `false` otherwise
+ * Returns whether the ordinal datum is non-empty. An ordinal datum is considered empty when its
+ * time is NaN, its ordinal is blank (empty or only whitespace), or its value is NaN.
+ * @param datum The ordinal datum to test
+ * @return `true` if the ordinal datum is non-empty; `false` otherwise
  */
 export const nonEmptyOrdinalDatum = (datum: OrdinalDatum): boolean =>
     !isNaN(datum.time) && datum.ordinal.replace(/\s/g, "").length > 0 && !isNaN(datum.value)
@@ -84,15 +89,17 @@ export function ordinateSeriesFromTuples(
 }
 
 /**
- * Creates an empty chart data object with all the values set to 0
- * @param seriesList The list of series names (identifiers) to update
- * @return An empty chart data object
+ * Creates the ordinal chart data for the specified series: their names, the stats calculated over
+ * their data (see {@link calculateOrdinalStats}), and copies of all their data as the new points
+ * @param seriesList The series
+ * @return The ordinal chart data for the series
  */
 export function initialOrdinalChartData(seriesList: Array<OrdinalSeries>): OrdinalChartData {
     return {
         seriesNames: new Set(seriesList.map(series => series.name)),
         stats: calculateOrdinalStats(seriesList),
-        newPoints: new Map<string, Array<OrdinalDatum>>(seriesList.map(series => [
+        // newPoints: new Map<string, Array<OrdinalDatum>>(seriesList.map(series => [
+        newPoints: new Map<string, FastShiftArray<OrdinalDatum>>(seriesList.map(series => [
             series.name,
             series.data.map(datum => ({
                 time: datum.time,
@@ -103,6 +110,14 @@ export function initialOrdinalChartData(seriesList: Array<OrdinalSeries>): Ordin
     }
 }
 
+/**
+ * Calculates the stats of the specified series: the data with the min and max time, and with the
+ * min and max value, over all the series, and each series' value stats (its min, max, count, sum,
+ * sum of squares, and mean)
+ * @param seriesList The series
+ * @return The stats (when there's no data, the extremes are the initial ones that searches start
+ * from -- see e.g. `initialMinTimeDatum`)
+ */
 export function calculateOrdinalStats(seriesList: Array<OrdinalSeries>): OrdinalStats {
     const ordinalValueStats = new Map<string, OrdinalValueStats>(seriesList.map(
         (series: OrdinalSeries) => {
@@ -138,20 +153,20 @@ export function calculateOrdinalStats(seriesList: Array<OrdinalSeries>): Ordinal
     const minTimeDatum: OrdinalDatum = seriesList.reduce(
         (globalMin: OrdinalDatum, series: OrdinalSeries) => {
             const seriesMin = series.data.reduce(
-                (min, datum) =>  datum.value < min.value ? datum : min,
+                (min, datum) =>  datum.time < min.time ? datum : min,
                 globalMin
             )
-            return seriesMin.value < globalMin.value ? seriesMin : globalMin
+            return seriesMin.time < globalMin.time ? seriesMin : globalMin
         },
         initialMinTimeDatum()
     )
     const maxTimeDatum: OrdinalDatum = seriesList.reduce(
         (globalMax: OrdinalDatum, series: OrdinalSeries) => {
             const seriesMax = series.data.reduce(
-                (max, datum) =>  datum.value > max.value ? datum : max,
+                (max, datum) =>  datum.time > max.time ? datum : max,
                 globalMax
             )
-            return seriesMax.value > globalMax.value ? seriesMax : globalMax
+            return seriesMax.time > globalMax.time ? seriesMax : globalMax
         },
         initialMaxTimeDatum()
     )

package/src/app/charts/series/outlierSeries.ts

@@ -0,0 +1,188 @@
+import type {Datum} from "./timeSeries";
+import {type BaseSeries, seriesFrom} from "./baseSeries";
+import {failureResult, type Result, resultFromAll, successResult} from "result-fn";
+import type {FastShiftArray} from "fast-shift-array";
+
+/**
+ * A series of {@link OutlierDatum}s, along with the measures that the data's bounds are for
+ * @template M The type of the measures that is expressed as a tuple of numbers.
+ */
+export interface OutlierSeries<M extends readonly number[]> extends BaseSeries<OutlierDatum<M>> {
+    /**
+     * The measures of the datum. For example, this could be a series of probabilities of
+     * the point being an outlier.
+     */
+    readonly measures: readonly [...M]
+    /**
+     * The descriptions of the measures. For example, this could be a series of descriptions
+     * of the probabilities of the point being an outlier.
+     */
+    readonly measureDescriptions?: {readonly [K in keyof M]: string}
+}
+
+/**
+ * The bounds of a datum.
+ */
+export interface OutlierBounds {
+    /**
+     * The lower bound of the datum
+     */
+    readonly lower: number
+    /**
+     * The upper bound of the datum
+     */
+    readonly upper: number
+}
+
+/**
+ * A datum with an upper and lower bounds B(L, U) associated with each measure. The idea is the
+ * following. We have a datum (x, y) value. The bounds determine whether the datum is
+ * within the range associated with the measure. For example, the measure could be the
+ * 0.95 probability that the datum falls within that bound. And if the (x, y) value falls
+ * outside the bounds B(L, U), the datum could be considered an "outlier".
+ *
+ * Often we would like to have a set of measures that mean different things. For example, if
+ * the datum falls outside the bounds B1(L, U) representing the range in which we expect
+ * the datum to fall with a 0.95 probability, then we could consider the datum an "outlier". We
+ * may also want to consider the datum an "outlier" if it falls outside the bounds B2(L, U)
+ * representing the range in which we expect the datum to fall with a 0.75 probability. If the
+ * datum falls outside B2(L, U), then we could consider the datum a "possible outlier" and
+ * treat it differently from an "outlier".
+ *
+ * Note that there are constraints.
+ * 1. The cardinality of the measures and the bounds must be the same.
+ * 2. The i-th bound is associated with the i-th measure.
+ *
+ * @template M The type of the measures that is expressed as a tuple of numbers.
+ * @see OutlierBounds
+ * @see outlierBoundsFor
+ * @see outlierDatumFor
+ * @see outlierSeriesFor
+ *
+ * @example
+ * // possible-outlier = 0.75, outlier = 0.95
+ * const Measures = [0.75, 0.95] as const;
+ * const value: Datum = datumOf(1, 10);
+ * const bounds = [
+ *     outlierBoundsFor(21, 121),
+ *     outlierBoundsFor(2, 52)
+ * ] as const;
+ * const datum = outlierDatumFor<typeof Measures>(value, Measures, bounds);
+ */
+export interface OutlierDatum<M extends readonly number[]> {
+    /**
+     * The datum with the x and y values
+     */
+    readonly datum: Datum
+    /**
+     * The bounds of the measures. For example, if the measures are probabilities, then
+     * the bounds are a series that hold the lower and upper bounds for each probability
+     * in the measures.
+     */
+    readonly bounds: {readonly [K in keyof M]: OutlierBounds}
+}
+
+/**
+ * Convenience function to create an outlier bounds object.
+ * @param lower The lower bound of the measure
+ * @param upper The upper bound of the measure
+ * @return An outlier bounds object
+ */
+export function outlierBoundsFor(lower: number, upper: number): OutlierBounds {
+    return {lower, upper}
+}
+
+/**
+ * Creates an outlier datum from the (x, y) value and the bounds associated with each measure. Because
+ * the length of the bounds-array must be the same as the length of the measures-array, this returns
+ * a {@link Result} object with the outcome of the operation.
+ * @param datum The (x, y) value
+ * @param measures The measures array where each measure is associated with a bound of the same index
+ * @param bounds The bounds array where each bound is associated with a measure of the same index
+ * @return A {@link Result} object with the outcome of the operation. If the operation is successful,
+ * then the result is an {@link OutlierDatum} object. If the operation is not successful, then
+ * the result is a `string` with the error message.
+ * @template M The type of the measures that is expressed as a tuple of numbers.
+ */
+export function outlierDatumFor<M extends readonly number[]>(
+    datum: Datum,
+    measures: readonly [...M],
+    bounds: {readonly [K in keyof M]: OutlierBounds},
+): Result<OutlierDatum<M>, string> {
+    if (measures.length !== bounds.length) {
+        return failureResult(
+            `The number of measures and bounds must be the same; ` +
+            `datum: (${datum.x}, ${datum.y}); ` +
+            `measures_length: ${measures.length}; ` +
+            `bounds_length: ${bounds.length}; ` +
+            `measures: [${measures.join(", ")}]; ` +
+            `bounds: [${Object.values(bounds).map(b => `(${b.lower}, ${b.upper})`).join(", ")}]`
+        )
+    }
+    return successResult({datum, bounds})
+}
+
+/**
+ * Creates an outlier series from the name and the array of (x, y, bounds) tuples. If any of the
+ * datum have bounds that do not have the same length as the measures, then this function will fail and
+ * return a failure result. Otherwise, it will return a success result with the outlier series.
+ * @param name The name of the series
+ * @param measures The measures that are associated with the series
+ * @param data The array of (x, y, bounds) tuples that define the series
+ * @param [measureDescriptions=undefined] The descriptions of the measures
+ * @return A {@link Result} object with the outcome of the operation. If the operation is successful,
+ * then the result is an {@link OutlierSeries} object. If the operation is not successful, then
+ * the result is an array of error messages.
+ * @template M The type of the measures that is expressed as a tuple of numbers.
+ */
+export function outlierSeriesFor<M extends readonly number[]>(
+    name: string,
+    measures: readonly [...M],
+    data: Array<[time: number, value: number, bounds: { readonly [K in keyof M]: OutlierBounds}]>,
+    measureDescriptions?: {readonly [K in keyof M]: string}
+): Result<OutlierSeries<M>, Array<string>> {
+    // enrich each datum in the data array with the measures
+    const outlierData = data.map(
+        ([time, value, bounds]) =>
+            outlierDatumFor({x: time, y: value}, measures, bounds)
+    )
+
+    // if all data has bounds-dimensions that match the measures-dimensions, then we can safely
+    // create the outlier series, otherwise we must report the errors
+    if (outlierData.filter(datum => datum.succeeded).length === data.length) {
+        // convert the Array<Result<OutlierDatum<M>, string>> to Result<Array<OutlierDatum<M>>, Array<string>>
+        return resultFromAll(outlierData)
+            .map(data => outlierSeriesFrom(name, data, measures, measureDescriptions))
+            .mapFailure(failure => [failure])
+    }
+
+    // collect all the errors for datum whose bounds and measures dimensions did not
+    // match and report each error
+    return failureResult(outlierData
+        .filter(result => result.failed)
+        .map(result => result.error!)
+    )
+}
+
+/**
+ * Creates an outlier series for the data and measures
+ *
+ * **Ownership warning:** `outlierData` is forwarded directly to {@link seriesFrom}, which wraps a
+ * plain array (or `FastShiftArray`) **by reference**, not a copy -- see {@link seriesFrom}'s own
+ * ownership warning for the full explanation. If you keep your own reference to `outlierData`,
+ * pass `outlierData.slice()` instead if you need an independent copy.
+ * @param name The name of the series
+ * @param outlierData The data for the series
+ * @param measures The measure defining the outlier bands
+ * @param measureDescriptions The (optional) meaning of each band
+ * @return An outlier series
+ * @template M The type of the measures that is expressed as a tuple of numbers.
+ */
+export function outlierSeriesFrom<M extends readonly number[]>(
+    name: string,
+    outlierData: Array<OutlierDatum<M>> | FastShiftArray<OutlierDatum<M>>,
+    measures: readonly [...M],
+    measureDescriptions?: {readonly [K in keyof M]: string}
+): OutlierSeries<M> {
+    return {...seriesFrom(name, outlierData), measures, measureDescriptions}
+}

package/src/app/charts/series/timeSeries.ts

@@ -1,11 +1,12 @@
-import {BaseSeries, seriesFrom} from "./baseSeries";
+import {type BaseSeries, seriesFrom} from "./baseSeries";
 
 /**
- * An immutable datum object that holds the spike (time, value) representing a neuron spike
+ * An immutable datum object that holds an (x, y) value -- for a time series, a (time, value) pair
+ * (e.g. a neuron spike, or a weight)
  */
 export interface Datum {
-    readonly time: number;
-    readonly value: number;
+    readonly x: number;
+    readonly y: number;
 }
 
 /**
@@ -14,10 +15,16 @@ export interface Datum {
  * @param value The value
  * @return A {@link Datum} instance with the specified (time, value)
  */
-export const datumOf = (time: number, value: number): Datum => ({time, value})
+export const datumOf = (time: number, value: number): Datum => ({x: time, y: value})
 
-export const emptyDatum = (): Datum => ({time: NaN, value: NaN})
+/**
+ * @return An empty datum (its x and y are `NaN`)
+ */
+export const emptyDatum = (): Datum => ({x: NaN, y: NaN})
 
+/**
+ * A series of (time, value) data (e.g. for the scatter and raster plots)
+ */
 export type TimeSeries = BaseSeries<Datum>
 
 
@@ -25,16 +32,11 @@ export type TimeSeries = BaseSeries<Datum>
  * Creates a series from the name and the optional array of (x, y) pairs (tuples)
  * @param name The name of the series
  * @param data The optional array of (x, y) pairs (tuples)
- * @return A `Series` for object that can be used by the `RasterChart`
+ * @return A {@link TimeSeries} that can be used by, e.g., the `ScatterPlot` and the `RasterPlot`
  * @see seriesFrom
  * @see emptySeries
  */
 export const timeSeriesFromTuples = (name: string, data: Array<[number, number]> = []): TimeSeries =>
     seriesFrom(name, data.map(([t, y]) => datumOf(t, y)))
 
-export interface PixelDatum extends Datum {
-    x: number;
-    y: number;
-}
-
 

package/src/app/charts/series/timeSeriesChartData.ts

@@ -1,8 +1,11 @@
-import {Datum, TimeSeries} from "./timeSeries";
-import {ChartData, defaultChartData} from "../observables/ChartData";
+import type {Datum, TimeSeries} from "./timeSeries";
+import {type ChartData, defaultChartData} from "../observables/ChartData";
+import {FastShiftArray} from "fast-shift-array";
+import {DEFAULT_COMPACTING_SIZE} from "./baseSeries";
 
 /**
- * The spike-chart data produced by the rxjs observable that is pushed to a streaming chart
+ * The time-series chart data produced by the rxjs observable that is pushed to a streaming chart
+ * (e.g. the scatter and raster charts): each chunk's new points, and the latest times
  */
 export interface TimeSeriesChartData extends ChartData {
     /**
@@ -28,40 +31,51 @@ export interface TimeSeriesChartData extends ChartData {
 }
 
 /**
- * Creates an empty chart data object with all the values set to 0
- * @param {Array<string>} series The list of series names (identifiers) to update
- * @return {TimeSeriesChartData} An empty chart data object
+ * Creates a chart data object for the specified series whose times are all 0, and whose new
+ * points are a single (0, 0) point for each series
+ * @param series The list of series names (identifiers) to update
+ * @return The chart data object
  */
 export function emptyTimeSeriesChartData(series: Array<string>): TimeSeriesChartData {
     return {
         ...defaultChartData(),
+        seriesNames: new Set(series),
         maxTime: 0,
         maxTimes: new Map(series.map(name => [name, 0])),
-        newPoints: new Map<string, Array<Datum>>(series.map(name => [name, [{time: 0, value: 0}]]))
+        newPoints: new Map<string, Array<Datum>>(series.map(name => [name, [{x: 0, y: 0}]]))
     }
 }
 
 /**
- * Creates an empty chart data object with all the values set to 0
- * @param seriesList The list of series names (identifiers) to update
+ * Creates the chart data object to start a stream from, for the specified series: its new points
+ * are each series' last datum (or (0, 0), for an empty series), each series' max time is the
+ * time of its last datum (or 0), and the max time is the latest of those (or `-Infinity`, when
+ * there are no series)
+ * @param seriesList The series
  * @param [currentTime=0] The current time
- * @return An empty chart data object
+ * @param [compactingSize=DEFAULT_COMPACTING_SIZE] The number of shifts each new-points array
+ * accumulates before it's compacted
+ * @return The chart data object
  */
-export function initialTimeSeriesChartData(seriesList: Array<TimeSeries>, currentTime: number = 0): TimeSeriesChartData {
+export function initialTimeSeriesChartData(
+    seriesList: Array<TimeSeries>,
+    currentTime: number = 0,
+    compactingSize: number = DEFAULT_COMPACTING_SIZE
+): TimeSeriesChartData {
     const maxTime = seriesList.reduce(
-        (tMax, series) => Math.max(tMax, series.last().map(datum => datum.time).getOrElse(-Infinity)),
+        (tMax, series) => Math.max(tMax, series.last().map(datum => datum.x).getOrElse(-Infinity)),
         -Infinity
     )
     return {
         seriesNames: new Set(seriesList.map(series => series.name)),
         maxTime,
-        maxTimes: new Map(seriesList.map(series => [series.name, series.last().map(datum => datum.time).getOrElse(0)])),
+        maxTimes: new Map(seriesList.map(series => [series.name, series.last().map(datum => datum.x).getOrElse(0)])),
         newPoints: new Map<string, Array<Datum>>(seriesList.map(series => [
             series.name,
-            [{
-                time: series.last().map(datum => datum.time).getOrElse(0),
-                value: series.last().map(datum => datum.value).getOrElse(0)
-            }]
+            FastShiftArray.fromArray([{
+                x: series.last().map(datum => datum.x).getOrElse(0),
+                y: series.last().map(datum => datum.y).getOrElse(0)
+            }], true, compactingSize)
         ])),
         currentTime: currentTime
     }

package/src/app/charts/styling/barPlotStyle.ts

@@ -1,7 +1,10 @@
-import {SeriesStyle} from "../axes/axes";
-import {SvgFillStyle, SvgStrokeStyle} from "./svgStyle";
+import type {SeriesStyle} from "../axes/axes";
+import type {SvgFillStyle, SvgStrokeStyle} from "./svgStyle";
 import * as d3 from "d3";
 
+/**
+ * The style of a bar series: the style of each of its bars and lines
+ */
 export interface BarSeriesStyle extends SeriesStyle {
     /**
      * The bar style for the lifetime min/max range bar. The style is for the width, fill,
@@ -27,17 +30,29 @@ export interface BarSeriesStyle extends SeriesStyle {
     windowedMeanValueLine: LineStyle
 }
 
+/**
+ * The style of a bar: its width (as a fraction of the category's width), its fill, and its stroke
+ */
 export interface BarStyle {
     widthFraction: number
     fill: SvgFillStyle
     stroke: SvgStrokeStyle
 }
 
+/**
+ * The style of a line: normally, and when highlighted
+ */
 export interface LineStyle {
     regular: SvgStrokeStyle
     highlight: SvgStrokeStyle
 }
 
+/**
+ * The default style for the lifetime min/max bar: 65% of the category's width, a translucent fill,
+ * and a thin stroke
+ * @param [color="#008aad"] The bar's fill and stroke color
+ * @return The bar style
+ */
 export function defaultMinMaxBarStyle(color: string = "#008aad"): BarStyle {
     return {
         widthFraction: 0.65,
@@ -53,6 +68,12 @@ export function defaultMinMaxBarStyle(color: string = "#008aad"): BarStyle {
     }
 }
 
+/**
+ * The default style for the windowed min/max bar: 25% of the category's width (narrower than the
+ * lifetime bar, so both can be seen), filled with a slightly darker color, and no stroke
+ * @param [color="#008aad"] The color to darken for the bar's fill (used as-is when it can't be parsed)
+ * @return The bar style
+ */
 export function defaultWindowedMinMaxBarStyle(color: string = "#008aad"): BarStyle {
     return {
         widthFraction: 0.25,
@@ -68,6 +89,11 @@ export function defaultWindowedMinMaxBarStyle(color: string = "#008aad"): BarSty
     }
 }
 
+/**
+ * The default style for the current-value line: 3 pixels wide (5 when highlighted)
+ * @param [color="#008aad"] The line's color
+ * @return The line style
+ */
 export function defaultValueLineStyle(color: string = "#008aad"): LineStyle {
     return {
         regular: {
@@ -83,6 +109,11 @@ export function defaultValueLineStyle(color: string = "#008aad"): LineStyle {
     }
 }
 
+/**
+ * The default style for the (lifetime) mean-value line: 1 pixel wide (3 when highlighted)
+ * @param [color="#008aad"] The line's color
+ * @return The line style
+ */
 export function defaultMeanValueLineStyle(color: string = "#008aad"): LineStyle {
     return {
         regular: {
@@ -98,21 +129,33 @@ export function defaultMeanValueLineStyle(color: string = "#008aad"): LineStyle
     }
 }
 
-export function defaultWindowedMeanValueLineStyle(color: string = "#008aad"): LineStyle {
+/**
+ * The default style for the windowed mean-value line: 1 pixel wide (3 when highlighted), and red
+ * by default to set it apart from the other lines
+ * @param [color="#ad0000"] The line's color
+ * @return The line style
+ */
+export function defaultWindowedMeanValueLineStyle(color: string = "#ad0000"): LineStyle {
     return {
         regular: {
-            color: 'red',
+            color: color,
             opacity: 0.6,
             width: 1
         },
         highlight: {
-            color: 'red',
+            color: color,
             opacity: 1,
             width: 3
         }
     }
 }
 
+/**
+ * The default style for a bar series: all the bars and lines in the specified color (see the
+ * default styles above), except for the windowed min/max bar's darker fill
+ * @param [color="#008aad"] The series' color
+ * @return The bar series style
+ */
 export function defaultBarSeriesStyle(color: string = "#008aad"): BarSeriesStyle {
     return {
         color,

package/src/app/charts/styling/canvasStyle.ts

@@ -0,0 +1,86 @@
+// Canvas equivalents of the stroke/fill helpers that used to live in svgStyle.ts. The old versions
+// mutated a *persistent* SVG element's CSS style (`selection.style('stroke', ...)`), so it stuck
+// around until changed again. Canvas has no persistent elements -- `ctx.strokeStyle`/`ctx.fillStyle`
+// /`ctx.lineWidth` are transient 2D-context state that only affects the *next* stroke()/fill() call,
+// so these must be (re-)applied immediately before every draw, every frame.
+//
+// IMPORTANT DIFFERENCE FROM SVG: canvas has a single `ctx.globalAlpha` shared between stroke and
+// fill, unlike SVG's independent `stroke-opacity`/`fill-opacity`. If a shape needs different
+// stroke and fill opacity in the same draw call, bake the opacity into the color string with
+// `withAlpha(...)` instead of relying on `globalAlpha` for one of them.
+
+import * as d3 from "d3"
+
+/**
+ * The style of a stroke (a line, or a shape's outline)
+ */
+export interface CanvasStrokeStyle {
+    readonly color: string
+    readonly width: number
+    readonly opacity: number
+}
+
+/**
+ * Applies a stroke style to the canvas context. Call this immediately before `ctx.stroke()` --
+ * unlike the old SVG version, the effect is not persistent.
+ * @param context The canvas 2D context to apply the style to
+ * @param style The (partial) stroke style to apply; unset fields are left untouched on `ctx`
+ * @return `ctx`, for chaining
+ */
+export function applyStrokeStyle(context: CanvasRenderingContext2D, style: Partial<CanvasStrokeStyle>): CanvasRenderingContext2D {
+    if (style.color !== undefined) context.strokeStyle = style.color
+    if (style.width !== undefined) context.lineWidth = style.width
+    if (style.opacity !== undefined) context.globalAlpha = style.opacity
+    return context
+}
+
+/**
+ * The style of a (shape's) fill
+ */
+export interface CanvasFillStyle {
+    readonly color: string
+    readonly opacity: number
+}
+
+/**
+ * Applies a fill style to the canvas context. Call this immediately before `ctx.fill()`/
+ * `ctx.fillText()`/`ctx.fillRect()` -- unlike the old SVG version, the effect is not persistent.
+ * @param context The canvas 2D context to apply the style to
+ * @param style The (partial) fill style to apply; unset fields are left untouched on `ctx`
+ * @return `ctx`, for chaining
+ */
+export function applyFillStyle(context: CanvasRenderingContext2D, style: Partial<CanvasFillStyle>): CanvasRenderingContext2D {
+    if (style.color !== undefined) context.fillStyle = style.color
+    if (style.opacity !== undefined) context.globalAlpha = style.opacity
+    return context
+}
+
+/**
+ * Bakes an opacity into a color string by resolving it to `rgba(...)`. Needed because canvas has
+ * a single `globalAlpha` shared between stroke and fill (see the module-level note above); when a
+ * shape needs independent stroke and fill opacity, use this to bake opacity into the color passed
+ * to `applyStrokeStyle`/`applyFillStyle` instead of setting `opacity` on both.
+ *
+ * Uses `d3.color(...)` (already the project's convention for this elsewhere -- see `Legend.tsx`,
+ * `barPlotStyle.ts`) rather than the previous approach of assigning `color` to a single
+ * module-level, lazily-created `<canvas>` context's `fillStyle` and reading back the browser's
+ * normalized value: assigning an unparseable CSS string to `fillStyle` is a silent no-op per the
+ * Canvas 2D spec, so an invalid `color` would have silently resolved to whatever the *previous,
+ * unrelated* `withAlpha` call (from any chart/tooltip/legend on the page, since the context was a
+ * single shared singleton) happened to leave `fillStyle` at -- order-dependent and effectively
+ * nondeterministic. `d3.color` instead returns `null` for unparseable input, so an invalid color
+ * falls through to the same "fall back to the original string" behavior this always had for the
+ * "no canvas 2d support" case, deterministically, with no shared state at all.
+ * @param color Any valid CSS color string (named, hex, rgb, rgba, hsl, etc)
+ * @param opacity The opacity to bake in, from 0 (transparent) to 1 (opaque)
+ * @return An `rgba(...)` string equivalent to `color` at the given `opacity`
+ */
+export function withAlpha(color: string, opacity: number): string {
+    const parsed = d3.color(color)
+    if (parsed === null) {
+        // unparseable color string; nothing sensible to bake an opacity into
+        return color
+    }
+    const {r, g, b} = parsed.rgb()
+    return `rgba(${r}, ${g}, ${b}, ${opacity})`
+}