@buildcanada/charts 0.1.0

package/src/components/styles/variables.scss

@@ -0,0 +1,208 @@
+/*******************************************************************************
+ * Spacing
+ */
+
+$padding-x-sm: 24px;
+$padding-x-md: 80px;
+$vertical-spacing: 16px;
+
+:root {
+    --grid-gap: 24px;
+
+    @media (max-width: 768px) {
+        --grid-gap: 16px;
+    }
+}
+
+/*******************************************************************************
+* Sizes
+*/
+
+$header-border-height: 4px;
+$header-bar-height-sm: 64px;
+$header-bar-height-md: 72px;
+$header-height-sm: $header-bar-height-sm + $header-border-height;
+$header-height-md: $header-bar-height-md + $header-border-height;
+
+$content-max-width: 800px;
+$sidebar-content-width: 224px;
+$sidebar-width: #{$sidebar-content-width + 2 * $padding-x-md};
+$sidebar-padding-top: 32px;
+$sidebar-toggle-width: 32px;
+$sidebar-closed-drawer-width: 0;
+$text-min-content-width: 480px;
+$text-max-content-width: 640px;
+// NB: the side by side layout depends on
+// $graph-min-content-width < $text-max-content-width + $graph-max-content-width
+$graph-min-content-width: 700px;
+$graph-max-content-width: 800px;
+
+$wrapper-max-width: $text-min-content-width + $graph-min-content-width + 3 *
+    $padding-x-md;
+
+$grid-card-min-width: 320px;
+
+$grapher-height: 575px;
+
+$article-cover-height: 224px;
+$article-page-top-offset: 88px;
+
+$search-cta-height: 40px;
+
+// Grapher sizing
+// Keep in sync with DEFAULT_GRAPHER_WIDTH, and the (dynamic/static) thumbnail generation code
+$grapher-thumbnail-width_deprecated: 850px;
+$grapher-thumbnail-height_deprecated: 600px;
+
+// Keep in sync with GRAPHER_THUMBNAIL_WIDTH and GRAPHER_THUMBNAIL_HEIGHT
+$grapher-thumbnail-width: 300px;
+$grapher-thumbnail-height: 160px;
+
+/*******************************************************************************
+* Breakpoints
+*/
+
+// $sm is duplicated in SiteConstants.ts and @ourworldindata/utils/../image.ts
+// Please change them there if you change them here.
+$sm: 768px;
+$md: 960px;
+$lg: 1280px;
+$xlg: 1440px;
+$xxlg: 1536px;
+
+@mixin sm-only {
+    @media (max-width: $sm) {
+        @content;
+    }
+}
+
+@mixin sm-up {
+    @media (min-width: #{$sm + 1}) {
+        @content;
+    }
+}
+
+@mixin md-only {
+    @media (min-width: #{$sm + 1}) and (max-width: $md) {
+        @content;
+    }
+}
+
+@mixin md-down {
+    @media (max-width: $md) {
+        @content;
+    }
+}
+
+@mixin md-up {
+    @media (min-width: #{$md + 1}) {
+        @content;
+    }
+}
+
+@mixin lg-only {
+    @media (min-width: #{$md + 1}) and (max-width: $lg) {
+        @content;
+    }
+}
+
+@mixin lg-down {
+    @media (max-width: $lg) {
+        @content;
+    }
+}
+
+@mixin lg-up {
+    @media (min-width: #{$lg + 1}) {
+        @content;
+    }
+}
+
+@mixin xlg-only {
+    @media (min-width: #{$lg + 1}) and (max-width: $xlg) {
+        @content;
+    }
+}
+
+// Blocks are shown side-by-side from that breakpoint up (when applicable)
+
+@mixin xlg-up {
+    @media only screen and (min-width: #{$xlg + 1}) {
+        @content;
+    }
+}
+
+// mixin duplicated in packages/@ourworldindata/grapher/src/core/grapher.scss
+@mixin xxlg-down {
+    @media only screen and (max-width: $xxlg) {
+        @content;
+    }
+}
+
+// The sidebar is shown from that breakpoint up
+@mixin xxlg-up {
+    @media only screen and (min-width: #{$xxlg + 1}) {
+        @content;
+    }
+}
+
+@mixin touch-device {
+    @media (hover: none) {
+        @content;
+    }
+}
+
+/*******************************************************************************
+ * Z-index
+ */
+
+$zindex-input: 1;
+$zindex-deprecation-notice: 10;
+$zindex-global-entity-select: 11;
+$zindex-footnote: 15;
+$zindex-sidebar: 20;
+$zindex-sidebar-page-overlay: $zindex-sidebar - 1;
+$zindex-popover: 100;
+$zindex-search-overlay: 100;
+$zindex-cookie-notice: 110;
+$zindex-site-header: 120;
+$zindex-extended-header: $zindex-site-header - 1; // ensures search overlays topic-page headers and ToC does not
+$zindex-tooltip: 1070;
+$zindex-lightbox: 99998;
+$zindex-adminbar: 99999;
+
+/*******************************************************************************
+  * Explorers
+  */
+
+$max-width-data-explorer: 1200px;
+
+/*******************************************************************************
+* Icons
+*/
+
+$right-arrow: 'data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M438.6 278.6l-160 160C272.4 444.9 264.2 448 256 448s-16.38-3.125-22.62-9.375c-12.5-12.5-12.5-32.75 0-45.25L338.8 288H32C14.33 288 .0016 273.7 .0016 256S14.33 224 32 224h306.8l-105.4-105.4c-12.5-12.5-12.5-32.75 0-45.25s32.75-12.5 45.25 0l160 160C451.1 245.9 451.1 266.1 438.6 278.6z"/></svg>';
+
+/*******************************************************************************
+* Box Shadows
+*/
+
+$box-shadow-m:
+    0px 0px 0px 0px #31250208,
+    0px 6px 13px 0px #31250208,
+    0px 93px 37px 0px #31250203,
+    0px 145px 41px 0px #31250200;
+
+$box-shadow-xl:
+    0px 0px 0px 0px #00000005,
+    0px 10px 23px 0px #00000005,
+    0px 41px 41px 0px #00000005,
+    0px 92px 55px 0px #00000003,
+    0px 164px 66px 0px #00000000,
+    0px 256px 72px 0px #00000000;
+
+/*******************************************************************************
+* Linear topic pages
+*/
+
+$margin-bottom-section-heading-ltp: 32px;

package/src/config/ChartsConfig.ts

@@ -0,0 +1,163 @@
+/**
+ * Configuration interface for @buildcanada/charts
+ *
+ * This allows customization of branding, API endpoints, and error handling
+ * to make the library work independently of any specific data provider.
+ */
+
+export interface ChartsBranding {
+    /**
+     * Text displayed for the license (e.g., "CC BY")
+     * @default "CC BY"
+     */
+    licenseText?: string
+
+    /**
+     * URL for the license link
+     * @default "https://creativecommons.org/licenses/by/4.0/"
+     */
+    licenseUrl?: string
+
+    /**
+     * Text displayed when showing "Powered by" attribution
+     * @default "Powered by Charts"
+     */
+    poweredByText?: string
+
+    /**
+     * URL for the "Powered by" link
+     */
+    poweredByUrl?: string
+
+    /**
+     * Support email for error messages
+     */
+    supportEmail?: string
+
+    /**
+     * Custom tooltip text for the license/attribution section
+     */
+    licenseTooltip?: string
+
+    /**
+     * Custom logos to use in charts
+     */
+    logos?: Record<string, LogoConfig>
+}
+
+export interface LogoConfig {
+    svg: string
+    width: number
+    height: number
+    url?: string
+}
+
+export interface ChartsDataApi {
+    /**
+     * Base URL for the data API
+     * Example: "https://api.example.com/v1/indicators/"
+     */
+    baseUrl: string
+
+    /**
+     * Custom route builder for variable data
+     * If not provided, uses default: `${baseUrl}/${variableId}.data.json`
+     */
+    getVariableDataRoute?: (variableId: number) => string
+
+    /**
+     * Custom route builder for variable metadata
+     * If not provided, uses default: `${baseUrl}/${variableId}.metadata.json`
+     */
+    getVariableMetadataRoute?: (variableId: number) => string
+}
+
+export interface ChartsErrorReporting {
+    /**
+     * Whether error reporting is enabled
+     */
+    enabled: boolean
+
+    /**
+     * Custom error handler function
+     * Use this to integrate with your error tracking service (e.g., Sentry, LogRocket)
+     */
+    handler?: (error: Error, context: Record<string, unknown>) => void
+}
+
+export interface ChartsAnalytics {
+    /**
+     * Whether analytics is enabled
+     */
+    enabled: boolean
+
+    /**
+     * Custom analytics handler
+     */
+    trackEvent?: (
+        eventName: string,
+        properties: Record<string, unknown>
+    ) => void
+}
+
+export interface ChartsConfig {
+    /**
+     * Branding configuration for customizing the appearance
+     */
+    branding?: ChartsBranding
+
+    /**
+     * Data API configuration
+     */
+    dataApi: ChartsDataApi
+
+    /**
+     * Error reporting configuration
+     */
+    errorReporting?: ChartsErrorReporting
+
+    /**
+     * Analytics configuration
+     */
+    analytics?: ChartsAnalytics
+}
+
+/**
+ * Default configuration values
+ */
+export const defaultChartsConfig: Partial<ChartsConfig> = {
+    branding: {
+        licenseText: "CC BY",
+        licenseUrl: "https://creativecommons.org/licenses/by/4.0/",
+        poweredByText: "Powered by Build Canada Charts",
+    },
+    errorReporting: {
+        enabled: false,
+    },
+    analytics: {
+        enabled: false,
+    },
+}
+
+/**
+ * Merge user config with defaults
+ */
+export function mergeWithDefaults(
+    config: ChartsConfig
+): Required<ChartsConfig> {
+    return {
+        branding: {
+            ...defaultChartsConfig.branding,
+            ...config.branding,
+        },
+        dataApi: config.dataApi,
+        errorReporting: {
+            ...defaultChartsConfig.errorReporting,
+            ...config.errorReporting,
+        },
+        analytics: {
+            ...defaultChartsConfig.analytics,
+            ...config.analytics,
+        },
+    } as Required<ChartsConfig>
+}

package/src/config/ChartsProvider.tsx

@@ -0,0 +1,157 @@
+import * as React from "react"
+import { createContext, useContext, useMemo } from "react"
+
+import {
+    ChartsConfig,
+    defaultChartsConfig,
+    mergeWithDefaults,
+} from "./ChartsConfig"
+
+/**
+ * Context for charts configuration
+ */
+const ChartsContext = createContext<Required<ChartsConfig> | null>(null)
+
+export interface ChartsProviderProps {
+    /**
+     * Configuration for the charts library
+     */
+    config: ChartsConfig
+
+    /**
+     * Child components that will have access to the configuration
+     */
+    children: React.ReactNode
+}
+
+/**
+ * Provider component for charts configuration.
+ *
+ * Wrap your application or chart components with this provider to configure
+ * branding, API endpoints, and error handling.
+ *
+ * @example
+ * ```tsx
+ * const config = {
+ *   branding: {
+ *     poweredByText: 'My Organization',
+ *     licenseText: 'CC BY 4.0'
+ *   },
+ *   dataApi: {
+ *     baseUrl: 'https://api.example.com/v1/indicators/'
+ *   }
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <ChartsProvider config={config}>
+ *       <Grapher {...chartProps} />
+ *     </ChartsProvider>
+ *   )
+ * }
+ * ```
+ */
+export function ChartsProvider({
+    config,
+    children,
+}: ChartsProviderProps): React.ReactElement {
+    const mergedConfig = useMemo(() => mergeWithDefaults(config), [config])
+
+    return (
+        <ChartsContext.Provider value={mergedConfig}>
+            {children}
+        </ChartsContext.Provider>
+    )
+}
+
+/**
+ * Hook to access the charts configuration.
+ *
+ * Must be used within a ChartsProvider.
+ *
+ * @throws Error if used outside of ChartsProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const config = useChartsConfig()
+ *   return <div>Powered by: {config.branding.poweredByText}</div>
+ * }
+ * ```
+ */
+export function useChartsConfig(): Required<ChartsConfig> {
+    const config = useContext(ChartsContext)
+
+    if (!config) {
+        throw new Error(
+            "useChartsConfig must be used within a ChartsProvider. " +
+                "Wrap your component tree with <ChartsProvider config={...}>."
+        )
+    }
+
+    return config
+}
+
+/**
+ * Hook to access the charts configuration, returning undefined if not in a provider.
+ *
+ * Use this for optional configuration access where a fallback is acceptable.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const config = useMaybeChartsConfig()
+ *   const brandingText = config?.branding.poweredByText ?? 'Default'
+ *   return <div>Powered by: {brandingText}</div>
+ * }
+ * ```
+ */
+export function useMaybeChartsConfig(): Required<ChartsConfig> | undefined {
+    return useContext(ChartsContext) ?? undefined
+}
+
+/**
+ * Get a fallback configuration for use outside of a provider.
+ *
+ * This creates a minimal configuration with the provided data API URL.
+ * Useful for standalone usage or testing.
+ */
+export function createFallbackConfig(
+    dataApiBaseUrl: string
+): Required<ChartsConfig> {
+    return mergeWithDefaults({
+        dataApi: {
+            baseUrl: dataApiBaseUrl,
+        },
+    })
+}
+
+/**
+ * Report an error using the configured error handler.
+ *
+ * Falls back to console.error if no handler is configured.
+ */
+export function reportError(
+    config: Required<ChartsConfig> | undefined,
+    error: Error,
+    context: Record<string, unknown> = {}
+): void {
+    if (config?.errorReporting?.enabled && config.errorReporting.handler) {
+        config.errorReporting.handler(error, context)
+    } else {
+        console.error("Chart error:", error, context)
+    }
+}
+
+/**
+ * Track an analytics event using the configured handler.
+ */
+export function trackEvent(
+    config: Required<ChartsConfig> | undefined,
+    eventName: string,
+    properties: Record<string, unknown> = {}
+): void {
+    if (config?.analytics?.enabled && config.analytics.trackEvent) {
+        config.analytics.trackEvent(eventName, properties)
+    }
+}

package/src/config/index.ts

@@ -0,0 +1,20 @@
+export {
+    type ChartsConfig,
+    type ChartsBranding,
+    type ChartsDataApi,
+    type ChartsErrorReporting,
+    type ChartsAnalytics,
+    type LogoConfig,
+    defaultChartsConfig,
+    mergeWithDefaults,
+} from "./ChartsConfig"
+
+export {
+    ChartsProvider,
+    type ChartsProviderProps,
+    useChartsConfig,
+    useMaybeChartsConfig,
+    createFallbackConfig,
+    reportError,
+    trackEvent,
+} from "./ChartsProvider"