@buildcanada/charts 0.1.0

package/src/grapher/scatterCharts/ScatterSizeLegend.tsx

@@ -0,0 +1,327 @@
+import * as React from "react"
+import * as R from "remeda"
+import { computed, makeObservable } from "mobx"
+import { scaleLinear, ScaleLinear } from "d3-scale"
+import { TextWrap, Halo } from "../../components/index.js"
+import {
+    Color,
+    makeIdForHumanConsumption,
+    OwidVariableRoundingMode,
+} from "../../utils/index.js"
+import {
+    BASE_FONT_SIZE,
+    GRAPHER_FONT_SCALE_10,
+    GRAPHER_FONT_SCALE_11,
+    GRAPHER_TEXT_OUTLINE_FACTOR,
+} from "../core/GrapherConstants"
+import { CoreColumn } from "../../core-table/index.js"
+import {
+    ScatterSeries,
+    SCATTER_POINT_MAX_RADIUS,
+    SCATTER_POINT_OPACITY,
+    SCATTER_POINT_STROKE_WIDTH,
+    SCATTER_POINT_DEFAULT_RADIUS,
+} from "./ScatterPlotChartConstants"
+import { darkenColorForText } from "../color/ColorUtils"
+import {
+    GRAPHER_BACKGROUND_DEFAULT,
+    GRAPHER_DARK_TEXT,
+    GRAPHER_LIGHT_TEXT,
+} from "../color/ColorConstants"
+
+export interface ScatterSizeLegendManager {
+    sidebarWidth: number
+    sizeColumn: CoreColumn
+    sizeScale: ScaleLinear<number, number>
+    fontSize?: number
+    tooltipSeries?: ScatterSeries
+    backgroundColor?: Color
+}
+
+const LEGEND_PADDING = 3
+const LEGEND_CIRCLE_COLOR = "#bbb"
+const LEGEND_VALUE_COLOR = "#444"
+const LABEL_PADDING = 2
+const LABEL_COLOR = GRAPHER_LIGHT_TEXT
+const TITLE_COLOR = GRAPHER_DARK_TEXT
+
+const MIN_FONT_SIZE = 9
+
+export class ScatterSizeLegend {
+    manager: ScatterSizeLegendManager
+    constructor(manager: ScatterSizeLegendManager) {
+        makeObservable(this)
+        this.manager = manager
+    }
+
+    @computed private get baseFontSize(): number {
+        return this.manager.fontSize ?? BASE_FONT_SIZE
+    }
+
+    @computed private get maxWidth(): number {
+        return this.manager.sidebarWidth
+    }
+
+    @computed private get ticks(): number[] {
+        const { sizeScale } = this.manager
+        const [domainStart, domainEnd] = sizeScale.domain()
+        if (domainStart === domainEnd) return [domainStart]
+        const [largestTick, ...restTicks] = sizeScale.ticks(6).toReversed()
+        if (largestTick === undefined) return []
+        const ticks = [largestTick]
+        restTicks.forEach((value) => {
+            if (
+                // make sure there is enough distance to prevent overlap with previous tick
+                sizeScale(value) <= sizeScale(R.last(ticks)!) - 6 &&
+                // don't go below the minimum tick radius
+                sizeScale(value) >= 6
+            ) {
+                ticks.push(value)
+            }
+        })
+        return ticks
+    }
+
+    private getPointRadius(value: number | undefined): number {
+        if (value === undefined) return SCATTER_POINT_DEFAULT_RADIUS
+        return this.manager.sizeScale(value)
+    }
+
+    // input radius, output font size
+    @computed private get fontSizeFromRadius(): ScaleLinear<number, number> {
+        return (
+            scaleLinear()
+                // choosing the domain & range somewhat arbitrarily here,
+                // by experimenting visually with font sizes
+                .domain([6, SCATTER_POINT_MAX_RADIUS])
+                .range([8, 11])
+                .clamp(true)
+        )
+    }
+
+    // Since it's circular, this is both the width and the height of the legend.
+    @computed private get legendSize(): number {
+        if (this.ticks.length === 0) return 0
+        const maxRadius = R.last(this.manager.sizeScale.range()) ?? 0
+        // adding some padding to account for label sticking out at the top
+        return 2 * maxRadius + 2
+    }
+
+    @computed private get label(): TextWrap {
+        const fontSize = Math.max(
+            MIN_FONT_SIZE,
+            GRAPHER_FONT_SCALE_10 * this.baseFontSize
+        )
+        return new TextWrap({
+            text: "Circles sized by",
+            // Allow text to _slightly_ go outside boundaries.
+            // Since we have padding left and right, this doesn't
+            // actually visibly overflow.
+            maxWidth: this.maxWidth + 12,
+            fontSize,
+            lineHeight: 1,
+        })
+    }
+
+    @computed private get title(): TextWrap {
+        const fontSize = Math.max(
+            MIN_FONT_SIZE,
+            GRAPHER_FONT_SCALE_11 * this.baseFontSize
+        )
+        return new TextWrap({
+            text: this.manager.sizeColumn.displayName,
+            // Allow text to _slightly_ go outside boundaries.
+            // Since we have padding left and right, this doesn't
+            // actually visibly overflow.
+            maxWidth: this.maxWidth + 10,
+            fontSize,
+            fontWeight: 700,
+            lineHeight: 1,
+        })
+    }
+
+    @computed get width(): number {
+        return this.manager.sidebarWidth
+    }
+
+    @computed get height(): number {
+        return (
+            this.legendSize +
+            LEGEND_PADDING +
+            this.label.height +
+            LABEL_PADDING +
+            this.title.height
+        )
+    }
+
+    @computed private get highlight():
+        | { value: number | undefined; color: string }
+        | undefined {
+        const { tooltipSeries } = this.manager
+        if (
+            tooltipSeries?.points.length === 1 &&
+            R.first(tooltipSeries.points)?.size !== undefined
+        ) {
+            return {
+                value: R.first(tooltipSeries.points)!.size,
+                color: tooltipSeries.color,
+            }
+        }
+        return undefined
+    }
+
+    private renderLegend(targetX: number, targetY: number): React.ReactElement {
+        const { highlight } = this
+        const cx = targetX + this.maxWidth / 2
+        return (
+            <React.Fragment>
+                {this.ticks.map((value) => {
+                    const radius = this.getPointRadius(value)
+                    return (
+                        <LegendItem
+                            key={value}
+                            label={this.manager.sizeColumn.formatValueShortWithAbbreviations(
+                                value,
+                                {
+                                    roundingMode:
+                                        OwidVariableRoundingMode.decimalPlaces,
+                                }
+                            )}
+                            cx={cx}
+                            cy={targetY + this.legendSize - radius}
+                            circleRadius={radius}
+                            circleStroke={
+                                highlight ? "#ddd" : LEGEND_CIRCLE_COLOR
+                            }
+                            labelFontSize={this.fontSizeFromRadius(radius)}
+                            labelFill={highlight ? "#bbb" : LEGEND_VALUE_COLOR}
+                            backgroundColor={this.manager.backgroundColor}
+                        />
+                    )
+                })}
+                {highlight && (
+                    <LegendItem
+                        key={highlight.value}
+                        label={this.manager.sizeColumn.formatValueShort(
+                            highlight.value
+                        )}
+                        cx={cx}
+                        cy={
+                            targetY +
+                            this.legendSize -
+                            this.getPointRadius(highlight.value)
+                        }
+                        circleFill={highlight.color}
+                        circleStroke={"#333"}
+                        circleStrokeWidth={SCATTER_POINT_STROKE_WIDTH}
+                        circleRadius={this.getPointRadius(highlight.value)}
+                        circleOpacity={SCATTER_POINT_OPACITY}
+                        labelFontSize={12}
+                        labelFill={darkenColorForText(highlight.color)}
+                        labelFontWeight={700}
+                        outsideLabel={true}
+                        backgroundColor={this.manager.backgroundColor}
+                    />
+                )}
+            </React.Fragment>
+        )
+    }
+
+    render(
+        targetX: number,
+        targetY: number,
+        renderOptions: React.SVGAttributes<SVGGElement> = {}
+    ): React.ReactElement {
+        const centerX = targetX + this.maxWidth / 2
+        return (
+            <g id={makeIdForHumanConsumption("size-legend")} {...renderOptions}>
+                {this.renderLegend(targetX, targetY)}
+                {this.label.renderSVG(
+                    centerX,
+                    targetY + this.legendSize + LEGEND_PADDING,
+                    {
+                        textProps: {
+                            fill: LABEL_COLOR,
+                            textAnchor: "middle",
+                        },
+                    }
+                )}
+                {this.title.renderSVG(
+                    centerX,
+                    targetY +
+                        this.legendSize +
+                        LEGEND_PADDING +
+                        this.label.height +
+                        LABEL_PADDING,
+                    {
+                        textProps: {
+                            fill: TITLE_COLOR,
+                            textAnchor: "middle",
+                        },
+                    }
+                )}
+            </g>
+        )
+    }
+}
+
+const LegendItem = ({
+    label,
+    cx,
+    cy,
+    circleRadius,
+    circleFill = "none",
+    circleStroke = LEGEND_CIRCLE_COLOR,
+    circleStrokeWidth = 1.25,
+    circleOpacity = 1,
+    labelFill = LEGEND_VALUE_COLOR,
+    labelFontSize,
+    labelFontWeight = 400,
+    outsideLabel = false,
+    backgroundColor = GRAPHER_BACKGROUND_DEFAULT,
+}: {
+    label: string
+    cx: number
+    cy: number
+    circleRadius: number
+    circleFill?: string
+    circleStroke?: string
+    circleStrokeWidth?: number
+    circleOpacity?: number
+    labelFill?: string
+    labelFontSize: number
+    labelFontWeight?: number
+    outsideLabel?: boolean
+    backgroundColor?: Color
+}): React.ReactElement => {
+    return (
+        <g>
+            <circle
+                cx={cx}
+                cy={cy}
+                r={circleRadius}
+                fill={circleFill}
+                stroke={circleStroke}
+                strokeWidth={circleStrokeWidth}
+                opacity={circleOpacity}
+            />
+            <Halo
+                id={label}
+                outlineWidth={GRAPHER_TEXT_OUTLINE_FACTOR * labelFontSize}
+                outlineColor={backgroundColor}
+            >
+                <text
+                    x={cx}
+                    y={cy - circleRadius}
+                    dy={outsideLabel ? "-.32em" : ".47em"}
+                    fill={labelFill}
+                    fontSize={labelFontSize}
+                    fontWeight={labelFontWeight}
+                    textAnchor="middle"
+                >
+                    {label}
+                </text>
+            </Halo>
+        </g>
+    )
+}

package/src/grapher/scatterCharts/ScatterUtils.ts

@@ -0,0 +1,265 @@
+import * as _ from "lodash-es"
+import * as R from "remeda"
+import {
+    Bounds,
+    ColumnSlug,
+    PointVector,
+    ValueRange,
+} from "../../utils/index.js"
+import {
+    SCATTER_LABEL_FONT_SIZE_FACTOR_WHEN_HIDDEN_LINES,
+    SCATTER_LINE_DEFAULT_WIDTH,
+    SCATTER_LINE_MAX_WIDTH,
+    SCATTER_POINT_DEFAULT_RADIUS,
+    SCATTER_POINT_MAX_RADIUS,
+    ScatterLabel,
+    ScatterRenderPoint,
+    ScatterRenderSeries,
+} from "./ScatterPlotChartConstants"
+import { BASE_FONT_SIZE } from "../core/GrapherConstants.js"
+import { ScatterPlotChartState } from "./ScatterPlotChartState"
+import { OwidTable } from "../../core-table/index.js"
+
+export const labelPriority = (label: ScatterLabel): number => {
+    let priority = label.fontSize
+
+    if (label.series.isHover) priority += 10000
+    if (label.series.isFocus) priority += 1000
+    if (label.isEnd) priority += 100
+
+    return priority
+}
+
+// Create the start year label for a series
+export const makeStartLabel = (
+    series: ScatterRenderSeries,
+    isSubtleForeground: boolean,
+    hideConnectedScatterLines: boolean,
+    baseFontSize: number
+): ScatterLabel | undefined => {
+    // No room to label the year if it's a single point
+    if (!series.isForeground || series.points.length <= 1) return undefined
+
+    const fontSize = hideConnectedScatterLines
+        ? SCATTER_LABEL_FONT_SIZE_FACTOR_WHEN_HIDDEN_LINES * baseFontSize
+        : series.isForeground
+          ? isSubtleForeground
+              ? (8 / BASE_FONT_SIZE) * baseFontSize
+              : (9 / BASE_FONT_SIZE) * baseFontSize
+          : (7 / BASE_FONT_SIZE) * baseFontSize
+    const firstValue = series.points[0]
+    const nextValue = series.points[1]
+    const nextSegment = nextValue.position.subtract(firstValue.position)
+
+    const pos = firstValue.position.subtract(nextSegment.normalize().times(5))
+    let bounds = Bounds.forText(firstValue.label, {
+        x: pos.x,
+        y: pos.y,
+        fontSize: fontSize,
+    })
+    if (pos.x < firstValue.position.x)
+        bounds = new Bounds(
+            bounds.x - bounds.width + 2,
+            bounds.y,
+            bounds.width,
+            bounds.height
+        )
+    if (pos.y > firstValue.position.y)
+        bounds = new Bounds(
+            bounds.x,
+            bounds.y + bounds.height / 2,
+            bounds.width,
+            bounds.height
+        )
+
+    return {
+        text: firstValue.label,
+        fontSize,
+        fontWeight: 400,
+        color: firstValue.color,
+        bounds,
+        series,
+        isStart: true,
+    }
+}
+
+// Make labels for the points between start and end on a series
+// Positioned using normals of the line segments
+export const makeMidLabels = (
+    series: ScatterRenderSeries,
+    isSubtleForeground: boolean,
+    hideConnectedScatterLines: boolean,
+    baseFontSize: number
+): ScatterLabel[] => {
+    if (
+        !series.isForeground ||
+        series.points.length <= 1 ||
+        (!series.isHover && isSubtleForeground)
+    )
+        return []
+
+    const fontSize = hideConnectedScatterLines
+        ? SCATTER_LABEL_FONT_SIZE_FACTOR_WHEN_HIDDEN_LINES * baseFontSize
+        : series.isForeground
+          ? isSubtleForeground
+              ? (8 / BASE_FONT_SIZE) * baseFontSize
+              : (9 / BASE_FONT_SIZE) * baseFontSize
+          : (7 / BASE_FONT_SIZE) * baseFontSize
+    const fontWeight = 400
+
+    // label all the way to the end for the tooltip series, otherwise to n-1
+    const lastIndex = series.isTooltip && !series.isFocus ? Infinity : -1
+
+    return series.points.slice(1, lastIndex).map((v, i) => {
+        const prevPos = i > 0 && series.points[i - 1].position
+        const prevSegment = prevPos && v.position.subtract(prevPos)
+        const nextPos = series.points[i + 1].position
+        const nextSegment = nextPos.subtract(v.position)
+
+        let pos = v.position
+        if (prevPos && prevSegment) {
+            const normals = prevSegment
+                .add(nextSegment)
+                .normalize()
+                .normals()
+                .map((x) => x.times(5))
+            const potentialSpots = normals.map((n) => v.position.add(n))
+            pos = _.maxBy(potentialSpots, (p) => {
+                return (
+                    PointVector.distance(p, prevPos) +
+                    PointVector.distance(p, nextPos)
+                )
+            }) as PointVector
+        } else {
+            pos = v.position.subtract(nextSegment.normalize().times(5))
+        }
+
+        let bounds = Bounds.forText(v.label, {
+            x: pos.x,
+            y: pos.y,
+            fontSize: fontSize,
+            fontWeight: fontWeight,
+        })
+        if (pos.x < v.position.x)
+            bounds = new Bounds(
+                bounds.x - bounds.width + 2,
+                bounds.y,
+                bounds.width,
+                bounds.height
+            )
+        if (pos.y > v.position.y)
+            bounds = new Bounds(
+                bounds.x,
+                bounds.y + bounds.height / 2,
+                bounds.width,
+                bounds.height
+            )
+
+        return {
+            text: v.label,
+            fontSize,
+            fontWeight,
+            color: v.color,
+            bounds,
+            series,
+            isMid: true,
+        }
+    })
+}
+
+// Make the end label (entity label) for a series. Will be pushed
+// slightly out based on the direction of the series if multiple values
+// are present
+// This is also the one label in the case of a single point
+export const makeEndLabel = (
+    series: ScatterRenderSeries,
+    isSubtleForeground: boolean,
+    hideConnectedScatterLines: boolean,
+    baseFontSize: number
+): ScatterLabel => {
+    const lastValue = R.last(series.points) as ScatterRenderPoint
+    const lastPos = lastValue.position
+    const fontSize = hideConnectedScatterLines
+        ? SCATTER_LABEL_FONT_SIZE_FACTOR_WHEN_HIDDEN_LINES * baseFontSize
+        : series.fontSize *
+          (series.isForeground ? (isSubtleForeground ? 1.2 : 1.3) : 1.1)
+    const fontWeight =
+        series.isForeground && !hideConnectedScatterLines ? 700 : 400
+
+    let offsetVector = PointVector.up
+    if (series.points.length > 1) {
+        const prevValue = series.points[series.points.length - 2]
+        const prevPos = prevValue.position
+        offsetVector = lastPos.subtract(prevPos)
+    }
+    series.offsetVector = offsetVector
+
+    const labelPos = lastPos.add(
+        offsetVector
+            .normalize()
+            .times(series.points.length === 1 ? lastValue.size + 1 : 5)
+    )
+
+    let labelBounds = Bounds.forText(series.text, {
+        x: labelPos.x,
+        y: labelPos.y,
+        fontSize: fontSize,
+    })
+
+    if (labelPos.x < lastPos.x)
+        labelBounds = labelBounds.set({
+            x: labelBounds.x - labelBounds.width,
+        })
+    if (labelPos.y > lastPos.y)
+        labelBounds = labelBounds.set({
+            y: labelBounds.y + labelBounds.height / 2,
+        })
+
+    return {
+        text:
+            hideConnectedScatterLines && series.isForeground
+                ? lastValue.label
+                : series.isTooltip && !series.isFocus
+                  ? "" // don't doubly label the series name when the tooltip is visible
+                  : series.text,
+        fontSize,
+        fontWeight,
+        color: lastValue.color,
+        bounds: labelBounds,
+        series,
+        isEnd: true,
+    }
+}
+
+export function toSizeRange(
+    chartState: ScatterPlotChartState,
+    bounds: Bounds
+): [number, number] {
+    if (chartState.sizeColumn.isMissing) {
+        // if the size column is missing, we want all points/lines to have the same width
+        return chartState.isConnected
+            ? [SCATTER_LINE_DEFAULT_WIDTH, SCATTER_LINE_DEFAULT_WIDTH]
+            : [SCATTER_POINT_DEFAULT_RADIUS, SCATTER_POINT_DEFAULT_RADIUS]
+    }
+
+    const maxLineWidth = SCATTER_LINE_MAX_WIDTH
+    const maxPointRadius = Math.min(
+        SCATTER_POINT_MAX_RADIUS,
+        _.round(Math.min(bounds.width, bounds.height) * 0.06, 1)
+    )
+
+    return chartState.isConnected
+        ? // Note that the scale starts at 0.
+          // When using the scale to plot marks, we need to make sure the minimums
+          // (e.g. `SCATTER_POINT_MIN_RADIUS`) are respected.
+          [0, maxLineWidth]
+        : [0, maxPointRadius]
+}
+
+export function computeSizeDomain(
+    table: OwidTable,
+    slug: ColumnSlug
+): ValueRange {
+    const sizeValues = table.get(slug).values.filter(_.isNumber)
+    return [0, _.max(sizeValues) ?? 1]
+}

package/src/grapher/scatterCharts/Triangle.tsx

@@ -0,0 +1,41 @@
+import * as React from "react"
+import * as _ from "lodash-es"
+
+type TriangleProps = Readonly<{
+    cx: number
+    cy: number
+    r: number
+    fill?: string
+    stroke?: string
+    strokeWidth?: number
+    rotation?: number
+}> &
+    React.SVGProps<SVGPolygonElement>
+
+export const Triangle = (props: TriangleProps): React.ReactElement => {
+    const { cx, cy, r, rotation } = props
+    const x = cx - r,
+        y = cy - r
+    const points = [
+        [x, y + r * 2],
+        [x + (r * 2) / 2, y],
+        [x + r * 2, y + r * 2],
+    ]
+    const rotationRounded = rotation
+        ? [rotation, cx, cy].map((v) => _.round(v, 2))
+        : undefined
+
+    return (
+        <polygon
+            points={points
+                .map((p) => `${p[0].toFixed(2)},${p[1].toFixed(2)}`)
+                .join(" ")}
+            transform={
+                rotationRounded
+                    ? `rotate(${rotationRounded.join(", ")})`
+                    : undefined
+            }
+            {..._.omit(props, "rotation")}
+        />
+    )
+}

package/src/grapher/schema/README.md

@@ -0,0 +1,33 @@
+This folder contains the JSON schema for the configuration of Grapher.
+
+## How to evolve the schema
+
+The schema is versioned. There is one yaml file with a version number. For nonbreaking changes (e.g. additions of optional fields) you can just
+edit the yaml file as is. A github action will then generate a .latest.yaml and two json files (one .latest.json and one with the version number.json)
+and upload them to S3 so they can be accessed publicly.
+
+If you update the default value of an existing property or you add a new property with a default value, make sure to regenerate the default object from the schema and save it to `defaultGrapherConfig.ts` (see below).
+
+Breaking changes should be done by renaming the schema file to an increased version number. Make sure to also rename the authorative url
+inside the schema file (the "$id" field at the top level) to point to the new version number json. Then write the migrations from the last to
+the current version of the schema, including the migration of pointing to the URL of the new schema version.s
+
+Checklist for breaking changes:
+
+- Rename the schema file to an increased version number
+- Rename the authorative url inside the schema file to point to the new version number json
+- Write the migrations from the last to the current version of the schema, including the migration of pointing to the URL of the new schema version
+- Regenerate the default object from the schema and save it to `defaultGrapherConfig.ts` (see below)
+- Write a migration to update the `chart_configs.full` column in the database for all stand-alone charts
+- Write a migration to update configs in code (see `migrations/migrations.ts`)
+- Update the hardcoded default schema version in ETL
+
+To regenerate `defaultGrapherConfig.ts` from the schema, replace `XXX` with the current schema version number and run:
+
+```bash
+# generate json from the yaml schema
+nu -c 'open packages/@ourworldindata/grapher/src/schema/grapher-schema.XXX.yaml | to json' > packages/@ourworldindata/grapher/src/schema/grapher-schema.XXX.json
+
+# generate the default object from the schema
+yarn tsx --tsconfig tsconfig.tsx.json devTools/schema/generate-default-object-from-schema.ts packages/@ourworldindata/grapher/src/schema/grapher-schema.XXX.json --save-ts packages/@ourworldindata/grapher/src/schema/defaultGrapherConfig.ts
+```