@searsuite/sear-domain-workbook

Workbook state

WorkbookDocumentState holds stable Sheet identities, order, names, visibility, and each Sheet's document state. WorkbookSessionState holds local values needed to remount the active Sheet. Internal references use stable sheetId values so renaming a Sheet changes its label without changing its identity.

The Workbook assembly mounts one active Sheet editor. Before switching, it captures that Sheet's document and local session, tears down the editor, and mounts the next Sheet. Switching back restores the captured session; viewport state does not become durable Workbook content.

addWorkbookSheet(), moveWorkbookSheet(), and related operations describe structural changes. The Workbook assembly stages add, remove, move, rename, hide, and unhide commands as Workbook transactions, with history separate from edits inside a mounted Sheet.

Use when: managing several Sheets or resolving references across them. Keep structural reads and identity in the Workbook domain; use the active Sheet editor and its feature commands for cell content or appearance. Formula references and collaboration channels use stable Sheet identities rather than mutable display names.

functioncreateWorkbookDocumentState: createWorkbookDocumentState<SheetState>(input: CreateWorkbookDocumentStateInput<SheetState>): WorkbookDocumentState<SheetState>

Creates a validated workbook state using array order as the sheet tab order.
classWorkbookError: class WorkbookError extends SearError

Error thrown when workbook state or workbook references violate their domain contract.

constructorWorkbookError(code: WorkbookErrorCode, message: string, details?: SearErrorDetails): WorkbookError

propertyreadonly code: WorkbookErrorCode

Stable machine-readable error code.

Inherited members 9

Inherited from SearError.

cause

details

message

name

stack

stackTraceLimit

report

captureStackTrace

prepareStackTrace
interfaceAddWorkbookSheetInput: interface AddWorkbookSheetInput<SheetState>

Input accepted by addWorkbookSheet.

propertyreadonly index?: number

Optional insertion index; defaults to appending after the current last sheet.

propertyreadonly sheet: WorkbookSheetDescriptor

Descriptor for the sheet being inserted.

propertyreadonly sheetState: SheetState

Initial state payload for the inserted sheet.
interfaceCreateWorkbookDocumentStateInput: interface CreateWorkbookDocumentStateInput<SheetState>

Input accepted by createWorkbookDocumentState.

propertyreadonly id: string

Stable workbook id used by persistence and collaboration rooms.

propertyreadonly metadata?: Readonly<Record<string, unknown>>

Extension-owned serializable metadata copied onto the workbook state.

propertyreadonly sheets: readonly WorkbookSheetDescriptor[]

Ordered sheet descriptors.

propertyreadonly sheetStates: WorkbookSheetStateMap<SheetState>

Per-sheet state payloads keyed by sheet id.
interfaceMoveWorkbookSheetInput: Input accepted by moveWorkbookSheet.

propertyreadonly sheetId: string

Sheet id to move.

propertyreadonly toIndex: number

Destination index in WorkbookDocumentState.sheets.
interfaceRemoveWorkbookSheetInput: Input accepted by removeWorkbookSheet.

propertyreadonly sheetId: string

Sheet id to remove.
interfaceRenameWorkbookSheetInput: Input accepted by renameWorkbookSheet.

propertyreadonly name: string

New user-facing sheet name.

propertyreadonly sheetId: string

Sheet id to rename.
interfaceSetWorkbookSheetHiddenInput: Input accepted by setWorkbookSheetHidden.

propertyreadonly hidden: boolean

Whether the sheet should be hidden.

propertyreadonly sheetId: string

Sheet id whose hidden flag should change.
interfaceUpdateWorkbookSheetStateInput: interface UpdateWorkbookSheetStateInput<SheetState>

Input accepted by updateWorkbookSheetState.

propertyreadonly sheetId: string

Sheet id whose state payload should be replaced.

propertyreadonly sheetState: SheetState

Replacement sheet state payload.
interfaceWorkbookDocumentState: interface WorkbookDocumentState<SheetState>

Workbook state containing sheet metadata plus per-sheet state payloads.

SheetState is generic so this package stays independent from sheet, render, formula, and assembly packages.

propertyreadonly id: string

Stable workbook id used by persistence and collaboration rooms.

propertyreadonly metadata?: Readonly<Record<string, unknown>>

Extension-owned serializable metadata that does not affect core workbook semantics.

propertyreadonly sheets: readonly WorkbookSheetDescriptor[]

Ordered sheet descriptors; array order is the persisted tab order.

propertyreadonly sheetStates: WorkbookSheetStateMap<SheetState>

Per-sheet state payloads keyed by stable sheet id.
interfaceWorkbookSheetDescriptor: Workbook-level sheet metadata.

The containing WorkbookDocumentState.sheets array is the only source of sheet order; descriptors intentionally do not carry a separate order field.

propertyreadonly color?: string

Optional UI tab color owned by the workbook host.

propertyreadonly hidden?: boolean

Whether the sheet is hidden from normal tab navigation.

propertyreadonly id: string

Stable sheet id used by workbook state, collaboration envelopes, and formula dependencies.

propertyreadonly metadata?: Readonly<Record<string, unknown>>

Extension-owned serializable metadata that does not affect core workbook semantics.

propertyreadonly name: string

Unique user-facing sheet name used when displaying formula references.
typeWorkbookErrorCode: type WorkbookErrorCode = typeof WorkbookErrorCode[keyof typeof WorkbookErrorCode] WorkbookErrorCode: { cannotHideAllSheets: "SEAR_WORKBOOK_CANNOT_HIDE_ALL_SHEETS"; cannotRemoveLastSheet: "SEAR_WORKBOOK_CANNOT_REMOVE_LAST_SHEET"; duplicateSheetId: "SEAR_WORKBOOK_DUPLICATE_SHEET_ID"; duplicateSheetName: "SEAR_WORKBOOK_DUPLICATE_SHEET_NAME"; invalidCellKey: "SEAR_WORKBOOK_INVALID_CELL_KEY"; invalidReference: "SEAR_WORKBOOK_INVALID_REFERENCE"; invalidSheetIndex: "SEAR_WORKBOOK_INVALID_SHEET_INDEX"; invalidSheetName: "SEAR_WORKBOOK_INVALID_SHEET_NAME"; … }

Machine-readable workbook error code type.
typeWorkbookId: type WorkbookId = string

Stable workbook identifier used by host-level workbook registries.
typeWorkbookSheetId: type WorkbookSheetId = string

Stable sheet identifier used inside workbook metadata and cross-sheet references.
typeWorkbookSheetStateMap: type WorkbookSheetStateMap = Readonly<Record<WorkbookSheetId, SheetState>>

Map from workbook sheet id to the host-selected sheet state payload.
functionaddWorkbookSheet: addWorkbookSheet<SheetState>(state: WorkbookDocumentState<SheetState>, input: AddWorkbookSheetInput<SheetState>): WorkbookDocumentState<SheetState>

Adds a sheet descriptor and its initial state payload without mutating the source workbook.
functiongetWorkbookSheetDescriptor: getWorkbookSheetDescriptor<SheetState>(state: WorkbookDocumentState<SheetState>, sheetId: string): WorkbookSheetDescriptor | null

Returns the descriptor for a sheet id, or null when the sheet is absent.
functiongetWorkbookSheetState: getWorkbookSheetState<SheetState>(state: WorkbookDocumentState<SheetState>, sheetId: string): SheetState | null

Returns one sheet state payload, or null when the sheet is absent.
functionmoveWorkbookSheet: moveWorkbookSheet<SheetState>(state: WorkbookDocumentState<SheetState>, input: MoveWorkbookSheetInput): WorkbookDocumentState<SheetState>

Moves a sheet descriptor to a new tab index without mutating the source workbook.
functionquoteWorkbookSheetName: quoteWorkbookSheetName(name: string): string

Returns a formula-safe display name for a workbook sheet.
functionremoveWorkbookSheet: removeWorkbookSheet<SheetState>(state: WorkbookDocumentState<SheetState>, input: RemoveWorkbookSheetInput): WorkbookDocumentState<SheetState>

Removes a sheet descriptor and its state payload without mutating the source workbook.
functionrenameWorkbookSheet: renameWorkbookSheet<SheetState>(state: WorkbookDocumentState<SheetState>, input: RenameWorkbookSheetInput): WorkbookDocumentState<SheetState>

Renames a workbook sheet without mutating the source workbook.
functionsetWorkbookSheetHidden: setWorkbookSheetHidden<SheetState>(state: WorkbookDocumentState<SheetState>, input: SetWorkbookSheetHiddenInput): WorkbookDocumentState<SheetState>

Sets the hidden flag for a sheet without mutating the source workbook.
functionupdateWorkbookSheetState: updateWorkbookSheetState<SheetState>(state: WorkbookDocumentState<SheetState>, input: UpdateWorkbookSheetStateInput<SheetState>): WorkbookDocumentState<SheetState>

Replaces one sheet state payload without mutating the source workbook.
functionvalidateWorkbookDocumentState: validateWorkbookDocumentState<SheetState>(state: WorkbookDocumentState<SheetState>): void

Validates the workbook structural invariants shared by commands and persistence.
variableWorkbookErrorCodeValue: WorkbookErrorCodeValue: { cannotHideAllSheets: "SEAR_WORKBOOK_CANNOT_HIDE_ALL_SHEETS"; cannotRemoveLastSheet: "SEAR_WORKBOOK_CANNOT_REMOVE_LAST_SHEET"; duplicateSheetId: "SEAR_WORKBOOK_DUPLICATE_SHEET_ID"; duplicateSheetName: "SEAR_WORKBOOK_DUPLICATE_SHEET_NAME"; invalidCellKey: "SEAR_WORKBOOK_INVALID_CELL_KEY"; invalidReference: "SEAR_WORKBOOK_INVALID_REFERENCE"; invalidSheetIndex: "SEAR_WORKBOOK_INVALID_SHEET_INDEX"; invalidSheetName: "SEAR_WORKBOOK_INVALID_SHEET_NAME"; … }

Stable machine-readable error codes owned by the workbook domain package.

References

interfaceParsedWorkbookFormulaReference: Parsed workbook formula reference bound to a stable sheet id.

propertyreadonly range: WorkbookRangeReference

Normalized workbook range. Single-cell references use the same start and end coordinate.

propertyreadonly sheetId: string

Stable sheet id resolved from the user-facing formula sheet name.
interfaceWorkbookCellReference: Qualified cell reference used by workbook-level formulas and dependency graphs.

propertyreadonly col: number

Zero-based column index.

propertyreadonly row: number

Zero-based row index.

propertyreadonly sheetId: string

Stable sheet id containing the referenced cell.
interfaceWorkbookColumnRangeReference: Qualified whole-column range reference used by workbook-level formulas.

propertyreadonly endCol: number

Zero-based end column index.

propertyreadonly sheetId: string

Stable sheet id containing the referenced columns.

propertyreadonly startCol: number

Zero-based start column index.
interfaceWorkbookRangeReference: Qualified rectangular range reference used by workbook-level formulas.

propertyreadonly end: readonly [number, number]

Zero-based bottom-right coordinate.

propertyreadonly sheetId: string

Stable sheet id containing the referenced range.

propertyreadonly start: readonly [number, number]

Zero-based top-left coordinate.
interfaceWorkbookRowRangeReference: Qualified whole-row range reference used by workbook-level formulas.

propertyreadonly endRow: number

Zero-based end row index.

propertyreadonly sheetId: string

Stable sheet id containing the referenced rows.

propertyreadonly startRow: number

Zero-based start row index.
typeWorkbookCellKey: type WorkbookCellKey = string

Serialized key for a workbook-qualified formula cell.
typeWorkbookCoordinateAxis: type WorkbookCoordinateAxis = typeof WorkbookCoordinateAxis[keyof typeof WorkbookCoordinateAxis] WorkbookCoordinateAxis: { col: "col"; row: "row" }

Stable workbook coordinate axis-name type.
typeWorkbookFormulaReference: type WorkbookFormulaReference = WorkbookCellReference | WorkbookRangeReference | WorkbookColumnRangeReference | WorkbookRowRangeReference

Any workbook-qualified formula reference supported by the workbook protocol.
typeWorkbookReferenceDiagnosticField: type WorkbookReferenceDiagnosticField = WorkbookReferenceField | templateLiteral | templateLiteral

Diagnostic field path emitted by workbook reference validation errors.
typeWorkbookReferenceField: type WorkbookReferenceField = typeof WorkbookReferenceField[keyof typeof WorkbookReferenceField] WorkbookReferenceField: { col: "col"; end: "end"; endCol: "endCol"; endRow: "endRow"; row: "row"; sheetId: "sheetId"; start: "start"; startCol: "startCol"; … }

Stable workbook reference property-name type.
variableWorkbookCoordinateIndex: WorkbookCoordinateIndex: { col: 1; row: 0 }

Tuple positions for workbook range coordinates.
functioncreateWorkbookCellKey: createWorkbookCellKey(reference: WorkbookCellReference): string

Creates a stable string key for a workbook-qualified cell reference.
functionformatParsedWorkbookFormulaReference: formatParsedWorkbookFormulaReference(reference: ParsedWorkbookFormulaReference, sheets: readonly WorkbookSheetDescriptor[]): string

Formats a parsed workbook formula reference with the current user-facing sheet name.
functionformatWorkbookCellReference: formatWorkbookCellReference(reference: WorkbookCellReference, sheetName: string): string

Formats a workbook-qualified cell reference using a caller-provided sheet name.
functionformatWorkbookRangeReference: formatWorkbookRangeReference(reference: WorkbookRangeReference, sheetName: string): string

Formats a workbook-qualified rectangular range reference using a caller-provided sheet name.
functionisValidWorkbookReference: isValidWorkbookReference(reference: unknown): reference

Reports whether an unknown value is any valid workbook-qualified formula reference.
functionisWorkbookCellReference: isWorkbookCellReference(reference: unknown): reference

Reports whether an unknown value is a valid workbook-qualified cell reference.
functionisWorkbookColumnRangeReference: isWorkbookColumnRangeReference(reference: unknown): reference

Reports whether an unknown value is a valid workbook-qualified whole-column range reference.
functionisWorkbookRangeReference: isWorkbookRangeReference(reference: unknown): reference

Reports whether an unknown value is a valid workbook-qualified rectangular range reference.
functionisWorkbookRowRangeReference: isWorkbookRowRangeReference(reference: unknown): reference

Reports whether an unknown value is a valid workbook-qualified whole-row range reference.
functionnormalizeWorkbookColumnRangeReference: normalizeWorkbookColumnRangeReference(reference: WorkbookColumnRangeReference): WorkbookColumnRangeReference

Normalizes a whole-column reference so the start column is before the end column.
functionnormalizeWorkbookRangeReference: normalizeWorkbookRangeReference(reference: WorkbookRangeReference): WorkbookRangeReference

Normalizes a range reference so start is top-left and end is bottom-right.
functionnormalizeWorkbookRowRangeReference: normalizeWorkbookRowRangeReference(reference: WorkbookRowRangeReference): WorkbookRowRangeReference

Normalizes a whole-row reference so the start row is before the end row.
functionparseWorkbookCellKey: parseWorkbookCellKey(key: string): WorkbookCellReference

Parses a string produced by createWorkbookCellKey back into a cell reference.
functionparseWorkbookFormulaReference: parseWorkbookFormulaReference(reference: string, sheets: readonly WorkbookSheetDescriptor[]): ParsedWorkbookFormulaReference

Parses a displayed workbook reference such as Sheet2!A1 or Sheet2!A1:B5 into a stable sheet-id range.
variableWorkbookCoordinateAxisValue: WorkbookCoordinateAxisValue: { col: "col"; row: "row" }

Stable coordinate axis names used by tuple-backed workbook range references.
variableWorkbookReferenceFieldValue: WorkbookReferenceFieldValue: { col: "col"; end: "end"; endCol: "endCol"; endRow: "endRow"; row: "row"; sheetId: "sheetId"; start: "start"; startCol: "startCol"; … }

Stable property names used by workbook-qualified formula references.