@buildcanada/charts 0.1.0

package/src/explorer/GrapherGrammar.ts

@@ -0,0 +1,387 @@
+import {
+    ALL_GRAPHER_CHART_TYPES,
+    ColorSchemeName,
+    FacetAxisDomain,
+    FacetStrategy,
+    GRAPHER_CHART_TYPES,
+    GRAPHER_TAB_CONFIG_OPTIONS,
+    GrapherChartType,
+    MissingDataStrategy,
+    StackMode,
+} from "../types/index.js"
+import { SortBy, SortOrder } from "../utils/index.js"
+import {
+    GridBoolean,
+    BooleanCellDef,
+    CellDef,
+    EnumCellDef,
+    Grammar,
+    IntegerCellDef,
+    NumericOrAutoCellDef,
+    SlugDeclarationCellDef,
+    SlugsDeclarationCellDef,
+    StringCellDef,
+    UrlCellDef,
+    IndicatorIdsOrEtlPathsCellDef,
+    IndicatorIdOrEtlPathCellDef,
+    SlugOrIndicatorIdOrEtlPathCellDef,
+    GrapherCellDef,
+} from "./gridLang/GridLangConstants.js"
+import * as R from "remeda"
+const toTerminalOptions = (keywords: string[]): CellDef[] => {
+    return keywords.map((keyword) => ({
+        keyword,
+        cssClass: "",
+        description: "",
+    }))
+}
+
+export const GrapherGrammar: Grammar<GrapherCellDef> = {
+    title: {
+        ...StringCellDef,
+        keyword: "title",
+        description: "Chart title",
+        valuePlaceholder: "Life Expectancy around the world.",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ title: parsedValue }),
+    },
+    subtitle: {
+        ...StringCellDef,
+        keyword: "subtitle",
+        description: "Chart subtitle",
+        valuePlaceholder: "Life Expectancy has risen over time.",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ subtitle: parsedValue }),
+    },
+    ySlugs: {
+        ...SlugsDeclarationCellDef,
+        description: "ColumnSlug(s) for the yAxis",
+        keyword: "ySlugs",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ ySlugs: parsedValue }),
+    },
+    yVariableIds: {
+        ...IndicatorIdsOrEtlPathsCellDef,
+        keyword: "yVariableIds",
+        description: "Variable ID(s) or ETL path(s) for the yAxis",
+        toGrapherObject: () => ({}), // explorer-specific, not used in grapher config
+    },
+    type: {
+        ...StringCellDef,
+        keyword: "type",
+        description: `The type of chart to show such as LineChart or ScatterPlot. If set to None, then the chart tab is hidden.`,
+        terminalOptions: toTerminalOptions([
+            ...ALL_GRAPHER_CHART_TYPES,
+            `${GRAPHER_CHART_TYPES.LineChart} ${GRAPHER_CHART_TYPES.SlopeChart}`,
+            `${GRAPHER_CHART_TYPES.LineChart} ${GRAPHER_CHART_TYPES.DiscreteBar}`,
+            `${GRAPHER_CHART_TYPES.SlopeChart} ${GRAPHER_CHART_TYPES.DiscreteBar}`,
+            `${GRAPHER_CHART_TYPES.LineChart} ${GRAPHER_CHART_TYPES.SlopeChart} ${GRAPHER_CHART_TYPES.DiscreteBar}`,
+            "None",
+        ]),
+        toGrapherObject: (parsedValue) => {
+            if (parsedValue === "None") return { chartTypes: [] }
+            if (parsedValue)
+                return {
+                    chartTypes: parsedValue.split(" ") as GrapherChartType[],
+                }
+            return {}
+        },
+    },
+    grapherId: {
+        ...IntegerCellDef,
+        description: "ID of a legacy Grapher to load",
+        keyword: "grapherId",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ id: parsedValue }),
+    },
+    tableSlug: {
+        ...SlugDeclarationCellDef,
+        description:
+            "Slug of the explorer table (i.e. csv file) to use for this row. All variables used in this row must be present in the table/file.",
+        keyword: "tableSlug",
+        toGrapherObject: () => ({}), // explorer-specific, not used in grapher config
+    },
+    hasMapTab: {
+        ...BooleanCellDef,
+        keyword: "hasMapTab",
+        description: "Show the map tab?",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ hasMapTab: parsedValue }),
+    },
+    tab: {
+        ...EnumCellDef,
+        keyword: "tab",
+        description: "Which tab to show by default",
+        terminalOptions: toTerminalOptions(
+            Object.values(GRAPHER_TAB_CONFIG_OPTIONS)
+        ),
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ tab: parsedValue }),
+    },
+    xSlug: {
+        ...SlugDeclarationCellDef,
+        description: "ColumnSlug for the xAxis",
+        keyword: "xSlug",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ xSlug: parsedValue }),
+    },
+    xVariableId: {
+        ...IndicatorIdOrEtlPathCellDef,
+        keyword: "xVariableId",
+        description: "Variable ID or ETL path for the xAxis",
+        toGrapherObject: () => ({}), // explorer-specific, not used in grapher config
+    },
+    colorSlug: {
+        ...SlugDeclarationCellDef,
+        description: "ColumnSlug for the color",
+        keyword: "colorSlug",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ colorSlug: parsedValue }),
+    },
+    colorVariableId: {
+        ...IndicatorIdOrEtlPathCellDef,
+        keyword: "colorVariableId",
+        description: "Variable ID or ETL path for the color",
+        toGrapherObject: () => ({}), // explorer-specific, not used in grapher config
+    },
+    sizeSlug: {
+        ...SlugDeclarationCellDef,
+        description: "ColumnSlug for the size of points on scatters",
+        keyword: "sizeSlug",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ sizeSlug: parsedValue }),
+    },
+    sizeVariableId: {
+        ...IndicatorIdOrEtlPathCellDef,
+        keyword: "sizeVariableId",
+        description:
+            "Variable ID or ETL path for the size of points on scatters",
+        toGrapherObject: () => ({}), // explorer-specific, not used in grapher config
+    },
+    tableSlugs: {
+        ...SlugsDeclarationCellDef,
+        description:
+            "Columns to show in the Table tab of the chart. If not specified all active slugs will be used.",
+        keyword: "tableSlugs",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ tableSlugs: parsedValue }),
+    },
+    sourceDesc: {
+        ...StringCellDef,
+        keyword: "sourceDesc",
+        description: "Short comma-separated list of source names",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ sourceDesc: parsedValue }),
+    },
+    hideAnnotationFieldsInTitle: {
+        ...BooleanCellDef,
+        description: "Hide automatic time/entity",
+        keyword: "hideAnnotationFieldsInTitle",
+        parse: (value: any) => {
+            const parsedValue = value === GridBoolean.true
+            return {
+                entity: parsedValue,
+                time: parsedValue,
+                changeInPrefix: parsedValue,
+            }
+        },
+        toGrapherObject: (parsedValue) => ({
+            hideAnnotationFieldsInTitle: parsedValue,
+        }),
+    },
+    yScaleToggle: {
+        ...BooleanCellDef,
+        keyword: "yScaleToggle",
+        description: "Set to 'true' if the user can change the yAxis",
+        toGrapherObject: (parsedValue) => ({
+            yAxis: omitEmptyStringValues({ canChangeScaleType: parsedValue }),
+        }),
+    },
+    yAxisMin: {
+        ...NumericOrAutoCellDef,
+        keyword: "yAxisMin",
+        description: "Set the minimum parsedValue for the yAxis",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyObjectValues({
+                yAxis: omitEmptyStringValues({ min: parsedValue }),
+            }),
+    },
+    facetYDomain: {
+        ...EnumCellDef,
+        keyword: "facetYDomain",
+        description:
+            "Whether facets axes default to shared or independent domain",
+        terminalOptions: toTerminalOptions(Object.values(FacetAxisDomain)),
+        toGrapherObject: (parsedValue) =>
+            omitEmptyObjectValues({
+                yAxis: omitEmptyStringValues({ facetDomain: parsedValue }),
+            }),
+    },
+    selectedFacetStrategy: {
+        ...EnumCellDef,
+        keyword: "selectedFacetStrategy",
+        description: "Whether the chart should be faceted or not",
+        terminalOptions: toTerminalOptions(Object.values(FacetStrategy)),
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ selectedFacetStrategy: parsedValue }),
+    },
+    entityType: {
+        ...StringCellDef,
+        keyword: "entityType",
+        description:
+            "Default is 'country', but you can specify a different one such as 'state' or 'region'.",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ entityType: parsedValue }),
+    },
+    baseColorScheme: {
+        ...EnumCellDef,
+        keyword: "baseColorScheme",
+        description:
+            "The default color scheme if no color overrides are specified",
+        terminalOptions: toTerminalOptions(Object.keys(ColorSchemeName)),
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ baseColorScheme: parsedValue }),
+    },
+    note: {
+        ...StringCellDef,
+        keyword: "note",
+        description: "Chart footnote",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ note: parsedValue }),
+    },
+    sortBy: {
+        ...EnumCellDef,
+        keyword: "sortBy",
+        description: "Specify what to sort the entities by",
+        terminalOptions: toTerminalOptions(Object.values(SortBy)),
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ sortBy: parsedValue }),
+    },
+    sortOrder: {
+        ...EnumCellDef,
+        keyword: "sortOrder",
+        description: "Whether to sort entities ascending or descending",
+        terminalOptions: toTerminalOptions(Object.values(SortOrder)),
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ sortOrder: parsedValue }),
+    },
+    sortColumnSlug: {
+        ...SlugOrIndicatorIdOrEtlPathCellDef,
+        keyword: "sortColumnSlug",
+        description:
+            "Column slug, variable ID, or catalog path to sort by. This setting is only respected when `sortBy` is set to `column`",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ sortColumnSlug: parsedValue.toString() }),
+    },
+    stackMode: {
+        ...EnumCellDef,
+        keyword: "stackMode",
+        description:
+            "Show chart in absolute (default) or relative mode. Only works for some chart types.",
+        terminalOptions: toTerminalOptions(Object.values(StackMode)),
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ stackMode: parsedValue }),
+    },
+    hideTotalValueLabel: {
+        ...BooleanCellDef,
+        keyword: "hideTotalValueLabel",
+        description:
+            "Hide the total parsedValue that is normally displayed to the right of the bars in a stacked bar chart.",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({
+                hideTotalValueLabel: parsedValue,
+            }),
+    },
+    hideRelativeToggle: {
+        ...BooleanCellDef,
+        keyword: "hideRelativeToggle",
+        description: "Whether to hide the relative mode UI toggle",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ hideRelativeToggle: parsedValue }),
+    },
+    timelineMinTime: {
+        ...IntegerCellDef,
+        keyword: "timelineMinTime",
+        description:
+            "Set the minimum time for the timeline. For days, use days since 21 Jan 2020, e.g. 24 Jan 2020 is '3'.",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ timelineMinTime: parsedValue }),
+    },
+    timelineMaxTime: {
+        ...IntegerCellDef,
+        keyword: "timelineMaxTime",
+        description:
+            "Set the maximum time for the timeline. For days, use days since 21 Jan 2020, e.g. 24 Jan 2020 is '3'.",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ timelineMaxTime: parsedValue }),
+    },
+    defaultView: {
+        ...BooleanCellDef,
+        keyword: "defaultView",
+        description: "Whether this view is used as the default view.",
+        toGrapherObject: () => ({}), // explorer-specific, not used in grapher config
+    },
+    relatedQuestionText: {
+        ...StringCellDef,
+        keyword: "relatedQuestionText",
+        description:
+            "The text used for the related question (at the very bottom of the chart)",
+        toGrapherObject: () => ({}), // handled in code (can be done properly once the relatedQuestion field is refactored)
+    },
+    relatedQuestionUrl: {
+        ...UrlCellDef,
+        keyword: "relatedQuestionUrl",
+        description: "The link of the related question text",
+        toGrapherObject: () => ({}), // handled in code (can be done properly once the relatedQuestion field is refactored)
+    },
+    mapTargetTime: {
+        ...IntegerCellDef,
+        keyword: "mapTargetTime",
+        description:
+            "Set the 'target time' for the map chart. This is the year that will be shown by default in the map chart.",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyObjectValues({
+                map: omitEmptyStringValues({ time: parsedValue }),
+            }),
+    },
+    missingDataStrategy: {
+        ...EnumCellDef,
+        keyword: "missingDataStrategy",
+        description:
+            "Hide or show entities for which one or more variables are missing",
+        terminalOptions: toTerminalOptions(Object.values(MissingDataStrategy)),
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({
+                missingDataStrategy: parsedValue,
+            }),
+    },
+    minTime: {
+        ...IntegerCellDef,
+        keyword: "minTime",
+        description: "Start point of the initially selected time span",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ minTime: parsedValue }),
+    },
+    maxTime: {
+        ...IntegerCellDef,
+        keyword: "maxTime",
+        description: "End point of the initially selected time span",
+        toGrapherObject: (parsedValue) =>
+            omitEmptyStringValues({ maxTime: parsedValue }),
+    },
+} as const
+
+export function omitEmptyStringValues<T extends Record<string, any>>(
+    obj: T
+): Record<string, any> {
+    return R.omitBy(obj, (parsedValue) => parsedValue === "")
+}
+
+export function omitEmptyObjectValues<T extends Record<string, any>>(
+    obj: T
+): Record<string, any> {
+    return R.omitBy(
+        obj,
+        (parsedValue) => R.isPlainObject(parsedValue) && R.isEmpty(parsedValue)
+    )
+}

package/src/explorer/gridLang/GrammarUtils.ts

@@ -0,0 +1,121 @@
+// @ts-nocheck
+export const isBlankLine = (line: string[] | undefined) =>
+    line === undefined ? true : line.join("") === ""
+
+// Todo: figure out Matrix cell type and whether we need the double check
+export const isEmpty = (value: any) => value === "" || value === undefined
+
+// Adapted from: https://github.com/dcporter/didyoumean.js/blob/master/didYouMean-1.2.1.js
+export const didYouMean = (
+    str = "",
+    options: string[] = [],
+    caseSensitive = false,
+    threshold = 0.4,
+    thresholdAbsolute = 20
+) => {
+    if (!caseSensitive) str = str.toLowerCase()
+
+    // Calculate the initial value (the threshold) if present.
+    let maximumEditDistanceToBeBestMatch = Math.min(
+        threshold * str.length,
+        thresholdAbsolute
+    )
+
+    // Get the edit distance to each option. If the closest one is less than 40% (by default) of str's length, then return it.
+    let closestMatch
+    const len = options.length
+    for (let optionIndex = 0; optionIndex < len; optionIndex++) {
+        const candidate = options[optionIndex]
+
+        if (!candidate) continue
+
+        const editDistance = getEditDistance(
+            str,
+            caseSensitive ? candidate : candidate.toLowerCase(),
+            maximumEditDistanceToBeBestMatch
+        )
+        if (editDistance < maximumEditDistanceToBeBestMatch) {
+            maximumEditDistanceToBeBestMatch = editDistance
+            closestMatch = candidate
+        }
+    }
+
+    return closestMatch
+}
+
+const MAX_INT = Math.pow(2, 32) - 1
+const getEditDistance = (stringA: string, stringB: string, maxInt: number) => {
+    const aLength = stringA.length
+    const bLength = stringB.length
+
+    // Fast path - no A or B.
+    if (aLength === 0) return Math.min(maxInt + 1, bLength)
+    if (bLength === 0) return Math.min(maxInt + 1, aLength)
+
+    // Fast path - length diff larger than max.
+    if (Math.abs(aLength - bLength) > maxInt) return maxInt + 1
+
+    // Slow path.
+    const matrix = []
+
+    // Set up the first row ([0, 1, 2, 3, etc]).
+    for (let bIndex = 0; bIndex <= bLength; bIndex++) {
+        matrix[bIndex] = [bIndex]
+    }
+
+    // Set up the first column (same).
+    for (let aIndex = 0; aIndex <= aLength; aIndex++) {
+        matrix[0][aIndex] = aIndex
+    }
+
+    let colMin
+    let minJ
+    let maxJ
+
+    // Loop over the rest of the columns.
+    for (let bIndex = 1; bIndex <= bLength; bIndex++) {
+        colMin = MAX_INT
+        minJ = 1
+        if (bIndex > maxInt) minJ = bIndex - maxInt
+        maxJ = bLength + 1
+        if (maxJ > maxInt + bIndex) maxJ = maxInt + bIndex
+        // Loop over the rest of the rows.
+        for (let aIndex = 1; aIndex <= aLength; aIndex++) {
+            // If j is out of bounds, just put a large value in the slot.
+            if (aIndex < minJ || aIndex > maxJ)
+                matrix[bIndex][aIndex] = maxInt + 1
+            // Otherwise do the normal Levenshtein thing.
+            else {
+                // If the characters are the same, there's no change in edit distance.
+                if (stringB.charAt(bIndex - 1) === stringA.charAt(aIndex - 1))
+                    matrix[bIndex][aIndex] = matrix[bIndex - 1][aIndex - 1]
+                // Otherwise, see if we're substituting, inserting or deleting.
+                else
+                    matrix[bIndex][aIndex] = Math.min(
+                        matrix[bIndex - 1][aIndex - 1] + 1, // Substitute
+                        Math.min(
+                            matrix[bIndex][aIndex - 1] + 1, // Insert
+                            matrix[bIndex - 1][aIndex] + 1
+                        )
+                    ) // Delete
+            }
+
+            // Either way, update colMin.
+            if (matrix[bIndex][aIndex] < colMin) colMin = matrix[bIndex][aIndex]
+        }
+
+        // If this column's minimum is greater than the allowed maximum, there's no point
+        // in going on with life.
+        if (colMin > maxInt) return maxInt + 1
+    }
+    // If we made it this far without running into the max, then return the final matrix value.
+    return matrix[bLength][aLength]
+}
+
+const delimitedToMatrix = (
+    delimited: string,
+    rowDelimiter = "\n",
+    columnDelimiter = "\t"
+) => delimited.split(rowDelimiter).map((line) => line.split(columnDelimiter))
+
+export const tsvToMatrix = delimitedToMatrix