@buildcanada/charts 0.1.0

package/src/grapher/mapCharts/MapComponents.tsx

@@ -0,0 +1,338 @@
+import React from "react"
+import { makeIdForHumanConsumption } from "../../utils/index.js"
+import {
+    BLUR_FILL_OPACITY,
+    BLUR_STROKE_OPACITY,
+    ChoroplethSeries,
+    DEFAULT_STROKE_COLOR,
+    DEFAULT_STROKE_WIDTH,
+    HOVER_STROKE_COLOR,
+    HOVER_STROKE_WIDTH,
+    PATTERN_STROKE_WIDTH,
+    SELECTED_STROKE_WIDTH,
+    SVGMouseEvent,
+    RenderFeature,
+    InternalAnnotation,
+    ExternalAnnotation,
+} from "./MapChartConstants"
+import { isMapRenderFeature } from "./MapHelpers"
+import { getExternalMarkerEndPosition } from "./MapAnnotations"
+import { Patterns } from "../core/GrapherConstants"
+import { calculateLightnessScore, isDarkColor } from "../color/ColorUtils"
+import { Halo } from "../../components/index.js"
+import { InteractionState } from "../interaction/InteractionState"
+
+export function BackgroundCountry<Feature extends RenderFeature>({
+    feature,
+    path,
+    strokeWidth = DEFAULT_STROKE_WIDTH,
+}: {
+    feature: Feature
+    path?: string
+    strokeWidth?: number
+}): React.ReactElement {
+    return (
+        <path
+            id={makeIdForHumanConsumption(feature.id)}
+            d={isMapRenderFeature(feature) ? feature.path : path}
+            strokeWidth={strokeWidth}
+            stroke="#aaa"
+            fill="#fff"
+        />
+    )
+}
+
+export function CountryWithData<Feature extends RenderFeature>({
+    feature,
+    series,
+    path,
+    isSelected = false,
+    hover,
+    strokeScale = 1,
+    onClick,
+    onTouchStart,
+    onMouseEnter,
+    onMouseLeave,
+}: {
+    feature: Feature
+    series: ChoroplethSeries
+    path?: string
+    isSelected?: boolean
+    hover?: InteractionState
+    strokeScale?: number
+    onClick?: (event: SVGMouseEvent) => void
+    onTouchStart?: (event: React.TouchEvent<SVGElement>) => void
+    onMouseEnter?: (feature: Feature, event: MouseEvent) => void
+    onMouseLeave?: () => void
+}): React.ReactElement {
+    const isProjection = series.isProjection
+    const isHovered = hover?.active ?? false
+
+    const stroke =
+        isHovered || isSelected ? HOVER_STROKE_COLOR : DEFAULT_STROKE_COLOR
+    const strokeWidth = getStrokeWidth({ isHovered, isSelected }) / strokeScale
+    const strokeOpacity = hover?.background ? BLUR_STROKE_OPACITY : 1
+
+    const fill = isProjection
+        ? `url(#${makeProjectedDataPatternId(series.color)})`
+        : series.color
+    const fillOpacity = hover?.background ? BLUR_FILL_OPACITY : 1
+
+    return (
+        <path
+            id={makeIdForHumanConsumption(feature.id)}
+            data-feature-id={feature.id}
+            d={isMapRenderFeature(feature) ? feature.path : path}
+            strokeWidth={strokeWidth}
+            stroke={stroke}
+            strokeOpacity={strokeOpacity}
+            cursor="pointer"
+            fill={fill}
+            fillOpacity={fillOpacity}
+            onClick={onClick}
+            onTouchStart={onTouchStart}
+            onMouseEnter={(event): void =>
+                onMouseEnter?.(feature, event.nativeEvent)
+            }
+            onMouseLeave={onMouseLeave}
+        />
+    )
+}
+
+export function CountryWithNoData<Feature extends RenderFeature>({
+    feature,
+    path,
+    patternId,
+    isSelected = false,
+    hover,
+    strokeScale = 1,
+    onClick,
+    onTouchStart,
+    onMouseEnter,
+    onMouseLeave,
+}: {
+    feature: Feature
+    path?: string
+    patternId: string
+    isSelected?: boolean
+    hover?: InteractionState
+    strokeScale?: number
+    onClick?: (event: SVGMouseEvent) => void
+    onTouchStart?: (event: React.TouchEvent<SVGElement>) => void
+    onMouseEnter?: (feature: Feature, event: MouseEvent) => void
+    onMouseLeave?: () => void
+}): React.ReactElement {
+    const isHovered = hover?.active ?? false
+
+    const stroke = isHovered || isSelected ? HOVER_STROKE_COLOR : "#aaa"
+    const strokeWidth = getStrokeWidth({ isHovered, isSelected }) / strokeScale
+    const strokeOpacity = hover?.background ? BLUR_STROKE_OPACITY : 1
+
+    const fillOpacity = hover?.background ? BLUR_FILL_OPACITY : 1
+
+    return (
+        <path
+            id={makeIdForHumanConsumption(feature.id)}
+            data-feature-id={feature.id}
+            d={isMapRenderFeature(feature) ? feature.path : path}
+            strokeWidth={strokeWidth}
+            stroke={stroke}
+            strokeOpacity={strokeOpacity}
+            cursor="pointer"
+            fill={`url(#${patternId})`}
+            fillOpacity={fillOpacity}
+            onClick={onClick}
+            onTouchStart={onTouchStart}
+            onMouseEnter={(event): void =>
+                onMouseEnter?.(feature, event.nativeEvent)
+            }
+            onMouseLeave={onMouseLeave}
+        />
+    )
+}
+
+export function NoDataPattern({
+    patternId,
+    scale = 1,
+}: {
+    patternId: string
+    scale?: number
+}): React.ReactElement {
+    return (
+        <pattern
+            id={patternId}
+            patternUnits="userSpaceOnUse"
+            width="4"
+            height="4"
+            patternTransform={`rotate(-45 2 2) scale(${scale})`}
+        >
+            <path
+                d="M -1,2 l 6,0"
+                stroke="#ccc"
+                strokeWidth={PATTERN_STROKE_WIDTH}
+            />
+        </pattern>
+    )
+}
+
+export function ProjectedDataPattern({
+    color,
+    scale = 1,
+    forLegend = false,
+}: {
+    color: string
+    scale?: number
+    forLegend?: boolean
+}): React.ReactElement {
+    return (
+        <DottedProjectedDataPattern
+            patternId={makeProjectedDataPatternId(color, { forLegend })}
+            color={color}
+            scale={scale}
+            dotOpacity={forLegend ? 0.2 : undefined}
+        />
+    )
+}
+
+function DottedProjectedDataPattern({
+    patternId,
+    color,
+    scale = 1,
+    patternSize = 4,
+    dotSize = patternSize / 4,
+    dotOpacity,
+}: {
+    patternId: string
+    color: string
+    scale?: number
+    patternSize?: number
+    dotSize?: number
+    dotOpacity?: number // inferred from color lightness if not provided
+}): React.ReactElement {
+    // Choose the dot opacity based on the lightness of the color:
+    // - If the color is light, make the dots more transparent
+    // - If the color is dark, make the dots more opaque
+    const lightness = calculateLightnessScore(color) ?? 0
+    const opacity = dotOpacity ?? Math.max(1 - lightness, 0.1)
+
+    return (
+        <pattern
+            id={patternId}
+            patternUnits="userSpaceOnUse"
+            width={patternSize}
+            height={patternSize}
+            patternTransform={`rotate(45) scale(${scale})`}
+        >
+            {/* colored background */}
+            <rect width={patternSize} height={patternSize} fill={color} />
+
+            {/* dots */}
+            <circle
+                cx={patternSize / 2}
+                cy={patternSize / 2}
+                r={dotSize}
+                fill="black"
+                fillOpacity={opacity}
+            />
+        </pattern>
+    )
+}
+
+export function InternalValueAnnotation({
+    annotation,
+    strokeScale = 1,
+    showOutline = false,
+}: {
+    annotation: InternalAnnotation
+    strokeScale?: number
+    showOutline?: boolean
+}): React.ReactElement {
+    const { id, text, color, placedBounds, fontSize } = annotation
+
+    const showHalo = showOutline && isDarkColor(color)
+
+    return (
+        <Halo id={id} outlineWidth={3} show={showHalo}>
+            <text
+                id={makeIdForHumanConsumption(id)}
+                x={placedBounds.topLeft.x}
+                y={placedBounds.topLeft.y + placedBounds.height - 1}
+                fontSize={fontSize}
+                fontWeight={700}
+                fill={color}
+                strokeWidth={DEFAULT_STROKE_WIDTH / strokeScale}
+                style={{ pointerEvents: "none" }}
+            >
+                {text}
+            </text>
+        </Halo>
+    )
+}
+
+export function ExternalValueAnnotation({
+    annotation,
+    strokeScale = 1,
+    onMouseEnter,
+    onMouseLeave,
+}: {
+    annotation: ExternalAnnotation
+    strokeScale?: number
+    onMouseEnter?: (feature: RenderFeature) => void
+    onMouseLeave?: () => void
+}): React.ReactElement {
+    const { id, text, direction, anchor, placedBounds, fontSize } = annotation
+
+    const markerStart = anchor
+    const markerEnd = getExternalMarkerEndPosition({
+        textBounds: placedBounds,
+        direction,
+    })
+
+    return (
+        <g id={makeIdForHumanConsumption(id)}>
+            <line
+                x1={markerStart[0]}
+                y1={markerStart[1]}
+                x2={markerEnd[0]}
+                y2={markerEnd[1]}
+                stroke={annotation.color}
+                strokeWidth={(0.5 * HOVER_STROKE_WIDTH) / strokeScale}
+                style={{ pointerEvents: "none" }}
+            />
+            <text
+                x={placedBounds.x}
+                y={placedBounds.y + placedBounds.height - 1}
+                fontSize={fontSize}
+                strokeWidth={DEFAULT_STROKE_WIDTH / strokeScale}
+                fill={annotation.color}
+                fontWeight={700}
+                onMouseEnter={() => onMouseEnter?.(annotation.feature)}
+                onMouseLeave={onMouseLeave}
+            >
+                {text}
+            </text>
+        </g>
+    )
+}
+
+function getStrokeWidth({
+    isSelected,
+    isHovered,
+}: {
+    isSelected: boolean
+    isHovered: boolean
+}): number {
+    if (isHovered) return HOVER_STROKE_WIDTH
+    if (isSelected) return SELECTED_STROKE_WIDTH
+    return DEFAULT_STROKE_WIDTH
+}
+
+export function makeProjectedDataPatternId(
+    color: string,
+    options?: { forLegend: boolean }
+): string {
+    const prefix = options?.forLegend
+        ? Patterns.projectedDataPatternForLegend
+        : Patterns.projectedDataPattern
+    return `${prefix}_${color}`
+}

package/src/grapher/mapCharts/MapConfig.ts

@@ -0,0 +1,156 @@
+import { observable, makeObservable } from "mobx"
+import {
+    GlobeConfig,
+    MapRegionName,
+    MapConfigInterface,
+    TimeBound,
+    EntityName,
+} from "../../types/index.js"
+import { ColorScaleConfig } from "../color/ColorScaleConfig"
+import {
+    ColumnSlug,
+    Persistable,
+    updatePersistables,
+    objectWithPersistablesToObject,
+    deleteRuntimeAndUnchangedProps,
+    maxTimeBoundFromJSONOrPositiveInfinity,
+    maxTimeToJSON,
+    minTimeToJSON,
+    trimObject,
+    NoUndefinedValues,
+    ToleranceStrategy,
+    minTimeBoundFromJSONOrNegativeInfinity,
+} from "../../utils/index.js"
+import { MapSelectionArray } from "../selection/MapSelectionArray"
+import { DEFAULT_GLOBE_ROTATION, DEFAULT_GLOBE_ZOOM } from "./MapChartConstants"
+import * as R from "remeda"
+
+// MapConfig holds the data and underlying logic needed by MapTab.
+// It wraps the map property on ChartConfig.
+// TODO: migrate database config & only pass legend props
+class MapConfigDefaults {
+    columnSlug: ColumnSlug | undefined = undefined
+    time: TimeBound | undefined = undefined
+    startTime: TimeBound | undefined = undefined
+    timeTolerance: number | undefined = undefined
+    toleranceStrategy: ToleranceStrategy | undefined = undefined
+    hideTimeline: boolean | undefined = undefined
+
+    region = MapRegionName.World
+    selection = new MapSelectionArray()
+    hoverCountry?: EntityName // shared across facets
+
+    globe: GlobeConfig = {
+        isActive: false,
+        rotation: DEFAULT_GLOBE_ROTATION, // specified as [lot, lan]
+        zoom: DEFAULT_GLOBE_ZOOM,
+    }
+
+    colorScale = new ColorScaleConfig()
+    // Show the label from colorSchemeLabels in the tooltip instead of the numeric value
+    tooltipUseCustomLabels: boolean | undefined = undefined
+
+    constructor() {
+        makeObservable(this, {
+            columnSlug: observable,
+            time: observable,
+            startTime: observable,
+            timeTolerance: observable,
+            toleranceStrategy: observable,
+            hideTimeline: observable,
+            region: observable,
+            selection: observable,
+            globe: observable,
+            colorScale: observable,
+            tooltipUseCustomLabels: observable,
+            hoverCountry: observable,
+        })
+    }
+}
+
+export class MapConfig extends MapConfigDefaults implements Persistable {
+    updateFromObject(obj: Partial<MapConfigInterface>): void {
+        updatePersistables(this, obj)
+
+        this.time = maxTimeBoundFromJSONOrPositiveInfinity(obj.time)
+
+        // If a start time is provided, use it; otherwise, set it to the end time
+        // so that a single map (not a facetted one) is shown by default
+        if (obj.startTime) {
+            this.startTime = minTimeBoundFromJSONOrNegativeInfinity(
+                obj.startTime
+            )
+        } else {
+            this.startTime = this.time
+        }
+
+        // Map [lat, lon] to the internally used [lon, lat]
+        if (obj.globe?.rotation) {
+            this.globe = {
+                ...this.globe,
+                rotation: R.reverse(obj.globe.rotation),
+            }
+        }
+
+        // Update selection
+        if (obj.selectedEntityNames)
+            this.selection.setSelectedEntities(obj.selectedEntityNames)
+    }
+
+    toObject(): NoUndefinedValues<MapConfigInterface> {
+        const obj = objectWithPersistablesToObject(this) as MapConfigInterface
+        deleteRuntimeAndUnchangedProps(obj, new MapConfigDefaults())
+
+        if (obj.time) obj.time = maxTimeToJSON(this.time) as any
+        if (obj.startTime) obj.startTime = minTimeToJSON(this.startTime) as any
+
+        // No need to store the startTime if it's the same as the end time
+        if (obj.startTime === obj.time) delete obj.startTime
+
+        // persist selection
+        obj.selectedEntityNames = this.selection.selectedEntityNames
+        // @ts-expect-error hack to prevent selection from being persisted
+        delete obj.selection
+
+        // don't persist globe settings if the globe isn't active
+        if (!obj.globe?.isActive) delete obj.globe
+
+        // round rotation coordinates before persisting
+        if (obj.globe?.rotation)
+            obj.globe = {
+                ...obj.globe,
+                rotation: [
+                    // we use [lon, lat] internally, but persist [lat, lon]
+                    R.round(obj.globe.rotation[1], 2),
+                    R.round(obj.globe.rotation[0], 2),
+                ],
+            }
+
+        // round zoom level before persisting
+        if (obj.globe?.zoom) {
+            obj.globe = {
+                ...obj.globe,
+                zoom: R.round(obj.globe.zoom, 2),
+            }
+        }
+
+        return trimObject(obj)
+    }
+
+    constructor(obj?: Partial<MapConfigInterface>) {
+        super()
+        if (obj) this.updateFromObject(obj)
+    }
+
+    isContinentActive(): this is MapConfigWithActiveContinent {
+        return this.region !== MapRegionName.World
+    }
+
+    is2dContinentActive(): this is MapConfigWithActiveContinent {
+        return this.isContinentActive() && !this.globe.isActive
+    }
+}
+
+type MapConfigWithActiveContinent = MapConfig & {
+    region: Exclude<MapRegionName, "World">
+}

package/src/grapher/mapCharts/MapHelpers.ts

@@ -0,0 +1,181 @@
+import { Quadtree } from "d3-quadtree"
+import {
+    EntityName,
+    getAggregates,
+    getContinents,
+    getIncomeGroups,
+    getCountryNamesForRegion,
+    getRelativeMouse,
+    lazy,
+} from "../../utils/index.js"
+import { GlobeRegionName, MapRegionName } from "../../types/index.js"
+import {
+    GEO_FEATURES_CLASSNAME,
+    MAP_HOVER_TARGET_RANGE,
+    RenderFeature,
+    MapRenderFeature,
+    RenderFeatureType,
+} from "./MapChartConstants"
+import { CanadaTopology } from "./CanadaTopology.js"
+import { MapTopology } from "./MapTopology.js"
+import { MapSelectionArray } from "../selection/MapSelectionArray.js"
+import * as R from "remeda"
+
+export function detectNearbyFeature<Feature extends RenderFeature>({
+    quadtree,
+    element,
+    event,
+    distance = MAP_HOVER_TARGET_RANGE,
+}: {
+    quadtree: Quadtree<Feature>
+    element: SVGGElement
+    event: MouseEvent | TouchEvent
+    distance?: number
+}): Feature | undefined {
+    const groupElement = element.querySelector(`.${GEO_FEATURES_CLASSNAME}`)
+    if (!groupElement) {
+        console.error(`.${GEO_FEATURES_CLASSNAME} doesn't exist`)
+        return
+    }
+
+    const { x, y } = getRelativeMouse(groupElement, event)
+    return quadtree.find(x, y, distance)
+}
+
+export const sortFeaturesByInteractionStateAndSize = <
+    Feature extends RenderFeature,
+>(
+    features: Feature[],
+    {
+        isHovered,
+        isSelected,
+    }: {
+        isHovered: (featureId: string) => boolean
+        isSelected: (featureId: string) => boolean
+    }
+): Feature[] => {
+    const preferA = 1 as const
+    const preferB = -1 as const
+
+    return R.sort(features, (a, b) => {
+        if (isHovered(a.id) && !isHovered(b.id)) return preferA
+        if (!isHovered(a.id) && isHovered(b.id)) return preferB
+
+        if (isSelected(a.id) && !isSelected(b.id)) return preferA
+        if (!isSelected(a.id) && isSelected(b.id)) return preferB
+
+        return a.geoBounds.area < b.geoBounds.area ? preferA : preferB
+    })
+}
+
+export const calculateDistance = (
+    p1: [number, number],
+    p2: [number, number]
+): number => {
+    return Math.hypot(p2[0] - p1[0], p2[1] - p1[1])
+}
+
+/**
+ * Check if a country is visible on the rendered 3d globe from the current
+ * viewing angle, without taking into account the zoom level.
+ *
+ * More specifically, this function checks if the feature's _centroid_ is
+ * visible on the globe, i.e. parts of a country could still be visible
+ * even if the centroid is not.
+ */
+export function isPointPlacedOnVisibleHemisphere(
+    point: [number, number],
+    rotation: [number, number],
+    threshold = 0 // 1 = at the exact center, 0 = anywhere on the visible hemisphere
+): boolean {
+    const toRadians = (degree: number): number => (degree * Math.PI) / 180
+
+    // convert centroid degrees to radians
+    const lambda = toRadians(point[0])
+    const phi = toRadians(point[1])
+
+    // get current rotation in radians
+    const rotationLambda = toRadians(rotation[0])
+    const rotationPhi = toRadians(rotation[1])
+
+    // calculate the cosine of the angular distance between the feature's
+    // center point and the center points of the current view
+    const cosDelta =
+        Math.sin(phi) * Math.sin(rotationPhi) +
+        Math.cos(phi) *
+            Math.cos(rotationPhi) *
+            Math.cos(lambda - rotationLambda)
+
+    return cosDelta > threshold
+}
+
+export function getForegroundFeatures<Feature extends RenderFeature>(
+    features: Feature[],
+    selectionArray: MapSelectionArray
+): Feature[] {
+    // if no regions are selected, then all countries are in the foreground
+    if (!selectionArray.hasRegions) return features
+
+    // all countries within the selected regions are in the foreground
+    const countrySet = selectionArray.countryNamesForSelectedRegionsSet
+    return features.filter((feature) => countrySet.has(feature.id))
+}
+
+// A map of the form:
+// - Africa: [Algeria, Angola, ...]
+// - North America: [Canada, United States, ...]
+const countriesByRegionMap = lazy(
+    () =>
+        new Map(
+            [...getContinents(), ...getAggregates(), ...getIncomeGroups()].map(
+                (region) => [
+                    region.name,
+                    new Set(getCountryNamesForRegion(region)),
+                ]
+            )
+        )
+)
+
+export const getCountriesByRegion = (
+    regionName: string
+): Set<string> | undefined => countriesByRegionMap().get(regionName)
+
+let _isOnTheMapCache: Set<string>
+export const isOnTheMap = (entityName: EntityName): boolean => {
+    // Cache the result
+    if (!_isOnTheMapCache)
+        _isOnTheMapCache = new Set(
+            MapTopology.objects.world.geometries.map((region: any) => region.id)
+        )
+    return _isOnTheMapCache.has(entityName)
+}
+
+let _isOnTheCanadaMapCache: Set<string>
+export const isOnTheCanadaMap = (entityName: EntityName): boolean => {
+    // Cache the result
+    if (!_isOnTheCanadaMapCache)
+        _isOnTheCanadaMapCache = new Set(
+            CanadaTopology.objects.canada.geometries.map(
+                (region: any) => region.id
+            )
+        )
+    return _isOnTheCanadaMapCache.has(entityName)
+}
+
+export function isMapRenderFeature(
+    feature: RenderFeature
+): feature is MapRenderFeature {
+    return feature.type === RenderFeatureType.Map
+}
+
+export function isValidMapRegionName(
+    candidate: string
+): candidate is MapRegionName {
+    return Object.values(MapRegionName).includes(candidate as any)
+}
+
+export function isValidGlobeRegionName(
+    candidate: string
+): candidate is GlobeRegionName {
+    return isValidMapRegionName(candidate) && candidate !== MapRegionName.World
+}