@buildcanada/charts 0.1.0

package/src/grapher/facet/FacetChartConstants.ts

@@ -0,0 +1,24 @@
+import { ChartSeries } from "../chart/ChartInterface"
+import { ChartManager } from "../chart/ChartManager"
+import { GrapherChartType } from "../../types/index.js"
+import { Bounds } from "../../utils/index.js"
+
+export interface FacetChartManager extends ChartManager {
+    canSelectMultipleEntities?: boolean
+}
+
+export interface FacetChartProps {
+    bounds?: Bounds
+    chartTypeName?: GrapherChartType
+    manager: FacetChartManager
+}
+
+export interface FacetSeries extends ChartSeries {
+    manager: Partial<ChartManager>
+}
+
+export interface PlacedFacetSeries extends FacetSeries {
+    manager: ChartManager
+    bounds: Bounds
+    contentBounds: Bounds
+}

package/src/grapher/facet/FacetChartUtils.ts

@@ -0,0 +1,51 @@
+import { BASE_FONT_SIZE, GRAPHER_FONT_SCALE_10 } from "../core/GrapherConstants"
+
+// not sure if we want to do something more sophisticated
+export const getFontSize = (
+    containerWidth: number,
+    count: number,
+    baseFontSize = BASE_FONT_SIZE,
+    minSize = 8
+): number => {
+    // Pick a fixed font size for very small charts
+    if (containerWidth < 300) return GRAPHER_FONT_SCALE_10 * baseFontSize
+
+    // Scale the font size based on the number of series otherwise
+    if (count <= 2) return Math.max(minSize, baseFontSize * (15 / 16))
+    if (count <= 4) return Math.max(minSize, baseFontSize * (14 / 16))
+    if (count <= 9) return Math.max(minSize, baseFontSize * (13 / 16))
+    if (count <= 16) return Math.max(minSize, baseFontSize * (12 / 16))
+    if (count <= 25) return Math.max(minSize, baseFontSize * (11 / 16))
+    return minSize
+}
+
+export const getLabelPadding = (baseFontSize: number): number =>
+    0.5 * baseFontSize
+
+export const getFacetGridPadding = ({
+    baseFontSize,
+    shouldAddRowPadding = true,
+    shouldAddColumnPadding = true,
+}: {
+    baseFontSize: number
+    shouldAddRowPadding?: boolean
+    shouldAddColumnPadding?: boolean
+}): { rowPadding: number; columnPadding: number; outerPadding: number } => {
+    const labelHeight = baseFontSize
+    const labelPadding = getLabelPadding(baseFontSize)
+
+    const rowPadding = shouldAddRowPadding ? baseFontSize : 0
+    const columnPadding = shouldAddColumnPadding ? baseFontSize : 0
+
+    return {
+        rowPadding: Math.round(labelHeight + labelPadding + rowPadding),
+        columnPadding: Math.round(columnPadding),
+        outerPadding: 0,
+    }
+}
+
+export const calculateAspectRatio = (width: number, height: number): number => {
+    const aspectRatio = width / height // can be NaN if height is 0, which can happen when the chart is temporarily hidden
+    if (isNaN(aspectRatio)) return 1
+    return aspectRatio
+}

package/src/grapher/facet/FacetMap.tsx

@@ -0,0 +1,604 @@
+import React from "react"
+import { observer } from "mobx-react"
+import {
+    Bounds,
+    GridParameters,
+    HorizontalAlign,
+    Color,
+    makeIdForHumanConsumption,
+    exposeInstanceOnWindow,
+    SplitBoundsPadding,
+} from "../../utils/index.js"
+import { action, computed, makeObservable, observable } from "mobx"
+import {
+    BASE_FONT_SIZE,
+    DEFAULT_GRAPHER_BOUNDS,
+    GRAPHER_FONT_SCALE_18,
+} from "../core/GrapherConstants"
+import {
+    ChartErrorInfo,
+    GRAPHER_MAP_TYPE,
+    GrapherInteractionEvent,
+    MapRegionName,
+    Time,
+} from "../../types/index.js"
+import {
+    calculateAspectRatio,
+    getFacetGridPadding,
+    getLabelPadding as getFacetLabelPadding,
+} from "./FacetChartUtils"
+import {
+    FacetMapManager,
+    MapFacetSeries,
+    FacetMapProps,
+    PlacedMapFacetSeries,
+} from "./FacetMapConstants"
+import { OwidTable } from "../../core-table/index.js"
+import {
+    HorizontalCategoricalColorLegend,
+    HorizontalColorLegendManager,
+    HorizontalNumericColorLegend,
+} from "../legend/HorizontalColorLegends"
+import { CategoricalBin, ColorScaleBin } from "../color/ColorScaleBin"
+import { GRAPHER_DARK_TEXT, GRAY_30 } from "../color/ColorConstants"
+import {
+    LegendInteractionState,
+    LegendStyleConfig,
+} from "../legend/LegendInteractionState"
+import {
+    MAP_LEGEND_MAX_WIDTH_RATIO,
+    MapChart,
+    PADDING_BELOW_MAP_LEGEND,
+    PADDING_BETWEEN_MAP_AND_LEGEND,
+    PADDING_BETWEEN_MAP_LEGENDS,
+} from "../mapCharts/MapChart"
+import { ChartComponent, makeChartInstance } from "../chart/ChartTypeMap"
+import {
+    MAP_VIEWPORT_FACETED_WORLD,
+    MAP_VIEWPORTS,
+    MapChartManager,
+    MapViewport,
+} from "../mapCharts/MapChartConstants"
+import { ChartState } from "../chart/ChartInterface.js"
+import { MapConfig } from "../mapCharts/MapConfig"
+
+@observer
+export class FacetMap
+    extends React.Component<FacetMapProps>
+    implements ChartState, HorizontalColorLegendManager
+{
+    private legendHoverBin: ColorScaleBin | undefined = undefined
+
+    constructor(props: FacetMapProps) {
+        super(props)
+        makeObservable<FacetMap, "legendHoverBin">(this, {
+            legendHoverBin: observable.ref,
+        })
+    }
+
+    transformTable(table: OwidTable): OwidTable {
+        return table
+    }
+
+    @computed get inputTable(): OwidTable {
+        return this.manager.table
+    }
+
+    @computed get transformedTable(): OwidTable {
+        return (
+            this.manager.transformedTable ??
+            this.transformTable(this.inputTable)
+        )
+    }
+
+    @computed private get manager(): FacetMapManager {
+        return this.props.manager
+    }
+
+    @computed private get table(): OwidTable {
+        return this.manager.table
+    }
+
+    @computed private get transformedTableFromGrapher(): OwidTable | undefined {
+        return this.manager.transformedTable
+    }
+
+    @computed get isStatic(): boolean {
+        return !!this.manager.isStatic
+    }
+
+    @computed get errorInfo(): ChartErrorInfo {
+        if (this.manager.startTime === undefined)
+            return { reason: "No start time selected" }
+
+        if (this.manager.endTime === undefined)
+            return { reason: "No end time selected" }
+
+        return { reason: "" }
+    }
+
+    @computed private get startTime(): Time {
+        return this.manager.startTime!
+    }
+
+    @computed private get endTime(): Time {
+        return this.manager.endTime!
+    }
+
+    @computed private get bounds(): Bounds {
+        const bounds = this.props.bounds ?? DEFAULT_GRAPHER_BOUNDS
+        return bounds.padTop(6)
+    }
+
+    @computed private get facetsContainerBounds(): Bounds {
+        return (
+            this.bounds
+                // Make space for facet labels
+                .padTop(this.labelHeight + this.labelPadding)
+                // Make space for the legend
+                .padBottom(
+                    this.legendHeight +
+                        PADDING_BETWEEN_MAP_AND_LEGEND +
+                        PADDING_BELOW_MAP_LEGEND
+                )
+        )
+    }
+
+    @computed private get targetTimes(): [Time, Time] {
+        return [this.startTime, this.endTime]
+    }
+
+    @computed get fontSize(): number {
+        return this.manager.fontSize ?? BASE_FONT_SIZE
+    }
+
+    @computed private get facetFontSize(): number {
+        return Math.floor(this.fontSize * GRAPHER_FONT_SCALE_18)
+    }
+
+    @computed private get mapConfig(): MapConfig {
+        return this.manager.mapConfig ?? new MapConfig()
+    }
+
+    @computed private get mapViewport(): MapViewport {
+        const { region } = this.mapConfig
+
+        // Use a custom viewport for the World map that zooms in a little bit to make best use of the space
+        if (region === MapRegionName.World) return MAP_VIEWPORT_FACETED_WORLD
+
+        return MAP_VIEWPORTS[region]
+    }
+
+    private getGridParams(bounds: Bounds): GridParameters {
+        // We determine the preferred layout (horizontal vs vertical)
+        // by comparing which orientation produces an aspect ratio closest to
+        // the map's natural aspect ratio. The globe uses the horizontal layout.
+
+        const horizontalLayout = { rows: 1, columns: 2, count: 2 }
+        const verticalLayout = { rows: 2, columns: 1, count: 2 }
+
+        if (this.mapConfig.globe.isActive)
+            return bounds.width > bounds.height
+                ? horizontalLayout
+                : verticalLayout
+
+        const mapAspectRatio = this.mapViewport.ratio
+
+        // If the faceted maps are side-by-side
+        const horizontalLayoutAspectRatio = calculateAspectRatio(
+            bounds.width / 2,
+            bounds.height
+        )
+
+        // If the faceted maps are stacked vertically
+        const verticalLayoutAspectRatio = calculateAspectRatio(
+            bounds.width,
+            bounds.height / 2
+        )
+
+        const horizontalDiff = Math.abs(
+            Math.log2(mapAspectRatio / horizontalLayoutAspectRatio)
+        )
+        const verticalDiff = Math.abs(
+            Math.log2(mapAspectRatio / verticalLayoutAspectRatio)
+        )
+
+        // World maps tend to look better side-by-side, so we give the
+        // horizontal layout an advantage when the region is World
+        const bias = this.mapConfig.region === MapRegionName.World ? 0.5 : 0
+
+        return horizontalDiff - bias <= verticalDiff
+            ? horizontalLayout
+            : verticalLayout
+    }
+
+    @computed private get facetGridPadding(): SplitBoundsPadding {
+        return getFacetGridPadding({
+            baseFontSize: this.facetFontSize,
+            shouldAddRowPadding: false,
+        })
+    }
+
+    @computed private get labelHeight(): number {
+        return this.facetFontSize
+    }
+
+    @computed private get labelPadding(): number {
+        return getFacetLabelPadding(this.facetFontSize)
+    }
+
+    @computed get series(): MapFacetSeries[] {
+        return this.targetTimes.map((time) => ({
+            seriesName: this.table.timeColumn.formatTime(time),
+            // Required for a ChartSeries, but isn't meaningful for facets
+            color: "none",
+            // Only set overrides for this facet. Default properties are set elsewhere.
+            manager: { targetTime: time },
+        }))
+    }
+
+    @action.bound logGrapherInteractionEvent(
+        action: GrapherInteractionEvent,
+        target?: string
+    ): void {
+        this.manager.analytics?.logGrapherInteractionEvent(action, {
+            ...this.manager.analyticsContext,
+            target,
+        })
+    }
+
+    @computed private get intermediatePlacedSeries(): PlacedMapFacetSeries[] {
+        const {
+            manager,
+            series,
+            table,
+            transformedTableFromGrapher,
+            targetTimes,
+            mapViewport,
+            facetFontSize,
+            legendHoverBin,
+            logGrapherInteractionEvent,
+        } = this
+
+        // We are using `bounds` instead of `facetsContainerBounds` because the legend
+        // is not yet created, and it is derived from the intermediate chart series.
+        const bounds = this.bounds
+        const gridBoundsArr = bounds.grid(
+            this.getGridParams(bounds),
+            this.facetGridPadding
+        )
+
+        const {
+            backgroundColor,
+            isStatic,
+            mapColumnSlug = "",
+            mapConfig,
+            isMapSelectionEnabled,
+            colorScale,
+            globeController,
+            base,
+            tooltip,
+            shouldPinTooltipToBottom,
+            projectionColumnInfoBySlug,
+            isFaceted,
+            yColumnSlug,
+        } = manager
+
+        return series.map((series, index) => {
+            const { bounds } = gridBoundsArr[index]
+
+            const manager: MapChartManager = {
+                table,
+                transformedTable: transformedTableFromGrapher,
+                fontSize: facetFontSize,
+                showLegend: false,
+                backgroundColor,
+                isStatic,
+                mapColumnSlug,
+                mapConfig,
+                isMapSelectionEnabled,
+                colorScale,
+                globeController,
+                base,
+                tooltip,
+                shouldPinTooltipToBottom,
+                externalLegendHoverBin: legendHoverBin,
+                logGrapherInteractionEvent,
+                disableIntroAnimation: true,
+                projectionColumnInfoBySlug,
+                highlightedTimesInTooltip: targetTimes,
+                mapViewport,
+                isFaceted,
+                yColumnSlug,
+                ...series.manager,
+            }
+
+            return {
+                bounds,
+                manager,
+                seriesName: series.seriesName,
+                color: series.color,
+            }
+        })
+    }
+
+    @computed private get intermediateMapInstances(): MapChart[] {
+        return this.intermediatePlacedSeries.map(
+            ({ bounds, manager }) =>
+                makeChartInstance({
+                    manager,
+                    bounds,
+                    chartType: GRAPHER_MAP_TYPE,
+                    variant: this.manager.variant,
+                }) as MapChart
+        )
+    }
+
+    /**
+     * Used to construct the shared legend for all map facets.
+     *
+     * Unlike in FacetChart, we only need a single MapChart instance to construct
+     * the legend since all facets share the same legend.
+     */
+    @computed get intermediateMapInstance(): MapChart {
+        return this.intermediateMapInstances[0]
+    }
+
+    @computed private get gridParams(): GridParameters {
+        return this.getGridParams(this.facetsContainerBounds)
+    }
+
+    @computed private get facetArrangement(): "side-by-side" | "stacked" {
+        return this.gridParams.rows > this.gridParams.columns
+            ? "stacked"
+            : "side-by-side"
+    }
+
+    @computed get placedSeries(): PlacedMapFacetSeries[] {
+        const bounds = this.facetsContainerBounds
+        const gridBoundsArr = bounds.grid(
+            this.gridParams,
+            this.facetGridPadding
+        )
+        return this.intermediatePlacedSeries.map((series, i) => {
+            const { bounds } = gridBoundsArr[i]
+            return { ...series, bounds }
+        })
+    }
+
+    @computed private get externalLegend():
+        | HorizontalColorLegendManager
+        | undefined {
+        return this.intermediateMapInstance.externalLegend
+    }
+
+    @computed get legendX(): number {
+        return this.bounds.x
+    }
+
+    @computed get numericLegendY(): number {
+        if (!this.numericLegend) return 0
+        return (
+            this.bounds.bottom -
+            this.numericLegendHeight -
+            PADDING_BELOW_MAP_LEGEND -
+            // If present, the category legend is placed below the numeric legend
+            (this.categoryLegend
+                ? this.categoryLegendHeight + PADDING_BETWEEN_MAP_LEGENDS
+                : 0)
+        )
+    }
+
+    @computed get categoryLegendY(): number {
+        if (!this.categoryLegend) return 0
+        return (
+            this.bounds.bottom -
+            this.categoryLegend.height -
+            PADDING_BELOW_MAP_LEGEND
+        )
+    }
+
+    @computed get legendMaxWidth(): number {
+        return this.bounds.width * MAP_LEGEND_MAX_WIDTH_RATIO
+    }
+
+    @computed get legendAlign(): HorizontalAlign {
+        return HorizontalAlign.center
+    }
+
+    @computed get hoverColors(): Color[] | undefined {
+        if (!this.legendHoverBin) return undefined
+        return [this.legendHoverBin.color]
+    }
+
+    @computed get numericLegendData(): ColorScaleBin[] {
+        return this.externalLegend?.numericLegendData ?? []
+    }
+
+    @computed get categoricalLegendData(): CategoricalBin[] {
+        return this.externalLegend?.categoricalLegendData ?? []
+    }
+
+    @computed private get numericLegendHeight(): number {
+        return this.numericLegend ? this.numericLegend.height : 0
+    }
+
+    @computed private get categoryLegendHeight(): number {
+        return this.categoryLegend ? this.categoryLegend.height : 0
+    }
+
+    @computed get legendHeight(): number {
+        return this.categoryLegendHeight + this.numericLegendHeight
+    }
+
+    @action.bound onLegendMouseOver(bin: ColorScaleBin): void {
+        this.legendHoverBin = bin
+    }
+
+    @action.bound onLegendMouseLeave(): void {
+        this.legendHoverBin = undefined
+    }
+
+    @computed private get categoryLegend():
+        | HorizontalCategoricalColorLegend
+        | undefined {
+        return this.categoricalLegendData.length > 1
+            ? new HorizontalCategoricalColorLegend({ manager: this })
+            : undefined
+    }
+
+    @computed private get numericLegend():
+        | HorizontalNumericColorLegend
+        | undefined {
+        return this.numericLegendData.length > 1
+            ? new HorizontalNumericColorLegend({ manager: this })
+            : undefined
+    }
+
+    getLegendBinState(bin: ColorScaleBin): LegendInteractionState {
+        if (!this.legendHoverBin && !this.mapConfig.hoverCountry) {
+            return LegendInteractionState.Default
+        }
+
+        // Check if this bin is being hovered
+        if (this.legendHoverBin && bin.equals(this.legendHoverBin)) {
+            return LegendInteractionState.Focused
+        }
+
+        // Check if a country is being hovered and matches this bin
+        if (this.mapConfig.hoverCountry) {
+            const series = this.intermediateMapInstances.map((mapChart) =>
+                mapChart.chartState.series.find(
+                    (s) => s.seriesName === this.mapConfig.hoverCountry
+                )
+            )
+            if (series.some((s) => s?.color === bin.color))
+                return LegendInteractionState.Focused
+        }
+
+        return LegendInteractionState.Muted
+    }
+
+    @computed get legendStyleConfig(): LegendStyleConfig | undefined {
+        return this.externalLegend?.legendStyleConfig
+    }
+
+    override componentDidMount(): void {
+        exposeInstanceOnWindow(this, "facetMap")
+    }
+
+    private getLabelPosition(facet: PlacedMapFacetSeries): {
+        x: number
+        y: number
+    } {
+        const { mapConfig, labelPadding } = this
+        const { bounds } = facet
+
+        const labelX = bounds.centerX
+        let labelY = bounds.top - labelPadding
+
+        // For the globe and 2D continent views, simply render the label at the top
+        if (
+            mapConfig.globe.isActive ||
+            mapConfig.region !== MapRegionName.World
+        )
+            return { x: labelX, y: labelY }
+
+        // There is often quite a bit of vertical padding around the 2D World map.
+        // It looks nicer to position the facet label closer to the actual map content
+        // rather than at the very top
+
+        const mapAspectRatio = MAP_VIEWPORT_FACETED_WORLD.ratio
+
+        // Find the map's width and height
+        let mapWidth = bounds.width
+        let mapHeight = mapWidth / mapAspectRatio
+        if (mapHeight > bounds.height) {
+            mapHeight = bounds.height
+            mapWidth = mapHeight * mapAspectRatio
+        }
+
+        // Move the label closer to the map if there is vertical padding
+        if (mapHeight < bounds.height) {
+            const shiftY = (bounds.height - mapHeight) / 2
+            labelY = Math.max(labelY, labelY + shiftY - 3 * labelPadding)
+        }
+
+        return { x: labelX, y: labelY }
+    }
+
+    private renderMapLegend(): React.ReactElement {
+        return (
+            <>
+                {this.numericLegend && (
+                    <HorizontalNumericColorLegend manager={this} />
+                )}
+                {this.categoryLegend && (
+                    <HorizontalCategoricalColorLegend manager={this} />
+                )}
+            </>
+        )
+    }
+
+    private renderSeparatorLine(): React.ReactElement | null {
+        const {
+            mapConfig,
+            facetArrangement,
+            facetsContainerBounds: bounds,
+        } = this
+
+        // It can be difficult to visually distinguish two continent maps
+        // when plotted side by side, so we draw a gray line between them
+        if (
+            mapConfig.region !== MapRegionName.World &&
+            facetArrangement === "side-by-side"
+        ) {
+            return (
+                <line
+                    x1={bounds.centerX}
+                    y1={bounds.top}
+                    x2={bounds.centerX}
+                    y2={bounds.bottom}
+                    stroke={GRAY_30}
+                />
+            )
+        }
+
+        return null
+    }
+
+    override render(): React.ReactElement {
+        const { facetFontSize } = this
+        return (
+            <>
+                {this.renderMapLegend()}
+                {this.renderSeparatorLine()}
+                {this.placedSeries.map((series) => {
+                    const { bounds, seriesName } = series
+
+                    return (
+                        <React.Fragment key={seriesName}>
+                            <text
+                                {...this.getLabelPosition(series)}
+                                fill={GRAPHER_DARK_TEXT}
+                                fontSize={facetFontSize}
+                                textAnchor="middle"
+                                style={{ fontWeight: 700 }}
+                            >
+                                {seriesName}
+                            </text>
+                            <g id={makeIdForHumanConsumption(seriesName)}>
+                                <ChartComponent
+                                    manager={series.manager}
+                                    chartType={GRAPHER_MAP_TYPE}
+                                    variant={this.manager.variant}
+                                    bounds={bounds}
+                                />
+                            </g>
+                        </React.Fragment>
+                    )
+                })}
+            </>
+        )
+    }
+}

package/src/grapher/facet/FacetMapConstants.ts

@@ -0,0 +1,23 @@
+import { ChartSeries } from "../chart/ChartInterface"
+import { Bounds, GrapherAnalyticsContext } from "../../utils/index.js"
+import { MapChartManager } from "../mapCharts/MapChartConstants"
+import { GrapherAnalytics } from "../core/GrapherAnalytics"
+
+export interface FacetMapManager extends MapChartManager {
+    analytics?: GrapherAnalytics
+    analyticsContext?: GrapherAnalyticsContext
+}
+
+export interface FacetMapProps {
+    bounds?: Bounds
+    manager: FacetMapManager
+}
+
+export interface MapFacetSeries extends ChartSeries {
+    manager: Partial<MapChartManager>
+}
+
+export interface PlacedMapFacetSeries extends MapFacetSeries {
+    manager: MapChartManager
+    bounds: Bounds
+}