@buildcanada/charts 0.1.0

package/src/grapher/core/GrapherAnalytics.ts

@@ -0,0 +1,229 @@
+import {
+    EventCategory,
+    GrapherErrorAction,
+    type EntityControlEvent,
+    type EntitySelectorEvent,
+    type GrapherImageDownloadEvent,
+    type GrapherInteractionEvent,
+    type GrapherAnalyticsContext,
+    type GAEvent,
+} from "../../types/index.js"
+
+const DEBUG = false
+
+type GAEventWithClear = GAEvent & { _clear: boolean }
+
+// Add type information for dataLayer global provided by Google Tag Manager
+type WindowWithDataLayer = Window & {
+    dataLayer?: (GAEventWithClear | GAConsent)[]
+}
+declare const window: WindowWithDataLayer
+
+// taken from https://github.com/DefinitelyTyped/DefinitelyTyped/blob/de66435d18fbdb2684947d16b5cd3a77f876324c/types/gtag.js/index.d.ts#L151-L156
+interface GAConsentParams {
+    ad_storage?: "granted" | "denied" | undefined
+    analytics_storage?: "granted" | "denied" | undefined
+    wait_for_update?: number | undefined
+    region?: string[] | undefined
+}
+
+type GAConsent = ["consent", "default" | "update", GAConsentParams]
+
+// Note: consent-based blocking dealt with at the Google Tag Manager level.
+// Events are discarded if consent not given.
+export class GrapherAnalytics {
+    constructor(environment: string = "", version = "1.0.0") {
+        this.isDev = environment === "development"
+        this.version = version
+    }
+
+    private version: string // Ideally the Git hash commit
+    private isDev: boolean
+
+    logGrapherView(
+        slug: string,
+        ctx?: { viewConfigId?: string; narrativeChartName?: string }
+    ): void {
+        this.logToGA({
+            event: EventCategory.GrapherView,
+            grapherPath: `/grapher/${slug}`,
+            viewConfigId: ctx?.viewConfigId,
+            narrativeChartName: ctx?.narrativeChartName,
+        })
+    }
+
+    logGrapherViewError(error: Error): void {
+        this.logToGA({
+            event: EventCategory.GrapherError,
+            eventAction: GrapherErrorAction.GrapherViewError,
+            eventContext: error.message,
+        })
+    }
+
+    logEntitiesNotFoundError(entities: string[]): void {
+        this.logToGA({
+            event: EventCategory.GrapherError,
+            eventAction: GrapherErrorAction.EntitiesNotFound,
+            eventContext: JSON.stringify(entities),
+        })
+    }
+
+    logExplorerView(slug: string, view: Record<string, string>): void {
+        this.logToGA({
+            event: EventCategory.ExplorerView,
+            explorerPath: `/explorers/${slug}`,
+            explorerView: JSON.stringify(view),
+        })
+    }
+
+    /** Logs events for the globel entity selector used on country pages */
+    logGlobalEntitySelector(action: EntityControlEvent, note?: string): void {
+        this.logToGA({
+            event: EventCategory.GlobalEntitySelectorUsage,
+            eventAction: action,
+            eventContext: note,
+        })
+    }
+
+    /** Logs events for the explorer's entity selector */
+    logEntityPickerEvent(action: EntitySelectorEvent, note?: string): void {
+        this.logToGA({
+            event: EventCategory.ExplorerCountrySelector,
+            eventAction: action,
+            eventContext: note,
+        })
+    }
+
+    /** Logs events for Grapher's entity selector */
+    logEntitySelectorEvent(
+        action: EntitySelectorEvent,
+        ctx: GrapherAnalyticsContext & { target?: string }
+    ): void {
+        this.logToGA({
+            ...grapherAnalyticsContextToGAEventFields(ctx),
+            event: EventCategory.GrapherEntitySelector,
+            eventAction: action,
+            eventTarget: ctx.target,
+        })
+    }
+
+    logGrapherImageDownloadEvent(
+        action: GrapherImageDownloadEvent,
+        ctx: GrapherAnalyticsContext & { context?: Record<string, any> }
+    ): void {
+        this.logToGA({
+            ...grapherAnalyticsContextToGAEventFields(ctx),
+            event: EventCategory.GrapherClick,
+            eventAction: action,
+            eventContext: ctx.context ? JSON.stringify(ctx.context) : undefined,
+        })
+    }
+
+    logGrapherInteractionEvent(
+        action: GrapherInteractionEvent,
+        ctx: GrapherAnalyticsContext & { target?: string }
+    ): void {
+        this.logToGA({
+            ...grapherAnalyticsContextToGAEventFields(ctx),
+            event: EventCategory.GrapherHover,
+            eventAction: action,
+            eventTarget: ctx.target,
+        })
+    }
+
+    logGrapherClick(
+        action: string = "unknown-action",
+        ctx: {
+            label?: string
+            grapherUrl?: string
+            narrativeChartName?: string
+        }
+    ): void {
+        this.logToGA({
+            event: EventCategory.GrapherClick,
+            eventAction: action,
+            eventTarget: ctx.label,
+            grapherPath: getPathname(ctx.grapherUrl),
+            narrativeChartName: ctx.narrativeChartName,
+        })
+    }
+
+    logSiteClick(action: string = "unknown-action", label?: string): void {
+        this.logToGA({
+            event: EventCategory.SiteClick,
+            eventAction: action,
+            eventTarget: label,
+        })
+    }
+
+    logSiteFormSubmit(
+        action: "newsletter-subscribe" | "donate",
+        label?: string
+    ): void {
+        this.logToGA({
+            event: EventCategory.SiteFormSubmit,
+            eventAction: action,
+            eventTarget: label,
+        })
+    }
+
+    logKeyboardShortcut(shortcut: string, combo: string): void {
+        this.logToGA({
+            event: EventCategory.KeyboardShortcut,
+            eventAction: shortcut,
+            eventContext: combo,
+        })
+    }
+
+    protected logToGA(event: GAEvent): void {
+        if (DEBUG && this.isDev) {
+            // eslint-disable-next-line no-console
+            console.log("Analytics.logToGA", event)
+            return
+        }
+        if (typeof window !== "undefined") {
+            // It's very important that we clear (_clear) the data layer whenever we push an event,
+            // otherwise it will retain all properties from previous events which can lead to
+            // confusing and incorrect events data being sent.
+            // See https://www.simoahava.com/analytics/two-simple-data-model-tricks/.
+            // see also https://github.com/google/data-layer-helper/blob/4a65b385db1fac710d33bf5d1345e598e3d117fc/README.md#preventing-default-recursive-merge
+            window.dataLayer?.push({ ...event, _clear: true })
+        }
+    }
+
+    updateGAConsentSettings(consent: GAConsentParams): void {
+        function pushToDataLayer(..._args: any): void {
+            // Google Tag Manager is super weird here: it will not accept a normal array or object
+            // being pushed to dataLayer, it absolutely has to be an `Arguments` object.
+            // see https://stackoverflow.com/q/60400130/10670163
+
+            // eslint-disable-next-line prefer-rest-params
+            window.dataLayer?.push(arguments as unknown as GAConsent)
+        }
+        pushToDataLayer("consent", "update", consent)
+    }
+}
+
+function getPathname(url?: string): string | undefined {
+    // GA4 trims metadata fields down to 100 characters, so we want to be concise and only send
+    // the pathname, e.g. `/grapher/life-expectancy` or `/explorers/migration`
+    if (url === undefined) return undefined
+
+    try {
+        const urlObj = new URL(url)
+        return urlObj.pathname
+    } catch {
+        // Invalid URL, return undefined
+        return undefined
+    }
+}
+
+function grapherAnalyticsContextToGAEventFields(
+    ctx: GrapherAnalyticsContext
+): Partial<GAEvent> {
+    return {
+        grapherPath: ctx.slug ? `/grapher/${ctx.slug}` : undefined,
+        viewConfigId: ctx.viewConfigId,
+        narrativeChartName: ctx.narrativeChartName,
+    }
+}

package/src/grapher/core/GrapherConstants.ts

@@ -0,0 +1,173 @@
+import {
+    EntityName,
+    GRAPHER_CHART_TYPES,
+    GrapherChartType,
+} from "../../types/index.js"
+import { Bounds } from "../../utils/index.js"
+import { defaultGrapherConfig } from "../schema/defaultGrapherConfig.js"
+
+export const GRAPHER_PROD_URL = "https://ourworldindata.org"
+
+export const GRAPHER_EMBEDDED_FIGURE_ATTR = "data-grapher-src"
+
+export const GRAPHER_NARRATIVE_CHART_CONFIG_FIGURE_ATTR =
+    "data-grapher-narrative-chart-config"
+
+export const GRAPHER_ROUTE_FOLDER = "grapher"
+
+export const GRAPHER_PAGE_BODY_CLASS = "StandaloneGrapherOrExplorerPage"
+export const GRAPHER_IS_IN_IFRAME_CLASS = "IsInIframe"
+export const GRAPHER_TIMELINE_CLASS = "timeline-component"
+export const GRAPHER_SIDE_PANEL_CLASS = "side-panel"
+export const GRAPHER_SETTINGS_CLASS = "GrapherSettingsPopover"
+
+// The Figma plugin uses these class names to identify sections of the chart
+export const GRAPHER_CHART_AREA_CLASS = "chart-area"
+export const GRAPHER_HEADER_CLASS = "header"
+export const GRAPHER_FOOTER_CLASS = "footer"
+
+export const DEFAULT_GRAPHER_ENTITY_TYPE = "country or region"
+export const DEFAULT_GRAPHER_ENTITY_TYPE_PLURAL = "countries and regions"
+
+export const GRAPHER_LOADED_EVENT_NAME = "grapherLoaded"
+
+export const DEFAULT_GRAPHER_WIDTH = 850
+export const DEFAULT_GRAPHER_HEIGHT = 600
+
+// Keep in sync with $grapher-thumbnail-width and $grapher-thumbnail-height in Grapher.scss
+export const GRAPHER_THUMBNAIL_WIDTH = 300
+export const GRAPHER_THUMBNAIL_HEIGHT = 160
+
+// Image widths used for generating srcSet (1x and 2x for high-DPI displays)
+export const GRAPHER_IMAGE_WIDTH_1X = 850
+export const GRAPHER_IMAGE_WIDTH_2X = 1700
+
+export const GRAPHER_SQUARE_SIZE = 540
+
+export const DEFAULT_GRAPHER_BOUNDS = new Bounds(
+    0,
+    0,
+    DEFAULT_GRAPHER_WIDTH,
+    DEFAULT_GRAPHER_HEIGHT
+)
+
+export const DEFAULT_GRAPHER_BOUNDS_SQUARE = new Bounds(
+    0,
+    0,
+    GRAPHER_SQUARE_SIZE,
+    GRAPHER_SQUARE_SIZE
+)
+
+export const GRAPHER_FRAME_PADDING_VERTICAL = 16
+export const GRAPHER_FRAME_PADDING_HORIZONTAL = 16
+
+export const STATIC_EXPORT_DETAIL_SPACING = 8
+
+export const GRAPHER_OPACITY_MUTE = 0.5
+
+export const GRAPHER_AREA_OPACITY_DEFAULT = 0.8
+export const GRAPHER_AREA_OPACITY_MUTE = 0.3
+export const GRAPHER_AREA_OPACITY_FOCUS = 1
+
+export const GRAPHER_TEXT_OUTLINE_FACTOR = 0.25
+
+export const BASE_FONT_SIZE = 16
+
+export const GRAPHER_FONT_SCALE_9_6 = 9.6 / BASE_FONT_SIZE
+export const GRAPHER_FONT_SCALE_10 = 10 / BASE_FONT_SIZE
+export const GRAPHER_FONT_SCALE_10_5 = 10.5 / BASE_FONT_SIZE
+export const GRAPHER_FONT_SCALE_11 = 11 / BASE_FONT_SIZE
+export const GRAPHER_FONT_SCALE_11_2 = 11.2 / BASE_FONT_SIZE
+export const GRAPHER_FONT_SCALE_12 = 12 / BASE_FONT_SIZE
+export const GRAPHER_FONT_SCALE_12_8 = 12.8 / BASE_FONT_SIZE
+export const GRAPHER_FONT_SCALE_13 = 13 / BASE_FONT_SIZE
+export const GRAPHER_FONT_SCALE_14 = 14 / BASE_FONT_SIZE
+export const GRAPHER_FONT_SCALE_18 = 18 / BASE_FONT_SIZE
+
+// keep in sync with $max-tooltip-width in Tooltip.scss
+export const GRAPHER_MAX_TOOLTIP_WIDTH = 400
+
+export const latestGrapherConfigSchema = defaultGrapherConfig.$schema
+
+export enum CookieKey {
+    isAdmin = "isAdmin",
+}
+
+export const WORLD_ENTITY_NAME = "World"
+
+export const isWorldEntityName = (entityName: EntityName): boolean =>
+    entityName === WORLD_ENTITY_NAME
+
+export const CONTINENTS_INDICATOR_ID = 900801 // "Countries Continent"
+export const POPULATION_INDICATOR_ID_USED_IN_ADMIN = 953899 // "Population (various sources, 2024-07-15)"
+export const POPULATION_INDICATOR_ID_USED_IN_ENTITY_SELECTOR = 953903 // "Population (historical) (various sources, 2024-07-15)"
+export const GDP_PER_CAPITA_INDICATOR_ID_USED_IN_ENTITY_SELECTOR = 900793 // "GDP per capita - Maddison Project Database (2024-04-26)"
+
+export const isContinentsVariableId = (id: string | number): boolean =>
+    id.toString() === CONTINENTS_INDICATOR_ID.toString()
+
+// ETL paths are composed of channel/namespace/version/dataset/table#columnname
+// We want to identify the any version of these two columns (added whitespaces for readability):
+// grapher / demography / ANY VERSION / population / population # population
+// grapher / demography / ANY VERSION / population / historical # population_historical
+const population_regex =
+    /^grapher\/demography\/[\d-]+\/population\/(population#population|historical#population_historical)$/
+
+/**
+ * Manually configured list of sources that define geographic regions.
+ *
+ * By convention, entities are named with the format 'RegionName (Source)',
+ * such as 'Africa (UN)' or 'Africa (FAO)'.
+ *
+ * These source identifiers are used to compile group of regions for the
+ * filter dropdown in the entity selector and on the data tab.
+ *
+ * Ideally, all regions would be defined in the ETL's regions file,
+ * but currently we need to maintain this manual configuration until the
+ * regions file is more complete.
+ */
+export const CUSTOM_REGION_SOURCE_IDS = [
+    "un",
+    "fao",
+    "ei",
+    "pip",
+    "ember",
+    "gcp",
+    "niaid",
+    "unicef",
+    "unaids",
+    "undp",
+    "wid",
+    "oecd",
+] as const
+
+export const isPopulationVariableETLPath = (path: string): boolean => {
+    return population_regex.test(path)
+}
+
+export enum Patterns {
+    noDataPattern = "noDataPattern",
+    noDataPatternForMap = "noDataPatternForMap",
+    noDataPatternForGlobe = "noDataPatternForGlobe",
+    projectedDataPattern = "projectedDataPattern",
+    projectedDataPatternForLegend = "projectedDataPatternForLegend",
+}
+
+export const SVG_STYLE_PROPS: React.CSSProperties = {
+    fontFamily:
+        "Lato, 'Helvetica Neue', Helvetica, Arial, 'Liberation Sans', sans-serif",
+    fontFeatureSettings: '"liga", "kern", "calt", "lnum"', // keep in sync with typography.scss$default-font-features
+    textRendering: "geometricPrecision",
+    WebkitFontSmoothing: "antialiased",
+}
+
+export enum GrapherModal {
+    Sources = "sources",
+    Download = "download",
+    Embed = "embed",
+}
+
+export const CHART_TYPES_THAT_SHOW_ALL_ENTITIES: GrapherChartType[] = [
+    GRAPHER_CHART_TYPES.ScatterPlot,
+    GRAPHER_CHART_TYPES.Marimekko,
+]