@buildcanada/charts 0.1.0

package/src/grapher/tooltip/TooltipProps.ts

@@ -0,0 +1,123 @@
+import * as React from "react"
+import {
+    GrapherTooltipAnchor,
+    GrapherTrendArrowDirection,
+} from "../../utils/index.js"
+import { IObservableValue } from "mobx"
+
+export interface TooltipManager {
+    // We can't pass the property directly because we need it to be observable
+    tooltip?: IObservableValue<TooltipProps | undefined>
+}
+
+/**
+ * Controls the fade transition behavior for tooltips.
+ * - "delayed": Good for charts with gaps between targetable areas
+ * - "immediate": Better if the tooltip is displayed for all points in the chart's bounds
+ * - "none": Disables the fade transition altogether
+ */
+export type TooltipFadeMode = "delayed" | "immediate" | "none"
+
+export enum TooltipFooterIcon {
+    Notice = "notice",
+    Stripes = "stripes",
+    Significance = "significance",
+    None = "none",
+}
+
+export interface FooterItem {
+    icon: TooltipFooterIcon
+    text: string
+}
+
+export interface TooltipProps {
+    id: number | string
+    x?: number
+    y?: number
+    offsetX?: number
+    offsetY?: number
+    offsetXDirection?: "left" | "right"
+    offsetYDirection?: "upward" | "downward"
+    title?: string | number // header text
+    titleAnnotation?: string // rendered next to the title, but muted
+    subtitle?: string | number // header deck
+    subtitleFormat?: "notice" | "unit" // optional postprocessing for subtitle
+    footer?: FooterItem[]
+    style?: React.CSSProperties // css overrides (particularly width/maxWidth)
+    dissolve?: TooltipFadeMode // flag that the tooltip should begin fading out
+    children?: React.ReactNode
+    dismiss?: () => void
+}
+
+export interface TooltipValueProps {
+    label?: string
+    unit?: string
+    value?: string
+    color?: string
+    isProjection?: boolean
+    originalTime?: string // actual year data was drawn from (when ≠ target year)
+    isRoundedToSignificantFigures?: boolean
+    showSignificanceSuperscript?: boolean // show significance-s superscript if applicable
+    labelVariant?: "label+unit" | "unit-only"
+}
+
+export interface TooltipValueRangeProps {
+    label?: string
+    unit?: string
+    values: [string | undefined, string | undefined]
+    trend?: GrapherTrendArrowDirection
+    colors?: string[] // value colors, matched by indices
+    originalTimes?: (string | undefined)[] // actual year data was drawn from (when ≠ target year)
+    isRoundedToSignificantFigures?: boolean
+    showSignificanceSuperscript?: boolean // show significance-s superscript if applicable
+    labelVariant?: "label+unit" | "unit-only"
+}
+
+export interface TooltipTableProps {
+    columns: TooltipTableColumn[]
+    rows: TooltipTableRow[]
+    totals?: (number | undefined)[]
+}
+
+interface TooltipTableColumn {
+    label: string
+    formatValue: (value: unknown) => string
+}
+
+interface TooltipTableRow {
+    name: string
+    annotation?: string
+    swatch?: {
+        color?: string // css color string for the series's swatch
+        opacity?: number
+    }
+    focused?: boolean // highlighted (based on hovered series in chart)
+    blurred?: boolean // greyed out (typically due to missing data)
+    striped?: boolean // use textured swatch (to show data is extrapolated)
+    originalTime?: string // actual year data was drawn (when ≠ target year)
+    values: (string | number | undefined)[]
+}
+
+export interface TooltipVariableProps {
+    label?: string
+    unit?: string
+    color?: string
+    isProjection?: boolean
+    originalTimes?: (string | undefined)[]
+    labelVariant?: "label+unit" | "unit-only"
+    children?: React.ReactNode
+}
+
+export interface TooltipTableData {
+    value: number
+    fake?: boolean
+}
+
+export interface TooltipContainerProps {
+    containerBounds?: { width: number; height: number }
+    anchor?: GrapherTooltipAnchor
+}
+
+export const TooltipContext = React.createContext<
+    Pick<TooltipContainerProps, "anchor">
+>({})

package/src/grapher/tooltip/TooltipState.ts

@@ -0,0 +1,81 @@
+import { observable, computed, action, makeObservable } from "mobx"
+import { PointVector } from "../../utils/index.js"
+import { TooltipFadeMode } from "./TooltipProps"
+
+const TOOLTIP_FADE_DURATION = 400 // $fade-time + $fade-delay in scss
+
+interface TooltipStateArgs {
+    fade?: TooltipFadeMode
+}
+
+export class PlainTooltipState<T> {
+    position = new PointVector(0, 0)
+
+    protected _target: T | undefined = undefined
+    protected _timer: number | undefined = undefined
+    protected _fade: TooltipFadeMode
+
+    constructor({ fade }: TooltipStateArgs = {}) {
+        this._fade = fade ?? "delayed"
+    }
+
+    get target(): T | undefined {
+        return this._target
+    }
+
+    set target(newTarget: T | null) {
+        this.setTarget(newTarget)
+    }
+
+    get fading(): TooltipFadeMode | undefined {
+        // returns "delayed"|"immediate" during the timeout after clearing the target
+        return !!this._timer && !!this._target ? this._fade : undefined
+    }
+
+    protected setTarget(newTarget: T | null): void {
+        // delay clearing the target (and hiding the tooltip) for a bit to prevent
+        // flicker when frobbing between neighboring elements and allow an opacity
+        // transition to smoothly fade the tooltip out
+        clearTimeout(this._timer)
+
+        if (newTarget === null) {
+            const speed = { delayed: 1, immediate: 0.5, none: 0 }[this._fade]
+            this._timer = window.setTimeout(
+                () => this.resetTarget(),
+                speed * TOOLTIP_FADE_DURATION
+            )
+        } else {
+            this._target = newTarget
+            this._timer = undefined
+        }
+    }
+
+    protected resetTarget(): void {
+        this._target = undefined
+        this._timer = undefined
+    }
+}
+
+export class TooltipState<T> extends PlainTooltipState<T> {
+    constructor(args?: TooltipStateArgs) {
+        super(args)
+
+        makeObservable<
+            this,
+            "_target" | "_timer" | "setTarget" | "resetTarget"
+        >(this, {
+            // observables
+            position: observable,
+            _target: observable,
+            _timer: observable,
+
+            // computed (getters)
+            target: computed,
+            fading: computed,
+
+            // actions
+            setTarget: action.bound,
+            resetTarget: action.bound,
+        })
+    }
+}

package/src/grapher/verticalLabels/VerticalLabels.tsx

@@ -0,0 +1,31 @@
+import React from "react"
+import { VerticalAxis } from "../axis/Axis"
+import { VerticalLabelsState } from "./VerticalLabelsState"
+import { darkenColorForText } from "../color/ColorUtils.js"
+
+export function VerticalLabels({
+    state,
+    yAxis,
+    x = 0,
+    xAnchor = "start",
+}: {
+    state: VerticalLabelsState
+    yAxis: VerticalAxis
+    x?: number
+    xAnchor?: "start" | "end"
+}): React.ReactElement {
+    return (
+        <g>
+            {state.series.map((series) => (
+                <React.Fragment key={series.yPosition}>
+                    {series.textWrap.renderSVG(x, yAxis.place(series.value), {
+                        textProps: {
+                            textAnchor: xAnchor,
+                            fill: darkenColorForText(series.color),
+                        },
+                    })}
+                </React.Fragment>
+            ))}
+        </g>
+    )
+}

package/src/grapher/verticalLabels/VerticalLabelsState.ts

@@ -0,0 +1,154 @@
+import * as R from "remeda"
+import { computed } from "mobx"
+import { Bounds, RequiredBy, VerticalAlign } from "../../utils/index.js"
+import { TextWrap } from "../../components/index.js"
+
+interface VerticalLabelsOptions {
+    /** Font size for the labels */
+    fontSize: number
+
+    /** Font weight for the labels */
+    fontWeight?: number
+
+    /** Line height multiplier for multi-line labels (defaults to 1) */
+    lineHeight?: number
+
+    /** Maximum width for labels (no restriction by default) */
+    maxWidth?: number
+
+    /** Labels outside of this range are hidden */
+    yRange?: [number, number]
+
+    /** Minimum space between labels in pixels to prevent overlap */
+    minSpacing?: number
+
+    /** Controls how the label is aligned relative to the y-position */
+    verticalAlign?: VerticalAlign
+
+    /** Function to resolve collisions between two overlapping labels by choosing which one to keep */
+    resolveCollision?: (
+        s1: InitialVerticalLabelsSeries,
+        s2: InitialVerticalLabelsSeries
+    ) => InitialVerticalLabelsSeries
+}
+
+export interface InitialVerticalLabelsSeries {
+    seriesName: string
+    value: number
+    label: string
+    yPosition: number
+    color: string
+}
+
+interface SizedVerticalLabelsSeries extends InitialVerticalLabelsSeries {
+    textWrap: TextWrap
+    bounds: Bounds
+}
+
+type VerticalLabelsSeries = SizedVerticalLabelsSeries
+
+export class VerticalLabelsState {
+    private initialSeries: InitialVerticalLabelsSeries[]
+    private initialOptions: VerticalLabelsOptions
+
+    private defaultOptions = {
+        lineHeight: 1,
+        maxWidth: Infinity,
+        minSpacing: 5,
+        verticalAlign: VerticalAlign.middle,
+        fontWeight: 400,
+    } as const satisfies Partial<VerticalLabelsOptions>
+
+    constructor(
+        series: InitialVerticalLabelsSeries[],
+        options: VerticalLabelsOptions
+    ) {
+        this.initialSeries = series
+        this.initialOptions = options
+    }
+
+    @computed private get options(): RequiredBy<
+        VerticalLabelsOptions,
+        keyof typeof this.defaultOptions
+    > {
+        return { ...this.defaultOptions, ...this.initialOptions }
+    }
+
+    @computed
+    private get sizedSeries(): SizedVerticalLabelsSeries[] {
+        const { fontSize, fontWeight, maxWidth, verticalAlign, lineHeight } =
+            this.options
+
+        return this.initialSeries.map((series) => {
+            const { label, yPosition } = series
+
+            const textWrap = new TextWrap({
+                text: label,
+                maxWidth,
+                fontSize,
+                fontWeight,
+                lineHeight,
+                verticalAlign,
+            })
+
+            const [x, y] = textWrap.getPositionForSvgRendering(0, yPosition)
+            const bounds = new Bounds(x, y, textWrap.width, textWrap.height)
+
+            return { ...series, textWrap, bounds }
+        })
+    }
+
+    @computed get series(): VerticalLabelsSeries[] {
+        const { minSpacing, resolveCollision, yRange } = this.options
+
+        const margin = minSpacing > 0 ? minSpacing / 2 : 0
+        const margins = { top: margin, bottom: margin }
+
+        const series = this.sizedSeries.map((series) => ({
+            ...series,
+            // Bounds used to detect collisions. They're a bit larger than the
+            // text bounds to account for the minimum spacing between labels.
+            collisionBounds: series.bounds.expand(margins),
+            // None of the series are initially hidden
+            isHidden: false,
+        }))
+
+        // Hide labels that are overlapping or too close to each other
+        for (let i = 0; i < series.length; i++) {
+            const s1 = series[i]
+            if (s1.isHidden) continue
+
+            // Check if the label is out of bounds
+            if (
+                yRange &&
+                (s1.bounds.top < yRange[1] || s1.bounds.bottom > yRange[0])
+            ) {
+                s1.isHidden = true
+                continue
+            }
+
+            // Check if the label is overlapping with any other label
+            for (let j = i + 1; j < series.length; j++) {
+                const s2 = series[j]
+                if (s2.isHidden) continue
+
+                if (s1.collisionBounds.hasVerticalOverlap(s2.collisionBounds)) {
+                    const picked = resolveCollision?.(s1, s2) ?? s1
+
+                    if (picked === s1) s2.isHidden = true
+                    else s1.isHidden = true
+                }
+            }
+        }
+
+        return series
+            .filter((series) => !series.isHidden)
+            .map((series) => R.omit(series, ["isHidden", "collisionBounds"]))
+    }
+
+    @computed get width(): number {
+        const labelWidths = this.series.map((series) => series.textWrap.width)
+        const maxLabelWidth = R.firstBy(labelWidths, [R.identity(), "desc"])
+        return maxLabelWidth ?? 0
+    }
+}

package/src/index.ts

@@ -0,0 +1,226 @@
+/**
+ * @buildcanada/charts
+ *
+ * A configurable data visualization library for creating interactive charts.
+ * Extracted from Our World in Data's Grapher library.
+ *
+ * @example
+ * ```tsx
+ * import { ChartsProvider, Grapher, GrapherState } from '@buildcanada/charts'
+ * import '@buildcanada/charts/styles.css'
+ *
+ * const config = {
+ *   branding: { poweredByText: 'My Organization' },
+ *   dataApi: { baseUrl: 'https://api.example.com/v1/indicators/' }
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <ChartsProvider config={config}>
+ *       <Grapher {...chartProps} />
+ *     </ChartsProvider>
+ *   )
+ * }
+ * ```
+ */
+
+// Configuration
+export {
+    type ChartsConfig,
+    type ChartsBranding,
+    type ChartsDataApi,
+    type ChartsErrorReporting,
+    type ChartsAnalytics,
+    type LogoConfig,
+    defaultChartsConfig,
+    mergeWithDefaults,
+    ChartsProvider,
+    type ChartsProviderProps,
+    useChartsConfig,
+    useMaybeChartsConfig,
+    createFallbackConfig,
+    reportError,
+    trackEvent,
+} from "./config/index.js"
+
+// Re-export grapher components
+export {
+    Grapher,
+    type GrapherProgrammaticInterface,
+    type GrapherManager,
+} from "./grapher/core/Grapher.js"
+
+export { GrapherState } from "./grapher/core/GrapherState.js"
+export { FetchingGrapher } from "./grapher/core/FetchingGrapher.js"
+
+// Explorer
+export { Explorer } from "./explorer/Explorer.js"
+export type { ExplorerProps } from "./explorer/Explorer.js"
+
+// Chart State types
+export type { ChartState, ChartSeries } from "./grapher/chart/ChartInterface.js"
+export type { LineChartState } from "./grapher/lineCharts/LineChartState.js"
+export type { SlopeChartState } from "./grapher/slopeCharts/SlopeChartState.js"
+export type { DiscreteBarChartState } from "./grapher/barCharts/DiscreteBarChartState.js"
+export type { StackedAreaChartState } from "./grapher/stackedCharts/StackedAreaChartState.js"
+export type { StackedBarChartState } from "./grapher/stackedCharts/StackedBarChartState.js"
+export type { StackedDiscreteBarChartState } from "./grapher/stackedCharts/StackedDiscreteBarChartState.js"
+export type { ScatterPlotChartState } from "./grapher/scatterCharts/ScatterPlotChartState.js"
+export type { MarimekkoChartState } from "./grapher/stackedCharts/MarimekkoChartState.js"
+export { MapChartState } from "./grapher/mapCharts/MapChartState.js"
+export { MapConfig } from "./grapher/mapCharts/MapConfig.js"
+
+// Data loading
+export {
+    fetchInputTableForConfig,
+    getCachingInputTableFetcher,
+    type FetchInputTableForConfigFn,
+} from "./grapher/core/loadGrapherTableHelpers.js"
+
+export { loadVariableDataAndMetadata } from "./grapher/core/loadVariable.js"
+
+// Color system
+export { ColorScale } from "./grapher/color/ColorScale.js"
+export { ColorScaleConfig } from "./grapher/color/ColorScaleConfig.js"
+export { ColorScheme } from "./grapher/color/ColorScheme.js"
+export { ColorSchemes, getColorSchemeForChartType } from "./grapher/color/ColorSchemes.js"
+export {
+    NumericBin,
+    CategoricalBin,
+    type ColorScaleBin,
+    isCategoricalBin,
+    isNumericBin,
+    isNoDataBin,
+    isProjectedDataBin,
+} from "./grapher/color/ColorScaleBin.js"
+
+// Selection and Focus
+export { SelectionArray } from "./grapher/selection/SelectionArray.js"
+export { FocusArray } from "./grapher/focus/FocusArray.js"
+
+// Constants
+export {
+    DEFAULT_GRAPHER_WIDTH,
+    DEFAULT_GRAPHER_HEIGHT,
+    GRAPHER_THUMBNAIL_WIDTH,
+    GRAPHER_THUMBNAIL_HEIGHT,
+    DEFAULT_GRAPHER_BOUNDS,
+    BASE_FONT_SIZE,
+    Patterns,
+    latestGrapherConfigSchema,
+} from "./grapher/core/GrapherConstants.js"
+
+// Controls
+export { EntityPicker } from "./grapher/controls/entityPicker/EntityPicker.js"
+export type { EntityPickerManager } from "./grapher/controls/entityPicker/EntityPickerConstants.js"
+export { GlobalEntitySelector } from "./grapher/controls/globalEntitySelector/GlobalEntitySelector.js"
+export { Dropdown } from "./grapher/controls/Dropdown.js"
+
+// Schema and migrations
+export { defaultGrapherConfig } from "./grapher/schema/defaultGrapherConfig.js"
+export {
+    migrateGrapherConfigToLatestVersion,
+    migrateGrapherConfigToLatestVersionAndFailOnError,
+} from "./grapher/schema/migrations/migrate.js"
+
+// URL utilities
+export {
+    setSelectedEntityNamesParam,
+    migrateSelectedEntityNamesParam,
+    getSelectedEntityNamesParam,
+    generateSelectedEntityNamesParam,
+    generateFocusedSeriesNamesParam,
+    getEntityNamesParam,
+} from "./grapher/core/EntityUrlBuilder.js"
+
+export { grapherConfigToQueryParams } from "./grapher/core/GrapherUrl.js"
+
+// Chart utilities
+export { ChartDimension } from "./grapher/chart/ChartDimension.js"
+export { DimensionSlot } from "./grapher/chart/DimensionSlot.js"
+export { makeChartState } from "./grapher/chart/ChartTypeMap.js"
+export { generateGrapherImageSrcSet } from "./grapher/chart/ChartUtils.js"
+
+// Slideshow
+export {
+    type SlideShowManager,
+    SlideShowController,
+} from "./grapher/slideshowController/SlideShowController.js"
+
+// Analytics
+export { GrapherAnalytics } from "./grapher/core/GrapherAnalytics.js"
+
+// Rendering helpers
+export {
+    renderGrapherIntoContainer,
+    renderSingleGrapherOnGrapherPage,
+} from "./grapher/core/GrapherUseHelpers.js"
+
+// Map features
+export { GeoFeatures } from "./grapher/mapCharts/GeoFeatures.js"
+export {
+    MAP_REGION_LABELS,
+    type GeoFeature,
+    type Direction,
+    type Ellipse,
+    type EllipseCoords,
+} from "./grapher/mapCharts/MapChartConstants.js"
+
+// Comparison lines
+export { isValidVerticalComparisonLineConfig } from "./grapher/comparisonLine/ComparisonLineHelpers.js"
+
+// Binning strategies
+export { hasValidConfigForBinningStrategy } from "./grapher/color/BinningStrategies.js"
+
+// Chart tabs
+export {
+    isChartTypeName,
+    isValidTabQueryParam,
+    findPotentialChartTypeSiblings,
+    mapGrapherTabNameToQueryParam,
+    mapGrapherTabNameToConfigOption,
+    makeLabelForGrapherTab,
+} from "./grapher/chart/ChartTabs.js"
+
+// Guided chart utilities
+export {
+    useMaybeGlobalGrapherStateRef,
+    useGuidedChartLinkHandler,
+    GuidedChartContext,
+    type GuidedChartContextValue,
+    type ArchiveGuidedChartRegistration,
+    buildArchiveGuidedChartSrc,
+} from "./grapher/chart/guidedChartUtils.js"
+
+// Legacy conversion
+export {
+    legacyToOwidTableAndDimensions,
+    legacyToOwidTableAndDimensionsWithMandatorySlug,
+} from "./grapher/core/LegacyToOwidTable.js"
+
+export { legacyToCurrentGrapherUrl } from "./grapher/core/GrapherUrlMigrations.js"
+
+// Test data helpers (useful for demos and testing)
+export {
+    fakeEntities,
+    createOwidTestDataset,
+    type TestData,
+    type TestMetadata,
+} from "./grapher/testData/OwidTestData.js"
+export { LifeExpectancyGrapher } from "./grapher/testData/OwidTestData.sample.js"
+
+// Types commonly needed for data loading
+export {
+    DimensionProperty,
+    GRAPHER_CHART_TYPES,
+    ALL_GRAPHER_CHART_TYPES,
+    ColorSchemeName,
+    MapRegionName,
+    type EntityName,
+    type EntityId,
+    type EntityCode,
+} from "./types/index.js"
+
+// Utilities for data loading
+export { Bounds } from "./utils/index.js"
+export { parseDelimited, OwidTable, BlankOwidTable } from "./core-table/index.js"

package/src/styles/charts.scss

@@ -0,0 +1,15 @@
+/**
+ * @buildcanada/charts - Main Stylesheet
+ *
+ * This file imports all necessary styles for the charts library.
+ * Import this in your application:
+ *
+ *   import '@buildcanada/charts/styles.css'
+ */
+
+// Import the main grapher styles which include all component styles
+@import "../grapher/core/grapher.scss";
+
+// Explorer styles
+@import "../explorer/Explorer.scss";
+@import "../explorer/ExplorerControls.scss";

package/src/types/NominalType.ts

@@ -0,0 +1,30 @@
+declare const __nominal__type: unique symbol
+/** Typescript is structurally typed, not nominally typed. This means that
+ * two types are considered equivalent if their members are equivalent.
+ * This is often useful but sometimes you want to distingish types based on their
+ * name alone - e.g. if you have an identifier that is just a string but you'd like
+ * some type safety when using it. This is where this nominal type comes in.
+ * @example
+ * type UserName = Nominal<string, "UserName">
+ * type UserId = Nominal<string, "UserId">
+ *
+ * function getUserName(name: UserName) {
+ *     return name
+ * }
+ *
+ * const name = getUserName("123" as UserName)   // OK
+ * const name2 = getUserName("123")              // Error
+ * const name3 = getUserName("123" as UserId)    // Error
+ * // of course the main benefit comes when the UserName and UserId types are used in a more complex call hierarchy
+ */
+export type Nominal<Type, Identifier> = Type & {
+    readonly [__nominal__type]: Identifier
+}
+
+export function wrap<T, I>(obj: T): Nominal<T, I> {
+    return obj as Nominal<T, I>
+}
+
+export function unwrap<T, I>(obj: Nominal<T, I>): T {
+    return obj
+}

package/src/types/OwidOrigin.ts

@@ -0,0 +1,18 @@
+import { OwidLicense } from "./OwidVariable.js"
+export interface OwidOrigin {
+    id?: number
+    title?: string
+    titleSnapshot?: string
+    attribution?: string
+    attributionShort?: string
+    versionProducer?: string
+    license?: OwidLicense
+    descriptionSnapshot?: string
+    description?: string
+    producer?: string
+    citationFull?: string
+    urlMain?: string
+    urlDownload?: string
+    dateAccessed?: string
+    datePublished?: string
+}

package/src/types/OwidSource.ts

@@ -0,0 +1,9 @@
+export interface OwidSource {
+    id?: number
+    name?: string
+    dataPublishedBy?: string
+    dataPublisherSource?: string
+    link?: string
+    retrievedDate?: string
+    additionalInfo?: string
+}