@buildcanada/charts 0.1.0

package/src/types/domainTypes/StaticViz.ts

@@ -0,0 +1,64 @@
+import { z } from "zod"
+
+export const StaticVizTableName = "static_viz"
+
+export interface DbRawStaticViz {
+    id: number
+    name: string
+    description: string | null
+    grapherSlug: string | null
+    sourceUrl: string | null
+    imageId: number
+    mobileImageId: number | null
+    createdBy: number | null
+    updatedBy: number | null
+    createdAt: Date
+    updatedAt: Date
+}
+
+type StaticVizImage = {
+    id: number
+    cloudflareId: string
+    filename: string
+    originalHeight: number
+    originalWidth: number
+}
+
+// A type for rendering the static viz admin, with images resolved and user names instead of numeric IDs
+export type DbEnrichedStaticViz = Omit<
+    DbRawStaticViz,
+    "createdBy" | "updatedBy" | "imageId" | "mobileImageId"
+> & {
+    desktop?: StaticVizImage
+    mobile?: StaticVizImage
+    name: string
+    grapherSlug?: string
+    chartId?: number
+    sourceUrl?: string
+    description?: string
+    createdBy: string
+    updatedBy: string
+}
+
+export const StaticVizInsertSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().nullable().optional(),
+    grapherSlug: z.string().nullable().optional(),
+    sourceUrl: z.string().nullable().optional(),
+    imageId: z.number().min(1),
+    mobileImageId: z.number().min(1).nullable().optional(),
+    createdBy: z.number().min(1).nullable().optional(),
+    updatedBy: z.number().min(1).nullable().optional(),
+})
+
+export const StaticVizUpdateSchema = z.object({
+    name: z.string().min(1).optional(),
+    description: z.string().nullable().optional(),
+    grapherSlug: z.string().nullable().optional(),
+    sourceUrl: z.string().nullable().optional(),
+    imageId: z.number().min(1).optional(),
+    mobileImageId: z.number().min(1).nullable().optional(),
+    updatedBy: z.number().min(1).nullable().optional(),
+})
+
+export type StaticVizUpdate = z.infer<typeof StaticVizUpdateSchema>

package/src/types/domainTypes/Toc.ts

@@ -0,0 +1,11 @@
+export interface TocHeading {
+    text: string
+    html?: string // used by SectionHeading toc. Excluded from LongFormPage toc.
+    slug: string
+    isSubheading: boolean
+}
+
+export interface TocHeadingWithTitleSupertitle extends TocHeading {
+    title: string
+    supertitle?: string
+}

package/src/types/domainTypes/Tombstone.ts

@@ -0,0 +1,19 @@
+export type CreateTombstoneData = {
+    reason?: string
+    includeArchiveLink?: boolean
+    relatedLinkUrl?: string
+    relatedLinkTitle?: string
+    relatedLinkDescription?: string
+    relatedLinkThumbnail?: string
+}
+
+export type TombstonePageData = {
+    slug: string
+    reason: string
+    includeArchiveLink: boolean
+    relatedLinkUrl: string
+    relatedLinkTitle: string
+    relatedLinkDescription: string
+    relatedLinkThumbnail: string
+    archiveUrl?: string
+}

package/src/types/domainTypes/Various.ts

@@ -0,0 +1,79 @@
+import { Nominal } from "../NominalType"
+
+export type Integer = number
+
+export type OwidVariableId = Integer // remove.
+
+export type JsonString = string
+export type Base64String = Nominal<string, "Base64">
+export type HexString = Nominal<string, "Hex">
+
+/**
+ * Pageview information about a single URL
+ */
+export interface RawPageview {
+    day: Date
+    url: string
+    views_7d: number
+    views_14d: number
+    views_365d: number
+}
+
+export interface UserCountryInformation {
+    code: string
+    name: string
+    short_code: string
+    slug: string
+    regions: string[] | null
+}
+
+export enum SiteFooterContext {
+    gdocsDocument = "gdocsDocument", // the rendered version (on the site)
+    grapherPage = "grapherPage",
+    dataPageV2 = "dataPageV2",
+    multiDimDataPage = "multiDimDataPage",
+    dynamicCollectionPage = "dynamicCollectionPage",
+    explorerPage = "explorerPage",
+    explorerIndexPage = "explorerIndexPage",
+    default = "default",
+    dataInsightsIndexPage = "data-insights-index-page",
+    searchPage = "search-page",
+    subscribePage = "subscribe-page",
+}
+
+export interface GitCommit {
+    author_email: string
+    author_name: string
+    body: string
+    date: string
+    hash: string
+    message: string
+}
+export interface SerializedGridProgram {
+    slug: string
+    program: string
+    lastCommit?: GitCommit
+}
+
+export enum TaggableType {
+    Charts = "charts",
+}
+
+// Exception format that can be easily given as an API error
+export class JsonError extends Error {
+    status: number
+    constructor(message: string, status?: number, options?: ErrorOptions) {
+        super(message, options)
+        this.status = status ?? 400
+    }
+}
+
+export interface QueryParams {
+    [key: string]: string | undefined
+}
+
+export enum R2GrapherConfigDirectory {
+    byUUID = "config/by-uuid",
+    publishedGrapherBySlug = "config/by-slug-published",
+    multiDim = "multi-dim-config",
+}

package/src/types/gdocTypes/Gdoc.ts

@@ -0,0 +1,280 @@
+/**
+ * Stub types for Google Docs integration.
+ * These are simplified versions of the full OWID gdocTypes.
+ * Most Google Docs CMS functionality is not needed for the standalone charts library,
+ * but the types are required for compilation.
+ */
+
+import { QueryParams } from "../domainTypes/Various.js"
+import { ArchivedPageVersion } from "../domainTypes/Archive.js"
+
+/**
+ * Document types in the OWID CMS.
+ */
+export enum OwidGdocType {
+    Article = "article",
+    TopicPage = "topic-page",
+    LinearTopicPage = "linear-topic-page",
+    DataInsight = "data-insight",
+    Homepage = "homepage",
+    AboutPage = "about-page",
+    Author = "author",
+    Fragment = "fragment",
+    Announcement = "announcement",
+    Profile = "profile",
+}
+
+/**
+ * Information about a narrative chart embedded in content.
+ */
+export interface NarrativeChartInfo {
+    name: string
+    title: string
+    chartConfigId: string
+    parentChartSlug: string
+    queryParamsForParentChart: QueryParams
+    latestArchivedParent?: ArchivedPageVersion
+}
+
+/**
+ * Detail on demand entry - used for interactive tooltips on terms.
+ */
+export interface EnrichedDetail {
+    id: string
+    text: string
+}
+
+/**
+ * Dictionary mapping term IDs to their detail definitions.
+ */
+export type DetailDictionary = Record<string, EnrichedDetail>
+
+// =====================================================
+// Stub types for CMS integration
+// These are minimal stubs for type compatibility.
+// The actual CMS functionality is not used by the charts library.
+// =====================================================
+
+/**
+ * User country information from geolocation.
+ */
+export interface UserCountryInformation {
+    code: string
+    name: string
+    short_code_v2?: string
+    continent?: string
+    regions?: string[]
+}
+
+/**
+ * Base interface for Gdoc content.
+ */
+export interface OwidGdocBaseInterface {
+    id: string
+    slug: string
+    content: OwidGdocContent
+    published: boolean
+    createdAt: Date
+    publishedAt: Date | null
+    updatedAt: Date | null
+    // Allow additional properties for CMS-specific fields
+    contentMd5?: string
+    breadcrumbs?: unknown
+    manualBreadcrumbs?: unknown
+    tags?: unknown[]
+    linkedAuthors?: unknown[]
+    linkedDocuments?: unknown[]
+    linkedStaticViz?: unknown[]
+    linkedCharts?: unknown[]
+    linkedNarrativeCharts?: unknown[]
+    linkedIndicators?: unknown[]
+    imageMetadata?: unknown
+    relatedCharts?: unknown[]
+    donors?: unknown
+    homepageMetadata?: unknown
+    latestDataInsights?: unknown[]
+    latestWorkLinks?: unknown[]
+    [key: string]: unknown
+}
+
+/**
+ * Gdoc content type.
+ */
+export interface OwidGdocContent {
+    type: OwidGdocType
+    title?: string
+    body?: OwidEnrichedGdocBlock[]
+    [key: string]: unknown
+}
+
+/**
+ * Generic Gdoc interface.
+ */
+export type OwidGdoc =
+    | OwidGdocPostInterface
+    | OwidGdocDataInsightInterface
+    | OwidGdocAuthorInterface
+    | OwidGdocAboutInterface
+    | OwidGdocHomepageInterface
+
+/**
+ * JSON representation of a Gdoc.
+ */
+export interface OwidGdocJSON {
+    id: string
+    slug: string
+    content: OwidGdocContent
+    published: boolean
+    createdAt: string
+    publishedAt: string | null
+    updatedAt: string | null
+    [key: string]: unknown
+}
+
+/**
+ * Post (article/topic page) interface.
+ */
+export interface OwidGdocPostInterface extends OwidGdocBaseInterface {
+    content: OwidGdocPostContent
+}
+
+export interface OwidGdocPostContent extends OwidGdocContent {
+    type:
+        | OwidGdocType.Article
+        | OwidGdocType.TopicPage
+        | OwidGdocType.LinearTopicPage
+        | OwidGdocType.Fragment
+        | OwidGdocType.AboutPage
+}
+
+/**
+ * Data insight interface.
+ */
+export interface OwidGdocDataInsightInterface extends OwidGdocBaseInterface {
+    content: OwidGdocDataInsightContent
+}
+
+export interface OwidGdocDataInsightContent extends OwidGdocContent {
+    type: OwidGdocType.DataInsight
+}
+
+/**
+ * Author interface.
+ */
+export interface OwidGdocAuthorInterface extends OwidGdocBaseInterface {
+    content: OwidGdocAuthorContent
+}
+
+export interface OwidGdocAuthorContent extends OwidGdocContent {
+    type: OwidGdocType.Author
+}
+
+/**
+ * About page interface.
+ */
+export interface OwidGdocAboutInterface extends OwidGdocBaseInterface {
+    content: OwidGdocAboutContent
+}
+
+export interface OwidGdocAboutContent extends OwidGdocContent {
+    type: OwidGdocType.AboutPage
+}
+
+/**
+ * Homepage interface.
+ */
+export interface OwidGdocHomepageInterface extends OwidGdocBaseInterface {
+    content: OwidGdocHomepageContent
+}
+
+export interface OwidGdocHomepageContent extends OwidGdocContent {
+    type: OwidGdocType.Homepage
+}
+
+// =====================================================
+// Block and Span types (for content traversal)
+// =====================================================
+
+/**
+ * Base interface for enriched Gdoc blocks.
+ */
+export interface OwidEnrichedGdocBlock {
+    type: string
+    parseErrors?: unknown[]
+    [key: string]: unknown
+}
+
+/**
+ * Base interface for spans (inline content).
+ */
+export interface Span {
+    spanType: string
+    children?: Span[]
+    [key: string]: unknown
+}
+
+/**
+ * Key insights slide block.
+ */
+export interface EnrichedBlockKeyInsightsSlide extends OwidEnrichedGdocBlock {
+    type: "key-insights-slide"
+    title?: string
+    [key: string]: unknown
+}
+
+/**
+ * Topic page intro related topic.
+ */
+export interface EnrichedTopicPageIntroRelatedTopic {
+    text?: string
+    url?: string
+    [key: string]: unknown
+}
+
+/**
+ * Topic page intro download button.
+ */
+export interface EnrichedTopicPageIntroDownloadButton {
+    text?: string
+    url?: string
+    [key: string]: unknown
+}
+
+/**
+ * Hybrid link (can be internal or external).
+ */
+export interface EnrichedHybridLink {
+    url?: string
+    text?: string
+    [key: string]: unknown
+}
+
+// =====================================================
+// TOC types
+// =====================================================
+
+/**
+ * Table of contents heading with title and supertitle.
+ */
+export interface TocHeadingWithTitleSupertitle {
+    text: string
+    slug: string
+    isSubheading?: boolean
+    supertitle?: string
+}
+
+// =====================================================
+// Data display types
+// =====================================================
+
+/**
+ * Source information for display in data pages.
+ */
+export interface DisplaySource {
+    label: string
+    description?: string
+    dataPublishedBy?: string
+    retrievedOn?: string
+    retrievedFrom?: string
+    citation?: string
+}

package/src/types/grapherTypes/BinningStrategyTypes.ts

@@ -0,0 +1,46 @@
+export const logBinningStrategies = [
+    "log-auto",
+    "log-1-2-5",
+    "log-1-3",
+    "log-10",
+] as const
+
+export const equalSizeBinningStrategies = [
+    "equalSizeBins-normal",
+    "equalSizeBins-few-bins",
+    "equalSizeBins-many-bins",
+    "equalSizeBins-percent",
+] as const
+
+export const automaticBinningStrategies = [
+    "auto",
+    ...logBinningStrategies,
+    ...equalSizeBinningStrategies,
+] as const
+
+export const binningStrategiesIncludingManual = [
+    "manual",
+    ...automaticBinningStrategies,
+] as const
+
+export type LogBinningStrategy = (typeof logBinningStrategies)[number]
+export type EqualSizeBinningStrategy =
+    (typeof equalSizeBinningStrategies)[number]
+
+export type ResolvedLogBinningStrategy = Exclude<LogBinningStrategy, "log-auto">
+
+export type AutomaticBinningStrategy =
+    (typeof automaticBinningStrategies)[number]
+
+export type ResolvedBinningStrategy = Exclude<AutomaticBinningStrategy, "auto">
+export type BinningStrategyIncludingManual =
+    (typeof binningStrategiesIncludingManual)[number]
+
+export const binningMidpointModes = [
+    undefined, // Automatic
+    "none", // No midpoint
+    "symmetric", // Symmetric bins around a midpoint, with negBins = -1 * posBins
+    "same-num-bins", // Symmetric bins around a midpoint, with negBins.length = posBins.length
+    "asymmetric", // Bins around a midpoint, with negBins.length not necessarily equal to posBins.length
+] as const
+export type MidpointMode = (typeof binningMidpointModes)[number]

package/src/types/grapherTypes/GrapherConstants.ts

@@ -0,0 +1,53 @@
+// todo: remove when we ditch Year and YearIsDay
+export const EPOCH_DATE = "2020-01-21"
+
+/** The "plot" is a chart without any header, footer or controls */
+export const IDEAL_PLOT_ASPECT_RATIO = 1.8
+
+export const GRAPHER_MAP_TYPE = "WorldMap"
+
+export const GRAPHER_CHART_TYPES = {
+    LineChart: "LineChart",
+    ScatterPlot: "ScatterPlot",
+    StackedArea: "StackedArea",
+    DiscreteBar: "DiscreteBar",
+    StackedDiscreteBar: "StackedDiscreteBar",
+    SlopeChart: "SlopeChart",
+    StackedBar: "StackedBar",
+    Marimekko: "Marimekko",
+} as const
+
+export const ALL_GRAPHER_CHART_TYPES = Object.values(GRAPHER_CHART_TYPES)
+
+/**
+ * Grapher tab specified in the config that determines the default tab to show.
+ * If `chart` is selected and Grapher has more than one chart tab, then the
+ * first chart tab will be active.
+ */
+export const GRAPHER_TAB_CONFIG_OPTIONS = {
+    // general
+    table: "table",
+    map: "map",
+    chart: "chart",
+
+    // chart types
+    line: "line",
+    scatter: "scatter",
+    "stacked-area": "stacked-area",
+    "discrete-bar": "discrete-bar",
+    "stacked-discrete-bar": "stacked-discrete-bar",
+    slope: "slope",
+    "stacked-bar": "stacked-bar",
+    marimekko: "marimekko",
+} as const
+
+/** Internal tab names used in Grapher */
+export const GRAPHER_TAB_NAMES = {
+    Table: "Table",
+    WorldMap: "WorldMap",
+
+    ...GRAPHER_CHART_TYPES,
+} as const
+
+/** Valid values for the `tab` query parameter in Grapher */
+export const GRAPHER_TAB_QUERY_PARAMS = GRAPHER_TAB_CONFIG_OPTIONS