@buildcanada/charts 0.1.0

package/src/utils/archival/archivalDate.ts

@@ -0,0 +1,48 @@
+import {
+    ARCHIVE_DATE_TIME_FORMAT,
+    ArchivalDateString,
+} from "../../types/index.js"
+import dayjs from "../dayjs.js"
+
+export interface ArchivalTimestamp {
+    date: Date
+    formattedDate: ArchivalDateString
+}
+
+export type DateInput = Date | ArchivalDateString | string | dayjs.Dayjs
+
+export const parseArchivalDate = (dateInput: DateInput): dayjs.Dayjs => {
+    if (typeof dateInput === "string") {
+        if (dateInput.length === ARCHIVE_DATE_TIME_FORMAT.length)
+            return dayjs.utc(dateInput, ARCHIVE_DATE_TIME_FORMAT)
+        else return dayjs.utc(dateInput)
+    }
+    return dayjs.utc(dateInput)
+}
+
+export const formatAsArchivalDate = (date: dayjs.Dayjs): ArchivalDateString =>
+    date.format(ARCHIVE_DATE_TIME_FORMAT) as ArchivalDateString
+
+export const convertToArchivalDateStringIfNecessary = (
+    dateInput: DateInput
+): ArchivalDateString => {
+    if (
+        typeof dateInput === "string" &&
+        dateInput.length === ARCHIVE_DATE_TIME_FORMAT.length
+    )
+        return dateInput as ArchivalDateString
+
+    return formatAsArchivalDate(parseArchivalDate(dateInput))
+}
+
+export const getDateForArchival = (): ArchivalTimestamp => {
+    const date = dayjs
+        .utc()
+        // it's important here that we explicitly set the milliseconds to 0 -
+        // otherwise we run the risk of MySQL rounding up to the next second,
+        // which then breaks the archival URL
+        .millisecond(0)
+    const formattedDate = formatAsArchivalDate(date)
+
+    return { date: date.toDate(), formattedDate }
+}

package/src/utils/dayjs.ts

@@ -0,0 +1,32 @@
+// Imports dayjs and loads the plugins we need. Then exports it with the correct types.
+
+import dayjs, { Dayjs } from "dayjs"
+import customParseFormat from "dayjs/plugin/customParseFormat.js"
+import isToday from "dayjs/plugin/isToday.js"
+import isYesterday from "dayjs/plugin/isYesterday.js"
+import relativeTime from "dayjs/plugin/relativeTime.js"
+import utc from "dayjs/plugin/utc.js"
+
+dayjs.extend(customParseFormat)
+dayjs.extend(isToday)
+dayjs.extend(isYesterday)
+dayjs.extend(relativeTime)
+dayjs.extend(utc)
+
+export default dayjs
+
+// We need these explicit plugin type imports _and exports_ to get the right Dayjs type down the line
+import type customParseFormatType from "dayjs/plugin/customParseFormat.js"
+import type isTodayType from "dayjs/plugin/isToday.js"
+import type isYesterdayType from "dayjs/plugin/isYesterday.js"
+import type relativeTimeType from "dayjs/plugin/relativeTime.js"
+import type utcType from "dayjs/plugin/utc.js"
+
+export type {
+    Dayjs,
+    customParseFormatType,
+    isTodayType,
+    isYesterdayType,
+    relativeTimeType,
+    utcType,
+}

package/src/utils/formatValue.ts

@@ -0,0 +1,242 @@
+import { FormatSpecifier } from "d3-format"
+import { createFormatter } from "./Util.js"
+import {
+    OwidVariableRoundingMode,
+    TickFormattingOptions,
+} from "../types/index.js"
+
+// Used outside this module to figure out if the unit will be joined with the number.
+export function checkIsVeryShortUnit(unit: string): unit is "$" | "£" | "%" {
+    return ["%", "$", "£"].includes(unit)
+}
+
+function checkIsUnitCurrency(unit: string): unit is "$" | "£" {
+    return ["$", "£"].includes(unit)
+}
+
+function checkIsUnitPercent(unit: string): unit is "%" {
+    return unit[0] === "%"
+}
+
+function getTrim({
+    roundingMode,
+    trailingZeroes,
+}: {
+    roundingMode: OwidVariableRoundingMode
+    trailingZeroes: boolean
+}): "~" | "" {
+    // always show trailing zeroes when rounding to significant figures
+    return roundingMode === OwidVariableRoundingMode.significantFigures
+        ? ""
+        : trailingZeroes
+          ? ""
+          : "~"
+}
+
+function getSign({ showPlus }: { showPlus: boolean }): "+" | "" {
+    return showPlus ? "+" : ""
+}
+
+function getSymbol({ unit }: { unit: string }): "$" | "" {
+    return checkIsUnitCurrency(unit) ? "$" : ""
+}
+
+function getType({
+    roundingMode,
+    numberAbbreviation,
+    value,
+    unit,
+}: {
+    roundingMode: OwidVariableRoundingMode
+    numberAbbreviation: "long" | "short" | false
+    value: number
+    unit: string
+}): "f" | "s" | "r" {
+    // f: fixed-point notation (i.e. fixed number of decimal points)
+    // r: decimal notation, rounded to significant digits
+    // s: decimal notation with an SI prefix, rounded to significant digits
+
+    const typeMap: Record<OwidVariableRoundingMode, "f" | "r"> = {
+        [OwidVariableRoundingMode.decimalPlaces]: "f",
+        [OwidVariableRoundingMode.significantFigures]: "r",
+    }
+    const type = typeMap[roundingMode]
+
+    if (checkIsUnitPercent(unit)) {
+        return type
+    }
+    if (numberAbbreviation === "long") {
+        // do not abbreviate until 1 million
+        return Math.abs(value) < 1e6 ? type : "s"
+    }
+    if (numberAbbreviation === "short") {
+        // do not abbreviate until 1 thousand
+        return Math.abs(value) < 1e3 ? type : "s"
+    }
+
+    return type
+}
+
+function getPrecision({
+    value,
+    roundingMode,
+    numDecimalPlaces,
+    numSignificantFigures,
+    type,
+}: {
+    value: number
+    roundingMode: OwidVariableRoundingMode
+    numDecimalPlaces: number
+    numSignificantFigures: number
+    type: "f" | "s" | "r"
+}): string {
+    if (roundingMode === OwidVariableRoundingMode.significantFigures) {
+        return `${numSignificantFigures}`
+    }
+
+    if (type === "f") {
+        return `${numDecimalPlaces}`
+    }
+
+    // when dealing with abbreviated numbers, adjust precision so we get 12.84 million instead of 13 million
+    // the modulo one-liner counts the "place columns" of the number, resetting every 3
+    // 1 -> 1, 48 -> 2, 981 -> 3, 7222 -> 1
+    const numberOfDigits = String(Math.floor(Math.abs(value))).length
+    const precisionPadding = ((numberOfDigits - 1) % 3) + 1
+
+    // hard-coded 2 decimal places for abbreviated numbers
+    return `${precisionPadding + 2}`
+}
+
+function replaceSIPrefixes({
+    string,
+    numberAbbreviation,
+}: {
+    string: string
+    numberAbbreviation: "short" | "long"
+}): string {
+    const prefix = string[string.length - 1]
+
+    const prefixMap: Record<string, Record<string, string>> = {
+        short: {
+            k: "k",
+            M: "M",
+            G: "B",
+            T: "T",
+            P: "quad",
+            E: "quint",
+            Z: "sext",
+            Y: "sept",
+        },
+        long: {
+            k: "k",
+            M: " million",
+            G: " billion",
+            T: " trillion",
+            P: " quadrillion",
+            E: " quintillion",
+            Z: " sextillion",
+            Y: " septillion",
+        },
+    }
+
+    if (prefixMap[numberAbbreviation][prefix]) {
+        return string.replace(prefix, prefixMap[numberAbbreviation][prefix])
+    }
+    return string
+}
+
+function postprocessString({
+    string,
+    roundingMode,
+    numberAbbreviation,
+    spaceBeforeUnit,
+    useNoBreakSpace,
+    unit,
+    value,
+    numDecimalPlaces,
+}: {
+    string: string
+    roundingMode: OwidVariableRoundingMode
+    numberAbbreviation: "long" | "short" | false
+    spaceBeforeUnit: boolean
+    useNoBreakSpace: boolean
+    unit: string
+    value: number
+    numDecimalPlaces: number
+}): string {
+    let output = string
+
+    // handling infinitesimal values
+    if (roundingMode !== OwidVariableRoundingMode.significantFigures) {
+        const tooSmallThreshold = Math.pow(10, -numDecimalPlaces).toPrecision(1)
+        if (numberAbbreviation && 0 < value && value < +tooSmallThreshold) {
+            output = "<" + output.replace(/0\.?(\d+)?/, tooSmallThreshold)
+        }
+    }
+
+    if (numberAbbreviation) {
+        output = replaceSIPrefixes({
+            string: output,
+            numberAbbreviation,
+        })
+    }
+
+    if (unit && !checkIsUnitCurrency(unit)) {
+        const spaceCharacter = useNoBreakSpace ? "\u00a0" : " "
+        const appendage = spaceBeforeUnit ? spaceCharacter + unit : unit
+        output += appendage
+    }
+
+    return output
+}
+
+export function formatValue(
+    value: number,
+    {
+        roundingMode = OwidVariableRoundingMode.decimalPlaces,
+        trailingZeroes = false, // only applies to fixed-point notation
+        unit = "",
+        spaceBeforeUnit = !checkIsUnitPercent(unit),
+        useNoBreakSpace = false,
+        showPlus = false,
+        numDecimalPlaces = 2, // only applies to fixed-point notation
+        numSignificantFigures = 3, // only applies to sig fig rounding
+        numberAbbreviation = "long",
+    }: TickFormattingOptions
+): string {
+    const formatter = createFormatter(unit)
+
+    // Explore how specifiers work here
+    // https://observablehq.com/@ikesau/d3-format-interactive-demo
+    const specifier = new FormatSpecifier({
+        zero: "0",
+        trim: getTrim({ roundingMode, trailingZeroes }),
+        sign: getSign({ showPlus }),
+        symbol: getSymbol({ unit }),
+        comma: ",",
+        precision: getPrecision({
+            roundingMode,
+            value,
+            numDecimalPlaces,
+            numSignificantFigures,
+            type: getType({ roundingMode, numberAbbreviation, value, unit }),
+        }),
+        type: getType({ roundingMode, numberAbbreviation, value, unit }),
+    }).toString()
+
+    const formattedString = formatter(specifier)(value)
+
+    const postprocessedString = postprocessString({
+        string: formattedString,
+        roundingMode,
+        numberAbbreviation,
+        spaceBeforeUnit,
+        useNoBreakSpace,
+        unit,
+        value,
+        numDecimalPlaces,
+    })
+
+    return postprocessedString
+}

package/src/utils/grapherConfigUtils.ts

@@ -0,0 +1,81 @@
+import { GrapherInterface } from "../types/index.js"
+import * as _ from "lodash-es"
+import {
+    excludeUndefined,
+    omitUndefinedValuesRecursive,
+    omitEmptyObjectsRecursive,
+    traverseObjects,
+    merge,
+} from "./Util"
+
+const REQUIRED_KEYS = ["$schema", "dimensions"]
+
+const KEYS_EXCLUDED_FROM_INHERITANCE = [
+    "$schema",
+    "id",
+    "slug",
+    "version",
+    "isPublished",
+]
+
+export function mergeGrapherConfigs(
+    ...grapherConfigs: GrapherInterface[]
+): GrapherInterface {
+    const configsToMerge = grapherConfigs.filter((c) => !_.isEmpty(c))
+
+    // return early if there are no configs to merge
+    if (configsToMerge.length === 0) return {}
+    if (configsToMerge.length === 1) return configsToMerge[0]
+
+    // warn if one of the configs is missing a schema version
+    const configsWithoutSchema = configsToMerge.filter(
+        (c) => c["$schema"] === undefined
+    )
+    if (configsWithoutSchema.length > 0) {
+        const configsJson = JSON.stringify(configsWithoutSchema, null, 2)
+        console.warn(
+            `About to merge Grapher configs with missing schema information: ${configsJson}`
+        )
+    }
+
+    // abort if the grapher configs have different schema versions
+    const uniqueSchemas = _.uniq(
+        excludeUndefined(configsToMerge.map((c) => c["$schema"]))
+    )
+    if (uniqueSchemas.length > 1) {
+        const message = `Merging Grapher configs with different schema versions. This may lead to unexpected behavior. Found: ${uniqueSchemas.join(
+            ", "
+        )}`
+        console.warn(message)
+    }
+
+    // keys that should not be inherited are removed from all but the last config
+    const cleanedConfigs = configsToMerge.map((config, index) => {
+        if (index === configsToMerge.length - 1) return config
+        return _.omit(config, KEYS_EXCLUDED_FROM_INHERITANCE)
+    })
+
+    return merge(
+        ...(cleanedConfigs as [GrapherInterface, ...GrapherInterface[]])
+    )
+}
+
+export function diffGrapherConfigs(
+    config: GrapherInterface,
+    reference: GrapherInterface
+): GrapherInterface {
+    const keepKeys = [...REQUIRED_KEYS, ...KEYS_EXCLUDED_FROM_INHERITANCE]
+    const keep = _.pick(config, keepKeys)
+
+    const diffed = omitEmptyObjectsRecursive(
+        omitUndefinedValuesRecursive(
+            traverseObjects(config, reference, (value, refValue) => {
+                if (refValue === undefined) return value
+                if (!_.isEqual(value, refValue)) return value
+                return undefined
+            })
+        )
+    )
+
+    return { ...diffed, ...keep }
+}

package/src/utils/image.ts

@@ -0,0 +1,225 @@
+// @ts-nocheck
+/*
+Common utlities for deriving properties from image metadata.
+*/
+
+import { traverseEnrichedBlock } from "./Util.js"
+import {
+    AssetMap,
+    OwidGdoc,
+    OwidGdocType,
+    ImageMetadata,
+} from "../types/index.js"
+import { match, P } from "ts-pattern"
+
+export const AUTHOR_BYLINE_WIDTH = 48
+export const THUMBNAIL_WIDTH = 100
+export const LARGE_THUMBNAIL_WIDTH = 350
+export const LARGEST_IMAGE_WIDTH = 1350
+
+export function getArchivalSizes(
+    originalWidth: ImageMetadata["originalWidth"]
+): number[] {
+    if (!originalWidth) return []
+    const widths: number[] = []
+    if (originalWidth > LARGE_THUMBNAIL_WIDTH) {
+        widths.push(LARGE_THUMBNAIL_WIDTH)
+    }
+    if (originalWidth > LARGEST_IMAGE_WIDTH) {
+        widths.push(LARGEST_IMAGE_WIDTH)
+    }
+    widths.push(originalWidth)
+    return widths
+}
+
+export function getSizes(
+    originalWidth: ImageMetadata["originalWidth"]
+): number[] {
+    if (!originalWidth) return []
+    // ensure a thumbnail and author byline is generated
+    const widths = [AUTHOR_BYLINE_WIDTH, THUMBNAIL_WIDTH]
+    // start at large thumbnail and go up by 500 to a max of 1350 before we just show the original image
+    let width = LARGE_THUMBNAIL_WIDTH
+    while (width < originalWidth && width <= LARGEST_IMAGE_WIDTH) {
+        widths.push(width)
+        width += 500
+    }
+    widths.push(originalWidth)
+    return widths
+}
+
+export function generateSrcSet(
+    sizes: number[],
+    id: ImageMetadata["cloudflareId"],
+    absoluteUrl: string = ""
+): string {
+    return sizes
+        .map((size) => {
+            const path = `${absoluteUrl}/${id}/w=${size}`
+            return `${path} ${size}w`
+        })
+        .join(", ")
+}
+
+export function getFilenameWithoutExtension(
+    filename: ImageMetadata["filename"]
+): string {
+    return filename.slice(0, filename.indexOf("."))
+}
+
+export function getFilenameExtension(
+    filename: ImageMetadata["filename"]
+): string {
+    return filename.slice(filename.lastIndexOf(".") + 1)
+}
+
+export function getFilenameAsPng(filename: ImageMetadata["filename"]): string {
+    return `${getFilenameWithoutExtension(filename)}.png`
+}
+
+export function getFilenameMIMEType(filename: string): string | undefined {
+    const fileExtension = getFilenameExtension(filename)
+    const MIMEType = {
+        png: "image/png",
+        svg: "image/svg+xml",
+        jpg: "image/jpg",
+        jpeg: "image/jpeg",
+        webp: "image/webp",
+    }[fileExtension]
+
+    return MIMEType
+}
+
+export type SourceProps = {
+    media: string | undefined
+    srcSet: string
+}
+
+export function appendImageSizeSuffix(filename: string, size: number): string {
+    const extIndex = filename.lastIndexOf(".")
+    if (extIndex === -1) return `${filename}-${size}w`
+    const name = filename.slice(0, extIndex)
+    const ext = filename.slice(extIndex)
+    return `${name}-${size}w${ext}`
+}
+
+function generateArchivalSrcSet(
+    image: ImageMetadata,
+    sizes: number[],
+    assetMap: AssetMap
+): string {
+    return sizes
+        .map((size) => {
+            const filename =
+                size === image.originalWidth
+                    ? image.filename
+                    : appendImageSizeSuffix(image.filename, size)
+            const path = assetMap[filename]
+            if (!path) {
+                throw new Error(
+                    `Image ${image.filename} not found in asset map`
+                )
+            }
+            return `${path} ${size}w`
+        })
+        .filter(Boolean)
+        .join(", ")
+}
+
+/**
+ * When we have a small and large image, we want to generate two <source> elements.
+ * The first will only be active at small screen sizes, due to its `media` property.
+ * The second will be active at all screen sizes.
+ * These props work in conjuction with a `sizes` attribute on the <source> element.
+ */
+export function generateSourceProps(
+    smallImage: ImageMetadata | undefined,
+    regularImage: ImageMetadata,
+    absoluteUrl: string = "",
+    assetMap?: AssetMap
+): SourceProps[] {
+    const props: SourceProps[] = []
+
+    function buildProps(image: ImageMetadata, media: string | undefined): void {
+        const sizes = assetMap
+            ? getArchivalSizes(image.originalWidth)
+            : getSizes(image.originalWidth)
+        if (sizes.length === 0) return
+
+        let srcSet: string | undefined
+        if (assetMap) {
+            srcSet = generateArchivalSrcSet(image, sizes, assetMap)
+        } else if (image.cloudflareId) {
+            const encodedId = encodeURIComponent(image.cloudflareId)
+            srcSet = generateSrcSet(sizes, encodedId, absoluteUrl)
+        }
+
+        if (!srcSet) return
+
+        props.push({
+            media,
+            srcSet,
+        })
+    }
+
+    if (smallImage) {
+        buildProps(smallImage, "(max-width: 768px)")
+    }
+    if (regularImage) {
+        buildProps(regularImage, undefined)
+    }
+
+    return props
+}
+
+export function getFeaturedImageFilename(gdoc: OwidGdoc): string | undefined {
+    return match(gdoc)
+        .with(
+            {
+                content: {
+                    type: P.union(
+                        OwidGdocType.Article,
+                        OwidGdocType.TopicPage,
+                        OwidGdocType.LinearTopicPage,
+                        OwidGdocType.AboutPage,
+                        OwidGdocType.Author,
+                        OwidGdocType.Announcement
+                    ),
+                },
+            },
+            (match) => {
+                const featuredImageFilename = match.content["featured-image"]
+                return featuredImageFilename
+            }
+        )
+        .with({ content: { type: OwidGdocType.DataInsight } }, (gdoc) => {
+            // Use the first image in the document as the featured image
+            let filename: string | undefined = undefined
+            for (const block of gdoc.content.body) {
+                traverseEnrichedBlock(block, (block) => {
+                    if (!filename && block.type === "image") {
+                        filename = block.smallFilename || block.filename
+                    }
+                })
+            }
+            return filename
+        })
+        .with(
+            {
+                content: { type: OwidGdocType.Profile },
+            },
+            (match) => match.content["featured-image"]
+        )
+        .with(
+            {
+                content: {
+                    type: P.optional(
+                        P.union(OwidGdocType.Fragment, OwidGdocType.Homepage)
+                    ),
+                },
+            },
+            // This will fallback to DEFAULT_THUMBNAIL_FILENAME in Head.tsx
+            () => undefined
+        )
+        .exhaustive()
+}