@buildcanada/charts 0.1.0

package/src/explorer/gridLang/GridCell.ts

@@ -0,0 +1,298 @@
+import { trimArray } from "../../core-table/index.js"
+import { imemo, isPresent } from "../../utils/index.js"
+
+import { didYouMean, isBlankLine, isEmpty } from "./GrammarUtils.js"
+import {
+    CellPosition,
+    CellDef,
+    CellHasErrorsClass,
+    MatrixLine,
+    MatrixProgram,
+    Grammar,
+    FrontierCellClass,
+    ParsedCell,
+    CommentCellDef,
+    SubTableValueCellDef,
+    WorkInProgressCellDef,
+    NothingGoesThereCellDef,
+} from "./GridLangConstants.js"
+
+export class GridCell implements ParsedCell {
+    private position: CellPosition
+    private matrix: MatrixProgram
+    private rootDefinition: CellDef
+    constructor(
+        matrix: MatrixProgram,
+        position: CellPosition,
+        rootDefinition: CellDef
+    ) {
+        this.position = position
+        this.matrix = matrix
+        this.rootDefinition = rootDefinition
+    }
+
+    private get row() {
+        return this.position.row
+    }
+
+    private get column() {
+        return this.position.column
+    }
+
+    private get line(): MatrixLine | undefined {
+        return this.matrix[this.row]
+    }
+
+    private get isCommentCell() {
+        const { contents } = this
+        return contents && CommentCellDef.regex!.test(contents)
+    }
+
+    private get cellTerminalTypeDefinition(): CellDef | undefined {
+        const { rootDefinition } = this
+        if (this.isCommentCell) return CommentCellDef
+        const grammar = rootDefinition.grammar as unknown as Grammar
+        if (this.column === 0) return rootDefinition as unknown as CellDef
+        const firstWordOnLine = this.line ? this.line[0] : undefined
+        const isFirstWordAKeyword =
+            firstWordOnLine && grammar[firstWordOnLine] !== undefined
+        if (this.column === 1 && firstWordOnLine && isFirstWordAKeyword)
+            return grammar[firstWordOnLine]
+
+        if (!isFirstWordAKeyword) return undefined
+
+        // It has a keyword but it is column >1
+        const def = grammar[firstWordOnLine!]
+        const positionalCellTypeDef =
+            def.positionalCellDefs && def.positionalCellDefs[this.column - 2]
+        if (positionalCellTypeDef) return positionalCellTypeDef
+        if (def.isHorizontalList && this.contents) return def // For now only return a def for lists if it is non-empty
+        return NothingGoesThereCellDef
+    }
+
+    private get parentSubTableInfo() {
+        const { row, matrix } = this
+        let pointerRow = row
+        let subTableHeaderRow = -1
+        while (pointerRow >= 0) {
+            const line = matrix[pointerRow]
+            if (!line) break
+            const parentKeyword = line[0]
+            if (parentKeyword) {
+                if (subTableHeaderRow === -1) return undefined
+                return {
+                    parentKeyword,
+                    parentRow: pointerRow,
+                    subTableHeaderRow,
+                    isCellInHeader: row === subTableHeaderRow,
+                    headerKeyword: matrix[subTableHeaderRow][this.column],
+                }
+            }
+
+            if (!isBlankLine(line)) subTableHeaderRow = pointerRow
+            pointerRow--
+        }
+
+        return undefined
+    }
+
+    @imemo private get subTableParseResults() {
+        const { cellTerminalTypeDefinition } = this
+        if (cellTerminalTypeDefinition) return undefined
+
+        const info = this.parentSubTableInfo
+
+        if (!info) return undefined
+
+        const {
+            parentKeyword,
+            isCellInHeader,
+            subTableHeaderRow,
+            headerKeyword,
+        } = info
+
+        const subTableDef = this.rootDefinition.grammar![parentKeyword]
+
+        const headerCellDef = subTableDef && subTableDef.headerCellDef
+
+        if (!headerCellDef) return undefined
+
+        const headerGrammar = headerCellDef.grammar
+        const valueCellDef =
+            !isCellInHeader && headerGrammar
+                ? headerGrammar[headerKeyword]
+                : undefined
+
+        return {
+            isFrontierCell: this.isSubTableFrontierCell(
+                subTableHeaderRow,
+                subTableDef
+            ),
+            def: isCellInHeader
+                ? headerCellDef
+                : (valueCellDef ?? SubTableValueCellDef),
+        }
+    }
+
+    /**
+     * If a cell is:
+     *  - to the right of the last filled cell in a line
+     *  - and that line is indented to be part of a subtable, with options
+     *  - and it is the first non-blank line in the subtabel
+     *
+     * Then consider is a "frontier cell"
+     *
+     */
+    private isSubTableFrontierCell(headerRow: number, subTableDef: CellDef) {
+        const { line, column, row } = this
+        const grammar = subTableDef.headerCellDef!.grammar
+        const isToTheImmediateRightOfLastFullCell =
+            line && trimArray(line).length === column
+        return (
+            row === headerRow &&
+            !isBlankLine(line) &&
+            isToTheImmediateRightOfLastFullCell &&
+            grammar &&
+            Object.keys(grammar).length
+        )
+    }
+
+    // If true show a +
+    private get isFirstCellOnFrontierRow() {
+        const { row, column } = this
+        const numRows = this.matrix.length
+        if (column) return false // Only first column should have a +
+        if (!isBlankLine(this.line)) return false // Only blank lines can be frontier
+        if (numRows === 1) {
+            if (row === 1) return !isBlankLine(this.matrix[0])
+            return row === 0
+        }
+        return row === numRows
+    }
+
+    private get suggestions() {
+        return []
+    }
+
+    private get definitionLinks(): CellPosition[] {
+        return []
+    }
+
+    private get implementationLinks(): CellPosition[] {
+        return []
+    }
+
+    @imemo get cellDef(): CellDef {
+        const def = this.cellTerminalTypeDefinition
+        if (def) return def
+
+        const subTable = this.subTableParseResults?.def
+        if (subTable) return subTable as unknown as CellDef
+
+        return WorkInProgressCellDef
+    }
+
+    get errorMessage() {
+        if (!this.line) return ""
+        const { cellDef, contents, optionKeywords } = this
+        const { regex, requirementsDescription, catchAllCellDef } = cellDef
+        const catchAllKeywordRegex = catchAllCellDef?.regex
+
+        if (contents === undefined || contents === "") return ""
+
+        const regexResult = regex
+            ? validate(contents, regex, requirementsDescription)
+            : undefined
+        const catchAllRegexResult = catchAllKeywordRegex
+            ? validate(
+                  contents,
+                  catchAllKeywordRegex,
+                  catchAllCellDef!.requirementsDescription
+              )
+            : undefined
+
+        if (optionKeywords) {
+            if (optionKeywords.includes(contents)) return ""
+
+            if (regex) return regexResult
+            if (catchAllKeywordRegex) return catchAllRegexResult
+
+            const guess = didYouMean(contents, optionKeywords)
+            if (guess) return `Did you mean '${guess}'?`
+
+            return `Error: '${contents}' is not a valid option. Valid options are ${optionKeywords
+                .map((opt) => `'${opt}'`)
+                .join(", ")}`
+        }
+
+        if (regex) return regexResult
+        if (catchAllKeywordRegex) return catchAllRegexResult
+
+        return ""
+    }
+
+    get contents() {
+        return this.line ? this.line[this.column] : undefined
+    }
+
+    get comment() {
+        const { contents, errorMessage, cellDef } = this
+        if (isEmpty(contents)) return undefined
+        if (errorMessage) return errorMessage
+
+        if (cellDef.grammar) {
+            const def = cellDef.grammar[contents!] ?? cellDef.catchAllCellDef
+            return def.description
+        }
+
+        return [cellDef.description].join("\n")
+    }
+
+    get cssClasses() {
+        const { errorMessage, cellDef } = this
+        if (errorMessage) return [CellHasErrorsClass]
+        const showArrow =
+            this.isFirstCellOnFrontierRow ||
+            this.subTableParseResults?.isFrontierCell
+                ? FrontierCellClass
+                : undefined
+        const hasSuggestions =
+            this.cellDef.keyword === "table" ? "HasSuggestions" : null // todo: switch from strings to constants
+        return [cellDef.cssClass, hasSuggestions, showArrow].filter(isPresent)
+    }
+
+    get placeholder() {
+        const { contents, cellDef } = this
+        const { terminalOptions } = cellDef
+        const firstOption = terminalOptions && terminalOptions[0]
+        const firstOptionName = firstOption && firstOption.keyword
+        const placeholder = cellDef.valuePlaceholder ?? firstOptionName
+        return isEmpty(contents) && placeholder
+            ? `eg "${placeholder}"`
+            : undefined
+    }
+
+    get optionKeywords() {
+        const { cellDef } = this
+        const { grammar, headerCellDef, terminalOptions } = cellDef
+        return terminalOptions
+            ? terminalOptions.map((def) => def.keyword)
+            : grammar
+              ? Object.keys(grammar)
+              : headerCellDef
+                ? Object.keys(headerCellDef.grammar!)
+                : undefined
+    }
+}
+
+const validate = (value: any, regex: RegExp, requirements?: string) => {
+    if (typeof value !== "string") return ""
+    if (!regex.test(value)) {
+        return `Error: ${
+            requirements
+                ? requirements
+                : `'${value}' did not validate against ${regex}`
+        }`
+    }
+    return ""
+}

package/src/explorer/gridLang/GridLangConstants.ts

@@ -0,0 +1,255 @@
+import { GrapherInterface } from "../../types/index.js"
+
+export const CellHasErrorsClass = "CellHasErrorsClass"
+
+export enum GridBoolean {
+    true = "true",
+    false = "false",
+}
+
+export const GRID_NODE_DELIMITER = "\n"
+export const GRID_CELL_DELIMITER = "\t"
+export const GRID_EDGE_DELIMITER = "\t"
+
+export type CellCoordinate = number // An integer >= 0
+
+export type Grammar<TCellDef extends CellDef = CellDef> = {
+    [keywordSlug: string]: TCellDef
+}
+
+// A CellDef is a tuple: part keyword and the other half is the contents. The contents can be 1 cell, a list of cells, and/or a subtable.
+export interface CellDef {
+    keyword: string
+    cssClass: string
+    description: string
+    grammar?: Grammar
+    headerCellDef?: CellDef
+    terminalOptions?: CellDef[]
+    catchAllCellDef?: CellDef // Only used by vertical grammars, this cell def, if present, will be used if a keyword is unrecognized during parsing.
+    regex?: RegExp // A validation regex a value must pass. todo: seems like this is overloaded and used for testing keywords and contents.
+    requirementsDescription?: string
+    valuePlaceholder?: string
+    positionalCellDefs?: readonly CellDef[] // Additional cell types as positional arguments.
+    isHorizontalList?: boolean // a list type, such as "colors\tred\torange\tgreen"
+    parse?: (value: any) => any
+}
+
+export interface GrapherCellDef extends CellDef {
+    toGrapherObject: (value: any) => GrapherInterface // map to a partial config that is a valid GrapherInterface
+}
+
+export interface ColumnCellDef extends CellDef {
+    display?: boolean
+}
+
+export interface ParsedCell {
+    errorMessage?: string
+    cssClasses?: string[]
+    optionKeywords?: string[]
+    comment?: string
+    cellDef?: CellDef
+    placeholder?: string
+    contents?: any
+}
+
+export interface CellPosition {
+    row: CellCoordinate
+    column: CellCoordinate
+}
+
+export const Origin: CellPosition = {
+    row: 0,
+    column: 0,
+}
+
+export const BooleanCellDef: CellDef = {
+    keyword: "",
+    terminalOptions: [
+        { keyword: GridBoolean.true, cssClass: "", description: "" },
+        { keyword: GridBoolean.false, cssClass: "", description: "" },
+    ],
+    cssClass: "BooleanCellDef",
+    description: "Boolean",
+    parse: (value: any) => {
+        // Handle already parsed boolean values (to avoid double parsing)
+        if (typeof value === "boolean") return value
+        return value === GridBoolean.true
+    },
+}
+
+export const StringCellDef: CellDef = {
+    keyword: "",
+    cssClass: "StringCellDef",
+    description: "",
+    parse: (value: any) => `${value}`.replace(/\\n/g, "\n"),
+}
+
+export const StringDeclarationDef: CellDef = {
+    keyword: "",
+    cssClass: "StringDeclarationDef",
+    description: "",
+}
+
+export const EnumCellDef: CellDef = {
+    keyword: "",
+    cssClass: "EnumCellDef",
+    description: "",
+}
+
+export const RootKeywordCellDef: CellDef = {
+    keyword: "",
+    cssClass: "KeywordCellDef",
+    description: "Keyword",
+}
+
+export const NumericCellDef: CellDef = {
+    keyword: "",
+    cssClass: "NumericCellDef",
+    description: "",
+    regex: /^-?\d+\.?\d*$/,
+    requirementsDescription: `Must be a number`,
+    valuePlaceholder: "98.6",
+    parse: (value: any) => parseFloat(value),
+}
+
+export const NumericOrAutoCellDef: CellDef = {
+    keyword: "",
+    cssClass: "NumericCellDef",
+    description: "",
+    regex: /^(-?\d+\.?\d*|auto)$/,
+    requirementsDescription: `Must be a number or "auto"`,
+    valuePlaceholder: "98.6",
+    parse: (value: any) => {
+        if (value === "auto") return "auto"
+        return parseFloat(value)
+    },
+}
+
+export const IntegerCellDef: CellDef = {
+    keyword: "",
+    cssClass: "IntegerCellDef",
+    description: "",
+    regex: /^-?[0-9]+$/,
+    requirementsDescription: `Must be an integer`,
+    valuePlaceholder: "12345",
+    parse: (value: any) => parseInt(value),
+}
+
+export const PositiveIntegersCellDef: CellDef = {
+    keyword: "",
+    cssClass: "IntegerCellDef",
+    description: "",
+    regex: /^[0-9 ]+$/,
+    requirementsDescription: `Must be a positive integer or a list of positive integers`,
+    valuePlaceholder: "12345 23456",
+}
+
+export const SubTableHeaderCellDef: CellDef = {
+    keyword: "",
+    cssClass: "SubTableHeaderCellDef",
+    description: "",
+}
+
+export const SubTableValueCellDef: CellDef = {
+    keyword: "",
+    cssClass: "SubTableValueCellDef",
+    description: "",
+}
+
+const MatchUrlsOnlyRegex =
+    /((([A-Za-z]{3,9}:(?:\/\/)?)(?:[-;:&=+$,\w]+@)?[A-Za-z0-9.-]+|(?:www.|[-;:&=+$,\w]+@)[A-Za-z0-9.-]+)((?:\/[+~%/.\w-_]*)?\??(?:[-+=&;%@.\w_]*)#?(?:[\w]*))?)/
+
+export const UrlCellDef: CellDef = {
+    keyword: "",
+    cssClass: "UrlCellDef",
+    description: "",
+    regex: MatchUrlsOnlyRegex,
+}
+
+export const QueryStringCellDef: CellDef = {
+    keyword: "",
+    cssClass: "QueryStringCellDef",
+    description: "",
+}
+
+export const NothingGoesThereCellDef: CellDef = {
+    keyword: "",
+    cssClass: "NothingGoesThereType",
+    description:
+        "Nothing should be here. You can make this a comment by prepending a ##",
+}
+
+export const CommentCellDef: CellDef = {
+    keyword: "",
+    cssClass: "CommentType",
+    description: "Just a comment.",
+    regex: /^(##|💬)/,
+}
+
+export const WorkInProgressCellDef: CellDef = {
+    keyword: "",
+    cssClass: "WorkInProgressCellDef",
+    description: "Not a recognized statement. Treating as a work in progress.",
+}
+
+export const SlugDeclarationCellDef: CellDef = {
+    keyword: "",
+    cssClass: "SlugDeclarationType",
+    description: "A unique URL-friendly name.",
+    regex: /^[a-zA-Z0-9-_]+$/,
+    requirementsDescription: `Can only contain the characters a-zA-Z0-9-_`,
+}
+
+// This is the name for a cell that is on the "frontier", where the next user input is expected to go. Okay to rename if you have a better word.
+export const FrontierCellClass = "ShowDropdownArrow"
+
+export const SlugsDeclarationCellDef: CellDef = {
+    keyword: "",
+    cssClass: "SlugDeclarationType",
+    description: "Unique URL-friendly names.",
+    regex: /^[a-zA-Z0-9-_ ]+$/,
+    requirementsDescription: `Can only contain the characters a-zA-Z0-9-_ `,
+}
+
+export const EtlPathCellDef: CellDef = {
+    keyword: "",
+    cssClass: "IndicatorIdOrEtlPath",
+    description: "Path to an ETL indicator.",
+    regex: /^$|^[\w\d_/-]+#[\w\d_/-]+$/,
+    requirementsDescription: `Can only contain the characters a-zA-Z0-9-_/#`,
+}
+
+export const IndicatorIdOrEtlPathCellDef: CellDef = {
+    keyword: "",
+    cssClass: "IndicatorIdOrEtlPath",
+    description: "A single indicator ID or a path to an ETL indicator.",
+    regex: /^\d+|[\w\d_/-]+#[\w\d_/-]+$/,
+    requirementsDescription: `Can only contain the characters a-zA-Z0-9-_/#`,
+}
+
+export const SlugOrIndicatorIdOrEtlPathCellDef: CellDef = {
+    keyword: "",
+    cssClass: "SlugOrIndicatorIdOrEtlPath",
+    description: "A column slug, indicator ID, or catalog path.",
+    regex: /^[a-zA-Z0-9-_]+$|^\d+$|^[\w\d_/-]+#[\w\d_/-]+$/,
+    requirementsDescription: `Can be a slug (a-zA-Z0-9-_), an indicator ID (digits), or a catalog path (a-zA-Z0-9-_/#)`,
+}
+
+export const IndicatorIdsOrEtlPathsCellDef: CellDef = {
+    keyword: "",
+    cssClass: "IndicatorIdOrEtlPath",
+    description: "One or more indicator IDs or paths to an ETL indicator.",
+    regex: /^((\d+|[\w\d_/-]*#[\w\d_/-]+)( +|$))+$/,
+    requirementsDescription: `Can only contain the characters a-zA-Z0-9-_/# `,
+}
+
+export const JSONObjectCellDef: CellDef = {
+    keyword: "",
+    cssClass: "JSONObjectCellDef",
+    description: "JSON object",
+    regex: /^\{.*\}$/, // very basic validation that expression starts with { and ends with }
+    requirementsDescription: "Must contain a valid JSON object",
+}
+
+export type MatrixLine = string[]
+export type MatrixProgram = MatrixLine[]