@buildcanada/charts 0.1.0

package/src/grapher/core/GrapherUrl.ts

@@ -0,0 +1,184 @@
+import {
+    FacetAxisDomain,
+    GrapherInterface,
+    GrapherQueryParams,
+    TimeBoundValueStr,
+} from "../../types/index.js"
+import {
+    generateFocusedSeriesNamesParam,
+    generateSelectedEntityNamesParam,
+} from "./EntityUrlBuilder.js"
+import { match } from "ts-pattern"
+import { GrapherState } from "./GrapherState.js"
+import * as R from "remeda"
+import {
+    DEFAULT_GLOBE_ROTATION,
+    DEFAULT_GLOBE_ZOOM,
+} from "../mapCharts/MapChartConstants.js"
+
+// This function converts a (potentially partial) GrapherInterface to the query params this translates to.
+// This is helpful for when we have a patch config to a parent chart, and we want to know which query params we need to get the parent chart as close as possible to the patched child chart.
+// Note that some settings cannot be set in the config, so they are always set to undefined.
+export const grapherConfigToQueryParams = (
+    config: GrapherInterface
+): GrapherQueryParams => {
+    const { minTime, maxTime } = config // can be a number, or "earliest" or "latest"
+
+    // Note that this code will never format dates in yyyy-mm-dd format.
+    // For us to know that we're working with daily data, we need to have a DayColumn instance, which we only have when we have a grapher instance.
+    // Instead, we just serialize a date as a number - which also works fine for query params.
+    const timeParam =
+        minTime === maxTime
+            ? minTime // This case also covers the case where both are undefined, in which case the result is also undefined
+            : `${minTime ?? TimeBoundValueStr.unboundedLeft}..${maxTime ?? TimeBoundValueStr.unboundedRight}`
+
+    const paramsRaw: Record<
+        keyof GrapherQueryParams,
+        string | number | boolean | undefined
+    > = {
+        tab: config.tab,
+        xScale: config.xAxis?.scaleType,
+        yScale: config.yAxis?.scaleType,
+        stackMode: config.stackMode,
+        zoomToSelection: config.zoomToSelection,
+        endpointsOnly: config.compareEndPointsOnly,
+        time: timeParam,
+        region: config.map?.region,
+        facet: config.selectedFacetStrategy,
+        uniformYAxis: match(config.yAxis?.facetDomain)
+            .with(FacetAxisDomain.shared, () => 0)
+            .with(FacetAxisDomain.independent, () => 1)
+            .with(undefined, () => undefined)
+            .exhaustive(),
+        showNoDataArea: match(config.showNoDataArea)
+            .when(
+                (s) => typeof s === "boolean",
+                (s) => Number(s) // 1 or 0
+            )
+            .with(undefined, () => undefined)
+            .exhaustive(),
+        country: config.selectedEntityNames
+            ? generateSelectedEntityNamesParam(config.selectedEntityNames)
+            : undefined,
+        focus: config.focusedSeriesNames
+            ? generateFocusedSeriesNamesParam(config.focusedSeriesNames)
+            : undefined,
+        mapSelect: config.map?.selectedEntityNames
+            ? generateSelectedEntityNamesParam(config.map.selectedEntityNames)
+            : undefined,
+        globe: config.map?.globe?.isActive ? 1 : undefined,
+        globeRotation: configGlobeRotationToQueryParam(
+            config.map?.globe?.rotation
+        ),
+        globeZoom: configGlobeZoomToQueryParam(config.map?.globe?.zoom),
+
+        // These cannot be specified in config, so we always set them to undefined
+        showSelectionOnlyInTable: undefined,
+        overlay: undefined,
+        tableFilter: undefined,
+        tableSearch: undefined,
+    }
+
+    // Drop undefined values and convert all to string
+    const params = Object.entries(paramsRaw).reduce(
+        (acc, [currKey, currVal]) => {
+            if (currVal !== undefined)
+                acc[currKey as keyof GrapherQueryParams] = currVal.toString()
+            return acc
+        },
+        {} as GrapherQueryParams
+    )
+    return params
+}
+
+export const grapherObjectToQueryParams = (
+    grapher: GrapherState
+): GrapherQueryParams => {
+    const params: GrapherQueryParams = {
+        tab: grapher.mapGrapherTabToQueryParam(grapher.activeTab),
+        xScale: grapher.xAxis?.scaleType,
+        yScale: grapher.yAxis?.scaleType,
+        stackMode: grapher.stackMode,
+        zoomToSelection: grapher.zoomToSelection ? "true" : undefined,
+        endpointsOnly: grapher.compareEndPointsOnly ? "1" : "0",
+        time: grapher.timeParam,
+        region: grapher.map.region,
+        facet: grapher.selectedFacetStrategy,
+        uniformYAxis:
+            grapher.yAxis.facetDomain === FacetAxisDomain.independent
+                ? "0"
+                : "1",
+        showNoDataArea: grapher.showNoDataArea ? "1" : "0",
+        country: grapher.areSelectedEntitiesDifferentThanAuthors
+            ? generateSelectedEntityNamesParam(
+                  grapher.selection.selectedEntityNames
+              )
+            : undefined,
+        focus: grapher.areFocusedSeriesNamesDifferentThanAuthors
+            ? generateFocusedSeriesNamesParam(grapher.focusArray.seriesNames)
+            : undefined,
+        mapSelect: generateSelectedEntityNamesParam(
+            grapher.mapConfig.selection.selectedEntityNames
+        ),
+        globe: grapher.mapConfig.globe.isActive ? "1" : "0",
+        globeRotation: !R.isDeepEqual(
+            grapher.mapConfig.globe.rotation,
+            DEFAULT_GLOBE_ROTATION
+        )
+            ? stringifyGlobeRotation(grapher.mapConfig.globe.rotation)
+            : undefined,
+        globeZoom:
+            grapher.mapConfig.globe.zoom !== DEFAULT_GLOBE_ZOOM
+                ? R.round(grapher.mapConfig.globe.zoom, 2).toString()
+                : undefined,
+        tableFilter: grapher.dataTableConfig.filter,
+        tableSearch: grapher.dataTableConfig.search,
+        overlay: grapher.overlayParam,
+    }
+    return params
+}
+
+/**
+ * Maps the globe rotation given in a config, which is [lat, lon], to a query param
+ * which is [lat, lon] as well. The default globe rotation is not persisted.
+ */
+function configGlobeRotationToQueryParam(
+    configGlobeRotationLatLon?: [number, number]
+): string | undefined {
+    if (!configGlobeRotationLatLon) return undefined
+
+    // don't persist the default globe rotation
+    const isDefaultRotation = R.isDeepEqual(
+        configGlobeRotationLatLon,
+        // we use [lon, lat] internally, but here we are given [lat, lon]
+        R.reverse(DEFAULT_GLOBE_ROTATION)
+    )
+    if (isDefaultRotation) return undefined
+
+    return configGlobeRotationLatLon.map((r) => R.round(r, 2)).join(",")
+}
+
+function configGlobeZoomToQueryParam(zoom?: number): string | undefined {
+    if (!zoom) return undefined
+
+    // don't persist the default zoom level
+    if (zoom === DEFAULT_GLOBE_ZOOM) return undefined
+
+    return zoom.toString()
+}
+
+export function parseGlobeRotation(latLon: string): [number, number] {
+    // we use [lon, lat] internally and [lat, lon] in the URL
+    const [lat, lon] = latLon
+        .split(",")
+        .map((s) => +s)
+        .slice(0, 2) as [number, number]
+    return [lon, lat]
+}
+
+function stringifyGlobeRotation(lonLat: number[]): string {
+    // we use [lon, lat] internally and [lat, lon] in the URL
+    const lon = R.round(lonLat[0], 2)
+    const lat = R.round(lonLat[1], 2)
+    return [lat, lon].join(",")
+}

package/src/grapher/core/GrapherUrlMigrations.ts

@@ -0,0 +1,29 @@
+import {
+    QueryParams,
+    Url,
+    UrlMigration,
+    performUrlMigrations,
+} from "../../utils/index.js"
+import { migrateSelectedEntityNamesParam } from "./EntityUrlBuilder"
+
+export const grapherUrlMigrations: UrlMigration[] = [
+    (url: Url): Url => {
+        const { year, time } = url.queryParams
+        if (!year) return url
+        return url.updateQueryParams({
+            year: undefined,
+            time: time ?? year,
+        })
+    },
+    migrateSelectedEntityNamesParam,
+]
+
+export const legacyToCurrentGrapherUrl = (url: Url): Url =>
+    performUrlMigrations(grapherUrlMigrations, url)
+
+export const legacyToCurrentGrapherQueryParams = (
+    queryStr: string
+): QueryParams => {
+    const url = Url.fromQueryStr(queryStr)
+    return legacyToCurrentGrapherUrl(url).queryParams
+}

package/src/grapher/core/GrapherUseHelpers.tsx

@@ -0,0 +1,147 @@
+import * as React from "react"
+
+import { Bounds } from "../../utils/index.js"
+import { debounce } from "lodash-es"
+import { GrapherProgrammaticInterface } from "../index.js"
+import { FetchingGrapher } from "./FetchingGrapher.js"
+import {
+    ArchiveContext,
+    OwidVariableDataMetadataDimensions,
+    OwidVariableId,
+} from "../../types/index.js"
+import { loadVariableDataAndMetadata } from "./loadVariable.js"
+import { createRoot } from "react-dom/client"
+
+/**
+ * Simple error boundary component to catch rendering errors
+ */
+class ChartErrorBoundary extends React.Component<
+    { children: React.ReactNode },
+    { hasError: boolean; error?: Error }
+> {
+    constructor(props: { children: React.ReactNode }) {
+        super(props)
+        this.state = { hasError: false }
+    }
+
+    static getDerivedStateFromError(error: Error): { hasError: boolean; error: Error } {
+        return { hasError: true, error }
+    }
+
+    override componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
+        console.error("Chart rendering error:", error, errorInfo)
+    }
+
+    override render(): React.ReactNode {
+        if (this.state.hasError) {
+            return (
+                <div style={{ padding: "20px", textAlign: "center" }}>
+                    <p>Something went wrong loading this chart.</p>
+                    <p style={{ fontSize: "12px", color: "#666" }}>
+                        {this.state.error?.message}
+                    </p>
+                </div>
+            )
+        }
+        return this.props.children
+    }
+}
+
+export function renderGrapherIntoContainer(
+    config: GrapherProgrammaticInterface,
+    containerNode: Element,
+    dataApiUrl: string,
+    {
+        archiveContext,
+        noCache,
+    }: { archiveContext?: ArchiveContext; noCache?: boolean } = {}
+): void {
+    const reactRoot = createRoot(containerNode)
+
+    const setBoundsFromContainerAndRender = (
+        entries: ResizeObserverEntry[]
+    ): void => {
+        const entry = entries?.[0] // We always observe exactly one element
+        if (!entry)
+            throw new Error(
+                "Couldn't resize grapher, expected exactly one ResizeObserverEntry"
+            )
+
+        // Don't bother rendering if the container is hidden
+        // see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetParent
+        if ((entry.target as HTMLElement).offsetParent === null) return
+
+        const grapherConfigWithBounds = {
+            ...config,
+            additionalDataLoaderFn: (
+                varId: OwidVariableId
+            ): Promise<OwidVariableDataMetadataDimensions> =>
+                loadVariableDataAndMetadata(varId, dataApiUrl, { noCache }),
+        }
+
+        reactRoot.render(
+            <ChartErrorBoundary>
+                <FetchingGrapher
+                    config={grapherConfigWithBounds}
+                    dataApiUrl={dataApiUrl}
+                    archiveContext={archiveContext}
+                    externalBounds={Bounds.fromRect(entry.contentRect)}
+                    queryStr={grapherConfigWithBounds.queryStr}
+                    noCache={noCache}
+                />
+            </ChartErrorBoundary>
+        )
+    }
+
+    if (typeof window !== "undefined" && "ResizeObserver" in window) {
+        const resizeObserver = new ResizeObserver(
+            // Use a leading debounce to render immediately upon first load, and also immediately upon orientation change on mobile
+            debounce(setBoundsFromContainerAndRender, 400, {
+                leading: true,
+            })
+        )
+        resizeObserver.observe(containerNode)
+    } else if (typeof window === "object" && typeof document === "object") {
+        // only show the warning when we're in something that roughly resembles a browser
+        console.warn(
+            "ResizeObserver not available; grapher will not be able to render"
+        )
+    }
+}
+
+export function renderSingleGrapherOnGrapherPage(
+    jsonConfig: GrapherProgrammaticInterface,
+    dataApiUrl: string,
+    {
+        archiveContext,
+        noCache,
+        queryParams,
+    }: {
+        archiveContext?: ArchiveContext
+        noCache?: boolean
+        queryParams?: URLSearchParams
+    } = {}
+): void {
+    const container = document.getElementsByTagName("figure")[0]
+    const queryStrValue = queryParams
+        ? `?${queryParams.toString()}`
+        : window.location.search
+    try {
+        renderGrapherIntoContainer(
+            {
+                ...jsonConfig,
+                bindUrlToWindow: true,
+                enableKeyboardShortcuts: true,
+                queryStr: queryStrValue,
+                archiveContext,
+            },
+            container,
+            dataApiUrl,
+            { archiveContext, noCache }
+        )
+    } catch (err) {
+        container.innerHTML = `<p>Unable to load interactive visualization</p>`
+        container.setAttribute("id", "fallback")
+        throw err
+    }
+}