sheet-authoring

Authoring an open-sheet workbook

The one rule

Never write a cell address.

Not B5. Not SUM(B2:B13). Not $A$1. The framework assigns every coordinate after it has laid the blocks out, and references resolve against that layout. Writing an address by hand means writing a number that is correct only until someone adds a row — and then it is silently wrong, which in a financial model is worse than broken.

If you catch yourself counting rows to work out where something landed, stop. The thing you want is a reference.

The single exception is raw('...'), the deliberate escape hatch — see references/formulas.md.

The file contract

// sheets/<id>/index.tsx
import { Sheet, Table, Workbook, col, sub, type SheetMeta } from '@open-sheet/core'

export const meta: SheetMeta = {
  title: 'FY26 Budget',        // shown in the viewer and used as the export name
  description: 'One line.',    // optional
  theme: 'corporate-neutral',  // optional; links back to themes/<id>.md
  createdAt: '2026-08-18T00:00:00.000Z',
}

export const design: DesignSystem = { … }   // optional; see the Design panel note

export default (
  <Workbook>
    <Sheet name="…">…</Sheet>
  </Workbook>
)

The default export must be a <Workbook> containing <Sheet> children. meta and design are plain object literals — the dev UI parses and rewrites them, and a spread or an imported value makes the workbook untweakable.

Structure in JSX, data in TypeScript

JSX describes the report. Rows are plain arrays.

const quarters = [
  { quarter: 'Q1', revenue: 12_400_000, cogs: 5_100_000 },
  { quarter: 'Q2', revenue: 13_900_000, cogs: 5_600_000 },
]

<Table
  name="pl"
  data={quarters}
  columns={[
    col('quarter', { header: 'Quarter', width: 12 }),
    col('revenue', { header: 'Revenue', format: 'currency' }),
    col('grossProfit', {
      header: 'Gross profit',
      format: 'currency',
      formula: (r) => sub(r.cell('revenue'), r.cell('cogs')),
    }),
  ]}
  total={{ revenue: 'sum', grossProfit: 'sum' }}
/>