@buildcanada/charts 0.1.0

package/src/grapher/color/readme.md

@@ -0,0 +1,84 @@
+# Binning Strategies
+
+Grapher supports several automatic binning strategies, and can also automatically choose the best strategy to use based on data.
+One key input into choosing a suiting strategy is the (log10) magnitude difference, i.e. $\log_{10}(maxValue) - \log_{10}(minValue)$.
+For example, the magnitude difference between 4 and 400 is 2, because $4 \cdot 10^{\mathbf 2} = 400$.
+
+In general, if we have a high magnitude difference, we want to use a logarithmic binning strategy, and if we have a low one we want to use an equal-sized binning strategy.
+We only compute the magnitude difference based on positive values, and don't take the lowest and highest values directly, but rather some low and high quantiles.
+
+```mermaid
+flowchart TD
+    A -->|small magnitude diff| E
+    S --> E[equalSizeBins]
+    S(Binning Strategy) --> A[auto]
+    S --> L[logarithmic]
+    A -->|large magnitude diff| L
+
+    E --> E1(Compute min, max value based on quantiles)
+    E1 --> E2(Find fitting, nice step size that produces a decent number of bins)
+    E2 -->|e.g. 10| E3(Compute bins; e.g. 0, 10, 20, 30, 40)
+
+    L --> L1(Compute min, max value based on quantiles)
+    L1 --> L2(Decide specific strategy based on magnitude difference)
+    L2 -->|log-1-2-5| L3(Compute bins; e.g. 0, 10, 20, 50, 100)
+    L2 -->|log-1-3| L3
+    L2 -->|log-1-10| L3
+```
+
+## Finding min & max values
+
+To find the min and max values for binning, we use low and high quantiles instead of the raw min and max values.
+This naturally removes outliers and will produce open-ended bins more often.
+
+Min & max values can also be overridden manually in the admin.
+
+Note that min & max values need to be non-zero positive numbers for log strategies, but can be any number for equal-size strategies.
+
+## Equal-size strategy
+
+For the equal-size strategy, we are differentiating between four different strategies:
+
+- `equalSizeBins-normal` (default): creates 5-9 bins
+- `equalSizeBins-few-bins`: creates fewer bins than that
+- `equalSizeBins-many-bins`: creates more bins than that
+- `equalSizeBins-percent`: creates bins of size 10% (0-10%, 10-20%, ...)
+
+Note that `equalSizeBins-percent` is chosen automatically when we detect that the data is a percentage that's roughly in the 0-100% range.
+
+Once we have resolved the strategy to use, we can then proceed to pick the step size to use. This process is based on a list of "known good" step sizes, which we choose in such a way that we arrive at a reasonable number of bins that is within the target range of bins.
+
+## Logarithmic strategy
+
+For logarithmic binning, we also differentiate between several strategies:
+
+- `log-auto`: automatically chooses the best log binning strategy based on data, useful for when you want to force using a log strategy
+- `log-1-2-5`: follows the 1, 2, 5, 10, 20, ... pattern
+- `log-1-3`: follows the 1, 3, 10, 30, 100, ... pattern
+- `log-1-10`: follows the 1, 10, 100, ... pattern
+
+After picking out one of these strategies (either manually or automatically), the log strategy then produces bins such that they fill the range between `minValue` and `maxValue`.
+
+## Midpoints & midpoint modes
+
+Some of our charts also have natural midpoints, where we want to create a diverging color scale around the midpoint.
+The most common natural midpoint is 0.
+
+We have a bunch of different midpoint modes:
+
+- `undefined` (automatic): chooses `symmetric` if there are values on both sides of the midpoint, otherwise chooses `none`
+- `none`: disregards the midpoint
+- `symmetric`: creates bins around the midpoint that are fully symmetric, i.e. there's the same number of bins on both sides, and they have the same distance from the midpoint
+    - example: `-20, -10, -5, 0, 5, 10, 20`
+- `same-num-bins`: creates (roughly) the same number of bins on both sides, but creates them independently, without regard to the distance from the midpoint
+    - example: `-10, -5, -2, 0, 10, 20, 50`
+- `asymmetric`: like `symmetric`, but then prunes any bins that are not below `minValue` or above `maxValue`
+    - example: `-10, -5, 0, 5, 10, 20`
+
+### NO integration with diverging color schemes
+
+Note that currently, midpoints are not integrated with color scales.
+This means that modes other than `symmetric` will not pick "good/bad" colors from a _diverging color scheme_ for the bins on both sides of the midpoint.
+`symmetric` mode supports this, by virtue of it picking the same number of bins on both sides of the midpoint.
+
+This is a feature that's clearly relevant, and it shouldn't be too hard to implement this in the future.

package/src/grapher/comparisonLine/ComparisonLine.tsx

@@ -0,0 +1,31 @@
+import { DualAxis } from "../axis/Axis"
+import {
+    Color,
+    ComparisonLineConfig,
+    VerticalComparisonLineConfig,
+} from "../../types/index.js"
+import { VerticalComparisonLine } from "./VerticalComparisonLine"
+import { CustomComparisonLine } from "./CustomComparisonLine"
+import { isValidVerticalComparisonLineConfig } from "./ComparisonLineHelpers"
+
+export interface ComparisonLineProps<LineConfig extends ComparisonLineConfig> {
+    dualAxis: DualAxis
+    comparisonLine: LineConfig
+    backgroundColor?: Color
+}
+
+export const ComparisonLine = <LineConfig extends ComparisonLineConfig>(
+    props: ComparisonLineProps<LineConfig>
+) => {
+    if (isVerticalComparisonLineProps(props)) {
+        return <VerticalComparisonLine {...props} />
+    } else {
+        return <CustomComparisonLine {...props} />
+    }
+}
+
+function isVerticalComparisonLineProps(
+    props: ComparisonLineProps<ComparisonLineConfig>
+): props is ComparisonLineProps<VerticalComparisonLineConfig> {
+    return isValidVerticalComparisonLineConfig(props.comparisonLine)
+}

package/src/grapher/comparisonLine/ComparisonLineConstants.ts

@@ -0,0 +1,11 @@
+export const COMPARISON_LINE_STYLE = {
+    opacity: 0.9,
+    fill: "none",
+    stroke: "#ccc",
+    strokeDasharray: "2 2",
+}
+
+export const COMPARISON_LINE_LABEL_STYLE = {
+    fill: "#999",
+    opacity: 0.9,
+}

package/src/grapher/comparisonLine/ComparisonLineGenerator.ts

@@ -0,0 +1,60 @@
+import Formula from "fparser"
+import { scaleLinear, scaleLog } from "d3-scale"
+import { ScaleType } from "../../types/index.js"
+
+export function generateComparisonLinePoints(
+    lineFunction: string = "x",
+    xScaleDomain: [number, number],
+    yScaleDomain: [number, number],
+    xScaleType: ScaleType,
+    yScaleType: ScaleType
+): [number, number][] {
+    const formula = parseEquation(lineFunction)
+    const yFunc = (x: number): number | undefined =>
+        evalFormula(formula, { x }, undefined)
+
+    // Construct control data by running the equation across sample points
+    const numPoints = 500
+
+    const scaleFunction = xScaleType === ScaleType.log ? scaleLog : scaleLinear
+    const scale = scaleFunction().domain(xScaleDomain).range([0, numPoints])
+
+    const controlData: Array<[number, number]> = []
+    for (let i = 0; i < numPoints; i++) {
+        const x = scale.invert(i)
+        const y = yFunc(x)
+
+        if (y === undefined || Number.isNaN(x) || Number.isNaN(y)) continue
+        if (xScaleType === ScaleType.log && x <= 0) continue
+        if (yScaleType === ScaleType.log && y <= 0) continue
+        if (y > yScaleDomain[1]) continue
+        controlData.push([x, y])
+    }
+
+    return controlData
+}
+
+export function evalFormula<D>(
+    expr: Formula | undefined,
+    context: Record<string, number>,
+    defaultOnError: D
+): number | D {
+    if (expr === undefined) return defaultOnError
+    try {
+        return expr.evaluate(context) as number
+    } catch {
+        return defaultOnError
+    }
+}
+
+export function parseEquation(equation: string): Formula | undefined {
+    try {
+        const formula = new Formula(equation)
+        formula.ln = Math.log
+        formula.e = Math.E
+        return formula
+    } catch (e) {
+        console.error(e)
+        return undefined
+    }
+}

package/src/grapher/comparisonLine/ComparisonLineHelpers.ts

@@ -0,0 +1,10 @@
+import {
+    ComparisonLineConfig,
+    VerticalComparisonLineConfig,
+} from "../../types/index.js"
+
+export function isValidVerticalComparisonLineConfig(
+    lineConfig: ComparisonLineConfig
+): lineConfig is VerticalComparisonLineConfig {
+    return "xEquals" in lineConfig && lineConfig.xEquals !== undefined
+}

package/src/grapher/comparisonLine/CustomComparisonLine.tsx

@@ -0,0 +1,159 @@
+import * as React from "react"
+import { computed, makeObservable } from "mobx"
+import { observer } from "mobx-react"
+import { line as d3_line, curveLinear } from "d3-shape"
+import {
+    guid,
+    PointVector,
+    makeIdForHumanConsumption,
+} from "../../utils/index.js"
+import { CustomComparisonLineConfig } from "../../types/index.js"
+import { generateComparisonLinePoints } from "./ComparisonLineGenerator"
+import { Halo } from "../../components/index.js"
+import { GRAPHER_TEXT_OUTLINE_FACTOR } from "../core/GrapherConstants"
+import { ClipPath, makeClipPath } from "../chart/ChartUtils"
+import {
+    COMPARISON_LINE_STYLE,
+    COMPARISON_LINE_LABEL_STYLE,
+} from "./ComparisonLineConstants"
+import { ComparisonLineProps } from "./ComparisonLine"
+
+@observer
+export class CustomComparisonLine extends React.Component<
+    ComparisonLineProps<CustomComparisonLineConfig>
+> {
+    private renderUid = guid()
+    private pathId = `path-${this.renderUid}`
+
+    constructor(props: ComparisonLineProps<CustomComparisonLineConfig>) {
+        super(props)
+        makeObservable(this)
+    }
+
+    @computed private get fontSize(): number {
+        return this.props.dualAxis.comparisonLineLabelFontSize
+    }
+
+    @computed private get haloOutlineWidth(): number {
+        return GRAPHER_TEXT_OUTLINE_FACTOR * this.fontSize
+    }
+
+    @computed get clipPath(): ClipPath {
+        return makeClipPath({
+            name: "axisBounds",
+            renderUid: this.renderUid,
+            box: this.props.dualAxis.innerBounds,
+        })
+    }
+
+    @computed private get controlData(): [number, number][] {
+        const { comparisonLine, dualAxis } = this.props
+        const { horizontalAxis, verticalAxis } = dualAxis
+
+        return generateComparisonLinePoints(
+            comparisonLine.yEquals,
+            horizontalAxis.domain,
+            verticalAxis.domain,
+            horizontalAxis.scaleType,
+            verticalAxis.scaleType
+        )
+    }
+
+    @computed private get linePath(): string | null {
+        const { controlData } = this
+        const { horizontalAxis, verticalAxis } = this.props.dualAxis
+        const line = d3_line()
+            .curve(curveLinear)
+            .x((d) => horizontalAxis.place(d[0]))
+            .y((d) => verticalAxis.place(d[1]))
+        return line(controlData)
+    }
+
+    @computed private get placedLabel():
+        | { x: number; y: number; angle: number; text: string }
+        | undefined {
+        const { label } = this.props.comparisonLine
+        if (!label) return
+
+        const { controlData } = this
+        const { horizontalAxis, verticalAxis, innerBounds } =
+            this.props.dualAxis
+
+        // Find the points of the line that are actually placeable on the chart
+        const linePoints = controlData
+            .map(
+                (d) =>
+                    new PointVector(
+                        horizontalAxis.place(d[0]),
+                        verticalAxis.place(d[1])
+                    )
+            )
+            .filter((p) => innerBounds.contains(p))
+        if (!linePoints.length) return
+
+        const labelPosition = linePoints[Math.floor(linePoints.length / 2)]
+        const p1 = linePoints[0]
+        const p2 = linePoints[linePoints.length - 1]
+        const angle = (Math.atan2(p2.y - p1.y, p2.x - p1.x) * 180) / Math.PI
+
+        return {
+            x: labelPosition.x,
+            y: labelPosition.y,
+            angle: angle,
+            text: label,
+        }
+    }
+
+    private renderLabel(): React.ReactElement | null {
+        const { pathId, renderUid, placedLabel } = this
+
+        if (!placedLabel) return null
+
+        return (
+            <text
+                style={{
+                    ...COMPARISON_LINE_LABEL_STYLE,
+                    textAnchor: "end",
+                    fontSize: this.fontSize,
+                }}
+                clipPath={this.clipPath.id}
+            >
+                <Halo
+                    id={`halo-${renderUid}`}
+                    outlineWidth={this.haloOutlineWidth}
+                    outlineColor={this.props.backgroundColor}
+                >
+                    <textPath
+                        baselineShift="-0.2rem"
+                        href={`#${pathId}`}
+                        startOffset="90%"
+                    >
+                        {placedLabel.text}
+                    </textPath>
+                </Halo>
+            </text>
+        )
+    }
+
+    override render(): React.ReactElement | null {
+        if (!this.linePath) return null
+
+        return (
+            <g
+                id={makeIdForHumanConsumption(
+                    "comparison-line",
+                    this.props.comparisonLine.label
+                )}
+            >
+                {this.clipPath.element}
+                <path
+                    style={COMPARISON_LINE_STYLE}
+                    id={this.pathId}
+                    d={this.linePath}
+                    clipPath={this.clipPath.id}
+                />
+                {this.renderLabel()}
+            </g>
+        )
+    }
+}

package/src/grapher/comparisonLine/VerticalComparisonLine.tsx

@@ -0,0 +1,208 @@
+import * as React from "react"
+import { computed, makeObservable } from "mobx"
+import { observer } from "mobx-react"
+import * as _ from "lodash-es"
+import {
+    Bounds,
+    dyFromAlign,
+    makeIdForHumanConsumption,
+    VerticalAlign,
+} from "../../utils/index.js"
+import {
+    COMPARISON_LINE_STYLE,
+    COMPARISON_LINE_LABEL_STYLE,
+} from "./ComparisonLineConstants"
+import { ComparisonLineProps } from "./ComparisonLine"
+import { VerticalComparisonLineConfig } from "../../types/index.js"
+import { isValidVerticalComparisonLineConfig } from "./ComparisonLineHelpers"
+
+@observer
+export class VerticalComparisonLine extends React.Component<
+    ComparisonLineProps<VerticalComparisonLineConfig>
+> {
+    constructor(props: ComparisonLineProps<VerticalComparisonLineConfig>) {
+        super(props)
+        makeObservable(this)
+    }
+
+    @computed private get fontSize(): number {
+        return this.props.dualAxis.comparisonLineLabelFontSize
+    }
+
+    @computed private get labelHeight(): number {
+        // Since the label isn't wrapped, its height equals the font size
+        return this.fontSize
+    }
+
+    @computed private get lineConfig(): VerticalComparisonLineConfig {
+        return this.props.comparisonLine
+    }
+
+    @computed
+    private get otherVerticalComparisonLines(): VerticalComparisonLineConfig[] {
+        return this.props.dualAxis.comparisonLines.filter(
+            (lineConfig): lineConfig is VerticalComparisonLineConfig =>
+                isValidVerticalComparisonLineConfig(lineConfig) &&
+                lineConfig.xEquals !== this.props.comparisonLine.xEquals
+        )
+    }
+
+    /** Nearest comparison line to the left of this line */
+    @computed private get closestLeftLine():
+        | VerticalComparisonLineConfig
+        | undefined {
+        const linesOnTheLeft = this.otherVerticalComparisonLines.filter(
+            (otherLine) => otherLine.xEquals < this.lineConfig.xEquals
+        )
+        return _.maxBy(linesOnTheLeft, (line) => line.xEquals)
+    }
+
+    /** Nearest comparison line to the right of this line */
+    @computed private get closestRightLine():
+        | VerticalComparisonLineConfig
+        | undefined {
+        const linesOnTheRight = this.otherVerticalComparisonLines.filter(
+            (otherLine) => otherLine.xEquals > this.lineConfig.xEquals
+        )
+        return _.minBy(linesOnTheRight, (line) => line.xEquals)
+    }
+
+    /**
+     * X-coordinate of the leftmost boundary for label placement.
+     *
+     * Either the position of the nearest comparison line on the left
+     * or the chart's bound.
+     */
+    @computed private get leftBoundX(): number {
+        const { closestLeftLine } = this
+        const { innerBounds, horizontalAxis } = this.props.dualAxis
+
+        if (!closestLeftLine) return innerBounds.left
+
+        return Math.max(
+            horizontalAxis.place(closestLeftLine.xEquals),
+            innerBounds.left
+        )
+    }
+
+    /**
+     * X-coordinate of the rightmost boundary for label placement.
+     *
+     * Either the position of the nearest comparison line on the right
+     * or the chart's bound.
+     */
+    @computed private get rightBoundX(): number {
+        const { closestRightLine } = this
+        const { innerBounds, horizontalAxis } = this.props.dualAxis
+
+        if (!closestRightLine) return innerBounds.right
+
+        return Math.min(
+            horizontalAxis.place(closestRightLine.xEquals),
+            innerBounds.right
+        )
+    }
+
+    /** Screen coordinates for rendering the vertical line */
+    @computed private get lineCoordinates():
+        | { x: number; y1: number; y2: number }
+        | undefined {
+        const { dualAxis } = this.props
+        const { horizontalAxis, innerBounds } = dualAxis
+        const xValue = this.lineConfig.xEquals
+        const [minX, maxX] = horizontalAxis.domain
+
+        // Only render if the line is within the chart bounds
+        const isWithinBounds = xValue >= minX && xValue <= maxX
+        if (!isWithinBounds) return undefined
+
+        return {
+            x: horizontalAxis.place(xValue),
+            // The line extends outside of the chart area, so that the label
+            // isn't covered by any chart elements
+            y1: innerBounds.top - this.labelHeight,
+            y2: innerBounds.bottom,
+        }
+    }
+
+    /** Calculated position and alignment for the label text */
+    @computed private get labelPosition():
+        | { x: number; y: number; anchor: "start" | "end" }
+        | undefined {
+        const { fontSize, lineCoordinates, rightBoundX, leftBoundX } = this
+        const { label } = this.lineConfig
+
+        if (!label || !lineCoordinates) return undefined
+
+        const { x, y1: y } = lineCoordinates
+
+        // Calculate available space on both sides
+        const padding = 4 // padding between label and line
+        const availableSpaceRight = rightBoundX - x - 2 * padding
+        const availableSpaceLeft = x - leftBoundX - 2 * padding
+
+        // Determine label placement:
+        // - Prefer the right side if there's enough space
+        // - Otherwise, try placing the label on the left side
+        // - If neither side has enough space, hide the label
+        const labelWidth = Bounds.forText(label, { fontSize }).width
+        const side =
+            labelWidth <= availableSpaceRight
+                ? "right"
+                : labelWidth <= availableSpaceLeft
+                  ? "left"
+                  : null
+
+        // Can't fit the label
+        if (side === null) return undefined
+
+        // Add a bit of padding between label and line and determine text anchor
+        const labelX = side === "right" ? x + padding : x - padding
+        const anchor = side === "right" ? "start" : "end"
+
+        return { x: labelX, y, anchor }
+    }
+
+    private renderLabel(): React.ReactElement | null {
+        if (!this.labelPosition) return null
+
+        const { x, y, anchor } = this.labelPosition
+
+        return (
+            <text
+                {...COMPARISON_LINE_LABEL_STYLE}
+                x={x}
+                y={y}
+                fontSize={this.fontSize}
+                dy={dyFromAlign(VerticalAlign.bottom)}
+                textAnchor={anchor}
+            >
+                {this.lineConfig.label}
+            </text>
+        )
+    }
+
+    override render(): React.ReactElement | null {
+        if (!this.lineCoordinates || !this.labelPosition) return null
+
+        const { x, y1, y2 } = this.lineCoordinates
+
+        return (
+            <g
+                id={makeIdForHumanConsumption(
+                    "comparison-line",
+                    this.lineConfig.label
+                )}
+            >
+                <line
+                    x1={x}
+                    y1={y1}
+                    x2={x}
+                    y2={y2}
+                    style={COMPARISON_LINE_STYLE}
+                />
+                {this.renderLabel()}
+            </g>
+        )
+    }
+}

package/src/grapher/controls/ActionButtons.scss

@@ -0,0 +1,97 @@
+// keep in sync with constant values in ActionButtons.tsx
+$actionButtonHeight: 32px; // keep in sync with BUTTON_HEIGHT
+$paddingBetweenActionButtons: 8px; // keep in sync with PADDING_BETWEEN_BUTTONS
+$paddingBetweenIconAndLabel: 8px; // keep in sync with PADDING_BETWEEN_ICON_AND_LABEL
+$paddingX: 12px; // keep in sync with PADDING_X
+
+.ActionButtons {
+    margin: 0;
+    padding: 0;
+    white-space: nowrap;
+
+    ul {
+        display: flex;
+        list-style: none;
+        height: $actionButtonHeight;
+        padding: 0;
+    }
+
+    li {
+        height: 100%;
+        display: inline-block;
+        position: relative;
+    }
+
+    li + li {
+        margin-left: $paddingBetweenActionButtons;
+    }
+}
+
+div.ActionButton {
+    --light-fill: #{$gray-10};
+    --hover-fill: #{$gray-20};
+    --active-fill: #{$blue-20};
+    --text-color: #{$dark-text};
+
+    &.ActionButton--exploreData {
+        --light-fill: #{$blue-20};
+        --hover-fill: #{$blue-20};
+        --active-fill: #{$blue-10};
+        --text-color: #{$blue-90};
+
+        --hover-decoration: underline;
+    }
+
+    &.ActionButton--donate {
+        --light-fill: #{rgba($vermillion, 0.15)};
+        --hover-fill: #{rgba(#f4a39f, 0.15)};
+        --active-fill: var(--hover-fill);
+        --text-color: #{$vermillion};
+    }
+
+    height: 100%;
+    border-radius: 4px;
+    position: relative;
+
+    button,
+    a {
+        display: flex;
+        align-items: center;
+        gap: $paddingBetweenIconAndLabel;
+        height: 100%;
+        width: 100%;
+        cursor: pointer;
+        color: var(--text-color);
+        font-size: 13px;
+        font-weight: 500;
+        padding: 0 $paddingX;
+        border-radius: inherit;
+        background-color: var(--light-fill);
+        position: relative;
+        letter-spacing: 0.01em;
+
+        svg {
+            font-size: 12px;
+        }
+
+        &.icon-only {
+            justify-content: center;
+            padding: 0;
+        }
+
+        &:visited {
+            color: var(--text-color);
+        }
+
+        &:hover {
+            background-color: var(--hover-fill);
+            text-decoration: var(--hover-decoration);
+        }
+
+        &:active,
+        &.active {
+            color: $active-text;
+            background-color: var(--active-fill);
+        }
+    }
+}