@nachoggodino/cello 0.1.0

package/docs/SYNTAX_HIGHLIGHTING.md

@@ -0,0 +1,91 @@
+# Cello Syntax Highlighting
+
+Cello ships a TextMate grammar as the portable syntax-highlighting standard for `.cel` files:
+
+- Grammar: [`syntaxes/cel.tmLanguage.json`](../syntaxes/cel.tmLanguage.json)
+- Editor configuration: [`syntaxes/cel.language-configuration.json`](../syntaxes/cel.language-configuration.json)
+- Language id: `cel`
+- File extension: `.cel`
+- Root scope: `source.cel`
+
+TextMate grammars are supported directly by VS Code and can be consumed by Shiki, GitHub Linguist-derived tooling, Monaco bridges, and many other editor integrations.
+
+## VS Code Contribution
+
+Use this contribution block in a VS Code extension package:
+
+```json
+{
+  "contributes": {
+    "languages": [
+      {
+        "id": "cel",
+        "aliases": ["Cello", "cel"],
+        "extensions": [".cel"],
+        "configuration": "./syntaxes/cel.language-configuration.json"
+      }
+    ],
+    "grammars": [
+      {
+        "language": "cel",
+        "scopeName": "source.cel",
+        "path": "./syntaxes/cel.tmLanguage.json"
+      }
+    ]
+  }
+}
+```
+
+## Scope Map
+
+| Cello construct | Primary scope |
+|---|---|
+| `@sheet` | `keyword.control.sheet.cel` |
+| Sheet name | `entity.name.section.sheet.cel` |
+| Sheet format | `storage.type.format.cel` |
+| `@header` | `keyword.control.header.cel` |
+| `@defaults` | `keyword.control.defaults.cel` |
+| External source `->` | `keyword.operator.source.cel` |
+| External path | `string.unquoted.path.cel` |
+| Comment line | `comment.line.double-slash.cel` |
+| Cell separator `|` | `punctuation.separator.cell.cel` |
+| Formula cell | `meta.formula.cel` |
+| Formula function | `support.function.formula.cel` |
+| Sheet reference | `variable.other.sheet-reference.cel` |
+| Cell reference | `constant.other.cell-reference.cel` |
+| Range slice | `constant.other.range.cel` |
+| Merge token `<` or `^` | `keyword.operator.merge.cel` |
+| Modifier block | `meta.modifier.cel` |
+| Tone modifier | `support.constant.tone.cel` |
+| Color literal | `constant.other.color.rgb-value.cel` |
+| Forced text string | `string.quoted.double.cel` |
+| ISO date | `constant.other.date.iso.cel` |
+| Boolean | `constant.language.boolean.cel` |
+| Number | `constant.numeric.cel` |
+| Inline heading | `markup.heading.*.cel` |
+| Inline bold/italic/strike | `markup.bold.cel`, `markup.italic.cel`, `markup.strikethrough.cel` |
+
+## Recommended Theme Treatment
+
+Themes that want a distinctive Cello look can add these VS Code `tokenColors`. The palette is warm and spreadsheet-like: amber for workbook structure, blue for modifiers, green for references, and rose for formula operators/errors.
+
+```json
+[
+  { "scope": "keyword.control.sheet.cel, keyword.control.header.cel, keyword.control.defaults.cel", "settings": { "foreground": "#D97706", "fontStyle": "bold" } },
+  { "scope": "entity.name.section.sheet.cel", "settings": { "foreground": "#0F766E", "fontStyle": "bold" } },
+  { "scope": "storage.type.format.cel, support.constant.format.cel", "settings": { "foreground": "#2563EB" } },
+  { "scope": "meta.formula.cel", "settings": { "foreground": "#BE123C" } },
+  { "scope": "support.function.formula.cel", "settings": { "foreground": "#9333EA", "fontStyle": "bold" } },
+  { "scope": "variable.other.sheet-reference.cel, variable.other.identifier.cel", "settings": { "foreground": "#15803D" } },
+  { "scope": "meta.modifier.cel, support.constant.tone.cel", "settings": { "foreground": "#0284C7" } },
+  { "scope": "punctuation.separator.cell.cel", "settings": { "foreground": "#94A3B8" } },
+  { "scope": "keyword.operator.merge.cel", "settings": { "foreground": "#EA580C", "fontStyle": "bold" } },
+  { "scope": "comment.line.double-slash.cel", "settings": { "foreground": "#78716C", "fontStyle": "italic" } }
+]
+```
+
+## Design Notes
+
+The grammar highlights Cello's native syntax first and gracefully recognizes useful tokens in imported CSV, TSV, Markdown, and JSON sheet bodies. TextMate grammars do not track full workbook parse state, so imported sheet contents are highlighted heuristically rather than by the active `@sheet [format]` declaration.
+
+The grammar deliberately uses common TextMate parent scopes such as `keyword`, `entity.name.section`, `constant.numeric`, `string.quoted.double`, and `markup.*` so existing themes look good without Cello-specific theme rules. The `.cel` suffix on every specific scope lets dedicated themes add richer treatment.

package/examples/advanced_kpi.cel

@@ -0,0 +1,42 @@
+// Advanced KPI workbook using named refs, slices, cross-sheet refs and !! alias
+
+@sheet RawData [csv]
+date,region,agent,amount,units
+2026-01-01,Madrid,Ana,1200,4
+2026-01-01,Barcelona,Luis,980,3
+2026-01-02,Madrid,Sara,1420,5
+2026-01-02,Valencia,Pedro,760,2
+2026-01-03,Madrid,Ana,1660,6
+2026-01-03,Barcelona,Luis,1100,4
+2026-01-04,Valencia,Pedro,920,3
+2026-01-04,Madrid,Sara,1510,5
+2026-01-05,Barcelona,Luis,1340,5
+2026-01-05,Madrid,Ana,1720,6
+
+@sheet KPIs
+
+@header | Metric | Value |
+| ## Revenue KPIs | < |
+| Total revenue | =SUM(!!amount) |
+| Total units | =SUM(!!units) |
+| Avg ticket | =SUM(!!amount)/SUM(!!units) |
+| Best single sale | =MAX(!!amount) |
+| First 5 rows revenue | =SUM(!!amount[2:6]) |
+
+@sheet Regions
+
+@header | Region | Revenue[€][2d] | Units[0d] | Avg_ticket[€][2d] | Target[€][0d] | Variance[€][2d] | Attainment[%][1d] |
+@defaults | | =SUMIF(RawData!region,Region,RawData!amount) | =SUMIF(RawData!region,Region,RawData!units) | =Revenue/Units | | =Revenue-Target | =Revenue/Target |
+| Madrid | | | | 7200 | | |
+| Barcelona | | | | 3900 | | |
+| Valencia | | | | 1800 | | |
+[bold][bg:#f3f4f6] | ## TOTAL | =SUM(Revenue) | =SUM(Units) | =SUM(Revenue)/SUM(Units) | =SUM(Target) | =SUM(Variance) | =SUM(Revenue)/SUM(Target) |
+
+@sheet Agents
+
+@header | Agent | Revenue[€][2d] | Units[0d] | Avg_ticket[€][2d] |
+@defaults | | =SUMIF(RawData!agent,Agent,RawData!amount) | =SUMIF(RawData!agent,Agent,RawData!units) | =Revenue/Units |
+| Ana | | | |
+| Luis | | | |
+| Sara | | | |
+| Pedro | | | |

package/examples/basic.cel

@@ -0,0 +1,8 @@
+@sheet Sales [csv]
+product,price,quantity
+Apple,1.2,5
+Pear,0.9,3
+
+@sheet KPI
+@header | Metric | Value |
+| Revenue | =Sales!B2*Sales!C2 + Sales!B3*Sales!C3 |

package/examples/feature_showcase.cel

@@ -0,0 +1,37 @@
+// Feature showcase: merges, modifiers, markdown import, json import, formulas
+
+@sheet Board
+@header | Section | Owner | Status |
+| ## Sprint Board | < | < |
+| API | Nacho | *In progress* |
+| UI | Carla | ~~Blocked~~ |
+| Data | Mario | _Review_ |
+
+@sheet Budget
+@header | Item | Plan[€][2d] | Actual[€][2d] | Diff[€][2d] | Flag |
+@defaults | | | | =Actual-Plan | |
+| Hosting | 300 | 340 | | over[bg:#fee2e2][#991b1b] |
+| Tools   | 120 | 90  | | ok[bg:#dcfce7][#166534] |
+| Ops     | 210 | 210 | | ok[bg:#dcfce7][#166534] |
+[bold] | TOTAL | =SUM(Plan) | =SUM(Actual) | =SUM(Diff) | < |
+
+@sheet ImportedMd [markdown]
+| label | score |
+|------|------:|
+| quality | 9 |
+| speed | 8 |
+| scope | 7 |
+
+@sheet ImportedJson [json]
+[
+  {"team":"A","velocity":30,"bugs":2},
+  {"team":"B","velocity":24,"bugs":5},
+  {"team":"C","velocity":28,"bugs":3}
+]
+
+@sheet Summary
+@header | Metric | Value |
+| Budget diff total | =SUM(Budget!Diff) |
+| Avg imported score | =AVG(ImportedMd!score) |
+| Total bugs | =SUM(ImportedJson!bugs) |
+| Max velocity | =MAX(ImportedJson!velocity) |

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@nachoggodino/cello",
+  "version": "0.1.0",
+  "description": "Markdown, but for spreadsheets. Plain-text tabular data with formulas.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "cello": "./dist/cli/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "syntaxes",
+    "BYLAWS.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "Remove-Item -Recurse -Force dist -ErrorAction SilentlyContinue",
+    "dev": "tsc -w -p tsconfig.json",
+    "prepack": "npm run build",
+    "playground:dev": "vite --config playground/vite.config.ts",
+    "playground:build": "vite build --config playground/vite.config.ts",
+    "playground:preview": "vite preview --config playground/vite.config.ts",
+    "playground:typecheck": "tsc -p playground/tsconfig.json --noEmit",
+    "lint": "eslint \"playground/**/*.{ts,tsx}\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p playground/tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit playground/src/**/*.test.ts",
+    "test:it": "vitest run tests/it",
+    "test:e2e": "vitest run tests/e2e",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "spreadsheet",
+    "parser",
+    "formula",
+    "cello",
+    "tabular"
+  ],
+  "license": "GPL-3.0-only",
+  "author": "Nacho Godino",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nachoggodino/cello.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nachoggodino/cello/issues"
+  },
+  "homepage": "https://github.com/nachoggodino/cello#readme",
+  "overrides": {
+    "glob": "^13.0.0"
+  },
+  "dependencies": {
+    "hyperformula": "^3.0.0"
+  },
+  "devDependencies": {
+    "@codemirror/autocomplete": "^6.18.7",
+    "@codemirror/commands": "^6.8.1",
+    "@codemirror/language": "^6.11.3",
+    "@codemirror/search": "^6.5.11",
+    "@codemirror/state": "^6.5.2",
+    "@codemirror/view": "^6.38.8",
+    "@eslint/js": "^10.0.1",
+    "@lezer/highlight": "^1.2.1",
+    "@types/node": "^25.8.0",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "@vitest/coverage-v8": "^4.1.6",
+    "eslint": "^10.4.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.6.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.3",
+    "vite": "^8.0.13",
+    "vitest": "^4.1.6"
+  }
+}

package/syntaxes/cel.language-configuration.json

@@ -0,0 +1,31 @@
+{
+  "comments": {
+    "lineComment": "//"
+  },
+  "brackets": [
+    ["[", "]"],
+    ["(", ")"],
+    ["{", "}"]
+  ],
+  "autoClosingPairs": [
+    { "open": "[", "close": "]" },
+    { "open": "(", "close": ")" },
+    { "open": "{", "close": "}" },
+    { "open": "\"", "close": "\"" },
+    { "open": "|", "close": " |", "notIn": ["string"] }
+  ],
+  "surroundingPairs": [
+    { "open": "[", "close": "]" },
+    { "open": "(", "close": ")" },
+    { "open": "{", "close": "}" },
+    { "open": "\"", "close": "\"" },
+    { "open": "|", "close": "|" }
+  ],
+  "folding": {
+    "markers": {
+      "start": "^\\s*@sheet\\b",
+      "end": "^\\s*(?=@sheet\\b)"
+    }
+  },
+  "wordPattern": "(-?\\d*\\.\\d\\w*)|([^`~!@#$%^&*()=+[{\\]}\\\\|;:'\",.<>/?\\s]+)"
+}

package/syntaxes/cel.tmLanguage.json

@@ -0,0 +1,250 @@
+{
+  "$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
+  "name": "Cello",
+  "scopeName": "source.cel",
+  "fileTypes": ["cel"],
+  "patterns": [
+    { "include": "#comments" },
+    { "include": "#sheet-declaration" },
+    { "include": "#external-source" },
+    { "include": "#header-row" },
+    { "include": "#defaults-row" },
+    { "include": "#native-row" },
+    { "include": "#json" },
+    { "include": "#delimited-values" }
+  ],
+  "repository": {
+    "comments": {
+      "name": "comment.line.double-slash.cel",
+      "match": "^\\s*(//).*$",
+      "captures": {
+        "1": { "name": "punctuation.definition.comment.cel" }
+      }
+    },
+    "sheet-declaration": {
+      "name": "meta.sheet.declaration.cel",
+      "match": "^\\s*(@sheet)\\b(?:\\s+([^\\[\\r\\n]+?))?(?:\\s+(\\[)([^\\]\\r\\n]+)(\\]))?\\s*$",
+      "captures": {
+        "1": { "name": "keyword.control.sheet.cel" },
+        "2": {
+          "name": "entity.name.section.sheet.cel",
+          "patterns": [{ "include": "#identifiers" }]
+        },
+        "3": { "name": "punctuation.definition.format.begin.cel" },
+        "4": {
+          "name": "storage.type.format.cel",
+          "patterns": [
+            { "match": "\\b(?:csv|tsv|excel|markdown|json|noheader)\\b", "name": "support.constant.format.cel" },
+            { "match": "\\\\t|[,;|:]", "name": "constant.character.delimiter.cel" }
+          ]
+        },
+        "5": { "name": "punctuation.definition.format.end.cel" }
+      }
+    },
+    "external-source": {
+      "name": "meta.external-source.cel",
+      "match": "^\\s*(->)\\s*(.+)$",
+      "captures": {
+        "1": { "name": "keyword.operator.source.cel" },
+        "2": { "name": "string.unquoted.path.cel" }
+      }
+    },
+    "header-row": {
+      "name": "meta.header.row.cel",
+      "begin": "^\\s*(@header)\\b",
+      "beginCaptures": {
+        "1": { "name": "keyword.control.header.cel" }
+      },
+      "end": "$",
+      "patterns": [{ "include": "#row-content" }]
+    },
+    "defaults-row": {
+      "name": "meta.defaults.row.cel",
+      "begin": "^\\s*(@defaults)\\b",
+      "beginCaptures": {
+        "1": { "name": "keyword.control.defaults.cel" }
+      },
+      "end": "$",
+      "patterns": [{ "include": "#row-content" }]
+    },
+    "native-row": {
+      "name": "meta.table.row.cel",
+      "begin": "^\\s*(?=(?:\\[[^\\]\\r\\n]+\\]\\s*)*\\|)",
+      "end": "$",
+      "patterns": [
+        { "include": "#row-modifiers" },
+        { "include": "#row-content" }
+      ]
+    },
+    "row-content": {
+      "patterns": [
+        { "include": "#cell-separator" },
+        { "include": "#formula" },
+        { "include": "#merge-token" },
+        { "include": "#modifiers" },
+        { "include": "#forced-string" },
+        { "include": "#inline-heading" },
+        { "include": "#inline-strong" },
+        { "include": "#inline-emphasis" },
+        { "include": "#inline-strike" },
+        { "include": "#dates" },
+        { "include": "#booleans" },
+        { "include": "#numbers" },
+        { "include": "#identifiers" }
+      ]
+    },
+    "row-modifiers": {
+      "name": "meta.modifier.row.cel",
+      "match": "\\G\\s*(\\[[^\\]\\r\\n]+\\]\\s*)+(?=\\|)",
+      "captures": {
+        "1": {
+          "name": "meta.modifier.cel",
+          "patterns": [{ "include": "#modifiers" }]
+        }
+      }
+    },
+    "cell-separator": {
+      "name": "punctuation.separator.cell.cel",
+      "match": "\\|"
+    },
+    "merge-token": {
+      "name": "keyword.operator.merge.cel",
+      "match": "\\s*(<|\\^)\\s*(?=\\||$)"
+    },
+    "formula": {
+      "name": "meta.formula.cel",
+      "begin": "\\s*(=)",
+      "beginCaptures": {
+        "1": { "name": "punctuation.definition.formula.cel" }
+      },
+      "end": "(?=\\||$)",
+      "patterns": [
+        { "include": "#formula-functions" },
+        { "include": "#formula-ranges" },
+        { "include": "#formula-operators" },
+        { "include": "#forced-string" },
+        { "include": "#dates" },
+        { "include": "#booleans" },
+        { "include": "#numbers" },
+        { "include": "#identifiers" }
+      ]
+    },
+    "formula-functions": {
+      "name": "support.function.formula.cel",
+      "match": "\\b[A-Z][A-Z0-9_]*(?=\\s*\\()"
+    },
+    "formula-ranges": {
+      "patterns": [
+        {
+          "name": "variable.other.sheet-reference.cel",
+          "match": "(?:!!|[A-Za-z_][\\w.-]*!)"
+        },
+        {
+          "name": "constant.other.cell-reference.cel",
+          "match": "\\b[A-Z]+[1-9][0-9]*\\b"
+        },
+        {
+          "name": "meta.range.slice.cel",
+          "match": "\\[(?:\\*|[1-9][0-9]*:[1-9][0-9]*)\\]",
+          "captures": {
+            "0": { "name": "constant.other.range.cel" }
+          }
+        }
+      ]
+    },
+    "formula-operators": {
+      "name": "keyword.operator.formula.cel",
+      "match": "<=|>=|<>|[+\\-*/^&=<>(),:]|!"
+    },
+    "modifiers": {
+      "name": "meta.modifier.cel",
+      "begin": "\\[",
+      "beginCaptures": {
+        "0": { "name": "punctuation.definition.modifier.begin.cel" }
+      },
+      "end": "\\]",
+      "endCaptures": {
+        "0": { "name": "punctuation.definition.modifier.end.cel" }
+      },
+      "patterns": [
+        { "match": "\\b(?:bold|italic|hidden)\\b", "name": "storage.modifier.style.cel" },
+        { "match": "\\b(?:tone)(:)(?:ok|warn|error|info|muted|accent)\\b", "name": "support.constant.tone.cel", "captures": { "1": { "name": "punctuation.separator.key-value.cel" } } },
+        { "match": "\\b(?:bg|default)(:)", "name": "support.type.modifier-key.cel", "captures": { "1": { "name": "punctuation.separator.key-value.cel" } } },
+        { "match": "#(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})\\b", "name": "constant.other.color.rgb-value.cel" },
+        { "match": "#bg:", "name": "support.type.color-shorthand.cel" },
+        { "match": "[€$£%]", "name": "constant.character.currency.cel" },
+        { "match": "\\b[0-9]+d\\b", "name": "constant.numeric.decimal-places.cel" },
+        { "match": "\\b[a-zA-Z][a-zA-Z0-9-]*\\b", "name": "constant.language.color-name.cel" },
+        { "include": "#formula" }
+      ]
+    },
+    "forced-string": {
+      "name": "string.quoted.double.cel",
+      "begin": "\"",
+      "beginCaptures": {
+        "0": { "name": "punctuation.definition.string.begin.cel" }
+      },
+      "end": "\"",
+      "endCaptures": {
+        "0": { "name": "punctuation.definition.string.end.cel" }
+      },
+      "patterns": [
+        { "name": "constant.character.escape.cel", "match": "\\\\." }
+      ]
+    },
+    "inline-heading": {
+      "patterns": [
+        { "name": "markup.heading.1.cel", "match": "\\s*##\\s+[^|\\r\\n]+" },
+        { "name": "markup.heading.2.cel", "match": "\\s*#\\s+[^|\\r\\n]+" }
+      ]
+    },
+    "inline-strong": {
+      "name": "markup.bold.cel",
+      "begin": "(?<!\\*)\\*",
+      "end": "\\*(?!\\*)"
+    },
+    "inline-emphasis": {
+      "name": "markup.italic.cel",
+      "begin": "(?<!\\w)_",
+      "end": "_(?!\\w)"
+    },
+    "inline-strike": {
+      "name": "markup.strikethrough.cel",
+      "begin": "~~",
+      "end": "~~"
+    },
+    "dates": {
+      "name": "constant.other.date.iso.cel",
+      "match": "\\b[0-9]{4}-[0-9]{2}-[0-9]{2}\\b"
+    },
+    "booleans": {
+      "name": "constant.language.boolean.cel",
+      "match": "\\b(?:TRUE|FALSE|true|false|null)\\b"
+    },
+    "numbers": {
+      "name": "constant.numeric.cel",
+      "match": "(?<![\\w.])-?(?:\\d+\\.\\d+|\\d+|\\.\\d+)\\b"
+    },
+    "identifiers": {
+      "name": "variable.other.identifier.cel",
+      "match": "\\b[A-Za-z_][\\w.-]*\\b"
+    },
+    "json": {
+      "patterns": [
+        { "include": "#forced-string" },
+        { "match": "[{}\\[\\],:]", "name": "punctuation.definition.json.cel" },
+        { "include": "#booleans" },
+        { "include": "#numbers" }
+      ]
+    },
+    "delimited-values": {
+      "patterns": [
+        { "include": "#forced-string" },
+        { "include": "#dates" },
+        { "include": "#booleans" },
+        { "include": "#numbers" },
+        { "match": "[,;\\t]", "name": "punctuation.separator.delimited.cel" }
+      ]
+    }
+  }
+}