Calcillo format

Complete format specification for Calcillo, Cloudillo’s collaborative spreadsheet application.

Overview

Calcillo is a real-time collaborative spreadsheet that supports multiple sheets, formulas, merged cells, borders, hyperlinks, data validation, conditional formatting, and frozen panes. Documents are stored as Yjs CRDT structures for conflict-free concurrent editing. The cell data model is derived from FortuneSheet with inline styling.

Content type: application/vnd.cloudillo.calcillo+json
Format version: 1.0.0
File extension: .calcillo

Design Philosophy

Per-sheet encapsulation: Each sheet is a self-contained unit with its own rows, columns, merges, borders, and other features. This prevents cross-sheet conflicts and enables efficient partial sync – only active sheets need to be observed.
Nested row maps: Cell data uses rows[rowId][colId] = Cell, allowing efficient row-level operations (insert, delete, move) without touching unrelated cells.
ID-based addressing: Rows, columns, and sheets use random IDs (not sequential indices) for CRDT stability. IDs survive concurrent insertions and deletions without rebasing.
Inline styles: All cell formatting (font, color, alignment) is stored directly on each cell. There is no named style system – this trades storage efficiency for simplicity and avoids the style cascade complexity of apps like Prezillo.

Document Architecture

graph LR
    Doc[Y.Doc]

    subgraph Root
        so["sheetOrder (Y.Array&lt;SheetId&gt;)<br/>Sheet tab order"]
        sheets["sheets (Y.Map&lt;YSheetStructure&gt;)<br/>All sheets"]
        meta["meta (Y.Map)<br/>Document metadata"]
    end

    subgraph "Per-Sheet (YSheetStructure)"
        name["name (Y.Text)"]
        rows["rows (Y.Map&lt;Y.Map&lt;Cell&gt;&gt;)"]
        ro["rowOrder (Y.Array&lt;RowId&gt;)"]
        co["colOrder (Y.Array&lt;ColId&gt;)"]
        merges["merges (Y.Map&lt;MergeInfo&gt;)"]
        borders["borders (Y.Map&lt;BorderInfo&gt;)"]
        more["... 7 more sub-types"]
    end

    Doc --> Root
    sheets --> name
    sheets --> rows
    sheets --> ro
    sheets --> co
    sheets --> merges
    sheets --> borders
    sheets --> more

Quick Reference

Root-Level Shared Types

Key	Yjs Type	Purpose
`sheetOrder`	`Y.Array<SheetId>`	Sheet tab order
`sheets`	`Y.Map<YSheetStructure>`	All sheets keyed by `SheetId`
`meta`	`Y.Map`	Document metadata

Per-Sheet Sub-Types

Sub-type	Yjs Type	Purpose
`name`	`Y.Text`	Sheet name (collaborative editing)
`rowOrder`	`Y.Array<RowId>`	Stable row ordering
`colOrder`	`Y.Array<ColId>`	Stable column ordering
`rows`	`Y.Map<Y.Map<Cell>>`	Nested: `rows[rowId][colId] = Cell` (sparse)
`merges`	`Y.Map<MergeInfo>`	Key: `"${startRow}_${startCol}"`
`borders`	`Y.Map<BorderInfo>`	Key: `"${rowId}_${colId}"`
`hyperlinks`	`Y.Map<HyperlinkInfo>`	Key: `"${rowId}_${colId}"`
`validations`	`Y.Map<ValidationRule>`	Key: unique validation ID
`conditionalFormats`	`Y.Array<ConditionalFormat>`	Ordered rules
`hiddenRows`	`Y.Map<boolean>`	`rowId → true` if hidden
`hiddenCols`	`Y.Map<boolean>`	`colId → true` if hidden
`rowHeights`	`Y.Map<number>`	`rowId → height` in pixels
`colWidths`	`Y.Map<number>`	`colId → width` in pixels
`frozen`	`Y.Map<string\|number>`	Freeze pane settings

Detailed Documentation

Document Structure – Root Y.Doc, per-sheet structure, ID system, metadata, and initialization
Cells – Cell data model, values, formulas, inline styles, and cell types
Grid Structure – Row/column ordering, sizing, hidden rows/cols, and merged cells
Sheet Features – Borders, hyperlinks, data validation, conditional formatting, and frozen panes
Sheets – Multi-sheet support, sheet ordering, and sheet operations
Export Format – JSON export envelope with complete example