@buildcanada/charts 0.1.0

package/src/utils/index.ts

@@ -0,0 +1,318 @@
+/**
+ * Utility exports for @buildcanada/charts
+ */
+
+// Bounds utility
+export {
+    type GridBounds,
+    type SplitBoundsPadding,
+    FontFamily,
+    Bounds,
+} from "./Bounds.js"
+
+// Browser utilities
+export { isAndroid, isIOS } from "./BrowserUtils.js"
+
+// Dayjs
+import dayjs from "./dayjs.js"
+export { dayjs }
+export type {
+    Dayjs,
+    customParseFormatType,
+    isTodayType,
+    isYesterdayType,
+    relativeTimeType,
+    utcType,
+} from "./dayjs.js"
+
+// Format value
+export { formatValue, checkIsVeryShortUnit } from "./formatValue.js"
+
+// Fuzzy search
+export { FuzzySearch, type FuzzySearchResult } from "./FuzzySearch.js"
+
+// Grapher config utilities
+export {
+    diffGrapherConfigs,
+    mergeGrapherConfigs,
+} from "./grapherConfigUtils.js"
+
+// Image utilities
+export {
+    THUMBNAIL_WIDTH,
+    LARGE_THUMBNAIL_WIDTH,
+    LARGEST_IMAGE_WIDTH,
+    appendImageSizeSuffix,
+    getSizes,
+    generateSrcSet,
+    getFilenameWithoutExtension,
+    getFilenameAsPng,
+    getFilenameExtension,
+    getFilenameMIMEType,
+    type SourceProps,
+    generateSourceProps,
+    getFeaturedImageFilename,
+} from "./image.js"
+
+// isPresent utility
+export { isPresent } from "./isPresent.js"
+
+// Metadata helpers
+export {
+    getOriginAttributionFragments,
+    getAttributionFragmentsFromVariable,
+    getETLPathComponents,
+    formatAuthors,
+    formatAuthorsForBibtex,
+    getLastUpdatedFromVariable,
+    getNextUpdateFromVariable,
+    getPhraseForProcessingLevel,
+    splitSourceTextIntoFragments,
+    prepareSourcesForDisplay,
+    formatSourceDate,
+    getDateRange,
+    getCitationLong,
+    getCitationShort,
+    getPhraseForArchivalDate,
+} from "./metadataHelpers.js"
+
+// OwidVariable display config
+export { OwidVariableDisplayConfig } from "./OwidVariable.js"
+
+// Persistable
+export {
+    type Persistable,
+    objectWithPersistablesToObject,
+    updatePersistables,
+    deleteRuntimeAndUnchangedProps,
+} from "./persistable/Persistable.js"
+
+// PointVector
+export { PointVector } from "./PointVector.js"
+
+// PromiseCache
+export { PromiseCache } from "./PromiseCache.js"
+
+// PromiseSwitcher
+export { PromiseSwitcher } from "./PromiseSwitcher.js"
+
+// Regions
+export {
+    RegionType,
+    regions,
+    type Region,
+    countries,
+    listedRegionsNames,
+    type Country,
+    type IncomeGroup,
+    type OwidIncomeGroupName,
+    checkIsOwidIncomeGroupName,
+    getCountryBySlug,
+    getCountryByName,
+    getRegionByNameOrVariantName,
+    isCountryName,
+    getContinents,
+    type Continent,
+    getAggregates,
+    type Aggregate,
+    type AggregateSource,
+    aggregateSources,
+    getOthers,
+    countriesByName,
+    incomeGroupsByName,
+    getRegionAlternativeNames,
+    mappableCountries,
+    checkIsCountry,
+    checkIsOwidContinent,
+    checkIsIncomeGroup,
+    getIncomeGroups,
+    getCountryNamesForRegion,
+    checkHasMembers,
+    getRegionByName,
+    getRegionBySlug,
+    getParentRegions,
+    getSiblingRegions,
+    articulateEntity,
+} from "./regions.js"
+
+// Serializers
+export { serializeJSONForHTML, deserializeJSONFromHTML } from "./serializers.js"
+
+// String utilities
+export {
+    camelCaseProperties,
+    titleCase,
+    toAsciiQuotes,
+    removeDiacritics,
+} from "./string.js"
+
+// TimeBounds
+export {
+    timeFromTimebounds,
+    minTimeBoundFromJSONOrNegativeInfinity,
+    maxTimeBoundFromJSONOrPositiveInfinity,
+    minTimeToJSON,
+    maxTimeToJSON,
+    timeBoundToTimeBoundString,
+    getTimeDomainFromQueryString,
+} from "./TimeBounds.js"
+
+// Tippy tooltip component
+export { Tippy, TippyIfInteractive, LazyTippy } from "./Tippy.js"
+
+// URL utilities
+export {
+    strToQueryParams,
+    queryParamsToStr,
+    getWindowQueryStr,
+    setWindowQueryStr,
+} from "./urls/UrlUtils.js"
+
+export { Url, setWindowUrl, getWindowUrl } from "./urls/Url.js"
+
+export { type UrlMigration, performUrlMigrations } from "./urls/UrlMigration.js"
+
+// Main utility exports (from Util.ts)
+export {
+    type NoUndefinedValues,
+    type AllKeysRequired,
+    type PartialBy,
+    type RequiredBy,
+    type PartialRecord,
+    createFormatter,
+    getRelativeMouse,
+    exposeInstanceOnWindow,
+    makeSafeForCSS,
+    makeIdForHumanConsumption,
+    formatDay,
+    formatYear,
+    numberMagnitude,
+    normaliseToSingleDigitNumber,
+    roundSigFig,
+    excludeNull,
+    excludeNullish,
+    excludeUndefined,
+    firstOfNonEmptyArray,
+    lastOfNonEmptyArray,
+    next,
+    previous,
+    domainExtent,
+    cagr,
+    makeAnnotationsSlug,
+    slugify,
+    slugifySameCase,
+    guid,
+    TESTING_ONLY_disable_guid,
+    pointsToPath,
+    sortedFindClosestIndex,
+    sortedFindClosest,
+    isMobile,
+    isTouchDevice,
+    type Json,
+    csvEscape,
+    trimObject,
+    fetchText,
+    fetchJson,
+    fetchWithTimeout,
+    getUserCountryInformation,
+    stripHTML,
+    getRandomNumberGenerator,
+    sampleFrom,
+    getIdealGridParams,
+    findClosestTimeIndex,
+    findClosestTime,
+    es6mapValues,
+    type DataValue,
+    valuesByEntityAtTimes,
+    dateDiffInDays,
+    diffDateISOStringInDays,
+    getYearFromISOStringAndDayOffset,
+    parseIntOrUndefined,
+    anyToString,
+    scrollIntoViewIfNeeded,
+    rollingMap,
+    keyMap,
+    intersectionOfSets,
+    differenceOfSets,
+    areSetsEqual,
+    isSubsetOf,
+    intersection,
+    sortByUndefinedLast,
+    mapNullToUndefined,
+    lowerCaseFirstLetterUnlessAbbreviation,
+    sortNumeric,
+    getClosestTimePairs,
+    omitUndefinedValues,
+    isInIFrame,
+    differenceObj,
+    findDOMParent,
+    wrapInDiv,
+    textAnchorFromAlign,
+    dyFromAlign,
+    stringifyUnknownError,
+    toRectangularMatrix,
+    checkIsStringIndexable,
+    checkIsTouchEvent,
+    triggerDownloadFromBlob,
+    triggerDownloadFromUrl,
+    removeAllWhitespace,
+    moveArrayItemToIndex,
+    getIndexableKeys,
+    retryPromise,
+    fetchWithRetry,
+    formatDate,
+    canWriteToClipboard,
+    isNegativeInfinity,
+    isPositiveInfinity,
+    imemo,
+    isArrayOfNumbers,
+    greatestCommonDivisor,
+    findGreatestCommonDivisorOfArray,
+    copyToClipboard,
+    cartesian,
+    removeTrailingParenthetical,
+    commafyNumber,
+    isFiniteWithGuard,
+    formatInlineList,
+    lazy,
+    getParentVariableIdFromChartConfig,
+    isArrayDifferentFromReference,
+    readFromAssetMap,
+    downloadImage,
+    getUserNavigatorLanguages,
+    getUserNavigatorLanguagesNonEnglish,
+    convertDaysSinceEpochToDate,
+    sleep,
+    lowercaseObjectKeys,
+    detailOnDemandRegex,
+    guidedChartRegex,
+    extractDetailsFromSyntax,
+    parseFloatOrUndefined,
+    bind,
+    merge,
+    calculateTrendDirection,
+    getDisplayUnit,
+    stripOuterParentheses,
+    dimensionsToViewId,
+} from "./Util.js"
+
+// Archival date utilities
+export {
+    type ArchivalTimestamp,
+    type DateInput,
+    parseArchivalDate,
+    formatAsArchivalDate,
+    convertToArchivalDateStringIfNecessary,
+    getDateForArchival,
+} from "./archival/archivalDate.js"
+
+// Multi-dimensional data page config (stub)
+export {
+    MultiDimDataPageConfig,
+    extractMultiDimChoicesFromSearchParams,
+    searchParamsToMultiDimView,
+} from "./MultiDimDataPageConfig.js"
+
+// Re-export all types from the types package for convenience
+// This matches the pattern in @ourworldindata/utils
+export * from "../types/index.js"

package/src/utils/isPresent.ts

@@ -0,0 +1,5 @@
+// https://github.com/robertmassaioli/ts-is-present
+// A predicate for filtering an array of nulls and undefineds that returns the correct type
+
+export const isPresent = <T>(t: T | undefined | null | void): t is T =>
+    t !== undefined && t !== null

package/src/utils/metadataHelpers.ts

@@ -0,0 +1,329 @@
+// @ts-nocheck
+import * as R from "remeda"
+import {
+    OwidOrigin,
+    OwidVariableWithSource,
+    OwidProcessingLevel,
+    DisplaySource,
+    IndicatorTitleWithFragments,
+    OwidSource,
+} from "../types/index.js"
+import * as _ from "lodash-es"
+import { excludeUndefined } from "./Util"
+import dayjs from "./dayjs.js"
+import { parseArchivalDate } from "./archival/archivalDate.js"
+
+export function getOriginAttributionFragments(
+    origins: OwidOrigin[] | undefined
+): string[] {
+    return origins
+        ? origins.map((origin) => {
+              const yearPublished = origin.datePublished
+                  ? dayjs(origin.datePublished, ["YYYY-MM-DD", "YYYY"]).year()
+                  : undefined
+              const yearPublishedString = yearPublished
+                  ? ` (${yearPublished})`
+                  : ""
+              return (
+                  origin.attribution ??
+                  `${origin.producer}${yearPublishedString}`
+              )
+          })
+        : []
+}
+
+export const splitSourceTextIntoFragments = (
+    text: string | undefined
+): string[] => {
+    return text ? text.split(";").map((fragment) => fragment.trim()) : []
+}
+
+export function getAttributionFragmentsFromVariable(
+    variable: Pick<
+        OwidVariableWithSource,
+        "presentation" | "origins" | "source"
+    >
+): string[] {
+    if (
+        variable.presentation?.attribution &&
+        variable.presentation?.attribution !== ""
+    )
+        return [variable.presentation?.attribution]
+
+    const originAttributionFragments = getOriginAttributionFragments(
+        variable.origins
+    )
+    const name = variable.source?.name
+    return _.uniq(_.compact([name, ...originAttributionFragments]))
+}
+
+interface ETLPathComponents {
+    channel: string
+    producer: string
+    version: string
+    dataset: string
+    table: string
+    indicator: string
+}
+
+export const getETLPathComponents = (path: string): ETLPathComponents => {
+    const [channel, producer, version, dataset, table, indicator] =
+        path.split("/")
+    return { channel, producer, version, dataset, table, indicator }
+}
+
+export function formatAuthors(authors: string[]): string {
+    if (authors.length === 0) return ""
+    if (authors.length === 1) return authors[0]
+    if (authors.length === 2) return authors.join(" and ")
+    return authors.slice(0, -1).join(", ") + `, and ${R.last(authors)}`
+}
+
+export function formatAuthorsForBibtex(authors: string[]): string {
+    return authors.join(" and ")
+}
+
+const isDate = (date: string): boolean => {
+    const dateRegex = /^\d{4}-\d{2}-\d{2}$/
+    return !!date.match(dateRegex)
+}
+
+export const getLastUpdatedFromVariable = (
+    variable: Pick<OwidVariableWithSource, "catalogPath" | "origins">
+): string | undefined => {
+    // if possible, extract date from the catalog path
+    const version = getETLPathComponents(variable.catalogPath ?? "")?.version
+    if (version && isDate(version)) return version
+
+    const { origins = [] } = variable
+    const originDates = excludeUndefined(
+        origins.map((origin) => origin.dateAccessed)
+    )
+
+    if (originDates.length === 0) return undefined
+
+    // alternatively, pick the latest dateAccessed from the origins
+    const latestDate = new Date(
+        Math.max(...originDates.map((date) => new Date(date).getTime()))
+    )
+    return dayjs(latestDate).format("YYYY-MM-DD")
+}
+
+export const getNextUpdateFromVariable = (
+    variable: Pick<OwidVariableWithSource, "catalogPath" | "updatePeriodDays">
+): string | undefined => {
+    const lastUpdated = getLastUpdatedFromVariable(variable)
+    let nextUpdate = undefined
+    if (variable.updatePeriodDays) {
+        const date = dayjs(lastUpdated)
+        const nextUpdateDate = date.add(variable.updatePeriodDays, "day")
+        // If the next update date is in the past, we set it to the next month
+        if (nextUpdateDate.isBefore(dayjs()))
+            nextUpdate = dayjs().add(1, "month")
+        else nextUpdate = nextUpdateDate
+    }
+    return nextUpdate?.format("YYYY-MM-DD")
+}
+
+export const getPhraseForProcessingLevel = (
+    processingLevel: OwidProcessingLevel | undefined
+): string => {
+    switch (processingLevel) {
+        case "major":
+            return "with major processing"
+        case "minor":
+            return "with minor processing"
+        default:
+            return "processed"
+    }
+}
+
+const prepareOriginForDisplay = (origin: OwidOrigin): DisplaySource => {
+    let label = origin.producer ?? ""
+    if (origin.title && origin.title !== label) {
+        label += " – " + origin.title
+    }
+
+    return {
+        label,
+        description: origin.description,
+        retrievedOn: origin.dateAccessed,
+        retrievedFrom: origin.urlMain,
+        citation: origin.citationFull,
+    }
+}
+
+export const prepareSourcesForDisplay = (
+    variable: Pick<OwidVariableWithSource, "origins" | "source">
+): DisplaySource[] => {
+    const { origins, source } = variable
+
+    const sourcesForDisplay: DisplaySource[] = []
+
+    if (
+        source?.name &&
+        (source?.dataPublishedBy || source?.retrievedDate || source?.link)
+    ) {
+        sourcesForDisplay.push({
+            label: source?.name,
+            dataPublishedBy: source?.dataPublishedBy,
+            retrievedOn: source?.retrievedDate,
+            retrievedFrom: source?.link,
+        })
+    }
+
+    if (origins && origins.length > 0) {
+        sourcesForDisplay.push(
+            ...origins.map((origin) => prepareOriginForDisplay(origin))
+        )
+    }
+
+    return sourcesForDisplay
+}
+
+const getYearSuffixFromOrigin = (o: OwidOrigin): string => {
+    const year = o.dateAccessed
+        ? dayjs(o.dateAccessed, ["YYYY-MM-DD", "YYYY"]).year()
+        : o.datePublished
+          ? dayjs(o.datePublished, ["YYYY-MM-DD", "YYYY"]).year()
+          : undefined
+    if (year) return ` (${year})`
+    else return ""
+}
+
+export const getCitationShort = (
+    origins: OwidOrigin[],
+    attributions: string[],
+    owidProcessingLevel: OwidProcessingLevel | undefined
+): string => {
+    const producersWithYear = _.uniq(
+        origins.map((o) => `${o.producer}${getYearSuffixFromOrigin(o)}`)
+    )
+    const processingLevelPhrase =
+        getPhraseForProcessingLevel(owidProcessingLevel)
+
+    const attributionFragments = attributions ?? producersWithYear
+    const attributionPotentiallyShortened =
+        attributionFragments.length > 3
+            ? `${attributionFragments[0]} and other sources`
+            : attributionFragments.join("; ")
+
+    return `${attributionPotentiallyShortened} – ${processingLevelPhrase} by Our World in Data`
+}
+
+const getDateForCitation = (date: dayjs.Dayjs): string =>
+    date.format("MMMM D, YYYY")
+
+export const getPhraseForArchivalDate = (
+    archivalDate: string | undefined
+): string | undefined => {
+    if (!archivalDate) return undefined
+
+    const parsedDate = parseArchivalDate(archivalDate)
+    const formatted = getDateForCitation(parsedDate)
+    return `(archived on ${formatted}).`
+}
+
+export const getCitationLong = (
+    indicatorTitle: IndicatorTitleWithFragments,
+    origins: OwidOrigin[],
+    source: OwidSource | undefined,
+    attributions: string[],
+    attributionShort: string | undefined,
+    titleVariant: string | undefined,
+    owidProcessingLevel: OwidProcessingLevel | undefined,
+    citationUrl: string | undefined,
+    archivalDate: string | undefined
+): string => {
+    const sourceShortName =
+        attributionShort && titleVariant
+            ? `${attributionShort} – ${titleVariant}`
+            : attributionShort || titleVariant
+    const producersWithYear = _.uniq(
+        origins.map((o) => `${o.producer}${getYearSuffixFromOrigin(o)}`)
+    )
+    const processingLevelPhrase =
+        getPhraseForProcessingLevel(owidProcessingLevel)
+
+    const attributionFragments = attributions ?? producersWithYear
+    const attributionUnshortened = attributionFragments.join("; ")
+    const citationLonger = `${attributionUnshortened} – ${processingLevelPhrase} by Our World in Data`
+    const titleWithOptionalFragments = excludeUndefined([
+        indicatorTitle.title,
+        sourceShortName,
+    ]).join(" – ")
+    const originsLong = _.uniq(
+        origins.map(
+            (o) =>
+                `${o.producer}, “${o.title ?? o.titleSnapshot}${
+                    o.versionProducer ? " " + o.versionProducer : ""
+                }”`
+        )
+    ).join("; ")
+    const today = getDateForCitation(dayjs())
+    const archivalString = getPhraseForArchivalDate(archivalDate)
+    return excludeUndefined([
+        `${citationLonger}.`,
+        `“${titleWithOptionalFragments}” [dataset].`,
+        originsLong
+            ? `${originsLong} [original data].`
+            : source?.name
+              ? `${source?.name} [original data].`
+              : undefined,
+        citationUrl
+            ? `Retrieved ${today} from ${citationUrl}${archivalString ? ` ${archivalString}` : ""}`
+            : undefined,
+    ]).join(" ")
+}
+
+export const formatSourceDate = (
+    date: string | undefined,
+    format: string
+): string | null => {
+    const parsedDate = dayjs(date ?? "", ["YYYY-MM-DD", "DD/MM/YYYY"])
+    if (!parsedDate.isValid()) return date || null
+    return parsedDate.format(format)
+}
+
+export const getDateRange = (dateRange: string): string | null => {
+    // This regex matches:
+    //   Beginning of string
+    //   Ignore whitespace
+    //   a named group called start that matches:
+    //     hyphen aka minus
+    //     1 or more digits
+    //   Ignore whitespace
+    //   hyphen aka minus OR en dash
+    //   Ignore whitespace
+    //   a named group called end that matches:
+    //     hyphen aka minus
+    //     1 or more digits
+    //   Ignore whitespace
+    //   End of string
+    const dateRangeRegex = /^\s*(?<start>(-)?\d+)\s*(-|–)\s*(?<end>(-)?\d+)\s*$/
+    const match = dateRange.match(dateRangeRegex)
+    if (match) {
+        const firstYearString = match.groups?.start
+        const lastYearString = match.groups?.end
+        if (!firstYearString || !lastYearString) return null
+
+        const firstYear = parseInt(firstYearString, 10)
+        const lastYear = parseInt(lastYearString, 10)
+        let formattedFirstYear
+
+        // if start year is before year 0, add BCE to the end
+        if (firstYear < 0) formattedFirstYear = `${Math.abs(firstYear)} BCE`
+        else formattedFirstYear = firstYear
+
+        // if end year is before year 0, add BCE to the end or, if start year is after year 0, add CE to the end
+        let formattedLastYear
+        if (lastYear < 0) formattedLastYear = `${Math.abs(lastYear)} BCE`
+        else if (firstYear < 0) formattedLastYear = `${lastYear} CE`
+        else formattedLastYear = lastYear
+
+        if (lastYear < 0 || firstYear < 0)
+            return `${formattedFirstYear} – ${formattedLastYear}`
+        else return `${formattedFirstYear}–${formattedLastYear}`
+    }
+    return null
+}