Skip to main content

GridHeim: Spreadsheet Surface for ValkyrAI

GridHeim/Sheetster is the workbook, cell, formula, and calculated-field experience in the ValkyrAI stack. It is built on generated ThorAPI models, OpenXLS formula evaluation, and React components, and it gives users a spreadsheet-like surface over generated objects.

Gridheim Runes are the OpenAPI-defined calculated-field part of this system: a formula expression is stored as an OpenAPI extension on a component property, ThorAPI emits it as @Rune on the Java model field, and ValkyrAI evaluates it in real time through OpenXLS without persisting the calculated value.

Current Implementation Map​

LayerCode
Generated object modelsrc/thorapi/model/Workbook.ts, Sheet.ts, Cell.ts, Formula.ts, Chart.ts, PivotTable.ts, NamedRange.ts, and related models.
Generated servicessrc/thorapi/redux/services/WorkbookService.tsx, SheetService.tsx, CellService.tsx, and FormulaService.tsx.
Cell UIsrc/components/Gridheim/GridheimCell.tsx handles edit mode, formula storage, number/string values, hyperlinks, validation messages, cell expansion, and ThorAPI add/update mutations.
Sheet UIsrc/components/Gridheim/GridheimSheet.tsx loads workbooks, sheets, and cells through generated RTK Query services and renders a spreadsheet grid with selection, keyboard navigation, and clipboard hooks.
Formula barsrc/components/Gridheim/GridheimFormulaBar.tsx provides the address box, formula input, basic syntax highlighting, function suggestions, and cell update persistence.
Formula utilitiessrc/components/Gridheim/utils/formulaUtils.ts parses formula references, validates basic syntax, expands ranges, and shifts references for copy/paste.
Client formula enginesrc/components/Spreadsheet/grid/engine/FormulaEngine.ts evaluates a spreadsheet-oriented formula subset for UI-side work.
Workflow formulascom.valkyrlabs.gridheim.formula.OpenXLSFormulaEvaluator, GridheimFormulaEvaluator, and ConditionService support workflow conditions and API connector formulas.
Generated field formulascom.valkyrlabs.valkyrai.runes.* evaluates generated @Rune model fields on the server through OpenXLS named ranges.

Generated Data Model​

The current ThorAPI-generated workbook object graph includes:

ModelCurrent fields of interest
Workbookname, sheets, formats, status, and standard DataObject audit/ownership fields.
SheetworkbookId, name, cells, rows, cols, namedRanges, mergeRanges, blankRanges, charts, and pivotTables.
CellsheetId, comment, hyperlink, row, column, stringValue, numberValue, formula, and format.
FormulaworkbookId, sheetId, expression, ptgRefs, and calculatingPtgs.

The generated RTK Query services use singular resource names relative to the configured ThorAPI base path, such as Workbook, Sheet, Cell, and Formula. They provide list, paged list, get by id, add, update, delete, and cascade-delete hooks.

What Works Today​

  • Workbook, sheet, cell, and formula records are represented as generated ThorAPI models.
  • Gridheim components use generated RTK Query services instead of a parallel handwritten CRUD layer.
  • Cells can persist text, numeric values, and formulas through Cell.formula.expression.
  • The sheet surface supports arrow navigation, Enter/Escape editing flow, Tab movement, and Ctrl/Cmd copy/cut/paste hooks.
  • The formula bar stores formulas and offers function suggestions and reference highlighting.
  • Formula utilities understand A1 references, ranges, absolute references, and reference shifting.
  • The separate spreadsheet engine can evaluate a client-side subset including arithmetic, comparisons, references, ranges, and common functions such as SUM, AVERAGE, COUNT, MIN, MAX, IF, AND, OR, CONCAT, LEN, UPPER, LOWER, and TRIM.

Boundaries​

  • Do not describe Gridheim Runes as stored database values. They are no-persistence calculated fields evaluated on read.
  • Do not describe Runes as a GrayMatter memory client or SWARM agent. They are generated object logic.
  • Do not assume the React formula engine has identical function coverage to server-side OpenXLS.
  • Do not document /api/workbooks-style endpoints as the current generated client path unless the server routing layer explicitly aliases them. The generated client uses resources such as Workbook, Sheet, Cell, and Formula relative to its base query.

Product Direction​

GridHeim should continue to converge the spreadsheet UX, generated ThorAPI workbook models, OpenAPI design previews, workflow formula configuration, and Rune authoring into a coherent formula experience. The server-side convergence point is OpenXLS; the client-side controls should make that behavior visible and predictable.

Related: