SearSuite
← All packages

@searsuite/sear-assembly-workbook

Create a workbook editor

createWorkbookEditor() creates the Workbook runtime and mounts a Sheet editor for the active Sheet. The Workbook owns structure and shared services; the mounted Sheet editor owns its own commands, queries, capabilities, and selected plugins. WorkbookEditor keeps structural reads under document and mounted-Sheet access under sheets.

Use when: a product needs several Sheets with stable identities, switching, structural commands, or shared Workbook services. A single Sheet host can use createSheetEditor() directly.

functioncreateWorkbookEditor
createWorkbookEditor(configuration: WorkbookEditorConfiguration): WorkbookEditor

Creates a Workbook editor with an isolated DI container and plugin graph.

Workbook-owned services survive individual Sheet mounts. The editor keeps structure, collaboration channels, formula registries, and detached Sheet sessions keyed by stable Sheet identifiers.

ReturnsA Workbook facade that owns its mounted Sheet editor lifecycle.

Example
const workbook = createWorkbookEditor(configuration);
await workbook.commands.run(ActivateWorkbookSheetCommand, { sheetId });
workbook.destroy();
configuration

Workbook document state, host adapters, and Workbook and Sheet plugins.

interfaceWorkbookEditor

Public workbook facade returned by createWorkbookEditor().

propertyreadonly capabilities: RuntimeCapabilityReader

Read-only access to typed services owned by this editor's isolated runtime.

propertyreadonly commands: WorkbookCommandBus

The supported command entry point for workbook user and program actions.

propertyreadonly document: WorkbookDocumentApi

Read-only access to document-owned workbook state.

propertyreadonly observations: ObservationRegistry

Typed editor-local state and event observations exposed to the host.

propertyreadonly sheets: WorkbookSheetsApi

Read-only access to the active and mounted SheetEditor.

methoddestroy(): void

Releases the active SheetEditor, plugins, observations, commands, and editor-local services.

classWorkbookPlugin
class WorkbookPlugin extends PluginExtension<WorkbookCommandBus, ObservationRegistry, SessionStateRegistry, WorkbookRuntimeExtensionRegistry>

Base contract for plugins owned by createWorkbookEditor().

constructorWorkbookPlugin(): WorkbookPlugin
methodenforceRuntimeWriteBoundary(assertWrite: (): void): void

Closes plugin-owned runtime mutations after Workbook assembly.

methodgetSheetPlugins(context: WorkbookCompanionSheetPluginContext): readonly SheetPluginImplementation<SheetPlugin<unknown>>[]
methodgetSheetServices(context: WorkbookCompanionSheetPluginContext): readonly WorkbookCompanionSheetService<unknown>[]

Contributes parent-owned services without exposing the child editor container.

methodinitialize(context: WorkbookPluginContext): void | WorkbookPluginDisposer
methodonBeforeSheetActivation(input: ActivateWorkbookSheetCommandInput): void

Runs inside the activation command before the source Sheet is captured.

methodonSheetActivationFailed(input: ActivateWorkbookSheetCommandInput): void

Restores plugin-local work if activation fails before commit.

methodonTransactionCommitted(event: WorkbookTransactionCommittedEvent): void
methodonWorkbookDestroy(context: WorkbookPluginContext): void
methodregisterCapabilities(registry: WorkbookRuntimeExtensionRegistry): void

Registers every runtime capability owned by this plugin.

methodregisterCommands(commands: WorkbookCommandBus): void

Registers every stable command id owned by this plugin.

methodregisterObservations(observations: ObservationRegistry): void

Registers every typed state and event observation source owned by this plugin.

methodregisterSessionState(registry: SessionStateRegistry): void

Registers every local session value owned by this plugin.

methodregisterServices(context: WorkbookPluginServiceContext): voidstatic
interfaceWorkbookPluginContext

Context passed to Workbook plugin lifecycle hooks.

propertyreadonly container: Container
propertyreadonly runtime: WorkbookPluginRuntime
interfaceWorkbookPluginImplementation
interface WorkbookPluginImplementation<TPlugin>

Injectable Workbook plugin class accepted by createWorkbookEditor().

constructorWorkbookPluginImplementation(...args: never[]): TPlugin
propertyreadonly symbol: symbol
methodregisterServices(context: WorkbookPluginServiceContext): void
interfaceWorkbookPluginServiceContext

Services available before a Workbook plugin is registered in its editor-local container.

propertyreadonly container: Container
typeWorkbookPluginDisposer
type WorkbookPluginDisposer = (): void

Resource disposer returned by Workbook plugin lifecycle hooks.

typeWorkbookRuntimeCapabilityReader
type WorkbookRuntimeCapabilityReader = RuntimeCapabilityReader
typeWorkbookRuntimeCapabilityToken
type WorkbookRuntimeCapabilityToken = RuntimeCapability<T>
variableWorkbookRuntimeCapability
WorkbookRuntimeCapability: { Commands: WorkbookRuntimeCapabilityToken<WorkbookCommandBus>; Formula: WorkbookRuntimeCapabilityToken<{ externalServices: IFormulaExternalServiceProvider; functions: IFunctionRegistry; textServices: IFormulaTextServiceProvider; webService: WebServiceClient; xmlXPath: XmlXPathEvaluator }>; Observations: WorkbookRuntimeCapabilityToken<ObservationRegistry>; Platform: WorkbookRuntimeCapabilityToken<Platform>; Runtime: WorkbookRuntimeCapabilityToken<WorkbookPluginRuntime>; Session: WorkbookRuntimeCapabilityToken<SessionStateRegistry> }

Workbook capabilities registered by the default assembly root.

functiondefineWorkbookRuntimeCapability
defineWorkbookRuntimeCapability<T>(id: string): WorkbookRuntimeCapabilityToken<T>

Creates a typed capability published by a Workbook plugin.

functionregisterWorkbookPluginCapabilities
registerWorkbookPluginCapabilities(plugins: readonly unknown[], registry: WorkbookRuntimeExtensionRegistry): void

Publishes every typed runtime capability contributed by Workbook plugins.

functionregisterWorkbookPluginCommands
registerWorkbookPluginCommands(plugins: readonly unknown[], commands: WorkbookCommandBus): void
functionregisterWorkbookPluginObservations
registerWorkbookPluginObservations(plugins: readonly unknown[], observations: ObservationRegistry): void
functionregisterWorkbookPluginSessionStates
registerWorkbookPluginSessionStates(plugins: readonly unknown[], session: SessionStateRegistry): void
functionresolveWorkbookPlugins
resolveWorkbookPlugins(container: Container, implementations: readonly WorkbookPluginImplementation<WorkbookPlugin>[]): WorkbookPlugin[]

Resolves isolated Workbook plugin singletons from one editor-local container.

Add and switch sheets

ActivateWorkbookSheetCommand captures the current Sheet document and local session, tears down that Sheet editor, and mounts the requested Sheet. The session is restored when returning to it. Workbook structural commands such as AddWorkbookSheetCommand and RenameWorkbookSheetCommand stage changes in a separate history from cell edits inside the active Sheet.

Stable sheetId values identify Sheets across rename and reorder operations. A host should use the Workbook document API for structure and the mounted Sheet API for content. WorkbookPlugin contributions can own shared services that survive a Sheet remount.

interfaceActivateWorkbookSheetCommandInput

Input for activating a workbook sheet.

propertyreadonly sheetId: string

Sheet id to make active.

interfaceHideWorkbookSheetCommandInput

Input for hiding a workbook sheet.

propertyreadonly nextActiveSheetId?: string

Optional active sheet to select when hiding the current active sheet.

propertyreadonly sheetId: string

Sheet id to hide.

interfaceUnhideWorkbookSheetCommandInput

Input for unhiding a workbook sheet.

propertyreadonly sheetId: string

Sheet id to reveal.

interfaceWorkbookSheetEditorFactoryInput

Input passed when the workbook assembly creates one active SheetEditor.

propertyreadonly configuration: SheetEditorConfiguration
propertyreadonly sheetId: string
interfaceWorkbookSheetsApi

Read-only access to SheetEditor instances owned by one WorkbookEditor.

methodgetActiveEditor(): SheetEditor

Returns the SheetEditor mounted for the active sheet.

methodgetActiveId(): string

Returns the stable id of the active sheet.

methodgetEditor(sheetId: string): SheetEditor | null

Returns the mounted SheetEditor when sheetId is active; detached sheets return null.

typeAddWorkbookSheetCommandInput
type AddWorkbookSheetCommandInput = AddWorkbookSheetInput<SheetDocumentState> & { activate?: boolean }

Input for adding a sheet to the workbook.

typeMoveWorkbookSheetCommandInput
type MoveWorkbookSheetCommandInput = MoveWorkbookSheetInput

Input for moving a sheet tab.

typeRemoveWorkbookSheetCommandInput
type RemoveWorkbookSheetCommandInput = RemoveWorkbookSheetInput & { nextActiveSheetId?: WorkbookSheetId }

Input for removing a sheet from the workbook.

typeRenameWorkbookSheetCommandInput
type RenameWorkbookSheetCommandInput = RenameWorkbookSheetInput

Input for renaming a workbook sheet.

typeWorkbookSheetEditorFactory
type WorkbookSheetEditorFactory = (input: WorkbookSheetEditorFactoryInput): SheetEditor
variableActivateWorkbookSheetCommand
ActivateWorkbookSheetCommand: WorkbookCommandDefinition<ActivateWorkbookSheetCommandInput, WorkbookCommandResult>

Official command for activating a workbook sheet.

variableAddWorkbookSheetCommand
AddWorkbookSheetCommand: WorkbookCommandDefinition<AddWorkbookSheetCommandInput, WorkbookCommandResult>

Official command for adding a sheet descriptor and sheet state payload.

variableHideWorkbookSheetCommand
HideWorkbookSheetCommand: WorkbookCommandDefinition<HideWorkbookSheetCommandInput, WorkbookCommandResult>

Official command for hiding a workbook sheet.

variableMoveWorkbookSheetCommand
MoveWorkbookSheetCommand: WorkbookCommandDefinition<MoveWorkbookSheetInput, WorkbookCommandResult>

Official command for moving a workbook sheet tab.

variableRemoveWorkbookSheetCommand
RemoveWorkbookSheetCommand: WorkbookCommandDefinition<RemoveWorkbookSheetCommandInput, WorkbookCommandResult>

Official command for removing a sheet descriptor and sheet state payload.

variableRenameWorkbookSheetCommand
RenameWorkbookSheetCommand: WorkbookCommandDefinition<RenameWorkbookSheetInput, WorkbookCommandResult>

Official command for renaming a workbook sheet.

variableUnhideWorkbookSheetCommand
UnhideWorkbookSheetCommand: WorkbookCommandDefinition<UnhideWorkbookSheetCommandInput, WorkbookCommandResult>

Official command for unhiding a workbook sheet.

Workbook document state

interfaceWorkbookDocumentApi

Read-only access to the document-owned state of one WorkbookEditor.

methodgetState(): WorkbookDocumentState<SheetDocumentState>

Returns the current in-memory workbook document state.

interfaceWorkbookDocumentStateSerializationOptions
interface WorkbookDocumentStateSerializationOptions<TSheetState>

Options for workbook document-state serialization.

propertyreadonly sheetRegistry?: DocumentStateCodecRegistry<TSheetState>

Registry that owns Sheet document-state module serialization.

interfaceWorkbookSheetStateCaptureInput

Read-only active SheetEditor capture hook used by custom hosts and focused tests.

propertyreadonly documentState: WorkbookDocumentState<SheetDocumentState>
propertyreadonly editor: SheetEditor
propertyreadonly sheetId: string
propertyreadonly sheetState: SheetDocumentState
typeWorkbookSheetStateCapture
type WorkbookSheetStateCapture = (input: WorkbookSheetStateCaptureInput): SheetDocumentState
variableWorkbookDocumentStateObservation
WorkbookDocumentStateObservation: StateObservationDefinition<WorkbookDocumentState<SheetDocumentState>>

Current workbook-owned metadata and per-sheet document payloads.

functiondeserializeWorkbookDocumentState
deserializeWorkbookDocumentState<TSheetState>(payload: unknown, options?: WorkbookDocumentStateSerializationOptions<TSheetState>): WorkbookDocumentState<TSheetState>

Deserializes a stable SearSuite JSON workbook file into runtime document state.

functionserializeWorkbookDocumentState
serializeWorkbookDocumentState<TSheetState>(documentState: WorkbookDocumentState<TSheetState>, options?: WorkbookDocumentStateSerializationOptions<TSheetState>): SearWorkbookFile<WorkbookSheetDescriptor>

Serializes a workbook document state into the stable SearSuite JSON format.

Capture sessions

interfaceCaptureWorkbookSessionStateCommandResult

Captured local state for remounting one WorkbookEditor runtime.

propertyreadonly sessionState: WorkbookSessionState
interfaceWorkbookActiveSheetEditorSnapshot

Current live SheetEditor mounted by one WorkbookEditor instance.

propertyreadonly editor: SheetEditor

Live editor owned by the workbook assembly.

propertyreadonly sheetId: string

Stable id of the sheet mounted by the live editor.

interfaceWorkbookCompanionSheetPluginContext
interface WorkbookCompanionSheetPluginContext extends WorkbookPluginContext

Context used when a Workbook plugin contributes plugins to a mounted SheetEditor.

propertyreadonly sheetId: string
propertyreadonly sheetState: SheetDocumentState
Inherited members 2

Inherited from WorkbookPluginContext.

interfaceWorkbookCompanionSheetService
interface WorkbookCompanionSheetService<Value>

One typed service value contributed to a temporary child SheetEditor container.

propertyreadonly token: symbol
propertyreadonly value: Value
typeWorkbookSessionState
type WorkbookSessionState = SessionStateSnapshot

Opaque editor-local workbook state keyed by contributor-owned definitions.

typeWorkbookSheetSessionStateCapture
type WorkbookSheetSessionStateCapture = (input: WorkbookSheetSessionStateCaptureInput): SheetSessionState | undefined
variableCaptureWorkbookSessionStateCommand
CaptureWorkbookSessionStateCommand: WorkbookCommandDefinition<void, CaptureWorkbookSessionStateCommandResult>
variableExportWorkbookStateCommand
ExportWorkbookStateCommand: WorkbookCommandDefinition<void, ExportWorkbookStateCommandResult>
variableWorkbookActiveSheetEditorObservation
WorkbookActiveSheetEditorObservation: StateObservationDefinition<WorkbookActiveSheetEditorSnapshot>

Current live active SheetEditor, updated only when the mounted editor changes.

variableWorkbookActiveSheetSessionStateDefinition
WorkbookActiveSheetSessionStateDefinition: SessionStateDefinition<string>

Stable session identity for the locally active workbook sheet.

variableWorkbookSheetSessionsStateDefinition
WorkbookSheetSessionsStateDefinition: SessionStateDefinition<Readonly<Record<string, Readonly<Record<string, unknown>>>>>

Stable session identity for detached SheetEditor snapshots keyed by sheet id.

Formula objects and names

Defined names and formula tables belong to the Workbook, so expressions can refer to them across Sheets.

classWorkbookFormulaObjectsPlugin
class WorkbookFormulaObjectsPlugin extends WorkbookPlugin

Workbook-owned editing surface for named formulas and table references.

constructorWorkbookFormulaObjectsPlugin(): WorkbookFormulaObjectsPlugin
propertyreadonly symbol: typeof symbolstatic
methodinitialize(context: WorkbookPluginContext): void
methodonTransactionCommitted(): void
methodonWorkbookDestroy(): void
methodregisterCommands(commands: WorkbookCommandBus): void

Registers every stable command id owned by this plugin.

methodregisterObservations(observations: ObservationRegistry): void

Registers every typed state and event observation source owned by this plugin.

Inherited members 8

Inherited from WorkbookPlugin.

variableRemoveWorkbookDefinedNameCommand
RemoveWorkbookDefinedNameCommand: WorkbookCommandDefinition<{ name: string }, void>
variableRemoveWorkbookFormulaTableCommand
RemoveWorkbookFormulaTableCommand: WorkbookCommandDefinition<{ name: string }, void>
variableSetWorkbookDefinedNameCommand
SetWorkbookDefinedNameCommand: WorkbookCommandDefinition<SetWorkbookDefinedNameInput, void>
variableSetWorkbookFormulaTableCommand
SetWorkbookFormulaTableCommand: WorkbookCommandDefinition<WorkbookFormulaTable, void>
variableWorkbookFormulaObjectsMetadataKey
WorkbookFormulaObjectsMetadataKey: "searsuite.workbook.formulaObjects"

Metadata key owned by workbook formula evaluation.

variableWorkbookFormulaObjectsObservation
WorkbookFormulaObjectsObservation: StateObservationDefinition<WorkbookFormulaObjects>

Formula references

interfaceWorkbookFormulaBrokenReference

Dependency entry retained after a workbook formula reference becomes invalid.

propertyreadonly kind: "broken"
propertyreadonly reason: WorkbookFormulaBrokenReferenceReason
propertyreadonly reference: WorkbookFormulaReference
propertyreadonly sheetId: string
interfaceWorkbookFormulaCompiledReferenceShiftResult

Result of applying row/column structure edits to one compiled workbook formula.

propertyreadonly changed: boolean

Whether formula position, AST, dependencies, or broken-reference metadata changed.

propertyreadonly compiled: CompiledWorkbookFormula

Updated compiled formula.

interfaceWorkbookFormulaReferenceShiftResult

Result of shifting workbook-qualified formula references in one AST.

propertyreadonly ast: FormulaAST

Shifted AST, or the original AST when no workbook reference changed.

propertyreadonly brokenReferences: readonly WorkbookFormulaReference[]

References that became invalid because the target row or column was deleted.

propertyreadonly changed: boolean

Whether the AST identity changed.

typeWorkbookFormulaBrokenReferenceReason
type WorkbookFormulaBrokenReferenceReason = typeof WorkbookFormulaBrokenReferenceReason[keyof typeof WorkbookFormulaBrokenReferenceReason] WorkbookFormulaBrokenReferenceReason: { ReferenceDeleted: "referenceDeleted"; SheetDeleted: "sheetDeleted" }

Reason a workbook formula reference can no longer resolve.

typeWorkbookFormulaGraphReference
type WorkbookFormulaGraphReference = WorkbookFormulaReference | WorkbookFormulaBrokenReference

Dependency entry stored by the workbook formula graph.

typeWorkbookFormulaGraphReferenceKind
type WorkbookFormulaGraphReferenceKind = typeof WorkbookFormulaGraphReferenceKind[keyof typeof WorkbookFormulaGraphReferenceKind] WorkbookFormulaGraphReferenceKind: { Broken: "broken" }

Dependency graph reference entry kind value.

variableCancelWorkbookFormulaReferencePickCommand
CancelWorkbookFormulaReferencePickCommand: WorkbookCommandDefinition<void, void>

Cancels a pending cross-sheet reference pick.

variableCaptureWorkbookFormulaDraftCommand
CaptureWorkbookFormulaDraftCommand: WorkbookCommandDefinition<void, void>

Retains the source formula draft before activating another sheet.

variablePickWorkbookFormulaReferenceCommand
PickWorkbookFormulaReferenceCommand: WorkbookCommandDefinition<{ end: Point; start: Point }, void>

Applies a picked range to the retained formula draft.

variableRestoreWorkbookFormulaDraftCommand
RestoreWorkbookFormulaDraftCommand: WorkbookCommandDefinition<void, void>

Restores the retained draft when the source sheet becomes active again.

functionisWorkbookFormulaBrokenReference
isWorkbookFormulaBrokenReference(reference: WorkbookFormulaGraphReference): reference

Reports whether one workbook formula graph reference is a retained broken reference.

Recalculate formulas

classWorkbookFormulaDependencyGraph

Workbook-qualified dependency graph owned by WorkbookFormulaPlugin.

constructorWorkbookFormulaDependencyGraph(): WorkbookFormulaDependencyGraph
memberdirtySize
dirtySize: unknown
memberresultSize
resultSize: unknown
membersize
size: unknown
methodclear(): void

Removes every formula and dependency edge.

methodgetBrokenReferences(formulaCell: WorkbookCellReference): readonly WorkbookFormulaBrokenReference[]

Returns broken references owned by one formula cell.

methodgetDependencies(formulaCell: WorkbookCellReference): readonly WorkbookFormulaGraphReference[]

Returns workbook-qualified dependencies owned by one formula cell.

methodgetDependents(cell: WorkbookCellReference): readonly WorkbookCellReference[]

Returns formula cells that currently depend on the given workbook cell.

methodgetDirtyFormulaCells(): readonly WorkbookCellReference[]

Returns every workbook-qualified formula cell currently marked dirty.

methodgetFormulaCells(): readonly WorkbookCellReference[]

Returns every workbook-qualified formula cell currently registered.

methodgetFormulaResult(formulaCell: WorkbookCellReference): FormulaValue | undefined

Returns a derived workbook formula result, or #REF! when references are broken.

methodhasBrokenReferences(formulaCell: WorkbookCellReference): boolean

Reports whether one formula cell currently contains broken references.

methodhasFormulaCell(formulaCell: WorkbookCellReference): boolean

Reports whether one workbook-qualified cell is registered as a formula cell.

methodisDirty(formulaCell: WorkbookCellReference): boolean

Reports whether one workbook formula cell needs recalculation.

methodmarkDirty(changedCells: readonly WorkbookCellReference[]): readonly WorkbookCellReference[]

Marks formulas that depend on changed workbook cells as dirty, including transitive formula chains.

methodmarkFormulaCellsDirty(formulaCells: readonly WorkbookCellReference[]): void

Marks formula cells themselves dirty after an external evaluation service changes.

methodremoveFormulaCell(formulaCell: WorkbookCellReference): void

Removes one formula cell and every reverse edge it owns.

methodremoveSheet(sheetId: string): void

Removes formulas on a deleted sheet and marks references to that sheet as broken.

methodsetFormulaResult(formulaCell: WorkbookCellReference, result: FormulaValue): void

Stores a derived workbook formula result and marks the formula clean.

methodupdateFormulaCell(formulaCell: WorkbookCellReference, dependencies: readonly WorkbookFormulaReference[]): void

Registers dependencies for one workbook-qualified formula cell.

methodupdateFormulaCellReferences(formulaCell: WorkbookCellReference, dependencies: readonly WorkbookFormulaGraphReference[]): void

Registers graph references for one formula cell, including broken references.

classWorkbookFormulaEvaluationRuntime

Runtime adapter that evaluates workbook formulas through the shared formula engine.

constructorWorkbookFormulaEvaluationRuntime(input?: { contextServices?: (): { dateTimeLocale?: FormulaDateTimeLocale; externalServices?: FormulaExternalServiceReader; languageService?: FormulaLanguageService; phoneticReader?: FormulaPhoneticReader; textLocale?: FormulaTextLocale; xmlXPath?: XmlXPathEvaluator }; evaluator?: IFormulaEvaluator; parser?: IFormulaParser }): WorkbookFormulaEvaluationRuntime

Creates a workbook formula evaluation runtime.

methodcompileFormula(formulaCell: WorkbookCellReference, source: string, workbookState: WorkbookDocumentState<SheetDocumentState>): CompiledWorkbookFormula

Compiles formula text into native AST plus stable workbook dependencies.

methodformatFormulaSource(compiled: CompiledWorkbookFormula, workbookState: WorkbookDocumentState<SheetDocumentState>): string

Formats workbook formula source with current sheet names while keeping stable sheet-id bindings.

methodrecalculateDirty(input: { formulas: ReadonlyMap<string, CompiledWorkbookFormula>; graph: WorkbookFormulaDependencyGraph; runtime: WorkbookPluginRuntime }): WorkbookFormulaRecalculationResult

Recalculates dirty formula cells whose dependencies are currently clean.

methodshiftCompiledFormulaReferences(input: { changedSheetId: string; changes: readonly StructureChange[]; compiled: CompiledWorkbookFormula; formulaCell: WorkbookCellReference }): WorkbookFormulaCompiledReferenceShiftResult

Shifts compiled formula references after a row or column structure change.

classWorkbookFormulaPlugin
class WorkbookFormulaPlugin extends WorkbookPlugin

Workbook-level formula coordinator and cross-sheet dependency owner.

constructorWorkbookFormulaPlugin(): WorkbookFormulaPlugin
propertyreadonly symbol: typeof symbolstatic
methodassertSheetRangeMoveSupported(sheetId: string, context: SheetRangeMoveContext): void

Rejects moves requiring reference edits outside the current Sheet transaction boundary.

methodassertSheetStructureMoveSupported(sheetId: string, context: SheetStructureMoveContext): void

Rejects qualified reference rewrites that cannot be persisted by a single Sheet transaction.

methodformatReference(reference: ParsedWorkbookFormulaReference): string

Formats a stable workbook reference with the latest workbook sheet name.

methodgetDependencyGraph(): WorkbookFormulaDependencyGraphReader

Returns the workbook-qualified dependency graph owned by this plugin instance.

methodgetFormulaResult(formulaCell: ParsedWorkbookFormulaReference): FormulaValue | undefined

Returns a workbook-level formula result when the skeleton can determine one.

methodgetSheetFormulaResult(sheetId: string, row: number, col: number): FormulaValue | undefined

Returns a result only for formula cells that contain workbook-qualified references.

methodgetSheetFormulaSource(sheetId: string, row: number, col: number): string | undefined

Returns display-ready formula source for workbook formulas on one mounted sheet.

methodgetSheetPlugins(context: WorkbookCompanionSheetPluginContext): readonly SheetPluginImplementation<SheetPlugin<unknown>>[]

Contributes the active-sheet companion that forwards committed Sheet transactions.

methodgetSheetServices(context: WorkbookCompanionSheetPluginContext): readonly { token: symbol; value: unknown }[]

Shares the workbook function registry with each mounted Sheet editor.

methodinitialize(context: WorkbookPluginContext): (): void

Starts observing workbook state for this WorkbookEditor instance.

methodobserveSheetTransaction(sheetId: string, transaction: Transaction): void

Receives a committed Sheet transaction from the active SheetEditor companion.

methodparseReference(reference: string): ParsedWorkbookFormulaReference

Parses a displayed cross-sheet reference against the latest workbook sheet names.

methodrecalculateDirtyFormulas(): RecalculateWorkbookFormulasCommandResult

Recalculates workbook formulas currently marked dirty.

methodregisterCommands(commands: WorkbookCommandBus): void

Registers workbook formula commands.

methodregisterObservations(observations: ObservationRegistry): void

Registers workbook formula diagnostic observations.

methodremoveFormulaCell(formulaCell: WorkbookCellReference): void

Removes workbook formula bookkeeping for one formula cell.

methodsetFormulaCellFormula(formulaCell: ParsedWorkbookFormulaReference, formulaSource: string): void

Registers and compiles one workbook formula source.

methodsetFormulaResult(formulaCell: ParsedWorkbookFormulaReference, result: FormulaValue): void

Stores a derived workbook formula result and marks the formula clean.

methodupdateFormulaCell(formulaCell: ParsedWorkbookFormulaReference, dependencies: readonly WorkbookFormulaReference[]): void

Registers workbook-qualified dependencies for one formula cell.

methodregisterServices(__namedParameters: WorkbookPluginServiceContext): voidstatic

Registers one workbook-owned formula runtime shared by mounted Sheet editors.

Inherited members 7

Inherited from WorkbookPlugin.

interfaceCompiledWorkbookFormula

Compiled workbook formula with native workbook-reference AST nodes.

propertyreadonly ast: FormulaAST

Parsed AST consumed by the configured formula evaluator.

propertyreadonly brokenReferences: readonly WorkbookFormulaBrokenReference[]

References that are already known to be invalid.

propertyreadonly dependencies: readonly WorkbookFormulaReference[]

Stable workbook dependencies extracted from the AST.

propertyreadonly hasExpandedObjects?: boolean
propertyreadonly hasWorkbookReferences: boolean

Whether the formula contains at least one workbook-qualified reference.

propertyreadonly sheetBindings: ReadonlyMap<string, string>

Formula-text sheet names bound to stable sheet ids at compile time.

propertyreadonly source: string

Original user-authored formula source.

interfaceRecalculateWorkbookFormulasCommandResult

Result returned after recalculating workbook-level dirty formulas.

propertyreadonly recalculatedCells: readonly WorkbookCellReference[]

Formula cells recalculated by this command.

propertyreadonly remainingDirtyCells: readonly WorkbookCellReference[]

Formula cells still dirty after the command completes.

interfaceWorkbookFormulaRecalculationResult

Result returned after recalculating dirty workbook formulas.

propertyreadonly recalculatedCells: readonly WorkbookCellReference[]

Formula cells that were evaluated and stored in the workbook result cache.

propertyreadonly remainingDirtyCells: readonly WorkbookCellReference[]

Dirty formula cells that could not be evaluated in this pass.

interfaceWorkbookFormulaSheetTransactionEvent

Local event emitted when a companion Sheet plugin observes a committed transaction.

propertyreadonly sheetId: string

Workbook sheet id that owned the active SheetEditor when the transaction committed.

propertyreadonly transaction: Transaction

Committed Sheet transaction observed from the active SheetEditor.

interfaceWorkbookFormulaStateSnapshot

State snapshot for the workbook-scoped formula runtime.

propertyreadonly activeSheetId: string | null

Active sheet id in the observed workbook state.

propertyreadonly cachedFormulaResultCount: number

Number of derived workbook formula results currently cached.

propertyreadonly dirtyFormulaCellCount: number

Number of workbook formula cells waiting for recalculation.

propertyreadonly formulaCellCount: number

Number of formula cells currently indexed in the workbook dependency graph.

propertyreadonly observedSheetTransactionCount: number

Number of active-sheet transactions observed by companion Sheet plugins.

propertyreadonly sheetIds: readonly string[]

Sheet ids currently present in the observed workbook state.

propertyreadonly workbookId: string | null

Workbook id currently observed by WorkbookFormulaPlugin.

variableRecalculateWorkbookFormulasCommand
RecalculateWorkbookFormulasCommand: WorkbookCommandDefinition<void, RecalculateWorkbookFormulasCommandResult>

Recalculates workbook-level formulas marked dirty by cross-sheet changes.

variableWorkbookFormulaBindingsMetadataKey
WorkbookFormulaBindingsMetadataKey: "searsuite.workbook.formulaBindings"

Runtime metadata holding bindings restored from a durable workbook file.

variableWorkbookFormulaSheetTransactionObservation
WorkbookFormulaSheetTransactionObservation: EventObservationDefinition<WorkbookFormulaSheetTransactionEvent>

WorkbookFormulaPlugin event stream for committed active-sheet transactions.

variableWorkbookFormulaStateObservation
WorkbookFormulaStateObservation: StateObservationDefinition<WorkbookFormulaStateSnapshot>

WorkbookFormulaPlugin state exposed to diagnostic hosts.

History and collaboration

classWorkbookHistoryPlugin
class WorkbookHistoryPlugin extends WorkbookPlugin

Built-in contributor for workbook structure and declared multi-sheet content history.

constructorWorkbookHistoryPlugin(): WorkbookHistoryPlugin
propertyreadonly symbol: typeof symbolstatic
methodgetContentMoveStatus(): WorkbookHistoryStatus

Exposes only multi-sheet content entries to the mounted Sheet history adapter.

methodgetStatus(): WorkbookHistoryStatus
methodinitialize(context: WorkbookPluginContext): void
methodonTransactionCommitted(event: WorkbookTransactionCommittedEvent): void
methodonWorkbookDestroy(): void
methodregisterCommands(commands: WorkbookCommandBus): void

Registers every stable command id owned by this plugin.

methodregisterObservations(observations: ObservationRegistry): void

Registers every typed state and event observation source owned by this plugin.

methodregisterSessionState(registry: SessionStateRegistry): void

Registers every local session value owned by this plugin.

methodsubscribe(listener: (status: WorkbookHistoryStatus): void): (): void
Inherited members 7

Inherited from WorkbookPlugin.

interfaceWorkbookCollaborationSession

Read-only host facade for Workbook-owned collaboration channels.

methodgetConnectedSheetIds(): readonly string[]
methodgetSheetStatus(sheetId: string): CollaborationStatus | undefined
interfaceWorkbookCollaborationTransportFactory
interface WorkbookCollaborationTransportFactory WorkbookCollaborationTransportFactory: { symbol: symbol }

Creates one transport per Workbook-owned Sheet collaboration channel.

methodcreate(): CollabTransport
interfaceWorkbookHistoryEntry

Workbook transaction snapshots retained independently from SheetEditor history.

propertyreadonly after: WorkbookTransactionState
propertyreadonly before: WorkbookTransactionState
propertyreadonly contentSheetIds?: readonly string[]

Sheet content restored with this entry; other sheet content stays current.

interfaceWorkbookHistoryStatus

Current workbook structure undo/redo availability.

propertyreadonly canRedo: boolean
propertyreadonly canUndo: boolean
typeWorkbookHistoryAction
type WorkbookHistoryAction = typeof WorkbookHistoryAction[keyof typeof WorkbookHistoryAction] WorkbookHistoryAction: { Ignore: "ignore"; Record: "record"; Redo: "redo"; Undo: "undo" }

History behavior attached to one workbook transaction.

variableConnectWorkbookCollaborationCommand
ConnectWorkbookCollaborationCommand: WorkbookCommandDefinition<{ options: CollaborationConnectOptions; sheetId: string }, Promise<void>>

Connects the long-lived collaboration channel for one Workbook sheet.

variableDisconnectWorkbookCollaborationCommand
DisconnectWorkbookCollaborationCommand: WorkbookCommandDefinition<{ sheetId: string }, void>

Disconnects one Workbook-owned collaboration channel.

variableRedoWorkbookCommand
RedoWorkbookCommand: WorkbookCommandDefinition<void, void>

Re-applies the most recently reverted workbook structure mutation.

variableUndoWorkbookCommand
UndoWorkbookCommand: WorkbookCommandDefinition<void, void>

Reverts the most recent committed workbook structure mutation.

variableWorkbookCollaborationCapability
WorkbookCollaborationCapability: WorkbookRuntimeCapabilityToken<WorkbookCollaborationSession>
variableWorkbookHistorySessionStateDefinition
WorkbookHistorySessionStateDefinition: SessionStateDefinition<WorkbookHistorySessionState>

Session identity owned by workbook structural history.

variableWorkbookHistoryStatusObservation
WorkbookHistoryStatusObservation: StateObservationDefinition<WorkbookHistoryStatus>

Typed workbook structural history status.

Commands and transactions

Workbook commands stage structural changes, and WorkbookTransaction commits them as one state transition.

classWorkbookCommandBus

Editor-scoped command bus for workbook-level sheet-list actions.

constructorWorkbookCommandBus(options?: WorkbookCommandBusOptions): WorkbookCommandBus

Creates an empty workbook command bus.

propertyreadonly symbol: typeof symbolstatic

DI token for the command bus owned by one WorkbookEditor.

methoddestroy(): void

Clears listeners and command registrations during teardown.

methodenforceRegistrationBoundary(assertWrite: (): void): void

Closes setup-time command registration after the editor is assembled.

methodgetRegisteredCommandIds(): readonly string[]

Returns a stable snapshot of all workbook command ids exposed by this editor.

methodgetRegisteredCommands(): readonly WorkbookCommandDefinition<unknown, unknown>[]

Returns the typed definitions registered on this workbook editor instance.

methodhas(definition: string | WorkbookCommandDefinition<unknown, unknown>): boolean

Returns whether this workbook editor currently exposes a command id.

methodisExecuting(): boolean

Whether this WorkbookEditor is currently dispatching a command.

methodregister<Definition>(definition: Definition, handler: WorkbookCommandHandler<Definition>): (): void

Registers one workbook command handler. The returned disposer removes the handler and is primarily useful for extension commands.

methodrun<Definition>(definition: Definition, input: WorkbookCommandInput<Definition>): WorkbookCommandDefinitionResult<Definition>

Executes a registered workbook command through its typed definition.

methodrunWithoutMutationAuthority<Value>(callback: (): Value): Value

Invokes external observers without inheriting this editor's command write authority.

methodsubscribe(listener: WorkbookCommandListener): (): void

Subscribes to command lifecycle events and returns an unsubscribe function.

classWorkbookRangeMoveError
class WorkbookRangeMoveError extends SearError

Prevents a same-sheet move from leaving workbook-qualified references stale.

constructorWorkbookRangeMoveError(sheetId: string): WorkbookRangeMoveError
propertyreadonly code: "WORKBOOK_RANGE_MOVE_QUALIFIED_REFERENCE"

Stable machine-readable identifier for this error category.

Inherited members 9

Inherited from SearError.

classWorkbookRuntimeExtensionRegistry
class WorkbookRuntimeExtensionRegistry extends RuntimeCapabilityRegistry

Editor-local capability registry exposed through WorkbookEditor.capabilities.

constructorWorkbookRuntimeExtensionRegistry(): WorkbookRuntimeExtensionRegistry
propertyreadonly symbol: typeof symbolstatic
Inherited members 7

Inherited from RuntimeCapabilityRegistry.

classWorkbookStructureMoveError
class WorkbookStructureMoveError extends SearError

Prevents an axis move from leaving qualified reference sources outside its transaction stale.

constructorWorkbookStructureMoveError(sheetId: string): WorkbookStructureMoveError
propertyreadonly code: "WORKBOOK_STRUCTURE_MOVE_QUALIFIED_REFERENCE"

Stable machine-readable identifier for this error category.

Inherited members 9

Inherited from SearError.

classWorkbookTransaction

Ordered, atomic workbook mutation assembled inside a typed command handler. Reducers stage state only; the WorkbookEditor owns validation and commit.

constructorWorkbookTransaction(id: string, historyAction?: WorkbookHistoryAction, contentSheetIds?: readonly string[]): WorkbookTransaction
contentSheetIds

Sheet states whose before/after snapshots belong to this history entry.

propertyreadonly contentSheetIds: readonly string[]
propertyreadonly historyAction: WorkbookHistoryAction
propertyreadonly id: string
methodaddStep(name: string, reduce: WorkbookTransactionReducer): this

Adds one pure reducer to the staged transaction.

methodgetStepNames(): readonly string[]

Returns stable step names for diagnostics and tests.

interfaceWorkbookCommandBusOptions

Optional diagnostics hooks used by the workbook command bus.

propertyreadonly warn?: (message: string, ...details: unknown[]): void

Receives non-fatal command-boundary diagnostics.

interfaceWorkbookCommandDefinition
interface WorkbookCommandDefinition<Input, Result>

Stable workbook command identifier carrying its input and result contract.

propertyreadonly [workbookCommandInputType]: Input

Phantom field that preserves the command input type for callers.

propertyreadonly [workbookCommandResultType]: Result

Phantom field that preserves the command result type for callers.

propertyreadonly id: string

Globally stable command id owned by the workbook assembly package.

interfaceWorkbookCommandEvent

Lifecycle event emitted by the workbook command bus for diagnostics and host UI.

propertyreadonly error?: unknown

Original thrown value when the command failed.

propertyreadonly id: string

Stable command id being executed.

propertyreadonly phase: CommandExecutionPhase

Execution phase represented by this event.

interfaceWorkbookCommandResult

Result returned by workbook-level sheet-list commands.

propertyreadonly activeSheetEditorChanged: boolean

Whether the live active SheetEditor instance was replaced.

propertyreadonly documentState: WorkbookDocumentState<SheetDocumentState>

Latest workbook state after the command.

interfaceWorkbookTransactionCommittedEvent

Immutable event delivered after a complete workbook transaction commits.

propertyreadonly after: WorkbookTransactionState
propertyreadonly before: WorkbookTransactionState
propertyreadonly transaction: WorkbookTransaction
interfaceWorkbookTransactionState

Detached state staged by workbook transaction reducers.

propertyreadonly activeSheetId: string
propertyreadonly documentState: WorkbookDocumentState<SheetDocumentState>
typeWorkbookCommandDefinitionResult
type WorkbookCommandDefinitionResult = conditional

Extracts the result contract from a typed workbook command definition.

typeWorkbookCommandHandler
type WorkbookCommandHandler = (input: WorkbookCommandInput<Definition>): WorkbookCommandDefinitionResult<Definition>

Factory installed by the workbook assembly to run one typed command.

typeWorkbookCommandInput
type WorkbookCommandInput = conditional

Extracts the input contract from a typed workbook command definition.

typeWorkbookCommandListener
type WorkbookCommandListener = (event: WorkbookCommandEvent): void

Observer invoked when workbook command execution starts, completes or fails.

typeWorkbookTransactionReducer
type WorkbookTransactionReducer = (state: WorkbookTransactionState): WorkbookTransactionState

One pure staged workbook mutation.

functiondefineWorkbookCommand
defineWorkbookCommand<Input, Result>(id: string): WorkbookCommandDefinition<Input, Result>

Creates an immutable workbook-owned command contract.

functionregisterDefaultWorkbookCommands
registerDefaultWorkbookCommands(commands: WorkbookCommandBus, controller: WorkbookCommandController): void

Registers the built-in workbook commands on one workbook command bus.

variableCommandExecutionPhase
CommandExecutionPhase: { Completed: "completed"; Failed: "failed"; Started: "started" }

Stable lifecycle phases emitted by Sheet, Doc, and Workbook command buses.