sheet

package
v0.6.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 1, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ValidateProps added in v0.6.7 

func ValidateProps(props map[string]string) error

ValidateProps allowlists style prop keys and values. Props come from arbitrary collaborators and end up as inline CSS on every viewer's DOM, so anything outside the known vocabulary is rejected (e.g. bg: "url(...)").

Types

type Cell 

type Cell struct {
	Raw       string `json:"raw"`
	Value     string `json:"value,omitempty"`
	ValueType string `json:"valueType,omitempty"`
	StyleId   int    `json:"styleId"`
}

Cell is the atomic unit of a sheet. Raw is the source of truth (a literal value or a formula string like "=SUM(A1:A10)"). Value/ValueType are an optional client-reported cache of the computed result; the backend core never computes them. StyleId references the workbook StylePool.

func (Cell) IsEmpty 

func (c Cell) IsEmpty() bool

IsEmpty reports whether the cell carries no content and default styling, i.e. it can be dropped from sparse storage.

func (Cell) Kind 

func (c Cell) Kind() CellKind

Kind reports whether the raw content is a formula (leading '=') or a value.

type CellKind 

type CellKind string

CellKind classifies a cell's raw content. 

const (
	KindValue   CellKind = "value"
	KindFormula CellKind = "formula"
)

type CellRef 

type CellRef struct {
	Row int
	Col int
}

CellRef is a zero-based (row, col) address within a single sheet. It is a comparable struct so it can be used directly as a map key.

type CellSnapshot 

type CellSnapshot struct {
	Row       int    `json:"row"`
	Col       int    `json:"col"`
	Raw       string `json:"raw"`
	Value     string `json:"value,omitempty"`
	ValueType string `json:"valueType,omitempty"`
	StyleId   int    `json:"styleId,omitempty"`
}

CellSnapshot is the serializable form of one populated cell (map keys can't be JSON-encoded, so cells become a flat slice).

type Document 

type Document struct {
	// contains filtered or unexported fields
}

Document is the authoritative server-side state for one sheet document: the current Workbook, a monotonically growing op-log, and the head revision. It is NOT goroutine-safe; the per-document serialization goroutine (plan 2c) provides the total order, exactly as the text pad channel does.

func NewDocument 

func NewDocument(wb *Workbook) *Document

func NewDocumentAt 

func NewDocumentAt(wb *Workbook, log []Op) *Document

NewDocumentAt builds a Document whose workbook is already materialized to the end of log; head becomes len(log). Used when loading a persisted document (workbook from the snapshot, log from sheet_op) so stale-op rebasing keeps working after a server restart.

func (*Document) Head 

func (d *Document) Head() int

func (*Document) Log 

func (d *Document) Log() []Op

func (*Document) Submit 

func (d *Document) Submit(op Op) (int, error)

Submit rebases an op composed against op.BaseRev past every op applied since then, applies it, appends the rebased op to the log, and returns the new head revision. The rebased op (not the original) is logged so replay is exact.

func (*Document) Workbook 

func (d *Document) Workbook() *Workbook

type MergeSnapshot added in v0.6.7 

type MergeSnapshot struct {
	Row  int `json:"row"`
	Col  int `json:"col"`
	Rows int `json:"rows"`
	Cols int `json:"cols"`
}

MergeSnapshot is one merged range: top-left anchor plus its span.

type Op 

type Op struct {
	Type    OpType `json:"type"`
	Sheet   string `json:"sheet"`
	BaseRev int    `json:"baseRev"`

	// Cell ops (setCell, setStyle) and the top-left of a range (clearRange).
	Row int `json:"row,omitempty"`
	Col int `json:"col,omitempty"`
	// Range end (inclusive) for clearRange.
	EndRow int `json:"endRow,omitempty"`
	EndCol int `json:"endCol,omitempty"`

	// setCell payload (pointers so "unset" is distinguishable from empty).
	Raw       *string `json:"raw,omitempty"`
	Value     *string `json:"value,omitempty"`
	ValueType *string `json:"valueType,omitempty"`
	// setCell + setStyle payload.
	StyleId *int `json:"styleId,omitempty"`
	// setCell + setStyle: style properties to intern into the workbook StylePool.
	// When present, Apply interns them and sets the cell's StyleId to the result.
	Props map[string]string `json:"props,omitempty"`

	// Structural ops (insert/delete rows/cols). Index doubles as the insertion
	// position for addSheet.
	Index int `json:"index,omitempty"`
	Count int `json:"count,omitempty"`

	// Sheet-list ops.
	Name    string `json:"name,omitempty"`    // addSheet, renameSheet
	ToIndex int    `json:"toIndex,omitempty"` // moveSheet

	// setDimension.
	Axis string `json:"axis,omitempty"` // "col" or "row"
	Size int    `json:"size,omitempty"` // px

	// setFreeze. 0 or 1 each (freeze first row / first col only for now).
	FrozenRows int `json:"frozenRows,omitempty"`
	FrozenCols int `json:"frozenCols,omitempty"`
}

Op is one cell-based operation. BaseRev is the workbook revision the client composed it against (used by the server to rebase stale ops). Payload fields are optional per type.

func Transform 

func Transform(in, applied Op) Op

Transform adjusts `in` so it applies cleanly after `applied`, where both were originally composed against the same base revision and `applied` was ordered first by the server. Only structural ops (row/col insert/delete) on the same sheet and axis move coordinates; everything else is returned unchanged.

func (Op) Validate 

func (o Op) Validate() error

Validate checks structural invariants independent of any workbook state.

type OpType 

type OpType string
const (
	OpSetCell    OpType = "setCell"
	OpSetStyle   OpType = "setStyle"
	OpClearRange OpType = "clearRange"
	OpInsertRows OpType = "insertRows"
	OpDeleteRows OpType = "deleteRows"
	OpInsertCols OpType = "insertCols"
	OpDeleteCols OpType = "deleteCols"
	// Sheet-list ops: Op.Sheet names the target sheet id.
	OpAddSheet    OpType = "addSheet"
	OpRenameSheet OpType = "renameSheet"
	OpDeleteSheet OpType = "deleteSheet"
	OpMoveSheet   OpType = "moveSheet"
	// Grid metadata ops.
	OpSetDimension OpType = "setDimension"
	OpSetFreeze    OpType = "setFreeze"
	// Merged cells: both carry the Row/Col..EndRow/EndCol rectangle.
	OpMergeCells   OpType = "mergeCells"
	OpUnmergeCells OpType = "unmergeCells"
)

type Sheet 

type Sheet struct {
	Id    string           `json:"id"`
	Name  string           `json:"name"`
	Cells map[CellRef]Cell `json:"-"` // sparse; JSON handled by the snapshot/persistence layer
	// Sparse per-index pixel overrides; unset = view default.
	ColWidths  map[int]int `json:"-"`
	RowHeights map[int]int `json:"-"`
	// 0 or 1 each: freeze the first row / first col (position: sticky in the view).
	FrozenRows int `json:"-"`
	FrozenCols int `json:"-"`
	// Merged-cell ranges keyed by top-left anchor. Non-anchor cells keep their
	// content (hidden by the view); unmerge reveals it again.
	Merges map[CellRef]Span `json:"-"`
}

Sheet is a single tab: sparse cells plus structural metadata.

func NewSheet 

func NewSheet(id, name string) *Sheet

func (*Sheet) GetCell 

func (s *Sheet) GetCell(ref CellRef) Cell

GetCell returns the cell at ref, or the zero Cell if unset.

func (*Sheet) SetCell 

func (s *Sheet) SetCell(ref CellRef, c Cell)

SetCell stores a cell, dropping it from storage if empty (keeps it sparse).

type SheetSnapshot 

type SheetSnapshot struct {
	Id    string         `json:"id"`
	Name  string         `json:"name"`
	Cells []CellSnapshot `json:"cells"`
	// Sparse dimension overrides; JSON object keys are stringified indices.
	ColWidths  map[int]int     `json:"colWidths,omitempty"`
	RowHeights map[int]int     `json:"rowHeights,omitempty"`
	FrozenRows int             `json:"frozenRows,omitempty"`
	FrozenCols int             `json:"frozenCols,omitempty"`
	Merges     []MergeSnapshot `json:"merges,omitempty"`
}

type Span added in v0.6.7 

type Span struct {
	Rows int `json:"rows"`
	Cols int `json:"cols"`
}

Span is the extent of a merged-cell range, keyed by its top-left anchor. Rows/Cols >= 1; a 1x1 span is never stored.

type Style 

type Style struct {
	Props map[string]string `json:"props"`
}

Style is a set of formatting properties (e.g. numFmt, bold, color, align, border). Kept as a string->string map so the pool stays format-agnostic.

type StylePool 

type StylePool struct {
	IdToStyle map[int]Style `json:"idToStyle"`

	NextId int `json:"nextId"`
	// contains filtered or unexported fields
}

StylePool deduplicates styles per workbook. Id 0 is reserved for the empty style; cells default to it.

func NewStylePool 

func NewStylePool() *StylePool

func (*StylePool) Get 

func (p *StylePool) Get(id int) (Style, bool)

Get returns the style for an id. Id 0 is always the empty style.

func (*StylePool) Put 

func (p *StylePool) Put(s Style) int

Put interns a style and returns its id (dedup by canonical key).

type Workbook 

type Workbook struct {
	Sheets []*Sheet   `json:"sheets"`
	Styles *StylePool `json:"styles"`
}

Workbook is the full document: ordered sheets plus the shared StylePool.

func NewWorkbook 

func NewWorkbook() *Workbook

func WorkbookFromSnapshot 

func WorkbookFromSnapshot(snap WorkbookSnapshot) *Workbook

WorkbookFromSnapshot rebuilds a Workbook (and its StylePool dedup index) from a deserialized snapshot.

func (*Workbook) AddSheet 

func (w *Workbook) AddSheet(id, name string) *Sheet

func (*Workbook) Apply 

func (w *Workbook) Apply(op Op) error

Apply mutates the workbook by op. The op is assumed already rebased to the current revision (see reconcile.go). Cell ops are last-writer-wins; the caller's total ordering decides the winner.

func (*Workbook) Clone 

func (w *Workbook) Clone() *Workbook

Clone returns a deep copy so callers can simulate clients independently.

func (*Workbook) SheetByID 

func (w *Workbook) SheetByID(id string) *Sheet

func (*Workbook) Snapshot 

func (w *Workbook) Snapshot() WorkbookSnapshot

Snapshot converts the workbook to its serializable form. Cells are emitted in (row, col) order for deterministic output.

type WorkbookSnapshot 

type WorkbookSnapshot struct {
	Sheets []SheetSnapshot `json:"sheets"`
	Styles *StylePool      `json:"styles"`
}

WorkbookSnapshot is the JSON-serializable form of a Workbook for persistence.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.