@buildcanada/charts 0.1.0

package/src/grapher/color/ColorScaleBin.ts

@@ -0,0 +1,147 @@
+import { Color, CoreValueType } from "../../types/index.js"
+import { NO_DATA_LABEL, PROJECTED_DATA_LABEL } from "./ColorScale"
+
+interface BinProps {
+    color: Color
+    label?: string
+    patternRef?: string
+}
+
+interface NumericBinProps extends BinProps {
+    isFirst: boolean
+    isOpenLeft: boolean
+    isOpenRight: boolean
+    min: number
+    max: number
+    displayMin: string
+    displayMax: string
+}
+
+interface CategoricalBinProps extends BinProps {
+    index: number
+    value: string
+    label: string
+    isHidden?: boolean
+}
+
+abstract class AbstractColorScaleBin<T extends BinProps> {
+    props: T
+    constructor(props: T) {
+        this.props = props
+    }
+    get color(): string {
+        return this.props.color
+    }
+    get patternRef(): string | undefined {
+        return this.props.patternRef
+    }
+    get label(): string | undefined {
+        return this.props.label
+    }
+}
+
+export class NumericBin extends AbstractColorScaleBin<NumericBinProps> {
+    get min(): number {
+        return this.props.min
+    }
+    get max(): number {
+        return this.props.max
+    }
+    get minText(): string {
+        if (this.props.isOpenLeft) return ""
+        return this.props.displayMin
+    }
+    get maxText(): string {
+        if (this.props.isOpenRight) return ""
+        return this.props.displayMax
+    }
+    get text(): string {
+        return this.props.label || ""
+    }
+    get isHidden(): boolean {
+        return false
+    }
+
+    contains(value: CoreValueType | undefined): boolean {
+        if (typeof value !== "number") return false
+
+        // In looking at this code, it is important to realise that `isOpenLeft`, `isOpenRight`,
+        // and `isFirst` are _not_ mutually exclusive.
+        // For example, if both `isOpenRight` and `isFirst` are set, then we effectively want `value >= min`.
+
+        // If the bin is left-open, we just need to check the right side
+        if (this.props.isOpenLeft && value <= this.max) return true
+
+        // If the bin is right-open, we just need to check the left side
+        if (this.props.isOpenRight && value > this.min) return true
+
+        // If this is the first bin of the chart, we want to include the `min` value and thus use greater-equals
+        if (this.props.isFirst) {
+            return value >= this.min && value <= this.max
+        } else {
+            return value > this.min && value <= this.max
+        }
+    }
+
+    equals(other: ColorScaleBin): boolean {
+        return (
+            other instanceof NumericBin &&
+            this.min === other.min &&
+            this.max === other.max
+        )
+    }
+}
+
+export class CategoricalBin extends AbstractColorScaleBin<CategoricalBinProps> {
+    get index(): number {
+        return this.props.index
+    }
+    get value(): string {
+        return this.props.value
+    }
+    get isHidden(): boolean | undefined {
+        return this.props.isHidden
+    }
+
+    get text(): string {
+        return this.props.label || this.props.value
+    }
+
+    contains(
+        value: CoreValueType | undefined,
+        { isProjection = false } = {}
+    ): boolean {
+        return (
+            (value === undefined && this.props.value === NO_DATA_LABEL) ||
+            (value !== undefined &&
+                isProjection &&
+                this.props.value === PROJECTED_DATA_LABEL) ||
+            (value !== undefined && value === this.props.value)
+        )
+    }
+
+    equals(other: ColorScaleBin): boolean {
+        return (
+            other instanceof CategoricalBin &&
+            this.props.index === other.props.index
+        )
+    }
+}
+
+export function isCategoricalBin(bin: ColorScaleBin): bin is CategoricalBin {
+    return bin instanceof CategoricalBin
+}
+
+export function isNumericBin(bin: ColorScaleBin): bin is NumericBin {
+    return bin instanceof NumericBin
+}
+
+export function isNoDataBin(bin: ColorScaleBin): bin is CategoricalBin {
+    return isCategoricalBin(bin) && bin.value === NO_DATA_LABEL
+}
+
+export function isProjectedDataBin(bin: ColorScaleBin): bin is CategoricalBin {
+    return isCategoricalBin(bin) && bin.value === PROJECTED_DATA_LABEL
+}
+
+export type ColorScaleBin = CategoricalBin | NumericBin

package/src/grapher/color/ColorScaleConfig.ts

@@ -0,0 +1,204 @@
+import * as _ from "lodash-es"
+import { observable, makeObservable } from "mobx"
+import {
+    Color,
+    ColumnColorScale,
+    BinningStrategyIncludingManual,
+    ColorSchemeName,
+    ColorScaleConfigInterface,
+    MidpointMode,
+} from "../../types/index.js"
+import {
+    trimObject,
+    deleteRuntimeAndUnchangedProps,
+    objectWithPersistablesToObject,
+    Persistable,
+    updatePersistables,
+} from "../../utils/index.js"
+
+import { NO_DATA_LABEL } from "./ColorScale"
+
+export class ColorScaleConfigDefaults implements ColorScaleConfigInterface {
+    // Color scheme
+    // ============
+
+    /** Key for a colorbrewer scheme */
+    baseColorScheme: ColorSchemeName | undefined = undefined
+
+    /** Reverse the order of colors in the color scheme (defined by `baseColorScheme`) */
+    colorSchemeInvert: boolean | undefined = undefined
+
+    // Numeric bins
+    // ============
+
+    /** The strategy for generating the bin boundaries */
+    binningStrategy: BinningStrategyIncludingManual = "auto"
+    createBinForMidpoint?: boolean
+    minValue?: number
+    maxValue?: number
+    midpoint?: number
+    midpointMode?: MidpointMode
+
+    /** Custom maximum brackets for each numeric bin. Only applied when strategy is `manual`. */
+    customNumericValues: number[] = []
+    /**
+     * Custom labels for each numeric bin. Only applied when strategy is `manual`.
+     * `undefined` or `null` falls back to default label.
+     * We need to handle `null` because JSON serializes `undefined` values
+     * inside arrays into `null`.
+     */
+    customNumericLabels: (string | undefined | null)[] = []
+
+    /** Whether `customNumericColors` are used to override the color scheme. */
+    customNumericColorsActive: boolean | undefined = undefined
+    /**
+     * Override some or all colors for the numerical color legend.
+     * `undefined` or `null` falls back the color scheme color.
+     * We need to handle `null` because JSON serializes `undefined` values
+     * inside arrays into `null`.
+     */
+    customNumericColors: (Color | undefined | null)[] = []
+
+    // Categorical bins
+    // ================
+
+    customCategoryColors: {
+        [key: string]: string | undefined
+    } = {}
+
+    customCategoryLabels: {
+        [key: string]: string | undefined
+    } = {}
+
+    // Allow hiding categories from the legend
+    customHiddenCategories: {
+        [key: string]: true | undefined
+    } = {}
+
+    // Other
+    // =====
+
+    /** A custom legend description. Only used in ScatterPlot legend titles for now. */
+    legendDescription: string | undefined = undefined
+
+    constructor() {
+        makeObservable(this, {
+            baseColorScheme: observable,
+            colorSchemeInvert: observable,
+            binningStrategy: observable,
+            customNumericValues: observable,
+            customNumericLabels: observable,
+            customNumericColorsActive: observable,
+            customNumericColors: observable,
+            customCategoryColors: observable.ref,
+            customCategoryLabels: observable.ref,
+            customHiddenCategories: observable.ref,
+            legendDescription: observable,
+            createBinForMidpoint: observable,
+            minValue: observable,
+            maxValue: observable,
+            midpoint: observable,
+            midpointMode: observable,
+        })
+    }
+}
+
+export class ColorScaleConfig
+    extends ColorScaleConfigDefaults
+    implements Persistable
+{
+    updateFromObject(obj: Record<string, unknown>): void {
+        _.extend(this, obj)
+    }
+
+    toObject(): ColorScaleConfigInterface {
+        const obj: ColorScaleConfigInterface =
+            objectWithPersistablesToObject(this)
+        deleteRuntimeAndUnchangedProps(obj, new ColorScaleConfigDefaults())
+        return trimObject(obj)
+    }
+
+    constructor(obj?: Partial<ColorScaleConfig>) {
+        super()
+        updatePersistables(this, obj)
+    }
+
+    static fromDSL(scale: ColumnColorScale): ColorScaleConfig | undefined {
+        const colorSchemeInvert = scale.colorScaleInvert
+        const baseColorScheme = scale.colorScaleScheme as ColorSchemeName
+
+        const customNumericValues: number[] = []
+        const customNumericLabels: (string | undefined)[] = []
+        const customNumericColors: (Color | undefined)[] = []
+
+        if (scale.colorScaleNumericBins) {
+            customNumericValues.push(scale.colorScaleNumericMinValue ?? 0)
+
+            scale.colorScaleNumericBins
+                .split(INTER_BIN_DELIMITER)
+                .forEach((bin: string): void => {
+                    const [value, color, ...label] = bin.split(
+                        INTRA_BIN_DELIMITER
+                    ) as (string | undefined)[]
+                    if (!value) return
+                    customNumericValues.push(parseFloat(value))
+                    customNumericColors.push(color?.trim() || undefined)
+                    customNumericLabels.push(
+                        label.join(INTRA_BIN_DELIMITER).trim() || undefined
+                    )
+                })
+        }
+
+        const customNumericColorsActive =
+            customNumericColors.length > 0 ? true : undefined
+
+        const customCategoryColors: {
+            [key: string]: string | undefined
+        } = {}
+        const customCategoryLabels: {
+            [key: string]: string | undefined
+        } = {}
+        scale.colorScaleCategoricalBins
+            ?.split(INTER_BIN_DELIMITER)
+            .forEach((bin: string): void => {
+                const [value, color, ...label] = bin.split(
+                    INTRA_BIN_DELIMITER
+                ) as (string | undefined)[]
+                if (!value) return
+                customCategoryColors[value] = color?.trim() || undefined
+                customCategoryLabels[value] =
+                    label.join(INTRA_BIN_DELIMITER).trim() || undefined
+            })
+        if (scale.colorScaleNoDataLabel) {
+            customCategoryLabels[NO_DATA_LABEL] = scale.colorScaleNoDataLabel
+        }
+
+        // Use user-defined binning strategy, otherwise set to manual if user has
+        // defined custom bins
+        const binningStrategy = scale.colorScaleBinningStrategy
+            ? (scale.colorScaleBinningStrategy as BinningStrategyIncludingManual)
+            : scale.colorScaleNumericBins || scale.colorScaleCategoricalBins
+              ? "manual"
+              : undefined
+
+        const legendDescription = scale.colorScaleLegendDescription
+
+        const trimmed: Partial<ColorScaleConfig> = trimObject({
+            colorSchemeInvert,
+            baseColorScheme,
+            binningStrategy,
+            customNumericValues,
+            customNumericColors,
+            customNumericColorsActive,
+            customNumericLabels,
+            customCategoryLabels,
+            customCategoryColors,
+            legendDescription,
+        })
+
+        return _.isEmpty(trimmed) ? undefined : new ColorScaleConfig(trimmed)
+    }
+}
+
+const INTER_BIN_DELIMITER = ";"
+const INTRA_BIN_DELIMITER = ","

package/src/grapher/color/ColorScheme.ts

@@ -0,0 +1,137 @@
+// @ts-nocheck
+import * as _ from "lodash-es"
+import { rgb } from "d3-color"
+import { interpolate } from "d3-interpolate"
+import { lastOfNonEmptyArray, Color } from "../../utils/index.js"
+import { ColorSchemeInterface } from "../../types/index.js"
+import { interpolateArray } from "./ColorUtils"
+
+export class ColorScheme implements ColorSchemeInterface {
+    name: string
+    colorSets: Color[][]
+    singleColorScale: boolean
+    isDistinct: boolean
+    colorMap?: Record<string, Color>
+
+    constructor(
+        name: string,
+        colorSets: Color[][],
+        singleColorScale?: boolean,
+        isDistinct?: boolean,
+        colorMap?: Record<string, Color>
+    ) {
+        this.name = name
+        this.colorSets = []
+        this.singleColorScale = !!singleColorScale
+        this.isDistinct = !!isDistinct
+        this.colorMap = colorMap
+        colorSets.forEach((set) => (this.colorSets[set.length] = set))
+    }
+
+    improviseGradientFromShorter(
+        shortColors: Color[],
+        numColors: number
+    ): Color[] {
+        const newColors = _.clone(shortColors)
+
+        while (newColors.length < numColors) {
+            for (let index = newColors.length - 1; index > 0; index -= 1) {
+                const startColor = rgb(newColors[index - 1])
+                const endColor = rgb(newColors[index])
+                const newColor = interpolate(startColor, endColor)(0.5)
+                newColors.splice(index, 0, newColor)
+
+                if (newColors.length >= numColors) break
+            }
+        }
+
+        return newColors
+    }
+
+    improviseGradientFromLonger(
+        knownColors: Color[],
+        numColors: number
+    ): Color[] {
+        const newColors = []
+        const scale = interpolateArray(knownColors)
+        for (let index = 0; index < numColors; index++) {
+            newColors.push(scale(index / numColors))
+        }
+        return newColors
+    }
+
+    getGradientColors(numColors: number): Color[] {
+        const { colorSets } = this
+
+        if (colorSets[numColors]) return _.clone(colorSets[numColors])
+
+        const prevColors = colorSets
+            .toReversed()
+            .find((set) => set && set.length < numColors)
+        if (prevColors)
+            return this.improviseGradientFromShorter(prevColors, numColors)
+        else
+            return this.improviseGradientFromLonger(
+                colorSets.find((set) => !!set) as Color[],
+                numColors
+            )
+    }
+
+    getDistinctColors(numColors: number): Color[] {
+        const { colorSets } = this
+        if (colorSets.length === 0) return []
+        if (colorSets[numColors]) return _.clone(colorSets[numColors])
+
+        if (numColors > colorSets.length - 1) {
+            // If more colors are wanted than we have defined, have to improvise
+            const colorSet = lastOfNonEmptyArray(colorSets)
+            // Special case for colorSchemes with a single color where the usual interpolation would not work
+            if (colorSet.length === 1) return Array(numColors).fill(colorSet[0])
+            return this.improviseGradientFromShorter(colorSet, numColors)
+        }
+
+        // We have enough colors but not a specific set for this number-- improvise from the closest longer set
+        for (let i = numColors; i < colorSets.length; i++) {
+            if (colorSets[i]) {
+                return colorSets[i].slice(0, numColors)
+            }
+        }
+
+        return []
+    }
+
+    getColors(numColors: number): Color[] {
+        return this.isDistinct
+            ? this.getDistinctColors(numColors)
+            : this.getGradientColors(numColors)
+    }
+
+    getUniqValueColorMap(
+        uniqValues: any[],
+        inverseOrder?: boolean
+    ): Map<number, string> {
+        const colors = this.getColors(uniqValues.length) || []
+        if (inverseOrder) colors.reverse()
+
+        // We want to display same values using the same color, e.g. two values of 100 get the same shade of green
+        // Therefore, we create a map from all possible (unique) values to the corresponding color
+        const colorByValue = new Map<number, Color>()
+        uniqValues.forEach((value, index) =>
+            colorByValue.set(value, colors[index])
+        )
+        return colorByValue
+    }
+
+    static fromObject(
+        name: string,
+        colorSets: { [key: string]: Color[] },
+        singleColorScale?: boolean
+    ): ColorScheme {
+        const colorSetsArray: Color[][] = []
+        Object.keys(colorSets).forEach(
+            (numColors): string[] =>
+                (colorSetsArray[+numColors] = colorSets[numColors])
+        )
+        return new ColorScheme(name, colorSetsArray, singleColorScale)
+    }
+}

package/src/grapher/color/ColorSchemes.ts

@@ -0,0 +1,149 @@
+import * as _ from "lodash-es"
+import { CustomColorSchemes } from "./CustomSchemes"
+import { ColorScheme } from "./ColorScheme"
+import { match } from "ts-pattern"
+import {
+    GRAPHER_CHART_TYPES,
+    ColorSchemeInterface,
+    ColorSchemeName,
+    GRAPHER_MAP_TYPE,
+    GrapherChartOrMapType,
+} from "../../types/index.js"
+import { getColorBrewerScheme } from "./ColorBrewerSchemes.js"
+
+function getPreferredSchemesByType(
+    type: GrapherChartOrMapType
+): ColorSchemeName[] {
+    // This function could also be a Map<GrapherChartOrMapType, ColorName[]> but
+    // by doing it as a function usign ts-pattern.match we get compile
+    // time safety that all enum cases in GrapherChartOrMapType are always handled here
+    return match(type)
+        .with(GRAPHER_CHART_TYPES.DiscreteBar, () => [
+            ColorSchemeName.SingleColorDenim,
+            ColorSchemeName.SingleColorDustyCoral,
+            ColorSchemeName.SingleColorPurple,
+            ColorSchemeName.SingleColorTeal,
+            ColorSchemeName.SingleColorDarkCopper,
+        ])
+        .with(GRAPHER_CHART_TYPES.LineChart, () => [
+            ColorSchemeName.OwidDistinctLines,
+        ])
+        .with(GRAPHER_CHART_TYPES.Marimekko, () => [
+            ColorSchemeName.continents,
+            ColorSchemeName.SingleColorDenim,
+            ColorSchemeName.SingleColorDustyCoral,
+            ColorSchemeName.SingleColorPurple,
+            ColorSchemeName.SingleColorTeal,
+            ColorSchemeName.SingleColorDarkCopper,
+            ColorSchemeName.OwidCategoricalA,
+            ColorSchemeName.OwidCategoricalB,
+            ColorSchemeName.OwidCategoricalC,
+            ColorSchemeName.OwidCategoricalD,
+            ColorSchemeName.OwidCategoricalE,
+        ])
+        .with(GRAPHER_CHART_TYPES.ScatterPlot, () => [
+            ColorSchemeName.continents,
+            ColorSchemeName.OwidDistinctLines,
+        ])
+        .with(GRAPHER_CHART_TYPES.SlopeChart, () => [
+            ColorSchemeName.continents,
+            ColorSchemeName.OwidDistinctLines,
+        ])
+        .with(GRAPHER_CHART_TYPES.StackedArea, () => [
+            ColorSchemeName["owid-distinct"],
+            ColorSchemeName.OwidCategoricalA,
+            ColorSchemeName.OwidCategoricalB,
+            ColorSchemeName.OwidCategoricalC,
+            ColorSchemeName.OwidCategoricalD,
+            ColorSchemeName.OwidCategoricalE,
+            ColorSchemeName.SingleColorGradientDenim,
+            ColorSchemeName.SingleColorGradientTeal,
+            ColorSchemeName.SingleColorGradientPurple,
+            ColorSchemeName.SingleColorGradientDustyCoral,
+            ColorSchemeName.SingleColorGradientDarkCopper,
+        ])
+        .with(GRAPHER_CHART_TYPES.StackedBar, () => [
+            ColorSchemeName["owid-distinct"],
+            ColorSchemeName.OwidCategoricalA,
+            ColorSchemeName.OwidCategoricalB,
+            ColorSchemeName.OwidCategoricalC,
+            ColorSchemeName.OwidCategoricalD,
+            ColorSchemeName.OwidCategoricalE,
+            ColorSchemeName.SingleColorGradientDenim,
+            ColorSchemeName.SingleColorGradientTeal,
+            ColorSchemeName.SingleColorGradientPurple,
+            ColorSchemeName.SingleColorGradientDustyCoral,
+            ColorSchemeName.SingleColorGradientDarkCopper,
+        ])
+        .with(GRAPHER_CHART_TYPES.StackedDiscreteBar, () => [
+            ColorSchemeName["owid-distinct"],
+            ColorSchemeName.OwidCategoricalA,
+            ColorSchemeName.OwidCategoricalB,
+            ColorSchemeName.OwidCategoricalC,
+            ColorSchemeName.OwidCategoricalD,
+            ColorSchemeName.OwidCategoricalE,
+            ColorSchemeName.SingleColorGradientDenim,
+            ColorSchemeName.SingleColorGradientTeal,
+            ColorSchemeName.SingleColorGradientPurple,
+            ColorSchemeName.SingleColorGradientDustyCoral,
+            ColorSchemeName.SingleColorGradientDarkCopper,
+        ])
+        .with(GRAPHER_MAP_TYPE, () => [
+            ColorSchemeName.BinaryMapPaletteA,
+            ColorSchemeName.BinaryMapPaletteB,
+            ColorSchemeName.BinaryMapPaletteC,
+            ColorSchemeName.BinaryMapPaletteD,
+            ColorSchemeName.BinaryMapPaletteE,
+        ])
+        .exhaustive()
+}
+
+const initColorScheme = (scheme: ColorSchemeInterface): ColorScheme =>
+    new ColorScheme(
+        scheme.displayName ?? scheme.name,
+        scheme.colorSets,
+        scheme.singleColorScale,
+        scheme.isDistinct,
+        scheme.colorMap
+    )
+
+const _colorSchemes = new Map<ColorSchemeName, ColorScheme>()
+
+// This object has a map-like appearance from the outside (with a .get() method),
+// but lazy-loads color schemes as they are requested
+export const ColorSchemes = {
+    get: (name: ColorSchemeName): ColorScheme => {
+        if (!_colorSchemes.has(name)) {
+            const schemeRaw =
+                getColorBrewerScheme(name) ??
+                CustomColorSchemes.find((s) => s.name === name)
+            if (!schemeRaw) throw new Error(`Color scheme ${name} not found`)
+            const scheme = initColorScheme(schemeRaw)
+            _colorSchemes.set(name, scheme)
+        }
+        return _colorSchemes.get(name)!
+    },
+}
+
+const getAllColorSchemes = (): Map<ColorSchemeName, ColorScheme> => {
+    return new Map(
+        Object.keys(ColorSchemeName).map((key) => [
+            key as ColorSchemeName,
+            ColorSchemes.get(key as ColorSchemeName),
+        ])
+    )
+}
+
+export function getColorSchemeForChartType(type: GrapherChartOrMapType): {
+    [key in ColorSchemeName]: ColorScheme
+} {
+    const preferred = new Set(getPreferredSchemesByType(type))
+    const allSchemes = getAllColorSchemes()
+    const [preferredSchemes, otherSchemes] = _.partition(
+        [...allSchemes.entries()],
+        (schemeKeyValue) => preferred.has(schemeKeyValue[0])
+    )
+    return Object.fromEntries([...preferredSchemes, ...otherSchemes]) as {
+        [key in ColorSchemeName]: ColorScheme
+    }
+}