@buildcanada/charts 0.1.0

package/src/grapher/schema/migrations/helpers.ts

@@ -0,0 +1,58 @@
+import {
+    latestSchemaVersion,
+    outdatedSchemaVersions,
+} from "../defaultGrapherConfig"
+
+const allSchemaVersions = [...outdatedSchemaVersions, latestSchemaVersion]
+
+type LatestSchemaVersion = typeof latestSchemaVersion
+type OutdatedSchemaVersion = (typeof outdatedSchemaVersions)[number]
+type SchemaVersion = OutdatedSchemaVersion | LatestSchemaVersion
+
+type Schema =
+    `https://files.ourworldindata.org/schemas/grapher-schema.${SchemaVersion}.json`
+
+// we can't type configs that don't adhere to the latest schema as we don't know what they look like
+export type AnyConfig = Record<string, any>
+export type AnyConfigWithValidSchema = AnyConfig & {
+    $schema: Schema
+}
+
+const schemaVersionRegex =
+    /https:\/\/files\.ourworldindata\.org\/schemas\/grapher-schema\.(?<version>\d{3})\.json/m
+
+const isValidSchemaVersion = (version: string): version is SchemaVersion =>
+    allSchemaVersions.includes(version as any)
+
+export function getSchemaVersion(
+    config: AnyConfigWithValidSchema
+): SchemaVersion
+export function getSchemaVersion(config: AnyConfig): SchemaVersion | null
+export function getSchemaVersion(
+    config: AnyConfig | AnyConfigWithValidSchema
+): SchemaVersion | null {
+    const version = config.$schema?.match(schemaVersionRegex)?.groups?.version
+    if (!version || !isValidSchemaVersion(version)) return null
+    return version
+}
+
+export function createSchemaForVersion(version: SchemaVersion): Schema {
+    return `https://files.ourworldindata.org/schemas/grapher-schema.${version}.json`
+}
+
+export const isLatestVersion = (version: SchemaVersion) =>
+    version === latestSchemaVersion
+
+export const isOutdatedVersion = (version: SchemaVersion) =>
+    outdatedSchemaVersions.includes(version as any)
+
+export const hasValidSchema = (
+    config: AnyConfig
+): config is AnyConfigWithValidSchema => getSchemaVersion(config) !== null
+
+export const hasOutdatedSchema = (
+    config: AnyConfigWithValidSchema
+): boolean => {
+    const version = getSchemaVersion(config)
+    return isOutdatedVersion(version)
+}

package/src/grapher/schema/migrations/migrate.ts

@@ -0,0 +1,75 @@
+import * as _ from "lodash-es"
+import { GrapherInterface } from "../../../types/index.js"
+
+import { defaultGrapherConfig } from "../defaultGrapherConfig"
+import {
+    getSchemaVersion,
+    hasValidSchema,
+    isLatestVersion,
+    hasOutdatedSchema,
+    type AnyConfig,
+    type AnyConfigWithValidSchema,
+} from "./helpers"
+import { runMigration } from "./migrations"
+
+const recursivelyApplyMigrations = (
+    config: AnyConfigWithValidSchema
+): AnyConfigWithValidSchema => {
+    const version = getSchemaVersion(config)
+    if (isLatestVersion(version)) return config
+    return recursivelyApplyMigrations(runMigration(config))
+}
+
+const migrate = (config: AnyConfigWithValidSchema): GrapherInterface =>
+    recursivelyApplyMigrations(config) as GrapherInterface
+
+/**
+ * Attempts to migrate a config to the latest schema version.
+ *
+ * An outdated config is migrated to the latest version by applying a series of
+ * predefined migrations. We rely on the schema version to determine if a config
+ * is outdated.
+ *
+ * Note that the given config is not actually validated against the schema!
+ */
+export const migrateGrapherConfigToLatestVersion = (
+    config: AnyConfig
+): GrapherInterface => {
+    // the config adheres to the latest schema
+    if (config.$schema === defaultGrapherConfig.$schema) return config
+
+    // if the schema version is outdated, migrate it
+    if (hasValidSchema(config) && hasOutdatedSchema(config)) {
+        return migrate(_.cloneDeep(config))
+    }
+
+    // throw if the schema is missing
+    if (config.$schema === undefined) {
+        throw new Error("Schema missing")
+    } else {
+        /**
+         * If the schema version is not outdated and not the latest, we have most likely received a
+         * config from a future version of the codebase, that the client code is not yet aware of.
+         * That's not perfect, but in reality, most schema changes are benign changes,
+         * and rendering the config with the current code will result in a better user experience
+         * than just throwing an error and grapher not rendering at all without any explanation.
+         * - @marcelgerber, 2025-07-02
+         */
+        const message = `Received grapher config with unsupported schema ${config.$schema}; this code expects schema ${defaultGrapherConfig.$schema}.`
+        console.warn(message)
+        return config
+    }
+}
+
+export const migrateGrapherConfigToLatestVersionAndFailOnError = (
+    config: AnyConfig
+): GrapherInterface => {
+    const migrated = migrateGrapherConfigToLatestVersion(config)
+
+    if (migrated.$schema !== defaultGrapherConfig.$schema) {
+        throw new Error(
+            `Invalid schema version after schema migration: ${migrated.$schema}. Expected: ${defaultGrapherConfig.$schema}`
+        )
+    }
+    return migrated
+}

package/src/grapher/schema/migrations/migrations.ts

@@ -0,0 +1,158 @@
+// Schema migrations
+//
+// Every breaking change to the schema should be accompanied by a migration.
+//
+// To add a migration, follow these steps:
+//    - Create a new function `migrateXXXToXXX` that migrates a config from one version to the next.
+//      Make sure to update the $schema field to the next version in your migration function,
+//      or else the recursively defined migrate function will not terminate!
+//    - Add a new case to the match statement in `runMigration` that calls the new migration function.
+
+import { match } from "ts-pattern"
+import {
+    type AnyConfigWithValidSchema,
+    createSchemaForVersion,
+    getSchemaVersion,
+    isLatestVersion,
+} from "./helpers"
+import { GRAPHER_CHART_TYPES } from "../../../types/index.js"
+
+// see https://github.com/owid/owid-grapher/commit/26f2a0d1790c71bdda7e12f284ca552945d2f6ef
+const migrateFrom001To002 = (
+    config: AnyConfigWithValidSchema
+): AnyConfigWithValidSchema => {
+    delete config.selectedData
+    config.$schema = createSchemaForVersion("002")
+    return config
+}
+
+// see https://github.com/owid/owid-grapher/commit/4525ad81fb7064709ffab83677a8b0354b324dfb
+const migrateFrom002To003 = (
+    config: AnyConfigWithValidSchema
+): AnyConfigWithValidSchema => {
+    if (config.hideTitleAnnotation) {
+        config.hideTitleAnnotations = {
+            entity: true,
+            time: true,
+            change: true,
+        }
+    }
+    delete config.hideTitleAnnotation
+
+    config.$schema = createSchemaForVersion("003")
+    return config
+}
+
+// see https://github.com/owid/owid-grapher/commit/1776721253cf61d7f1e24ebadeaf7a7ca2f43ced
+const migrateFrom003To004 = (
+    config: AnyConfigWithValidSchema
+): AnyConfigWithValidSchema => {
+    delete config.data
+    config.$schema = createSchemaForVersion("004")
+    return config
+}
+
+// see https://github.com/owid/owid-grapher/commit/1d67de3174764a413bc5055fbdf34efb2b49e079
+const migrateFrom004To005 = (
+    config: AnyConfigWithValidSchema
+): AnyConfigWithValidSchema => {
+    delete config.hideLinesOutsideTolerance
+    config.$schema = createSchemaForVersion("005")
+    return config
+}
+
+const migrateFrom005To006 = (
+    config: AnyConfigWithValidSchema
+): AnyConfigWithValidSchema => {
+    const { type = GRAPHER_CHART_TYPES.LineChart, hasChartTab = true } = config
+
+    // add types field
+    if (!hasChartTab) config.chartTypes = []
+    else if (type !== GRAPHER_CHART_TYPES.LineChart) config.chartTypes = [type]
+
+    // remove deprecated fields
+    delete config.type
+    delete config.hasChartTab
+
+    config.$schema = createSchemaForVersion("006")
+    return config
+}
+
+export const migrateFrom006To007 = (
+    config: AnyConfigWithValidSchema
+): AnyConfigWithValidSchema => {
+    // rename map.projection to map.region
+    if (config.map?.projection) {
+        config.map.region = config.map.projection
+        delete config.map.projection
+    }
+
+    config.$schema = createSchemaForVersion("007")
+    return config
+}
+
+export const migrateFrom007To008 = (
+    config: AnyConfigWithValidSchema
+): AnyConfigWithValidSchema => {
+    // remove colorScale.customNumericMinValue, merge it into colorScale.customNumericValues
+    if (config.map?.colorScale?.customNumericValues) {
+        config.map.colorScale.customNumericValues = [
+            config.map.colorScale.customNumericMinValue ?? 0,
+            ...config.map.colorScale.customNumericValues,
+        ]
+    }
+    if (config.map?.colorScale?.customNumericMinValue !== undefined) {
+        delete config.map.colorScale.customNumericMinValue
+    }
+
+    if (config.colorScale?.customNumericValues) {
+        config.colorScale.customNumericValues = [
+            config.colorScale.customNumericMinValue ?? 0,
+            ...config.colorScale.customNumericValues,
+        ]
+    }
+    if (config.colorScale?.customNumericMinValue !== undefined) {
+        delete config.colorScale.customNumericMinValue
+    }
+
+    config.$schema = createSchemaForVersion("008")
+    return config
+}
+
+export const migrateFrom008To009 = (config: AnyConfigWithValidSchema) => {
+    if ((config.map?.colorScale?.binningStrategy ?? "manual") !== "manual") {
+        config.map.colorScale.binningStrategy = "auto"
+    }
+
+    if (config.map?.colorScale?.binningStrategyBinCount !== undefined) {
+        delete config.map.colorScale.binningStrategyBinCount
+    }
+
+    if ((config.colorScale?.binningStrategy ?? "manual") !== "manual") {
+        config.colorScale.binningStrategy = "auto"
+    }
+
+    if (config.colorScale?.binningStrategyBinCount !== undefined) {
+        delete config.colorScale.binningStrategyBinCount
+    }
+
+    config.$schema = createSchemaForVersion("009")
+    return config
+}
+
+export const runMigration = (
+    config: AnyConfigWithValidSchema
+): AnyConfigWithValidSchema => {
+    const version = getSchemaVersion(config)
+    if (isLatestVersion(version)) return config
+    return match(version)
+        .with("001", () => migrateFrom001To002(config))
+        .with("002", () => migrateFrom002To003(config))
+        .with("003", () => migrateFrom003To004(config))
+        .with("004", () => migrateFrom004To005(config))
+        .with("005", () => migrateFrom005To006(config))
+        .with("006", () => migrateFrom006To007(config))
+        .with("007", () => migrateFrom007To008(config))
+        .with("008", () => migrateFrom008To009(config))
+        .exhaustive()
+}

package/src/grapher/selection/MapSelectionArray.ts

@@ -0,0 +1,99 @@
+import { computed, makeObservable } from "mobx"
+import { SelectionArray } from "./SelectionArray"
+import {
+    Aggregate,
+    checkHasMembers,
+    checkIsCountry,
+    Continent,
+    Country,
+    EntityName,
+    excludeUndefined,
+    getCountryNamesForRegion,
+    getRegionByName,
+    IncomeGroup,
+    Region,
+} from "../../utils/index.js"
+import * as R from "remeda"
+
+export class MapSelectionArray extends SelectionArray {
+    constructor(selectedEntityNames: EntityName[] = []) {
+        super(selectedEntityNames)
+
+        makeObservable(this)
+    }
+
+    @computed private get selectedEntitiesWithRegionInfo(): Region[] {
+        return excludeUndefined(
+            this.selectedEntityNames.map((name) => getRegionByName(name))
+        )
+    }
+
+    @computed get selectedCountries(): Country[] {
+        return this.selectedEntitiesWithRegionInfo.filter((region) =>
+            checkIsCountry(region)
+        )
+    }
+
+    @computed get selectedCountryNames(): EntityName[] {
+        return this.selectedCountries.map((country) => country.name)
+    }
+
+    @computed get hasCountries(): boolean {
+        return this.selectedCountries.length > 0
+    }
+
+    /**
+     * Subset of the selected countries that are part of the selected regions.
+     * Returns all selected countries if no region is selected.
+     */
+    @computed get selectedCountryNamesInForeground(): EntityName[] {
+        if (!this.hasRegions) return this.selectedCountryNames
+        const memberCountries = this.countryNamesForSelectedRegionsSet
+        return this.selectedCountries
+            .filter((country) => memberCountries.has(country.name))
+            .map((country) => country.name)
+    }
+
+    /**
+     * Complement of `selectedCountryNamesInForeground`.
+     * Subset of the selected countries that are not part of any selected region.
+     * Returns an empty list if no region is selected.
+     */
+    @computed get selectedCountryNamesInBackground(): EntityName[] {
+        return R.difference(
+            this.selectedCountryNames,
+            this.selectedCountryNamesInForeground
+        )
+    }
+
+    /**
+     * List of selected regions where a region is any geographic entity that
+     * is made up of a set of countries.
+     */
+    @computed get selectedRegions(): (Continent | Aggregate | IncomeGroup)[] {
+        return this.selectedEntitiesWithRegionInfo.filter(
+            (region): region is Continent | Aggregate | IncomeGroup =>
+                checkHasMembers(region) && region.code !== "OWID_WRL"
+        )
+    }
+
+    @computed get selectedRegionNames(): EntityName[] {
+        return this.selectedRegions.map((region) => region.name)
+    }
+
+    @computed get hasRegions(): boolean {
+        return this.selectedRegions.length > 0
+    }
+
+    @computed get countryNamesForSelectedRegionsSet(): Set<EntityName> {
+        return new Set(
+            this.selectedRegions.flatMap((region) =>
+                getCountryNamesForRegion(region)
+            )
+        )
+    }
+
+    @computed get countryNamesForSelectedRegions(): EntityName[] {
+        return Array.from(this.countryNamesForSelectedRegionsSet)
+    }
+}

package/src/grapher/selection/SelectionArray.ts

@@ -0,0 +1,71 @@
+import { EntityName } from "../../types/index.js"
+import { action, computed, observable, makeObservable } from "mobx"
+
+export class SelectionArray {
+    constructor(selectedEntityNames: EntityName[] = []) {
+        makeObservable(this, {
+            selectedEntityNames: observable,
+        })
+        this.selectedEntityNames = selectedEntityNames.slice()
+    }
+
+    selectedEntityNames: EntityName[]
+
+    @computed get hasSelection(): boolean {
+        return this.selectedEntityNames.length > 0
+    }
+
+    @computed get numSelectedEntities(): number {
+        return this.selectedEntityNames.length
+    }
+
+    @computed get selectedSet(): Set<EntityName> {
+        return new Set<EntityName>(this.selectedEntityNames)
+    }
+
+    // Clears and sets selected entities
+    @action.bound setSelectedEntities(entityNames: EntityName[]): this {
+        this.clearSelection()
+        return this.addToSelection(entityNames)
+    }
+
+    @action.bound addToSelection(entityNames: EntityName[]): this {
+        this.selectedEntityNames = this.selectedEntityNames.concat(entityNames)
+        return this
+    }
+
+    @action.bound clearSelection(): void {
+        this.selectedEntityNames = []
+    }
+
+    @action.bound toggleSelection(entityName: EntityName): this {
+        return this.selectedSet.has(entityName)
+            ? this.deselectEntity(entityName)
+            : this.selectEntity(entityName)
+    }
+
+    @action.bound selectEntity(entityName: EntityName): this {
+        if (!this.selectedSet.has(entityName))
+            return this.addToSelection([entityName])
+        return this
+    }
+
+    @action.bound deselectEntity(entityName: EntityName): this {
+        this.selectedEntityNames = this.selectedEntityNames.filter(
+            (name) => name !== entityName
+        )
+        return this
+    }
+
+    @action.bound selectEntities(entityNames: EntityName[]): this {
+        entityNames.forEach((entityName) => this.selectEntity(entityName))
+        return this
+    }
+
+    @action.bound deselectEntities(entityNames: EntityName[]): this {
+        this.selectedEntityNames = this.selectedEntityNames.filter(
+            (name) => !entityNames.includes(name)
+        )
+        return this
+    }
+}

package/src/grapher/selection/readme.md

@@ -0,0 +1,16 @@
+# SelectionArray
+
+The browser already has a class named `Selection`, so for now we have `SelectionArray`.
+
+This is a pretty simple class that maintains 2 arrays:
+
+1. An array of strings which contains the names and or codes of selected entities
+2. An array of Entities that can be selected
+
+If something happens so the user has new choices, you can expand #2.
+
+## Wish list
+
+Except for Scatters, only selected entities will appear in charts. In Scatters "selected entities" really are "highlighted entities". It may be nice to separate those concepts.
+
+SeriesSelection. It may be better to rename OwidTable to TimeSeriesTable, and remove the concept of `entityName` and replace with `seriesName`. Then we could have a nice simple concept "SeriesSelection". Similarly, we could ditch "EntityCode" and maybe have "SeriesNickname", which would be a shorter URL friendly way to specify seriesSelection. It would then be nice to rename the `country=` url param to something like `series=`

package/src/grapher/sidePanel/SidePanel.scss

@@ -0,0 +1,10 @@
+.side-panel {
+    flex-grow: 0;
+    flex-shrink: 0;
+    border-left: 1px solid $frame-color;
+
+    // don't show close button in the side panel header
+    .overlay-header .close-button {
+        display: none;
+    }
+}

package/src/grapher/sidePanel/SidePanel.tsx

@@ -0,0 +1,23 @@
+import * as React from "react"
+import { Bounds } from "../../utils/index.js"
+import { GRAPHER_SIDE_PANEL_CLASS } from "../core/GrapherConstants.js"
+
+export const SidePanel = ({
+    bounds,
+    children,
+}: {
+    bounds: Bounds
+    children: React.ReactNode
+}) => {
+    return (
+        <div
+            className={GRAPHER_SIDE_PANEL_CLASS}
+            style={{
+                width: bounds.width,
+                height: bounds.height,
+            }}
+        >
+            {children}
+        </div>
+    )
+}

package/src/grapher/slideInDrawer/SlideInDrawer.scss

@@ -0,0 +1,57 @@
+.drawer {
+    .drawer-contents {
+        position: absolute;
+        right: 0;
+        top: 0;
+        width: 300px;
+        height: 100%;
+        z-index: $zindex-controls-drawer;
+        background: white;
+    }
+
+    .drawer-backdrop {
+        position: absolute;
+        top: 0;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        background: rgba(0, 0, 0, 0.1);
+        z-index: $zindex-controls-backdrop;
+    }
+}
+
+@keyframes drawer-backdrop-enter {
+    0% {
+        opacity: 0;
+    }
+    100% {
+        opacity: 1;
+    }
+}
+
+@keyframes drawer-backdrop-exit {
+    0% {
+        opacity: 1;
+    }
+    100% {
+        opacity: 0;
+    }
+}
+
+@keyframes drawer-contents-enter {
+    0% {
+        transform: translate(301px, 0);
+    }
+    100% {
+        transform: translate(0, 0);
+    }
+}
+
+@keyframes drawer-contents-exit {
+    0% {
+        transform: translate(0, 0);
+    }
+    100% {
+        transform: translate(301px, 0);
+    }
+}

package/src/grapher/slideInDrawer/SlideInDrawer.tsx

@@ -0,0 +1,125 @@
+import * as React from "react"
+import cx from "classnames"
+import { computed, action, observable, makeObservable } from "mobx"
+import { observer } from "mobx-react"
+import { isTargetOutsideElement } from "../chart/ChartUtils"
+
+export const DrawerContext = React.createContext<{
+    toggleDrawerVisibility?: () => void
+}>({})
+
+interface SlideInDrawerProps {
+    active: boolean
+    toggle: () => void
+    children: React.ReactNode
+    grapherRef?: React.RefObject<HTMLDivElement | null>
+}
+
+@observer
+export class SlideInDrawer extends React.Component<SlideInDrawerProps> {
+    visible: boolean = this.props.active // true while the drawer is active and during enter/exit transitions
+    drawerRef = React.createRef<HTMLDivElement>()
+
+    constructor(props: SlideInDrawerProps) {
+        super(props)
+
+        makeObservable(this, {
+            visible: observable.ref,
+        })
+    }
+
+    override componentDidMount(): void {
+        document.addEventListener("keydown", this.onDocumentKeyDown)
+        document.addEventListener("click", this.onDocumentClick, {
+            capture: true,
+        })
+    }
+
+    override componentWillUnmount(): void {
+        document.removeEventListener("keydown", this.onDocumentKeyDown)
+        document.removeEventListener("click", this.onDocumentClick, {
+            capture: true,
+        })
+    }
+
+    override componentDidUpdate(): void {
+        const grapherElement = this.props.grapherRef?.current
+        if (grapherElement) {
+            grapherElement.style.overflowX =
+                this.active || this.visible ? "clip" : "visible"
+        }
+    }
+
+    @action.bound onDocumentKeyDown(e: KeyboardEvent): void {
+        // dismiss menu on esc
+        if (this.active && e.key === "Escape") this.toggleVisibility()
+    }
+
+    @action.bound onDocumentClick(e: MouseEvent): void {
+        if (
+            this.active &&
+            this.drawerRef?.current &&
+            isTargetOutsideElement(e.target!, this.drawerRef.current)
+        )
+            this.toggleVisibility()
+    }
+
+    @action.bound toggleVisibility(e?: React.MouseEvent): void {
+        this.props.toggle()
+        if (this.active) this.visible = true
+        e?.stopPropagation()
+    }
+
+    @action.bound onAnimationEnd(): void {
+        if (!this.active) this.visible = false
+    }
+
+    @computed private get active(): boolean {
+        return this.props.active
+    }
+
+    private animationFor(selector: string): React.CSSProperties {
+        const phase = this.active ? "enter" : "exit"
+        return {
+            animationName: `${selector}-${phase}`,
+            animationDuration: "333ms",
+            animationFillMode: "forwards",
+        }
+    }
+
+    override render(): React.ReactElement | null {
+        const { visible, active } = this
+
+        if (active || visible) {
+            return (
+                <div
+                    className={cx("drawer", { active: this.active })}
+                    ref={this.drawerRef}
+                >
+                    <div
+                        className="drawer-backdrop"
+                        onClick={this.toggleVisibility}
+                        style={this.animationFor("drawer-backdrop")}
+                        onAnimationEnd={this.onAnimationEnd} // triggers unmount
+                    ></div>
+                    <div
+                        className="drawer-contents"
+                        style={{
+                            ...this.animationFor("drawer-contents"),
+                        }}
+                    >
+                        <DrawerContext.Provider
+                            value={{
+                                toggleDrawerVisibility: this.toggleVisibility,
+                            }}
+                        >
+                            {this.props.children}
+                        </DrawerContext.Provider>
+                    </div>
+                </div>
+            )
+        }
+
+        return null
+    }
+}