@buildcanada/charts 0.1.0

package/src/utils/PointVector.ts

@@ -0,0 +1,97 @@
+/*
+ * Vector utility class
+ * Partly based on the Unity vector: https://docs.unity3d.com/ScriptReference/Vector2.html
+ * Wraps the Victor library, mainly so we can do type hinting
+ *
+ * @project Our World In Data
+ * @author  Jaiden Mispy
+ * @created 2017-03-15
+ */
+
+export class PointVector {
+    x: number
+    y: number
+
+    constructor(x: number, y: number) {
+        this.x = x
+        this.y = y
+    }
+
+    subtract(v: PointVector): PointVector {
+        return new PointVector(this.x - v.x, this.y - v.y)
+    }
+
+    add(v: PointVector): PointVector {
+        return new PointVector(this.x + v.x, this.y + v.y)
+    }
+
+    times(n: number): PointVector {
+        return new PointVector(this.x * n, this.y * n)
+    }
+
+    get magnitude(): number {
+        return Math.sqrt(this.x ** 2 + this.y ** 2)
+    }
+
+    normalize(): PointVector {
+        const magnitude = this.magnitude
+        if (magnitude > 1e-5)
+            return new PointVector(this.x / magnitude, this.y / magnitude)
+
+        return new PointVector(0, 0)
+    }
+
+    normals(): [PointVector, PointVector] {
+        return [
+            new PointVector(-this.y, this.x),
+            new PointVector(this.y, -this.x),
+        ]
+    }
+
+    toString(): string {
+        return `PointVector<${this.x}, ${this.y}>`
+    }
+
+    static up = new PointVector(0, -1)
+    static zero = new PointVector(0, 0)
+
+    static distanceSq(a: PointVector, b: PointVector): number {
+        return (b.x - a.x) ** 2 + (b.y - a.y) ** 2
+    }
+
+    static distance(a: PointVector, b: PointVector): number {
+        return Math.sqrt(PointVector.distanceSq(a, b))
+    }
+
+    static angle(a: PointVector, b: PointVector): number {
+        return (
+            Math.acos(
+                Math.max(
+                    Math.min(PointVector.dot(a.normalize(), b.normalize()), 1),
+                    -1
+                )
+            ) * 57.29578 // this is 180/pi, used to convert radians to degrees
+        )
+    }
+
+    private static dot(lhs: PointVector, rhs: PointVector): number {
+        return lhs.x * rhs.x + lhs.y * rhs.y
+    }
+
+    // From: http://stackoverflow.com/a/1501725/1983739
+    static distanceFromPointToLineSegmentSq(
+        p: PointVector,
+        v: PointVector, // start of line segment
+        w: PointVector // end of line segment
+    ): number {
+        const l2 = PointVector.distanceSq(v, w)
+        if (l2 === 0) return PointVector.distanceSq(p, v)
+
+        let t = ((p.x - v.x) * (w.x - v.x) + (p.y - v.y) * (w.y - v.y)) / l2
+        t = Math.max(0, Math.min(1, t))
+        return PointVector.distanceSq(
+            p,
+            new PointVector(v.x + t * (w.x - v.x), v.y + t * (w.y - v.y))
+        )
+    }
+}

package/src/utils/PromiseCache.ts

@@ -0,0 +1,36 @@
+/**
+ * Prevents creating multiple promises for a single key.
+ *
+ * If an existing promise for a key is pending, that promise will be returned without
+ * creating a new one.
+ *
+ * If a promise throws an error, it will be discarded, and a new one created the next
+ * time a key is requested.
+ *
+ * For now it only supports primitive value keys, but we can extend it if necessary.
+ */
+export class PromiseCache<Key extends string | number | undefined, Result> {
+    constructor(private createPromiseFromKey: (key: Key) => Promise<Result>) {}
+
+    private promisesByKey = new Map<Key, Promise<Result>>()
+
+    get(key: Key): Promise<Result> {
+        if (!this.promisesByKey.has(key)) {
+            this.promisesByKey.set(
+                key,
+                // Make sure to attach .catch() _before_ adding it to the cache.
+                // Otherwise external logic would be able to attach a catch() that
+                // could make this one unreachable.
+                this.createPromiseFromKey(key).catch((error) => {
+                    this.promisesByKey.delete(key)
+                    throw error
+                })
+            )
+        }
+        return this.promisesByKey.get(key)!
+    }
+
+    has(key: Key): boolean {
+        return this.promisesByKey.has(key)
+    }
+}

package/src/utils/PromiseSwitcher.ts

@@ -0,0 +1,52 @@
+interface PromiseSelectorArg<Result> {
+    onResolve?: (result: Result) => void
+    onReject?: (error: any) => void
+}
+
+/**
+ * An alternative to cancellable promises. Allows set()-ing a single promise,
+ * discarding the results of any previous ones, regardless whether they
+ * resolve or reject.
+ *
+ * The problem it solves:
+ *
+ * 1. User interacts with UI
+ * 2. Request sent to fetch required data: `getViewData().then((data) => updateView(data))`
+ * 3. But now what if the user navigates away? When the promise completes, it will
+ *    update the view regardless.
+ *
+ * In order to solve this, we use `switcher = PromiseSwitcher({ onResolve: updateView })`
+ * And then send off requests with `switcher.set(getViewData())`
+ * If set() is called with a new Promise while the previous is still pending, the
+ * pending promise is ignored – it doesn't call `onResolve` or `onReject`.
+ *
+ */
+export class PromiseSwitcher<Result> {
+    private pendingPromise: Promise<Result> | undefined
+
+    private onResolve?: (result: Result) => void
+    private onReject?: (error: any) => void
+
+    constructor(arg: PromiseSelectorArg<Result>) {
+        this.onResolve = arg.onResolve
+        this.onReject = arg.onReject
+    }
+
+    async set(promise: Promise<Result>): Promise<void> {
+        this.pendingPromise = promise
+        try {
+            const result = await promise
+            if (this.pendingPromise === promise) {
+                this.onResolve?.(result)
+            }
+        } catch (error) {
+            if (this.pendingPromise === promise) {
+                this.onReject?.(error)
+            }
+        }
+    }
+
+    clear(): void {
+        this.pendingPromise = undefined
+    }
+}

package/src/utils/TimeBounds.ts

@@ -0,0 +1,130 @@
+import {
+    EPOCH_DATE,
+    Time,
+    TimeBound,
+    TimeBoundValue,
+    TimeBoundValueStr,
+} from "../types/index.js"
+import {
+    parseIntOrUndefined,
+    diffDateISOStringInDays,
+    formatDay,
+    isNegativeInfinity,
+    isPositiveInfinity,
+} from "./Util.js"
+import * as R from "remeda"
+
+export const timeFromTimebounds = (
+    timeBound: TimeBound,
+    minTime: Time,
+    maxTime: Time
+): number => {
+    switch (timeBound) {
+        case -Infinity:
+            return minTime
+        case Infinity:
+            return maxTime
+        default:
+            return timeBound
+    }
+}
+
+const hasAnInfinity = (timeBound: TimeBound): timeBound is TimeBoundValue =>
+    isNegativeInfinity(timeBound) || isPositiveInfinity(timeBound)
+
+const formatTimeBound = (timeBound: TimeBound): string => {
+    if (isNegativeInfinity(timeBound)) return TimeBoundValueStr.unboundedLeft
+    if (isPositiveInfinity(timeBound)) return TimeBoundValueStr.unboundedRight
+    return `${timeBound}`
+}
+
+const parseTimeBound = (str: string): TimeBound | undefined => {
+    if (str === TimeBoundValueStr.unboundedLeft)
+        return TimeBoundValue.negativeInfinity
+
+    if (str === TimeBoundValueStr.unboundedRight)
+        return TimeBoundValue.positiveInfinity
+
+    return parseIntOrUndefined(str)
+}
+
+// Use this to not repeat logic
+const fromJSON = (value: TimeBound | string | undefined): number | undefined =>
+    R.isString(value) ? parseTimeBound(value) : value
+
+const toJSON = (
+    bound: TimeBound | undefined
+): TimeBoundValueStr | number | undefined => {
+    if (bound === undefined) return undefined
+    if (isNegativeInfinity(bound)) return TimeBoundValueStr.unboundedLeft
+    if (isPositiveInfinity(bound)) return TimeBoundValueStr.unboundedRight
+    return bound
+}
+
+export const minTimeBoundFromJSONOrNegativeInfinity = (
+    minTime: TimeBound | string | undefined
+): TimeBound => fromJSON(minTime) ?? TimeBoundValue.negativeInfinity
+
+export const maxTimeBoundFromJSONOrPositiveInfinity = (
+    maxTime: TimeBound | string | undefined
+): TimeBound => fromJSON(maxTime) ?? TimeBoundValue.positiveInfinity
+
+export const minTimeToJSON = toJSON
+export const maxTimeToJSON = toJSON
+
+const reISODateComponent = new RegExp("\\d{4}-[01]\\d-[0-3]\\d")
+const reISODate = new RegExp(`^(${reISODateComponent.source})$`)
+
+export const timeBoundToTimeBoundString = (
+    timeBound: TimeBound,
+    isDate: boolean
+): string => {
+    if (hasAnInfinity(timeBound)) return formatTimeBound(timeBound)
+    return isDate
+        ? formatDay(timeBound, { format: "YYYY-MM-DD" })
+        : `${timeBound}`
+}
+
+const parseTimeURIComponent = (param: string): TimeBound | undefined =>
+    reISODate.test(param)
+        ? diffDateISOStringInDays(param, EPOCH_DATE)
+        : parseTimeBound(param)
+
+const upgradeLegacyTimeString = (time: string): string => {
+    // In the past we supported unbounded time parameters like time=2015.. which would be
+    // equivalent to time=2015..latest. We don't actively generate these kinds of URL any
+    // more because URLs ending with dots are not interpreted correctly by many services
+    // (Twitter, Facebook and others) - but we still want to recognize incoming requests
+    // for these "legacy" URLs!
+    if (time === "..") return "earliest..latest"
+    return time.endsWith("..")
+        ? time + "latest"
+        : time.startsWith("..")
+          ? "earliest" + time
+          : time
+}
+
+export const getTimeDomainFromQueryString = (
+    time: string
+): [number, number] => {
+    time = upgradeLegacyTimeString(time)
+
+    const reIntComponent = new RegExp("\\-?\\d+")
+    const reIntRange = new RegExp(
+        `^(${reIntComponent.source}|earliest)\\.\\.(${reIntComponent.source}|latest)$`
+    )
+    const reDateRange = new RegExp(
+        `^(${reISODateComponent.source}|earliest)\\.\\.(${reISODateComponent.source}|latest)$`
+    )
+    if (reIntRange.test(time) || reDateRange.test(time)) {
+        const [start, end] = time.split("..")
+        return [
+            parseTimeURIComponent(start) ?? TimeBoundValue.negativeInfinity,
+            parseTimeURIComponent(end) ?? TimeBoundValue.positiveInfinity,
+        ]
+    }
+
+    const timebound =
+        parseTimeURIComponent(time) ?? TimeBoundValue.positiveInfinity
+    return [timebound, timebound]
+}

package/src/utils/Tippy.tsx

@@ -0,0 +1,57 @@
+import * as React from "react"
+import { default as OriginalTippy, TippyProps } from "@tippyjs/react"
+
+interface CustomTippyProps extends TippyProps {
+    lazy?: boolean
+}
+
+export const Tippy = (props: CustomTippyProps): React.ReactElement => {
+    const { lazy, ...tippyProps } = props
+
+    const TippyInstance = lazy ? LazyTippy : OriginalTippy
+    return <TippyInstance theme="light" {...tippyProps} />
+}
+
+// A Tippy instance that only evaluates `content` when the tooltip is shown.
+// Taken from https://gist.github.com/atomiks/520f4b0c7b537202a23a3059d4eec908
+// This will hopefully become supported in Tippy itself someday: See https://github.com/atomiks/tippyjs-react/issues/209
+export const LazyTippy = (props: TippyProps): React.ReactElement => {
+    const [mounted, setMounted] = React.useState(false)
+
+    const lazyPlugin = {
+        fn: (): { onMount: () => void; onHidden: () => void } => ({
+            onMount: (): void => setMounted(true),
+            onHidden: (): void => setMounted(false),
+        }),
+    }
+
+    const computedProps = { ...props }
+
+    computedProps.plugins = [lazyPlugin, ...(props.plugins || [])]
+
+    if (props.render) {
+        const render = props.render // let TypeScript safely derive that render is not undefined
+        computedProps.render = (...args): React.ReactNode =>
+            mounted ? render(...args) : ""
+    } else {
+        computedProps.content = mounted ? props.content : ""
+    }
+
+    return <Tippy {...computedProps} />
+}
+
+interface TippyIfInteractiveProps extends CustomTippyProps {
+    isInteractive: boolean
+}
+
+// We sometimes need a conditional Tippy instance, i.e. a Tippy that is only hooked up to
+// interactive charts (and not in static SVG exports etc.). This is that: If `isInteractive=false`,
+// then it bypasses Tippy and just renders the children.
+export const TippyIfInteractive = (
+    props: TippyIfInteractiveProps
+): React.ReactElement => {
+    const { isInteractive, ...tippyProps } = props
+
+    if (isInteractive) return <Tippy {...tippyProps} />
+    else return <>{props.children}</>
+}