@buildcanada/charts 0.1.0

package/src/explorer/gridLang/GridProgram.ts

@@ -0,0 +1,311 @@
+import { trimMatrix } from "../../core-table/index.js"
+import {
+    isPresent,
+    GitCommit,
+    SerializedGridProgram,
+} from "../../utils/index.js"
+
+import { GridCell } from "./GridCell.js"
+import {
+    CellDef,
+    CellPosition,
+    GRID_CELL_DELIMITER,
+    GRID_EDGE_DELIMITER,
+    GRID_NODE_DELIMITER,
+    Origin,
+    ParsedCell,
+} from "./GridLangConstants.js"
+import { tsvToMatrix } from "./GrammarUtils.js"
+
+/**
+ * Block location for the below would be like (numRows = 2)
+ * table             |
+ *  slug name        | startRow = 1
+ *  pop Population   | endRow   = 2
+ */
+interface BlockLocation {
+    startRow: number
+    endRow: number
+    numRows: number
+}
+
+export class GridProgram {
+    constructor(
+        slug: string,
+        tsv: string,
+        lastCommit?: GitCommit,
+        grammar?: CellDef
+    ) {
+        this.lines = tsvToMatrix(tsv.replace(/\r/g, ""))
+        this.slug = slug
+        this.lastCommit = lastCommit
+        this.grammar = grammar
+    }
+
+    private grammar?
+
+    private static guids = 0
+    guid = ++GridProgram.guids
+
+    lastCommit?: GitCommit
+    slug: string
+
+    private nodeDelimiter = GRID_NODE_DELIMITER
+    cellDelimiter = GRID_CELL_DELIMITER
+    private edgeDelimiter = GRID_EDGE_DELIMITER
+    lines: string[][]
+
+    toJson(): SerializedGridProgram {
+        return {
+            program: this.toString(),
+            slug: this.slug,
+            lastCommit: this.lastCommit,
+        }
+    }
+
+    findNext(position: CellPosition) {
+        const cell = this.getCell(position)
+        const { contents } = cell
+        return this.grepFirst(contents, {
+            ...position,
+            column: position.column + 1,
+        })
+    }
+
+    findAll(position: CellPosition) {
+        const cell = this.getCell(position)
+        const { contents } = cell
+        return this.grep(contents, {
+            ...position,
+            column: position.column + 1,
+        })
+    }
+
+    private ring(position: CellPosition) {
+        const lines = this.lines
+        const numRows = lines.length
+        if (!numRows)
+            return (function* generator() {
+                // no rows to iterate over
+            })()
+        const pointer = {
+            ...position,
+            started: false,
+            endRow: position.row,
+            endCol: position.column,
+        }
+        if (pointer.row >= numRows) pointer.endRow = numRows - 1
+
+        const lastLine = lines[pointer.endRow]
+        pointer.endCol =
+            lastLine[pointer.endCol] === undefined
+                ? lastLine.length
+                : pointer.endCol
+        function* generator() {
+            while (true) {
+                if (
+                    pointer.started &&
+                    pointer.row === pointer.endRow &&
+                    pointer.column === pointer.endCol
+                )
+                    return
+                pointer.started = true
+
+                if (
+                    lines[pointer.row] === undefined ||
+                    lines[pointer.row][pointer.column] === undefined
+                ) {
+                    pointer.row++
+                    pointer.column = 0
+                    if (pointer.row >= numRows) pointer.row = 0
+                    continue
+                }
+
+                yield {
+                    row: pointer.row,
+                    column: pointer.column,
+                } as CellPosition
+                pointer.column++
+            }
+        }
+
+        return generator()
+    }
+
+    valuesFrom(position = Origin) {
+        return Array.from(this.ring(position)).map((next) =>
+            this.getCellContents(next)
+        )
+    }
+
+    get numRows() {
+        return this.lines.length
+    }
+
+    patch(obj: any) {
+        Object.keys(obj).forEach((key) => this.setLineValue(key, obj[key]))
+        return this
+    }
+
+    grepFirst(key: string, position = Origin) {
+        for (const next of this.ring(position)) {
+            if (this.getCellContents(next) === key) return next
+        }
+        return undefined
+    }
+
+    grep(key: string, position = Origin) {
+        const hits: CellPosition[] = []
+        for (const next of this.ring(position)) {
+            if (this.getCellContents(next) === key) hits.push(next)
+        }
+        return hits
+    }
+
+    /**
+     * Returns all non-blocks as an object literal
+     */
+    get tuplesObject() {
+        const obj: { [key: string]: any } = {}
+        this.lines
+            .filter((line) => line[0] !== "")
+            .forEach((line) => {
+                const [key, ...rest] = line
+                if (key) obj[key.trim()] = rest.join(this.cellDelimiter).trim()
+            })
+        return obj
+    }
+
+    getLine(keyword: string) {
+        return this.lines.find((line) => line[0] === keyword)
+    }
+
+    getLineValue(keyword: string) {
+        const line = this.getLine(keyword)
+        return line?.[1]
+    }
+
+    protected getBlockLocation(
+        blockRowNumber: number
+    ): BlockLocation | undefined {
+        const startRow = blockRowNumber + 1
+        let numRows = this.lines
+            .slice(startRow)
+            .findIndex((line) => line.length && line[0] !== "")
+        if (numRows === 0) return undefined
+        if (numRows === -1) numRows = this.lines.slice(startRow).length
+        return { startRow, endRow: startRow + numRows, numRows }
+    }
+
+    protected getKeywordIndex(key: string) {
+        return this.lines.findIndex((line) => line[0] === key)
+    }
+
+    getCell(position: CellPosition): ParsedCell {
+        return new GridCell(this.lines, position, this.grammar!)
+    }
+
+    getCellContents(position: CellPosition) {
+        const line = this.lines[position.row]
+        return line ? line[position.column] : undefined
+    }
+
+    deleteBlock(row?: number) {
+        if (row === undefined) return this
+        const location = this.getBlockLocation(row)
+        if (!location) return this
+
+        this.lines.splice(location.startRow, location.numRows)
+        return this
+    }
+
+    deleteLine(row?: number) {
+        if (row === undefined) return this
+        this.lines.splice(row, 1)
+        return this
+    }
+
+    appendLine(line: string) {
+        this.lines.push(line.split(this.cellDelimiter))
+        return this
+    }
+
+    // todo: make immutable and return a new copy
+    setCell(row: number, col: number, value: string) {
+        this.lines[row][col] = value
+        return this
+    }
+
+    setLineValue(key: string, value: string | undefined) {
+        const index = this.getKeywordIndex(key)
+        if (index === -1 && value !== undefined) this.lines.push([key, value])
+        else if (value === undefined) this.deleteLine(index)
+        else this.lines[index] = [key, value]
+        return this
+    }
+
+    getBlock(keywordIndex: number) {
+        const location = this.getBlockLocation(keywordIndex)
+        if (!location) return undefined
+        return this.lines
+            .slice(location.startRow, location.endRow)
+            .map((line) => line.slice(1))
+    }
+
+    updateBlock(rowNumber: number, value: string[][]) {
+        const location = this.getBlockLocation(rowNumber)
+        if (!location) throw new Error("Block not found")
+        this.lines.splice(
+            location.startRow,
+            location.numRows,
+            ...value.map((line) => ["", ...line])
+        )
+        return this
+    }
+
+    protected appendBlock(key: string, value: string[][]) {
+        this.lines.push([key])
+        value.forEach((line) => this.lines.push(["", ...line]))
+    }
+
+    getRowNumbersStartingWith(startsWith: string) {
+        return this.lines
+            .map((line, index) => (line[0] === startsWith ? index : null))
+            .filter(isPresent)
+    }
+
+    private static lineMatchesWords = (
+        line: string[],
+        words: (string | undefined)[]
+    ): boolean =>
+        words.every((word, index) => word === undefined || line[index] === word)
+
+    getRowMatchingWords(...words: (string | undefined)[]): number {
+        return this.lines.findIndex((line) =>
+            GridProgram.lineMatchesWords(line, words)
+        )
+    }
+
+    getAllRowsMatchingWords(...words: (string | undefined)[]): number[] {
+        const rows: number[] = []
+        this.lines.forEach((line: string[], rowIndex: number) => {
+            if (GridProgram.lineMatchesWords(line, words)) rows.push(rowIndex)
+        })
+        return rows
+    }
+
+    // The max number of columns in any row when you view a program as a spreadsheet
+    get width() {
+        return Math.max(...this.lines.map((arr) => arr.length))
+    }
+
+    toString() {
+        return this.prettify()
+    }
+
+    protected prettify() {
+        return trimMatrix(this.lines)
+            .map((line) => line.join(this.cellDelimiter))
+            .join(this.nodeDelimiter)
+    }
+}

package/src/explorer/gridLang/readme.md

@@ -0,0 +1,17 @@
+# GridLang
+
+(Note: GridLang name is a placeholder and this readme is a stub)
+
+GridLang is a library for building 2-dimensional domain specific languages designed to be edited in a Spreadsheet UI.
+
+Unlike traditional computer languages that parse tokens in-order, tokens in GridLanguages are parsed in a lazy, non-linear manner, based upon there position in a 2-d matrix.
+
+Our "Explorer"—a DSL for building OWID explorers and Graphers—is a GridLang.
+
+GridLangs are also intrinsically "patchable"—a great way for perserving user state.
+
+## How it works
+
+1. Extend the base GridProgram class with a class for your new DSL.
+2. Create a grammar for your DSL.
+3. Load in some "programs" from TSVs.

package/src/explorer/index.ts

@@ -0,0 +1,69 @@
+export { Explorer, type ExplorerProps } from "./Explorer.js"
+
+export { buildExplorerProps } from "./ExplorerUtils.js"
+
+export {
+    DefaultNewExplorerSlug,
+    EMBEDDED_EXPLORER_DELIMITER,
+    EMBEDDED_EXPLORER_GRAPHER_CONFIGS,
+    EMBEDDED_EXPLORER_PARTIAL_GRAPHER_CONFIGS,
+    EXPLORER_CONSTANTS_DELIMITER,
+    EXPLORER_EMBEDDED_FIGURE_SELECTOR,
+    ExplorerChartCreationMode,
+    ExplorerContainerId,
+    ExplorerControlType,
+    ExplorerControlTypeRegex,
+    EXPLORERS_GIT_CMS_FOLDER,
+    EXPLORERS_PREVIEW_ROUTE,
+    EXPLORERS_ROUTE_FOLDER,
+    GetAllExplorersRoute,
+    GetAllExplorersTagsRoute,
+    type ChoiceMap,
+    type ChoiceName,
+    type ChoiceValue,
+    type ExplorerChoice,
+    type ExplorerChoiceOption,
+    type ExplorerChoiceParams,
+    type ExplorerFullQueryParams,
+    type ExplorersRouteResponse,
+    type ExplorerStandardQueryParams,
+    UNSAVED_EXPLORER_DRAFT,
+    UNSAVED_EXPLORER_PREVIEW_QUERYPARAMS,
+} from "./ExplorerConstants.js"
+
+export {
+    type TableDef,
+    ExplorerProgram,
+    EXPLORER_FILE_SUFFIX,
+    makeFullPath,
+    type ExplorerGrapherInterface,
+} from "./ExplorerProgram.js"
+
+export { type ExplorerPageUrlMigrationSpec } from "./urlMigrations/ExplorerPageUrlMigrationSpec.js"
+
+export {
+    explorerUrlMigrationsById,
+    migrateExplorerUrl,
+} from "./urlMigrations/ExplorerUrlMigrations.js"
+
+export { isEmpty } from "./gridLang/GrammarUtils.js"
+
+export { ColumnGrammar } from "./ColumnGrammar.js"
+
+export { GridCell } from "./gridLang/GridCell.js"
+
+export { GridProgram } from "./gridLang/GridProgram.js"
+
+export { ExplorerGrammar } from "./ExplorerGrammar.js"
+
+export { ExplorerUrlMigrationId } from "./urlMigrations/ExplorerUrlMigrations.js"
+
+export { DecisionMatrix } from "./ExplorerDecisionMatrix.js"
+
+export {
+    GridBoolean,
+    type CellPosition,
+    type ParsedCell,
+} from "./gridLang/GridLangConstants.js"
+
+export { GrapherGrammar } from "./GrapherGrammar.js"

package/src/explorer/readme.md

@@ -0,0 +1,19 @@
+# Explorers
+
+The Explorer is our component that allows easy navigating through a set of authored charts or charts generated on the fly. With the Explorer a reader can quickly navigate across dozens or hundreds of different chart views without leaving the page.
+
+The Explorer component adds a control bar above the chart with controls including radios, dropdowns and checkboxes that the reader can use to change the chart on the page. The Explorer also adds a standalone entity selection tool on the left.
+
+The Explorer works best on desktop but is also designed to work decently on mobile devices.
+
+## Implementation Notes
+
+The Explorer depends on our Chart library, but the Chart library does not have a dependency on the Explorer. You should be able to delete the `explorer` folder, remove a few links, and the rest of Grapher should still work fine.
+
+### Explorer DSL
+
+Explorers are created in a DSL that authors can edit in a spreadsheet which is parsed to create an instance of the ExplorerProgram class.
+
+# Explorer Grammars
+
+This folder also contains the declarative grammars that defines all the keywords and values authors can have in their Explorer programs.

package/src/explorer/urlMigrations/CO2UrlMigration.ts

@@ -0,0 +1,46 @@
+import { legacyToCurrentGrapherUrl } from "../../grapher/index.js"
+import { Url, UrlMigration } from "../../utils/index.js"
+import {
+    decodeURIComponentOrUndefined,
+    getExplorerSlugFromUrl,
+    QueryParamTransformMap,
+    transformQueryParams,
+} from "./ExplorerUrlMigrationUtils.js"
+
+const EXPLORER_SLUG = "co2"
+
+const co2QueryParamTransformMap: QueryParamTransformMap = {
+    "Gas ": {
+        newName: "Gas",
+        transformValue: decodeURIComponentOrUndefined,
+    },
+    "Accounting ": {
+        newName: "Accounting",
+        transformValue: decodeURIComponentOrUndefined,
+    },
+    "Fuel ": {
+        newName: "Fuel",
+        transformValue: decodeURIComponentOrUndefined,
+    },
+    "Count ": {
+        newName: "Count",
+        transformValue: decodeURIComponentOrUndefined,
+    },
+    "Relative to world total ": {
+        newName: "Relative to world total",
+        transformValue: (value) => (value ? "true" : "false"),
+    },
+}
+
+export const co2UrlMigration: UrlMigration = (url: Url) => {
+    // if it's not the /explorer/co2 path, skip it
+    const explorerSlug = getExplorerSlugFromUrl(url)
+    if (explorerSlug !== EXPLORER_SLUG) return url
+
+    url = legacyToCurrentGrapherUrl(url)
+    const queryParams = transformQueryParams(
+        url.queryParams,
+        co2QueryParamTransformMap
+    )
+    return url.setQueryParams(queryParams)
+}

package/src/explorer/urlMigrations/CovidUrlMigration.ts

@@ -0,0 +1,37 @@
+import { Url, UrlMigration } from "../../utils/index.js"
+import {
+    getExplorerSlugFromUrl,
+    QueryParamTransformMap,
+    transformQueryParams,
+} from "./ExplorerUrlMigrationUtils.js"
+
+const EXPLORER_SLUG = "coronavirus-data-explorer"
+
+const transformMap: QueryParamTransformMap = {
+    Metric: {
+        transformValue: (value) => {
+            // Since we introduced multiple vaccinations metrics, we want to
+            // differentiate between them.
+            // And while we're there, reduce the length of "Tests per confirmed
+            // case", because it wraps to 2 lines.
+            //
+            // -@danielgavrilov, 2021-03-30
+            //
+            if (value === "Vaccinations") return "Vaccine doses"
+            if (value === "Tests per confirmed case") return "Tests per case"
+            return value
+        },
+    },
+    "Align outbreaks": {
+        newName: "Color by test positivity",
+    },
+}
+
+export const covidUrlMigration: UrlMigration = (url: Url) => {
+    // if it's not the /explorer/energy path, skip it
+    const explorerSlug = getExplorerSlugFromUrl(url)
+    if (explorerSlug !== EXPLORER_SLUG) return url
+    return url.setQueryParams(
+        transformQueryParams(url.queryParams, transformMap)
+    )
+}

package/src/explorer/urlMigrations/EnergyUrlMigration.ts

@@ -0,0 +1,41 @@
+import { legacyToCurrentGrapherUrl } from "../../grapher/index.js"
+import { Url, UrlMigration } from "../../utils/index.js"
+import {
+    decodeURIComponentOrUndefined,
+    getExplorerSlugFromUrl,
+    QueryParamTransformMap,
+    transformQueryParams,
+} from "./ExplorerUrlMigrationUtils.js"
+
+const EXPLORER_SLUG = "energy"
+
+const energyQueryParamTransformMap: QueryParamTransformMap = {
+    "Total or Breakdown ": {
+        newName: "Total or Breakdown",
+        transformValue: decodeURIComponentOrUndefined,
+    },
+    "Select a source ": {
+        newName: "Select a source",
+        transformValue: decodeURIComponentOrUndefined,
+    },
+    "Energy or Electricity ": {
+        newName: "Energy or Electricity",
+        transformValue: decodeURIComponentOrUndefined,
+    },
+    "Metric ": {
+        newName: "Metric",
+        transformValue: decodeURIComponentOrUndefined,
+    },
+}
+
+export const energyUrlMigration: UrlMigration = (url: Url) => {
+    // if it's not the /explorer/energy path, skip it
+    const explorerSlug = getExplorerSlugFromUrl(url)
+    if (explorerSlug !== EXPLORER_SLUG) return url
+    url = legacyToCurrentGrapherUrl(url)
+    const queryParams = transformQueryParams(
+        url.queryParams,
+        energyQueryParamTransformMap
+    )
+    return url.setQueryParams(queryParams)
+}

package/src/explorer/urlMigrations/ExplorerPageUrlMigrationSpec.ts

@@ -0,0 +1,12 @@
+import { ExplorerUrlMigrationId } from "./ExplorerUrlMigrations.js"
+
+/**
+ * An object spec that gets encoded into pages that redirect to an explorer.
+ *
+ * It's encoded as a JSON object on the page in order to avoid storing all redirects
+ * in the client-side bundle.
+ */
+export interface ExplorerPageUrlMigrationSpec {
+    explorerUrlMigrationId: ExplorerUrlMigrationId
+    baseQueryStr: string
+}

package/src/explorer/urlMigrations/ExplorerUrlMigrationUtils.ts

@@ -0,0 +1,45 @@
+import * as _ from "lodash-es"
+import { Url, QueryParams } from "../../utils/index.js"
+
+import { EXPLORERS_ROUTE_FOLDER } from "../ExplorerConstants.js"
+
+export const decodeURIComponentOrUndefined = (value: string | undefined) =>
+    value !== undefined
+        ? decodeURIComponent(value.replace(/\+/g, "%20"))
+        : undefined
+
+export type QueryParamTransformMap = Record<
+    string,
+    {
+        newName?: string
+        transformValue?: (value: string | undefined) => string | undefined
+    }
+>
+
+export const transformQueryParams = (
+    oldQueryParams: Readonly<QueryParams>,
+    transformMap: QueryParamTransformMap
+) => {
+    const newQueryParams = _.omit(
+        oldQueryParams,
+        ...Object.keys(transformMap)
+    ) as QueryParams
+    for (const oldParamName in transformMap) {
+        if (!(oldParamName in oldQueryParams)) continue
+        const { newName, transformValue } = transformMap[oldParamName]
+        const name = newName ?? oldParamName
+        const transform = transformValue ?? _.identity
+        newQueryParams[name] = transform(oldQueryParams[oldParamName])
+    }
+    return newQueryParams
+}
+
+// todo(refactor): merge with Url's get explorerSlug()
+export const getExplorerSlugFromUrl = (url: Url): string | undefined => {
+    if (!url.pathname) return undefined
+    const match = url.pathname.match(
+        new RegExp(`^/+${EXPLORERS_ROUTE_FOLDER}/+([^/]+)`)
+    )
+    if (match && match[1]) return match[1]
+    return undefined
+}

package/src/explorer/urlMigrations/ExplorerUrlMigrations.ts

@@ -0,0 +1,33 @@
+import { Url, UrlMigration, performUrlMigrations } from "../../utils/index.js"
+
+import { legacyCovidMigrationSpec } from "./LegacyCovidUrlMigration.js"
+import { co2UrlMigration } from "./CO2UrlMigration.js"
+import { energyUrlMigration } from "./EnergyUrlMigration.js"
+import { covidUrlMigration } from "./CovidUrlMigration.js"
+
+export enum ExplorerUrlMigrationId {
+    legacyToGridCovidExplorer = "legacyToGridCovidExplorer",
+}
+
+export interface ExplorerUrlMigrationSpec {
+    explorerSlug: string
+    migrateUrl: (url: Url, baseQueryStr: string) => Url
+}
+
+export const explorerUrlMigrationsById: Record<
+    ExplorerUrlMigrationId,
+    ExplorerUrlMigrationSpec
+> = {
+    legacyToGridCovidExplorer: legacyCovidMigrationSpec,
+}
+
+const explorerUrlMigrations: UrlMigration[] = [
+    // NOTE: The order of migrations matters!
+    co2UrlMigration,
+    energyUrlMigration,
+    covidUrlMigration,
+]
+
+export const migrateExplorerUrl: UrlMigration = (url: Url): Url => {
+    return performUrlMigrations(explorerUrlMigrations, url)
+}