Gridheim Porting Guide
Gridheim brings OpenXLS and Sheetster spreadsheet capabilities into the modern ValkyrAI stack. The current codebase has several related formula paths, and the server-side ones should converge on OpenXLS semantics.
The most important boundary: Gridheim Runes are OpenAPI-defined calculated fields generated into Java model objects as @Rune. They are evaluated in real time and are not persisted values. Gridheim/Sheetster is the workbook and cell UX over generated objects.
Porting Targets
- React 18 and TypeScript components
- generated ThorAPI models for workbooks, sheets, cells, formats, and formulas
- RTK Query-backed service integration
- reusable formula editor behavior
- server-side workflow formulas backed by OpenXLS/JEXL where appropriate
- server-side generated field formulas backed by OpenXLS through the ValkyrAI Rune evaluator
Current Code Map
| Area | Current implementation |
|---|---|
| Generated field formulas | com.valkyrlabs.valkyrai.runes.* evaluates @Rune fields on model field reads with OpenXLS named ranges. |
| Legacy Rune compatibility | com.valkyrlabs.gridheim.core.* keeps older @Rune imports working and delegates to the same evaluator. |
| Workflow branching formulas | FormulaBranchingModule calls ConditionService, which tries OpenXLS first and then a JEXL fallback. |
| Workflow API connector formulas | GridheimFormulaEvaluator evaluates expressions through OpenXLS named ranges. |
| React Gridheim cells | GridheimCell edits and persists generated ThorAPI Cell objects, including Formula.expression. |
| React Gridheim sheet | GridheimSheet loads workbooks, sheets, and cells through generated RTK Query services and renders a 100x26 grid surface. |
| React formula bar | GridheimFormulaBar provides address display, formula entry, syntax highlighting, suggestions, and cell updates. |
| Client formula utilities | formulaUtils.ts parses references, validates basic syntax, expands ranges, and shifts formulas on copy/paste. |
| Client formula engine | Spreadsheet/grid/engine/FormulaEngine.ts evaluates a client-side formula subset for spreadsheet UI work. |
| ThorAPI object model | Generated Workbook, Sheet, Cell, Formula, Chart, PivotTable, NamedRange, and related services expose the workbook object graph. |
Feature Groups
Prioritize by user value:
| Area | Examples |
|---|---|
| Editing | in-place editing, formula bar, validation, error display |
| Navigation | arrow keys, tabbing, selection ranges, keyboard shortcuts |
| Clipboard | copy, cut, paste, paste special, transposed paste |
| Formatting | fonts, colors, alignment, borders, number formats |
| Formulas | parser, references, dependency tracking, errors |
| Performance | efficient range updates, server sync, selective rendering |
Rune Connection
OpenXLS is the server-side runtime substrate for generated Runes. ValkyrAI bridges object references into OpenXLS named ranges so formulas can stay authored as OpenAPI component-property expressions.
The product goal is still compositional: formula authoring, previews, and spreadsheet UX should feel consistent across:
- spreadsheet cells
- generated object fields
- OpenAPI designer previews
- workflow configuration surfaces
To get there safely, keep the React formula engine documented as a client helper until it intentionally matches the OpenXLS-backed server behavior.
Related: