@buildcanada/charts 0.1.0

package/src/grapher/controls/settings/AxisScaleToggle.tsx

@@ -0,0 +1,53 @@
+import * as React from "react"
+import { action, makeObservable } from "mobx"
+import { observer } from "mobx-react"
+import { ScaleType } from "../../../types/index.js"
+import { AxisConfig } from "../../axis/AxisConfig"
+import classnames from "classnames"
+
+interface AxisScaleToggleProps {
+    axis: AxisConfig
+    subtitle?: string
+    prefix?: string
+}
+
+@observer
+export class AxisScaleToggle extends React.Component<AxisScaleToggleProps> {
+    constructor(props: AxisScaleToggleProps) {
+        super(props)
+        makeObservable(this)
+    }
+
+    @action.bound private setAxisScale(scale: ScaleType): void {
+        this.props.axis.scaleType = scale
+    }
+
+    override render(): React.ReactElement {
+        const { linear, log } = ScaleType,
+            { axis, prefix, subtitle } = this.props,
+            isLinear = axis.scaleType === linear,
+            label = prefix ? `${prefix}: ` : undefined
+
+        return (
+            <>
+                <div className="config-toggle">
+                    {subtitle && <label>{subtitle}</label>}
+                    <button
+                        className={classnames({ active: isLinear })}
+                        onClick={(): void => this.setAxisScale(linear)}
+                        data-track-note="chart_toggle_scale"
+                    >
+                        {label}Linear
+                    </button>
+                    <button
+                        className={classnames({ active: !isLinear })}
+                        onClick={(): void => this.setAxisScale(log)}
+                        data-track-note="chart_toggle_scale"
+                    >
+                        {label}Logarithmic
+                    </button>
+                </div>
+            </>
+        )
+    }
+}

package/src/grapher/controls/settings/FacetStrategySelector.tsx

@@ -0,0 +1,110 @@
+import * as _ from "lodash-es"
+import * as React from "react"
+import { computed, makeObservable } from "mobx"
+import { observer } from "mobx-react"
+import { DEFAULT_GRAPHER_ENTITY_TYPE } from "../../core/GrapherConstants"
+import { FacetStrategy } from "../../../utils/index.js"
+import classnames from "classnames"
+
+export interface FacetStrategySelectionManager {
+    availableFacetStrategies: FacetStrategy[]
+    facetStrategy?: FacetStrategy
+    entityType?: string
+    facettingLabelByYVariables?: string
+}
+
+@observer
+export class FacetStrategySelector extends React.Component<{
+    manager: FacetStrategySelectionManager
+}> {
+    constructor(props: { manager: FacetStrategySelectionManager }) {
+        super(props)
+        makeObservable(this)
+    }
+
+    @computed get facetStrategyLabels(): { [key in FacetStrategy]: string } {
+        return {
+            [FacetStrategy.none]: "All together",
+            [FacetStrategy.entity]: `Split by ${this.entityName}`,
+            [FacetStrategy.metric]: `Split by ${this.metricName}`,
+        }
+    }
+
+    @computed get entityName(): string {
+        return this.props.manager.entityType ?? DEFAULT_GRAPHER_ENTITY_TYPE
+    }
+
+    @computed get metricName(): string {
+        return this.props.manager.facettingLabelByYVariables ?? "metric"
+    }
+
+    @computed get strategies(): FacetStrategy[] {
+        return (
+            this.props.manager.availableFacetStrategies || [
+                FacetStrategy.none,
+                FacetStrategy.entity,
+                FacetStrategy.metric,
+            ]
+        )
+    }
+
+    @computed get subtitle(): string {
+        const entityChoice = this.entityName.replace(/ or /, "/"),
+            byEntity = this.strategies.includes(FacetStrategy.entity),
+            byMetric = this.strategies.includes(FacetStrategy.metric)
+
+        if (byEntity || byMetric) {
+            const facet =
+                byEntity && byMetric
+                    ? `${this.metricName} or ${entityChoice}`
+                    : byEntity
+                      ? this.entityName
+                      : this.metricName
+            return (
+                "Visualize the data all together in one chart or split it by " +
+                facet
+            )
+        } else {
+            return ""
+        }
+    }
+
+    override render(): React.ReactElement {
+        return (
+            <>
+                <div className="config-subtitle">{this.subtitle}</div>
+                <div className="config-list">
+                    {this.strategies.map((value: FacetStrategy) => {
+                        const label = this.facetStrategyLabels[value],
+                            active = value === this.facetStrategy,
+                            option = value.toString()
+
+                        return (
+                            <button
+                                key={option}
+                                className={classnames(option, { active })}
+                                onClick={(): void => {
+                                    this.props.manager.facetStrategy = value
+                                }}
+                                data-track-note={`chart_facet_${option}`}
+                            >
+                                <div className="faceting-icon">
+                                    {_.range(value === "none" ? 1 : 6).map(
+                                        (i) => (
+                                            <span key={i}></span>
+                                        )
+                                    )}
+                                </div>
+                                {label}
+                            </button>
+                        )
+                    })}
+                </div>
+            </>
+        )
+    }
+
+    @computed get facetStrategy(): FacetStrategy {
+        return this.props.manager.facetStrategy || FacetStrategy.none
+    }
+}

package/src/grapher/controls/settings/FacetYDomainToggle.tsx

@@ -0,0 +1,51 @@
+import * as React from "react"
+import { computed, action, makeObservable } from "mobx"
+import { observer } from "mobx-react"
+import { FacetAxisDomain, FacetStrategy } from "../../../types/index.js"
+import { AxisConfig } from "../../axis/AxisConfig"
+import { LabeledSwitch } from "../../../components/index.js"
+
+export interface FacetYDomainToggleManager {
+    facetStrategy?: FacetStrategy
+    yAxis?: AxisConfig
+}
+
+@observer
+export class FacetYDomainToggle extends React.Component<{
+    manager: FacetYDomainToggleManager
+}> {
+    constructor(props: { manager: FacetYDomainToggleManager }) {
+        super(props)
+        makeObservable(this)
+    }
+
+    @action.bound onToggle(): void {
+        const { yAxis } = this.props.manager
+        if (yAxis) {
+            yAxis.facetDomain = this.isYDomainShared
+                ? FacetAxisDomain.independent
+                : FacetAxisDomain.shared
+        }
+    }
+
+    @computed get isYDomainShared(): boolean {
+        const { yAxis } = this.props.manager
+        const facetDomain = yAxis?.facetDomain || FacetAxisDomain.shared
+        return facetDomain === FacetAxisDomain.shared
+    }
+
+    override render(): React.ReactElement | null {
+        const { yAxis, facetStrategy } = this.props.manager
+        if (!yAxis || facetStrategy === "none") return null
+
+        return (
+            <LabeledSwitch
+                label="Align axis scales"
+                tooltip="Use the same minimum and maximum values on all charts or scale axes to fit the data in each chart"
+                value={this.isYDomainShared}
+                onToggle={this.onToggle}
+                tracking="chart_facet_ydomain_toggle"
+            />
+        )
+    }
+}

package/src/grapher/controls/settings/NoDataAreaToggle.tsx

@@ -0,0 +1,38 @@
+import * as React from "react"
+import { computed, action, makeObservable } from "mobx"
+import { observer } from "mobx-react"
+import { LabeledSwitch } from "../../../components/index.js"
+
+export interface NoDataAreaToggleManager {
+    showNoDataArea?: boolean
+}
+
+@observer
+export class NoDataAreaToggle extends React.Component<{
+    manager: NoDataAreaToggleManager
+}> {
+    constructor(props: { manager: NoDataAreaToggleManager }) {
+        super(props)
+        makeObservable(this)
+    }
+
+    @action.bound onToggle(): void {
+        this.manager.showNoDataArea = !this.manager.showNoDataArea
+    }
+
+    @computed get manager(): NoDataAreaToggleManager {
+        return this.props.manager
+    }
+
+    override render(): React.ReactElement {
+        return (
+            <LabeledSwitch
+                label={"Show \u2018no data\u2019 area"}
+                value={this.manager.showNoDataArea}
+                tooltip="Include entities for which ‘no data’ is available in the chart."
+                onToggle={this.onToggle}
+                tracking="chart_no_data_area_toggle"
+            />
+        )
+    }
+}

package/src/grapher/controls/settings/ZoomToggle.tsx

@@ -0,0 +1,36 @@
+import * as React from "react"
+import { action, makeObservable } from "mobx"
+import { observer } from "mobx-react"
+import { LabeledSwitch } from "../../../components/index.js"
+
+export interface ZoomToggleManager {
+    zoomToSelection?: boolean
+}
+
+@observer
+export class ZoomToggle extends React.Component<{
+    manager: ZoomToggleManager
+}> {
+    constructor(props: { manager: ZoomToggleManager }) {
+        super(props)
+        makeObservable(this)
+    }
+
+    @action.bound onToggle(): void {
+        this.props.manager.zoomToSelection = this.props.manager.zoomToSelection
+            ? undefined
+            : true
+    }
+
+    override render(): React.ReactElement {
+        return (
+            <LabeledSwitch
+                label="Zoom to selection"
+                tooltip="Scale axes to focus on the currently highlighted data points."
+                value={this.props.manager.zoomToSelection}
+                onToggle={this.onToggle}
+                tracking="chart_zoom_to_selection"
+            />
+        )
+    }
+}

package/src/grapher/core/EntitiesByRegionType.ts

@@ -0,0 +1,174 @@
+import * as _ from "lodash-es"
+import { EntityName } from "../../types/index.js"
+import {
+    AggregateSource,
+    aggregateSources,
+    Country,
+    excludeUndefined,
+    getRegionByName,
+} from "../../utils/index.js"
+import { CUSTOM_REGION_SOURCE_IDS, isWorldEntityName } from "./GrapherConstants"
+import * as R from "remeda"
+
+const customAggregateSources = CUSTOM_REGION_SOURCE_IDS
+type CustomAggregateSource = (typeof customAggregateSources)[number]
+
+const entityRegionTypes = [
+    "countries",
+    "continents", // owid continents
+    "incomeGroups",
+    "historicalCountries", // e.g. USSR, Austria-Hungary
+    ...aggregateSources,
+    ...customAggregateSources,
+] as const
+export type EntityRegionType = (typeof entityRegionTypes)[number]
+
+export interface EntityRegionTypeGroup {
+    regionType: EntityRegionType
+    entityNames: EntityName[]
+}
+
+export type EntityNamesByRegionType = Map<EntityRegionType, EntityName[]>
+
+export const entityRegionTypeLabels: Record<EntityRegionType, string> = {
+    countries: "Countries",
+    continents: "Continents", // OWID-defined continents
+    incomeGroups: "Income groups",
+    historicalCountries: "Historical countries and regions", // e.g. USSR, Austria-Hungary
+
+    // Regions defined by an institution, and where we have region definition about what constitutes these regions in regions.json
+    who: "World Health Organization regions",
+    wb: "World Bank regions",
+    un: "United Nations regions",
+    unsdg: "UN Sustainable Development Goals regions",
+    unm49: "United Nations M49 regions",
+    pew: "Pew Research Center regions",
+
+    // Regions defined by an institution, but we don't have region definitions in regions.json for these (we recognize them by their suffix)
+    unsd: "UN Statistics Division regions",
+    fao: "FAO regions", // UN's Food and Agriculture Organization
+    ei: "Education International regions",
+    pip: "PIP regions", // World Bank’s Poverty and Inequality Platform
+    ember: "Ember regions",
+    gcp: "Global Carbon Project regions",
+    niaid: "NIAID regions", // National Institute of Allergy and Infectious Diseases
+    unicef: "UNICEF regions",
+    unaids: "UNAIDS regions", // Joint United Nations Programme on HIV and AIDS
+    undp: "UN Development Programme regions",
+    wid: "World Inequality Database regions",
+    oecd: "OECD regions", // Organisation for Economic Co-operation and Development
+}
+
+export function groupEntityNamesByRegionType(
+    entityNames: EntityName[]
+): EntityRegionTypeGroup[] {
+    // the 'World' entity shouldn't show up in any of the groups
+    const availableEntityNames = entityNames.filter(
+        (entityName) => !isWorldEntityName(entityName)
+    )
+
+    // map entities to their regions
+    const availableRegions = excludeUndefined(
+        availableEntityNames.map((entityName) => getRegionByName(entityName))
+    )
+
+    // group regions by type
+    const regionsGroupedByType = _.groupBy(
+        availableRegions,
+        (r) => r.regionType
+    )
+
+    const entitiesByType: EntityRegionTypeGroup[] = []
+
+    // split countries into historical and non-historical
+    const [historicalCountries, nonHistoricalCountries] = R.partition(
+        regionsGroupedByType.country ?? [],
+        (country) => !!(country as Country).isHistorical
+    )
+
+    // add the 'countries' group
+    if (nonHistoricalCountries.length > 0) {
+        entitiesByType.push({
+            regionType: "countries",
+            entityNames: nonHistoricalCountries.map((region) => region.name),
+        })
+    }
+
+    // add the 'continents' group
+    if (regionsGroupedByType.continent) {
+        entitiesByType.push({
+            regionType: "continents",
+            entityNames: regionsGroupedByType.continent.map(
+                (region) => region.name
+            ),
+        })
+    }
+
+    // add the 'incomeGroups' group
+    if (regionsGroupedByType.income_group) {
+        // match by name instead of relying on the regions file because
+        // some charts have income groups that aren't listed in the regions
+        // file, e.g. 'Lower-middle-income countries'
+        const incomeGroups = availableEntityNames.filter(
+            (entityName) =>
+                entityName.includes("income countries") ||
+                // matches 'No income group available', for example
+                entityName.includes("income group")
+        )
+
+        entitiesByType.push({
+            regionType: "incomeGroups",
+            entityNames: incomeGroups,
+        })
+    }
+
+    const entitiesBySource = new Map<
+        AggregateSource | CustomAggregateSource,
+        EntityName[]
+    >()
+    for (const entityName of availableEntityNames) {
+        // The regions file includes a definedBy field for aggregates,
+        // which could be used here. However, non-OWID regions aren't
+        // standardized, meaning we might miss some entities.
+        // Instead, we rely on the convention that non-OWID regions
+        // are suffixed with (source) and check the entity name.
+        const match = entityName.match(/\(([^)]+)\)$/)
+        const sourceCandidate = match?.[1].toLowerCase().replaceAll(" ", "")
+        if (sourceCandidate && isAggregateSource(sourceCandidate)) {
+            if (!entitiesBySource.get(sourceCandidate))
+                entitiesBySource.set(sourceCandidate, [])
+            entitiesBySource.get(sourceCandidate)!.push(entityName)
+        }
+    }
+
+    for (const [source, entityNames] of entitiesBySource) {
+        entitiesByType.push({ regionType: source, entityNames })
+    }
+
+    // add a group for historical countries
+    if (historicalCountries.length > 0) {
+        entitiesByType.push({
+            regionType: "historicalCountries",
+            entityNames: historicalCountries.map((region) => region.name),
+        })
+    }
+
+    return entitiesByType
+}
+
+const aggregateSourceSet = new Set([
+    ...aggregateSources,
+    ...customAggregateSources,
+])
+
+export function isAggregateSource(
+    candidate: string
+): candidate is AggregateSource | CustomAggregateSource {
+    return aggregateSourceSet.has(candidate as any)
+}
+
+export function isEntityRegionType(
+    candidate: string
+): candidate is EntityRegionType {
+    return entityRegionTypes.includes(candidate as any)
+}

package/src/grapher/core/EntityCodes.ts

@@ -0,0 +1,19 @@
+import { lazy, regions } from "../../utils/index.js"
+import { EntityName } from "../../types/index.js"
+import * as R from "remeda"
+
+const getEntityCodesToEntityNames: () => Record<string, string> = lazy(() =>
+    Object.fromEntries(regions.map(({ code, name }) => [code, name]))
+)
+
+const getEntityNamesToEntityCodes = lazy(() =>
+    R.invert(getEntityCodesToEntityNames())
+)
+
+export const codeToEntityName = (codeOrEntityName: string): EntityName => {
+    return getEntityCodesToEntityNames()[codeOrEntityName] ?? codeOrEntityName
+}
+
+export const entityNameToCode = (entityName: EntityName): string => {
+    return getEntityNamesToEntityCodes()[entityName] ?? entityName
+}

package/src/grapher/core/EntityUrlBuilder.ts

@@ -0,0 +1,200 @@
+import { EntityName, SeriesName } from "../../types/index.js"
+import { Url, performUrlMigrations, UrlMigration } from "../../utils/index.js"
+import { codeToEntityName, entityNameToCode } from "./EntityCodes"
+
+/*
+ * Migration #1: Switch from + to ~ delimited entities.
+ *
+ * Implemented: May 2020
+ *
+ * See PR discussion on how we decided on ~ (tilde): https://github.com/owid/owid-grapher/pull/446
+ * And the initial issue (Facebook rewriting our URLs): https://github.com/owid/owid-grapher/issues/397
+ *
+ * In short:
+ *
+ * Facebook replaces `%20` in URLs with `+`. Before this migration we encoded
+ * ["North America", "South America"] → "North%20America+South%20America".
+ * Facebook would turn this into "North+America+South+America" making the delimiters and spaces
+ * ambiguous.
+ *
+ * We chose ~ (tilde) because no entities existed in the database that contain that symbol, so the
+ * existence of that symbol could be used to detect legacy URLs.
+ *
+ */
+
+// Todo: ensure EntityName never contains the v2Delimiter
+
+const V1_DELIMITER = "+"
+export const ENTITY_V2_DELIMITER = "~"
+
+const isV1Param = (encodedQueryParam: string): boolean => {
+    // No legacy entities have a v2Delimiter in their name,
+    // so if a v2Delimiter is present we know it's a v2 link.
+    return !decodeURIComponent(encodedQueryParam).includes(ENTITY_V2_DELIMITER)
+}
+
+const entityNamesFromV1EncodedParam = (
+    encodedQueryParam: string
+): EntityName[] => {
+    // need to use still-encoded URL params because we need to
+    // distinguish between `+` and `%20` in legacy URLs
+    return encodedQueryParam.split(V1_DELIMITER).map(decodeURIComponent)
+}
+
+const entityNamesToV2Param = (entityNames: EntityName[]): string => {
+    // Always include a v2Delimiter in a v2 link. When decoding we will drop any empty strings.
+    if (entityNames.length === 1) return ENTITY_V2_DELIMITER + entityNames[0]
+    return entityNames.join(ENTITY_V2_DELIMITER)
+}
+
+const entityNamesFromV2Param = (queryParam: string): EntityName[] => {
+    // Facebook turns %20 into +. v2 links will never contain a +, so we can safely replace all of them with %20.
+    return queryParam.split(ENTITY_V2_DELIMITER).filter((item) => item)
+}
+
+const migrateV1Delimited: UrlMigration = (url) => {
+    const { country } = url.encodedQueryParams
+
+    if (country !== undefined && isV1Param(country)) {
+        return url.updateQueryParams({
+            country: entityNamesToV2Param(
+                entityNamesFromV1EncodedParam(country)
+            ),
+        })
+    }
+    return url
+}
+
+/*
+ * Migration #2: Drop dimension keys from selected entities.
+ *
+ * Implemented: March 2021
+ *
+ * When plotting multiple variables on a chart, it used to be possible to pick which
+ * variable-entity pairs get plotted.
+ *
+ * For example, if you had a line chart with 3 variables: Energy consumption from Coal, Oil and Gas,
+ * then you (as a user) could select individual variable-entity pairs to plot:
+ *
+ * - France - Coal ("FRA-0")
+ * - France - Oil ("FRA-1")
+ * - France - Gas ("FRA-2")
+ * - ...
+ *
+ * The index of the dimension was appended to the entity (e.g. 0 for Coal).
+ *
+ * We dropped this feature in March 2021 in order to simplify the selection-handling logic, and it
+ * was also, in most cases, not desirable to present users with variable-entity options.
+ *
+ */
+
+// Pattern for a entity name - number pair, where the entity name contains at least one non-digit character.
+const LegacyDimensionRegex = /^(.*\D.*)-\d+$/
+
+const injectEntityNamesInLegacyDimension = (
+    entityNames: EntityName[]
+): EntityName[] => {
+    // If an entity has the old name-dimension encoding, removing the dimension part and add it as
+    // a new selection. So USA-1 becomes USA.
+    const newNames: EntityName[] = []
+    entityNames.forEach((entityName) => {
+        newNames.push(entityName)
+        if (LegacyDimensionRegex.test(entityName)) {
+            const nonDimensionName = entityName.replace(
+                LegacyDimensionRegex,
+                "$1"
+            )
+            newNames.push(nonDimensionName)
+        }
+    })
+    return newNames
+}
+
+const migrateLegacyDimensionPairs: UrlMigration = (url) => {
+    const { country } = url.queryParams
+    if (country) {
+        return url.updateQueryParams({
+            country: entityNamesToV2Param(
+                injectEntityNamesInLegacyDimension(
+                    entityNamesFromV2Param(country)
+                )
+            ),
+        })
+    }
+    return url
+}
+
+/*
+ * Combining all migrations
+ */
+
+const urlMigrations: UrlMigration[] = [
+    migrateV1Delimited,
+    migrateLegacyDimensionPairs,
+]
+
+export const migrateSelectedEntityNamesParam: UrlMigration = (
+    url: Url
+): Url => {
+    return performUrlMigrations(urlMigrations, url)
+}
+
+/*
+ * Accessors
+ */
+
+export const getEntityNamesParam = (
+    param: string | undefined
+): EntityName[] | undefined => {
+    if (param === undefined) return undefined
+    return entityNamesFromV2Param(param).map(codeToEntityName)
+}
+
+export const getSelectedEntityNamesParam = (
+    url: Url
+): EntityName[] | undefined => {
+    // Expects an already-migrated URL as input
+    const { country } = url.queryParams
+    return getEntityNamesParam(country)
+}
+
+export const generateSelectedEntityNamesParam = (
+    entityNames: EntityName[]
+): string => entityNamesToV2Param(entityNames.map(entityNameToCode))
+
+export const setSelectedEntityNamesParam = (
+    url: Url,
+    entityNames: EntityName[] | undefined
+): Url => {
+    // Expects an already-migrated URL as input
+    return url.updateQueryParams({
+        country: entityNames
+            ? generateSelectedEntityNamesParam(entityNames)
+            : undefined,
+    })
+}
+
+/*
+ * Focused series names
+ *
+ * A focused series name is one of:
+ * (i) an entity name (common case)
+ * (ii) an indicator name (less common, but not rare)
+ * (iii) a combination of both, typically represented as 'entityName – indicatorName' (rare)
+ *
+ * Parsing and serializing focused series names for the URL is done using utility
+ * functions that have originally been written for entity names, so that the same
+ * delimiter is used and entity names are mapped to their codes if possible. Note
+ * that stand-alone entity names are mapped to their codes (case i), while entity
+ * names that are a substring of a series name are not (case iii).
+ */
+
+export const getFocusedSeriesNamesParam = (
+    queryParam: string | undefined
+): SeriesName[] | undefined => {
+    return getEntityNamesParam(queryParam)
+}
+
+export const generateFocusedSeriesNamesParam = (
+    seriesNames: SeriesName[]
+): string => entityNamesToV2Param(seriesNames.map(entityNameToCode))