@buildcanada/charts 0.1.0

package/src/types/OwidVariable.ts

@@ -0,0 +1,133 @@
+import { OwidOrigin } from "./OwidOrigin.js"
+import { OwidSource } from "./OwidSource.js"
+import { OwidVariableDisplayConfigInterface } from "./OwidVariableDisplayConfigInterface.js"
+
+export interface OwidVariableWithSource {
+    id: number
+    name?: string
+    description?: string
+    descriptionShort?: string
+    descriptionFromProducer?: string
+    descriptionKey?: string[]
+    descriptionProcessing?: string
+    unit?: string
+    display?: OwidVariableDisplayConfigInterface
+    shortUnit?: string
+    datasetName?: string
+    datasetId?: number
+    coverage?: string
+    nonRedistributable?: boolean
+    source?: OwidSource
+    origins?: OwidOrigin[]
+    schemaVersion?: number
+    processingLevel?: OwidProcessingLevel
+    presentation?: OwidVariablePresentation
+    shortName?: string
+    timespan?: string
+    catalogPath?: string
+    license?: OwidLicense
+    updatePeriodDays?: number
+    datasetVersion?: string
+    licenses?: OwidLicense[]
+    type?: OwidVariableType
+
+    // omitted:
+    // code
+    // coverage
+    // dataPath
+    // metadataPath
+}
+
+export interface IndicatorTitleWithFragments {
+    title: string
+    attributionShort?: string
+    titleVariant?: string
+}
+
+export function joinTitleFragments(
+    attributionShort: string | undefined,
+    titleVariant: string | undefined
+): string | undefined {
+    if (attributionShort && titleVariant && attributionShort !== titleVariant) {
+        return `${titleVariant} – ${attributionShort}`
+    }
+    if (attributionShort) {
+        return attributionShort
+    }
+    if (titleVariant) {
+        return titleVariant
+    }
+    return undefined
+}
+
+export interface OwidLicense {
+    name: string
+    url: string
+}
+
+export interface OwidVariablePresentation {
+    titlePublic?: string
+    titleVariant?: string
+    attributionShort?: string
+    attribution?: string
+    topicTagsLinks?: string[]
+    faqs?: FaqLink[]
+}
+
+export type OwidProcessingLevel = "minor" | "major"
+
+export interface FaqLink {
+    gdocId: string
+    fragmentId: string
+}
+
+export type OwidVariableWithSourceAndDimension = OwidVariableWithSource & {
+    dimensions: OwidVariableDimensions
+}
+
+export type OwidVariableWithSourceAndDimensionWithoutId = Omit<
+    OwidVariableWithSourceAndDimension,
+    "id"
+>
+
+export interface OwidVariableMixedData {
+    years: number[]
+    entities: number[]
+    values: (string | number)[]
+}
+
+export type OwidVariableWithDataAndSource = OwidVariableWithSource &
+    OwidVariableMixedData
+
+export interface OwidVariableDimension {
+    values: OwidVariableDimensionValuePartial[]
+}
+
+export interface OwidVariableDimensions {
+    years: OwidVariableDimension
+    entities: OwidVariableDimension
+    values?: OwidVariableDimension
+}
+
+export type OwidVariableDataMetadataDimensions = {
+    data: OwidVariableMixedData
+    metadata: OwidVariableWithSourceAndDimension
+}
+export type MultipleOwidVariableDataDimensionsMap = Map<
+    number,
+    OwidVariableDataMetadataDimensions
+>
+
+export interface OwidVariableDimensionValuePartial {
+    id: number
+    name?: string
+    code?: string
+}
+export type OwidVariableDimensionValueFull =
+    Required<OwidVariableDimensionValuePartial>
+
+export interface OwidEntityKey {
+    [id: string]: OwidVariableDimensionValuePartial
+}
+
+export type OwidVariableType = "string" | "float" | "int" | "mixed" | "ordinal"

package/src/types/OwidVariableDisplayConfigInterface.ts

@@ -0,0 +1,49 @@
+import { OwidVariableId } from "./domainTypes/Various.js"
+import {
+    ColumnSlug,
+    DimensionProperty,
+    Time,
+} from "./grapherTypes/GrapherTypes.js"
+
+export interface OwidVariableDisplayConfigInterface {
+    name?: string
+    unit?: string
+    shortUnit?: string
+    isProjection?: boolean
+    conversionFactor?: number
+    roundingMode?: OwidVariableRoundingMode
+    numDecimalPlaces?: number
+    numSignificantFigures?: number
+    tolerance?: number
+    yearIsDay?: boolean
+    zeroDay?: string
+    entityAnnotationsMap?: string
+    includeInTable?: boolean
+    tableDisplay?: OwidVariableDataTableConfigInterface
+    color?: string
+    plotMarkersOnlyInLineChart?: boolean
+}
+
+// todo: flatten onto the above
+export interface OwidVariableDataTableConfigInterface {
+    hideAbsoluteChange?: boolean
+    hideRelativeChange?: boolean
+}
+
+export enum OwidVariableRoundingMode {
+    decimalPlaces = "decimalPlaces",
+    significantFigures = "significantFigures",
+}
+
+export interface OwidChartDimensionInterface {
+    property: DimensionProperty
+    targetYear?: Time
+    display?: OwidVariableDisplayConfigInterface
+    variableId: OwidVariableId
+    slug?: ColumnSlug
+}
+
+export interface OwidChartDimensionInterfaceWithMandatorySlug
+    extends OwidChartDimensionInterface {
+    slug: ColumnSlug
+}

package/src/types/analyticsTypes.ts

@@ -0,0 +1,54 @@
+/**
+ * Minimal analytics type stubs for chart functionality.
+ * These are simplified versions - actual analytics implementation
+ * should be provided by the consuming application.
+ */
+
+export enum EventCategory {
+    GrapherView = "grapher_view",
+    GrapherClick = "grapher_click",
+    GrapherHover = "grapher_hover",
+    GrapherError = "grapher_error",
+    GrapherEntitySelector = "grapher_entity_selector",
+    ExplorerView = "explorer_view",
+    ExplorerCountrySelector = "explorer_country_selector",
+    GlobalEntitySelectorUsage = "global_entity_selector_usage",
+    SiteClick = "site_click",
+    SiteFormSubmit = "site_form_submit",
+    KeyboardShortcut = "keyboard_shortcut",
+}
+
+export type EntityControlEvent = "open" | "change" | "close"
+
+export type EntitySelectorEvent =
+    | "enter"
+    | "select"
+    | "deselect"
+    | "sortBy"
+    | "sortOrder"
+    | "filterBy"
+    | "clear"
+
+export type GrapherImageDownloadEvent =
+    | "chart_download_png"
+    | "chart_download_svg"
+
+export type GrapherInteractionEvent =
+    | "map_country_hover"
+    | "map_legend_hover"
+
+export enum GrapherErrorAction {
+    GrapherViewError = "grapher_view_error",
+    EntitiesNotFound = "entities_not_found",
+}
+
+export interface GrapherAnalyticsContext {
+    slug?: string
+    viewConfigId?: string
+    narrativeChartName?: string
+}
+
+export interface GAEvent {
+    event: string
+    [key: string]: unknown
+}

package/src/types/dbTypes/Tags.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal stub types for database tags.
+ * These are simplified versions for type compatibility.
+ */
+
+export interface DbPlainTag {
+    id: number
+    name: string
+    slug: string | null
+    parentId?: number
+}

package/src/types/domainTypes/Archive.ts

@@ -0,0 +1,139 @@
+export type ArchivalDateString = `${number}-${number}`
+export const ARCHIVE_DATE_TIME_FORMAT = "YYYYMMDD-HHmmss" // e.g. 20250414-074331, always UTC
+
+export type AssetMap = Record<string, string>
+
+export type IndicatorChecksums = {
+    [id: string]: { metadataChecksum: string; dataChecksum: string }
+}
+
+export interface UrlAndMaybeDate {
+    url: string
+    date?: Date | ArchivalDateString
+}
+
+export type ArchiveContentType = "data" | "writing"
+
+export interface ArchiveSiteNavigationInfo {
+    contentType: ArchiveContentType
+    liveUrl?: string
+    previousVersion?: UrlAndMaybeDate
+    nextVersion?: UrlAndMaybeDate
+    versionsFileUrl?: string
+}
+
+// Information about an archived page version that is available, i.e. we can point to from the live site
+export interface ArchivedPageVersion {
+    archivalDate: ArchivalDateString
+    archiveUrl: string
+    versionsFileUrl?: string
+    type: "archived-page-version"
+}
+
+// Information about an archived chart that is necessary for rendering the archived page, incl. navigation and assets
+export interface ArchiveMetaInformation
+    extends Omit<ArchivedPageVersion, "type"> {
+    archiveNavigation: ArchiveSiteNavigationInfo
+    assets: {
+        runtime: AssetMap
+        static?: AssetMap
+    }
+    type: "archive-page"
+}
+
+export type ArchiveContext = ArchivedPageVersion | ArchiveMetaInformation
+
+export interface ArchiveVersions {
+    chartId: number
+    versions: Array<{
+        archivalDate: ArchivalDateString
+        slug: string
+        url: string
+    }>
+}
+
+export interface GrapherChecksums {
+    chartConfigMd5: string
+    indicators: IndicatorChecksums
+}
+
+export interface GrapherChecksumsObjectWithHash {
+    chartId: number
+    chartSlug: string
+    checksums: GrapherChecksums
+    checksumsHashed: string
+}
+
+export interface MultiDimChecksums {
+    multiDimConfigMd5: string
+    chartConfigs: {
+        [id: string]: string // chartConfigId -> MD5
+    }
+    indicators: IndicatorChecksums
+}
+
+export interface MultiDimChecksumsObjectWithHash {
+    multiDimId: number
+    multiDimSlug: string
+    checksums: MultiDimChecksums
+    checksumsHashed: string
+}
+
+export interface ExplorerChecksums {
+    explorerConfigMd5: string
+    chartConfigs: {
+        [id: string]: string // chartId -> chart_configs.fullMd5 of explorer view configs
+    }
+    indicators: IndicatorChecksums
+}
+
+export interface ExplorerChecksumsObjectWithHash {
+    explorerSlug: string
+    checksums: ExplorerChecksums
+    checksumsHashed: string
+}
+
+export interface PostChecksums {
+    postContentMd5: string
+    indicators: IndicatorChecksums // Shared across all chart types
+    graphers: {
+        [chartId: string]: {
+            slug: string
+            chartConfigMd5: string
+        }
+    }
+    explorers: {
+        [slug: string]: {
+            explorerConfigMd5: string
+            chartConfigs: {
+                [id: string]: string // chartConfigId -> MD5
+            }
+        }
+    }
+    multiDims: {
+        [multiDimId: string]: {
+            slug: string
+            multiDimConfigMd5: string
+            chartConfigs: {
+                [id: string]: string // chartConfigId -> MD5
+            }
+        }
+    }
+    narrativeCharts: {
+        [narrativeChartId: string]: {
+            name: string
+            chartConfigMd5: string
+            queryParamsForParentChartMd5: string
+        }
+    }
+    images: {
+        [imageId: string]: { filename: string; hash: string }
+    }
+}
+
+export interface PostChecksumsObjectWithHash {
+    postId: string
+    postSlug: string
+    checksums: PostChecksums
+    checksumsHashed: string
+}

package/src/types/domainTypes/Author.ts

@@ -0,0 +1,28 @@
+export interface DbRawLatestWork {
+    id: string
+    slug: string
+    title: string
+    subtitle: string | null
+    authors: string
+    "featured-image": string | null
+    publishedAt: string
+}
+
+export interface DbEnrichedLatestWork {
+    id: string
+    slug: string
+    title: string
+    subtitle: string | null
+    authors: string[]
+    "featured-image": string | null
+    publishedAt: string
+}
+
+export const parseLatestWork = (
+    latestWork: DbRawLatestWork
+): DbEnrichedLatestWork => {
+    return {
+        ...latestWork,
+        authors: JSON.parse(latestWork.authors),
+    }
+}

package/src/types/domainTypes/ContentGraph.ts

@@ -0,0 +1,76 @@
+import { DbPlainTag } from "../dbTypes/Tags.js"
+import { OwidGdocType } from "../gdocTypes/Gdoc.js"
+
+export interface EntryMeta {
+    slug: string
+    title: string
+}
+
+export interface CategoryWithEntries {
+    name: string
+    slug: string
+    entries: EntryMeta[]
+    subcategories?: CategoryWithEntries[]
+}
+
+export const TagGraphTableName = "tag_graph"
+
+export type DbInsertTagGraphNode = {
+    parentId: number
+    childId: number
+    weight?: number
+    updatedAt?: string
+}
+
+export type DbPlainTagGraphNode = Required<DbInsertTagGraphNode>
+
+export const TagGraphRootName = "tag-graph-root" as const
+
+export type FlatTagGraphNode = Pick<DbPlainTag, "name" | "slug"> & {
+    weight: number
+    isTopic: boolean
+    parentId: number
+    childId: number
+    slug: string | null
+}
+
+export type FlatTagGraph = Record<number, FlatTagGraphNode[]>
+
+export interface TagGraphNode {
+    children: TagGraphNode[]
+    id: number
+    isTopic: boolean
+    name: string
+    path: number[]
+    slug: string | null
+    weight: number
+}
+
+export type TagGraphRoot = TagGraphNode & {
+    children: TagGraphNode[]
+    id: number
+    isTopic: false
+    name: typeof TagGraphRootName
+    path: [number]
+    slug: null
+    weight: 0
+}
+
+export interface PostReference {
+    id: string
+    title: string
+    slug: string
+    url: string
+    type: OwidGdocType
+}
+
+export enum ContentGraphLinkType {
+    Gdoc = "gdoc",
+    Url = "url",
+    Grapher = "grapher",
+    Explorer = "explorer",
+    NarrativeChart = "narrative-chart",
+    StaticViz = "static-viz",
+    Dod = "dod",
+    GuidedChart = "guided-chart",
+}