@searsuite/sear-plugin-formula

Run evaluation

SheetFormulaPlugin owns formula source in the Sheet and reacts to committed cell and structure operations. It parses changed formulas, updates dependencies, and asks RecalcScheduler to evaluate affected cells. Calculated values live in FormulaResultStore and are exposed through result providers; they are derived data, separate from the formula text stored in the document.

The parser, evaluator, graph, and built-in functions are described in the formula-engine packages. Start here when integrating formula behavior into a Sheet editor; start with the engine contracts when implementing a new evaluator or function.

classSheetFormulaPlugin

class SheetFormulaPlugin extends Plugin<SearCoreSheet, CellProperties, FormulaPluginState>, IFormulaResultProvider, IFormulaSourceProvider, IFormulaStatusProvider

Owns formula source, dependency tracking, recalculation, and result projection.

constructor

SheetFormulaPlugin(parser: IFormulaParser, graph: IDependencyGraph, aggCache: IAggregationCache, resultStore: FormulaResultStore, scheduler: RecalcScheduler, refShifter: FormulaRefShifter, trace: FormulaCalculationTraceBus, dataEngine?: DataEngine, platform?: Platform, results?: IFormulaResultProvider, resultProviders?: FormulaResultProviderRegistry, richResultProviders?: FormulaRichResultProviderRegistry, sourceProviders?: FormulaSourceProviderRegistry, functions?: IFunctionRegistry, externalServices?: IFormulaExternalServiceProvider, textServices?: IFormulaTextServiceProvider): SheetFormulaPlugin

propertyinterestedIn: MatrixOTActionName[]

Operation types listened to by this plugin:

uc: UpdateCell
ri: RowInsert
rd: RowDelete
ci: ColInsert
cd: ColDelete

propertyreadonly pluginKey: PluginKeystatic

Stable plugin key for SheetFormulaPlugin.

propertyreadonly symbol: typeof symbolstatic

DI token for resolving SheetFormulaPlugin.

methodapply(_pluginState: null, transaction: Transaction): null

Rejects unsupported structure operations before the owning transaction commits. Derived ASTs are not staged as plugin state.

methodenforceProviderCommandBoundary(commands: SheetCommandBus, workbookOwnership?: FormulaRegistryOwnership): void

Seals provider registration once every configured Sheet plugin has started.

method

forEachFormulaResultInRange(startRow: number, startColumn: number, endRow: number, endColumn: number, visit: (row: number, column: number): void): void

Exposes derived spill coordinates to sparse range consumers.

methodgetFormulaCellStatus(row: number, col: number): FormulaCellStatus

IFormulaStatusProvider implementation used by hosts and plugins to inspect formula source, result, dirty state, and dependency edges without touching plugin-owned caches directly.

methodgetFormulaResult(row: number, col: number): FormulaValue | undefined

IFormulaResultProvider implementation used by rendering to read formula results.

Returns FormulaValue from resultStore, or undefined when it has not been calculated yet. The rendering layer (FormulaCell) converts it to display text.

methodgetFormulaSource(row: number, col: number): string | undefined

IFormulaSourceProvider implementation used by editors to read persisted formula text.

methodgetPluginConfig(): unknown

Returns the plugin config.

methodonInitialDataCell(_searCore: SearCoreSheet, value: unknown, row: number, col: number): void

Receives cells from shared startup scanning and builds AST/dependency indexes for existing formula cells.

Initial data such as content.json is injected directly into SheetDataPlugin and does not pass through the command pipeline -> apply, so formula-derived indexes must be built here.

methodonInitialDataComplete(_searCore: SearCoreSheet): void

Starts one recalculation after dependencies for all initial formulas have been registered.

methodonTransactionCommitted(transaction: Transaction): void

Rebuilds derived indexes after the owning document transaction commits.

transaction: Successfully committed transaction.

methodregisterCommands(commands: SheetCommandBus): void

Registers formula host commands.

commands: Command bus owned by one editor instance.

methodregisterConfig(): { config: ConfigUnit<FormulaReferenceHighlightConfig>; key: PluginKey }[]

Registers default configuration values owned by this plugin.

methodregisterObservations(observations: ObservationRegistry): void

Registers formula calculation trace as an editor-local host observation.

methodregisterRangeMoves(registry: SheetRangeMoveRegistry): void

Contributes formula identity updates to the same atomic cell-move plan.

methodregisterRangeReorders(registry: SheetRangeReorderRegistry): void

methodregisterState(): { dataEngine: { enabled: boolean }; key: PluginKey; state: null }

Formula indexes are editor-local and do not enter Sheet document views.

methodregisterStructureMoves(registry: SheetStructureMoveRegistry): void

Plans persisted reference rewrites for complete row and column reordering.

methodrender(): Node<CellProperties>[]

Render method; the formula plugin does not render nodes directly.

Formula cells are rendered by FormulaCell through render-registry registration. This plugin owns data updates, not visual presentation.

Inherited members 24

Inherited from Plugin.

classRecalcScheduler

Schedules dependency-aware formula recalculation with visible-cell priority.

constructor

RecalcScheduler(graph: IDependencyGraph, evaluator: IFormulaEvaluator, resultStore: FormulaResultStore, aggCache: IAggregationCache, dataSource: FormulaSchedulerDataSource, platform: Platform, renderInvalidator: FormulaRenderInvalidator, trace: FormulaCalculationTraceBus, functionRegistry?: IFunctionRegistry, iterationSettings?: IFormulaIterationSettingsProvider): RecalcScheduler

propertyreadonly symbol: typeof symbolstatic

DI token for resolving RecalcScheduler.

methodbindAstCache(cache: ReadonlyMap<number, FormulaAST>): void

Binds the formula owner's cache during plugin setup.

methodbindCommandBus(commands: SheetCommandBus): void

Binds asynchronous formula work to the owning editor's command bus.

methodbindTeardownToken(token: object): void

Gives the owning editor lifecycle exclusive authority to dispose the mounted scheduler.

methoddiscardPendingWork(): void

Discards pending formula batches when committed formula inputs are replaced.

methoddispose(token?: object): void

Releases scheduler-owned subscriptions.

methodgetFormulaKeys(): IterableIterator<number>

Iterates formula coordinates without exposing the cache for mutation.

methodmarkDirty(changedKeys: number[]): void

Triggers recalculation.

Performs only two actions:

Mark dirty formulas, propagated by BFS without sorting.
Start the async scheduling loop without blocking the current frame.

methodmarkFunctionsDirty(functionNames: readonly string[]): void

Recalculates formulas that contain any of the supplied function names.

methodprocessScheduledBatch(): void

Runs one budgeted batch inside the formula owner's command.

methodrecalculateVolatile(): void

Starts an explicit recalculation epoch for every formula containing a volatile call.

methodresumePendingWork(): void

Resumes pending work inside a viewport or external-service command.

methodwaitForIdle(): Promise<void>

Resolves when the scheduler has no running or pending formula work.

classFormulaResultStore

Stores calculated formula results independently from persisted formula source.

constructorFormulaResultStore(valueConverters: CellFormulaValueConverterRegistry): FormulaResultStore

propertyreadonly symbol: typeof symbolstatic

DI token for resolving FormulaResultStore.

methodcellToFormulaValue(row: number, col: number, cell: CellMatrixElement | null | undefined): FormulaValue

Converts a CellMatrixElement to a FormulaValue.

Used when evaluators read cell data:

formula cells: read the local calculated result from this store; derived and unsynced.
richtext/string cells: return text values, converting numeric strings to numbers.
null/undefined: return 0 for empty cells.

Called by both SheetFormulaPlugin.apply for aggCache delta calculation and RecalcScheduler.createEvalContext, so it lives on the store to avoid duplicated logic or callback plumbing.

methodclear(): void

Clears state owned by FormulaResultStore.

methoddelete(key: number): void

Removes the calculated result for one formula cell.

methodenforceCommandBoundary(isCommandExecuting: (): boolean): void

Closes direct result writes after the owning Sheet has started.

method

forEachSpillInRange(startRow: number, startColumn: number, endRow: number, endColumn: number, visit: (row: number, column: number): void): void

Visits projected spill coordinates in a range; formula anchors live in the Sheet data matrix.

methodget(key: number): FormulaValue | undefined

methodgetAt(row: number, col: number): FormulaValue | undefined

Reads an anchor or projected spill value at any sheet coordinate.

methodhas(key: number): boolean

Returns whether value exists.

methodset(key: number, value: FormulaValue): void

Updates the value.

method

setFormulaResult(key: number, value: FormulaValue, context: { isCellInBounds: unknown; isCellOccupied?: unknown }): number[]

Stores a formula result and projects a rectangular array into derived spill cells.

interfaceFormulaRegistryOwnership

interface FormulaRegistryOwnership FormulaRegistryOwnership: unknown

Marks formula registries borrowed from a Workbook owner by a mounted Sheet.

propertyreadonly externalServices: boolean

propertyreadonly functions: boolean

propertyreadonly textServices: boolean

variablesymbol

symbol: typeof symbol

interfaceFormulaSchedulerDataSource

interface FormulaSchedulerDataSource FormulaSchedulerDataSource: unknown

Narrow data-source contract used by RecalcScheduler.

Implementations adapt host-owned sheet data, viewport state, and dimension services into formula-engine concepts. The scheduler depends only on this contract, not on render, scroll, or DataEngine packages.

methodcreateEvalContext(resultStore: FormulaResultStore): EvalContext

Builds the latest evaluation context for a recalculation batch.

ReturnsEvalContext for the current committed sheet snapshot.

resultStore: Per-client derived formula result store used when formula cells reference formula cells.

methodgetViewportFormulaKeys(formulaKeys: Iterable<number>): Set<number>

Selects formula keys that are currently visible and should be evaluated first.

ReturnsFormula keys inside the current visible viewport.

formulaKeys: Formula AST keys known to the scheduler.

methodonExternalServiceInvalidated(handler: FormulaExternalServiceInvalidationHandler): (): void

Subscribes to host-service cache changes that require selected functions to be evaluated again.

methodonViewportChanged(handler: FormulaViewportChangeHandler): (): void

Subscribes to viewport changes that should wake pending formula recalculation.

ReturnsDisposer for the subscription.

handler: Callback invoked after viewport-priority inputs change.

variablesymbol

symbol: typeof symbol

DI token for resolving FormulaSchedulerDataSource.

typeFormulaPluginState

type FormulaPluginState = null

Formula owns no document state; its ASTs and results are derived caches.

variablesheetFormulaPluginKey

sheetFormulaPluginKey: PluginKey

Shared identity for formula plugin state and configuration.

Results and status

interfaceFormulaCellStatusCommandInput

Input for querying one cell's formula status through the host command bus.

propertyreadonly col: number

Column index (0-based).

propertyreadonly row: number

Row index (0-based).

interfaceFormulaCellStatusCommandResult

interface FormulaCellStatusCommandResult extends SheetCommandResult

Command result for a formula status query.

The pipeline is intentionally empty: formula status reads must not mutate OT state, request rendering, or produce local effects.

propertyreadonly status: FormulaCellStatus

Formula status snapshot returned by the formula status provider.

Inherited members 4

Inherited from SheetCommandResult.

interfaceFormulaDependencyCellRef

Product-facing cell coordinate plus A1 reference label.

propertyreadonly col: number

Column index (0-based).

propertyreadonly ref: string

A1 notation for display in product UI.

propertyreadonly row: number

Row index (0-based).

interfaceFormulaDependencyStatus

Product-facing formula dependency status for one queried cell.

propertyreadonly cell: FormulaDependencyCellRef

Queried cell with display label.

propertyreadonly dependents: readonly FormulaDependencyCellRef[]

Direct formula cells that depend on the queried cell.

propertyreadonly precedents: readonly FormulaDependencyReference[]

Direct precedent references used by the formula in the queried cell.

propertyreadonly status: FormulaCellStatus

Underlying formula status snapshot for consumers that need result/error/dirty details.

propertyreadonly transitiveDependents: readonly FormulaDependencyCellRef[]

Transitive dependent formula cells, only populated when requested.

propertyreadonly transitivePrecedents: readonly FormulaDependencyCellRef[]

Transitive precedent cells, only populated when requested.

interfaceFormulaDependencyStatusCommandInput

Input for querying product-facing formula dependency status.

propertyreadonly col: number

Column index (0-based).

propertyreadonly includeTransitive?: boolean

Whether to include transitive dependency/dependent cells beyond direct edges.

propertyreadonly maxDepth?: number

Maximum traversal depth used when includeTransitive is true. Defaults to 8.

propertyreadonly row: number

Row index (0-based).

interfaceFormulaDependencyStatusCommandResult

interface FormulaDependencyStatusCommandResult extends SheetCommandResult

Command result for a product-facing formula dependency query.

The pipeline is intentionally empty: dependency reads must not mutate OT state, request rendering, or produce local effects.

propertyreadonly dependencyStatus: FormulaDependencyStatus

Product-facing dependency snapshot for the queried cell.

Inherited members 4

Inherited from SheetCommandResult.

interfaceFormulaIdleCommandResult

interface FormulaIdleCommandResult extends SheetCommandResult

Result returned when waiting for one editor instance's formula scheduler.

propertyreadonly idle: Promise<void>

Promise resolved when the formula scheduler becomes idle.

Inherited members 4

Inherited from SheetCommandResult.

interfaceFormulaIdleProvider

Provider contract used by the deterministic formula-idle command.

methodwaitForIdle(): Promise<void>

Resolves after all currently scheduled formula work has completed.

variableFormulaCalculationTraceObservation

FormulaCalculationTraceObservation: EventObservationDefinition<FormulaCalculationTraceEvent>

Editor-local formula calculation trace events exposed to diagnostic hosts.

variableGetFormulaCellStatusCommand

GetFormulaCellStatusCommand: SheetCommandDefinition<FormulaCellStatusCommandInput, FormulaCellStatusCommandResult>

Host command that reads one cell's formula status.

variableGetFormulaDependencyStatusCommand

GetFormulaDependencyStatusCommand: SheetCommandDefinition<FormulaDependencyStatusCommandInput, FormulaDependencyStatusCommandResult>

Host command that reads product-facing formula dependency status.

variableWaitForFormulaIdleCommand

WaitForFormulaIdleCommand: SheetCommandDefinition<void, FormulaIdleCommandResult>

Host command that exposes deterministic formula-idle synchronization.

functionlockFormulaResultValue

lockFormulaResultValue(value: FormulaValue): void

Locks a calculated value once when it enters the editor-local result cache.

functionregisterFormulaStatusCommands

registerFormulaStatusCommands(commands: SheetCommandBus, provider: IFormulaStatusProvider, idleProvider?: FormulaIdleProvider): void

Registers formula status query commands.

commands: Command bus for one editor instance.
provider: Formula status provider bound to the same editor instance.

functionwaitForFormulaIdle

waitForFormulaIdle(commands: SheetCommandBus): Promise<void>

Waits deterministically for one editor's formula scheduler to become idle.

Providers and registries

classCellFormulaValueConverterRegistry

Cell type → formula semantic value registry.

Rendering and formula coercion intentionally use separate registries: a custom cell type can define its calculation semantics without coupling to a Canvas renderer.

constructorCellFormulaValueConverterRegistry(platform: Platform): CellFormulaValueConverterRegistry

Creates a registry with the built-in cell-to-formula semantics.

platform: Platform adapter used for diagnostics when unknown cell types fall back to text.

propertyreadonly symbol: typeof symbolstatic

DI token for resolving CellFormulaValueConverterRegistry.

methodregister(converter: CellFormulaValueConverter): (): void

Registers or overrides formula semantics for one cell type.

ReturnsDisposer that restores the previous converter only if this registration is still active.

converter: Converter owned by a built-in package or third-party plugin.

methodtoFormulaValue(cell: CellMatrixElement): FormulaValue

Converts a persisted sheet cell into the formula value contract.

ReturnsFormula value, including canonical propagated formula errors or #VALUE! for malformed error payloads.

cell: Matrix cell to convert; the method never writes back to the sheet matrix.

classFormulaResultProviderRegistry

class FormulaResultProviderRegistry extends IFormulaResultProvider

Instance-local result provider registry exposed as the renderer's formula result reader.

constructorFormulaResultProviderRegistry(): FormulaResultProviderRegistry

propertyreadonly symbol: typeof symbolstatic

DI token for resolving the registry owned by one SheetEditor instance.

methodenforceCommandBoundary(isExecuting: (): boolean, remove: (id: number): void): void

Binds post-assembly registration and disposal to the owning command bus.

method

forEachFormulaResultInRange(startRow: number, startColumn: number, endRow: number, endColumn: number, visit: (row: number, column: number): void): void

Visits derived result coordinates published by registered providers, once per position.

methodgetFormulaResult(row: number, col: number): FormulaValue | undefined

Reads the first defined result supplied by registered providers.

methodregister(registration: FormulaResultProviderRegistration): (): void

Registers one formula result provider and returns an idempotent disposer.

methodunregister(id: number): void

Removes one provider inside the formula owner's unregister command.

classFormulaRichResultProviderRegistry

class FormulaRichResultProviderRegistry extends IFormulaRichResultProvider

Instance-local provider registry for formula hyperlinks, images, and future rich results.

constructorFormulaRichResultProviderRegistry(): FormulaRichResultProviderRegistry

propertyreadonly symbol: typeof symbolstatic

methodenforceCommandBoundary(isExecuting: (): boolean, remove: (id: number): void): void

methodgetFormulaRichResult(row: number, col: number): FormulaRichResult | undefined

methodregister(registration: FormulaRichResultProviderRegistration): (): void

methodunregister(id: number): void

classFormulaSourceProviderRegistry

class FormulaSourceProviderRegistry extends IFormulaSourceProvider

Editor-local ordered registry for formula source providers.

constructorFormulaSourceProviderRegistry(): FormulaSourceProviderRegistry

propertyreadonly symbol: typeof symbolstatic

DI token for resolving IFormulaSourceProvider.

methodenforceCommandBoundary(isExecuting: (): boolean, remove: (id: number): void): void

methodgetFormulaSource(row: number, col: number): string | undefined

Gets the formula source that should be presented to the user for one cell.

Providers may return undefined when they do not own the queried cell. The default sheet formula provider returns the persisted formula text, while workbook-aware providers can return display text formatted from stable workbook bindings and the current sheet names.

methodregister(registration: FormulaSourceProviderRegistration): (): void

methodunregister(id: number): void

interfaceCellFormulaValueConverter

Defines how one persisted cell type enters the formula domain.

propertyreadonly cellType: string

Persisted cell type identifier handled by this converter.

methodtoFormulaValue(cell: CellMatrixElement): FormulaValue

Converts one sheet matrix element into a formula-engine value.

ReturnsFormula value used by formula evaluation and dependency recalculation.

cell: Persisted sheet cell to read without mutating sheet state.

interfaceFormulaResultProviderRegistration

Ordered formula result provider registered for one SheetEditor instance.

propertyreadonly priority?: number

Higher priority providers are queried first.

propertyreadonly provider: IFormulaResultProvider

Provider queried for formula results.

interfaceFormulaRichResultProviderRegistration

Ordered rich-result provider registered for one SheetEditor instance.

propertyreadonly priority?: number

propertyreadonly provider: IFormulaRichResultProvider

interfaceFormulaSourceProviderRegistration

propertyreadonly priority?: number

propertyreadonly provider: IFormulaSourceProvider

interfaceUnregisterFormulaProviderInput

propertyreadonly kind: FormulaProviderKind

propertyreadonly registrationId: number

typeFormulaProviderKind

type FormulaProviderKind = typeof FormulaProviderKind[keyof typeof FormulaProviderKind] FormulaProviderKind: { Result: "result"; RichResult: "richResult"; Source: "source" }

Formula-owned provider families sharing one editor-local unregister command.

variableUnregisterFormulaProviderCommand

UnregisterFormulaProviderCommand: SheetCommandDefinition<UnregisterFormulaProviderInput, SheetCommandResult>

Removes an editor-local formula provider registration.

variableUnregisterSheetFormulaExternalServiceCommand

UnregisterSheetFormulaExternalServiceCommand: SheetCommandDefinition<number, SheetCommandResult>

Removes one Sheet-owned external formula service contribution.

variableUnregisterSheetFormulaFunctionCommand

UnregisterSheetFormulaFunctionCommand: SheetCommandDefinition<number, SheetCommandResult>

Removes one function contribution through its Sheet owner.

variableUnregisterSheetFormulaTextServiceCommand

UnregisterSheetFormulaTextServiceCommand: SheetCommandDefinition<number, SheetCommandResult>

Removes one Sheet-owned formula text service contribution.

Schedule and invalidate

MarkFormulaDirtyCommand and RunFormulaBatchCommand are the command path for scheduled work. GetFormulaCellStatusCommand reads one cell's status, while WaitForFormulaIdleCommand waits for pending work to finish. FormulaCalculationTraceObservation reports calculation traces for diagnostics.

Host code should read formula results through a provider or status query. It should not write directly into FormulaResultStore, because the scheduler owns recalculation order and invalidation.

classFormulaCalculationTraceBus

class FormulaCalculationTraceBus extends IFormulaCalculationTraceProvider

Editor-local formula trace event hub.

The hub fans out local runtime trace to host/plugin subscribers. It is intentionally independent from OT, rendering, and persistence; publishing an event must not mutate sheet state or request a render pipeline.

constructorFormulaCalculationTraceBus(platform: Platform): FormulaCalculationTraceBus

propertyreadonly symbol: typeof symbolstatic

DI token for resolving FormulaCalculationTraceBus.

method

emit(event: Omit<FormulaBatchFlushedEvent, "sequence"> | Omit<FormulaDependenciesChangedEvent, "sequence"> | Omit<FormulaErrorChangedEvent, "sequence"> | Omit<FormulaRecalculationCompletedEvent, "sequence">): void

Emits one calculation trace event to current subscribers.

Listener failures are reported through Platform.warn and do not interrupt formula recalculation, dependency maintenance, rendering invalidation, or other subscribers.

event: Event payload without provider-owned sequence metadata.

methodenforceCommandBoundary(isCommandExecuting: (): boolean): void

Seals event publication after initial formula data has been scanned.

methodsubscribeFormulaCalculationTrace(listener: FormulaCalculationTraceListener): (): void

Subscribes to formula calculation trace events for one editor instance.

ReturnsFunction that removes the listener; calling it more than once is safe.

listener: Callback invoked for future calculation trace events.

classFormulaRenderInvalidator

Formula-result publisher for the shared displayed-value change bus.

The formula scheduler reports changes after updating derived results. Other features subscribe to the shared bus without depending on formula internals.

constructorFormulaRenderInvalidator(displayedValueChanges: SheetDisplayedValueChanges): FormulaRenderInvalidator

propertyreadonly symbol: typeof symbolstatic

DI token for resolving FormulaRenderInvalidator.

methodbind(handler: FormulaRenderInvalidationHandler): (): void

Registers the legacy formula-result callback for one editor instance.

ReturnsDisposer that removes this handler if it is still active.

handler: Callback that maps changed formula keys to render work.

methodinvalidateFormulaResults(keys: readonly number[]): void

Reports formula result changes to displayed-value subscribers.

keys: Formula cell keys whose derived display values changed.

typeFormulaRenderInvalidationHandler

type FormulaRenderInvalidationHandler = (keys: readonly CellKey[]): void

Compatibility callback for formula-result change notifications.

typeFormulaViewportChangeHandler

type FormulaViewportChangeHandler = (): void

Callback invoked when viewport-priority scheduling inputs may have changed.

variableDiscardFormulaWorkCommand

DiscardFormulaWorkCommand: SheetCommandDefinition<void, SheetCommandResult>

Invalidates an obsolete formula calculation generation.

variableMarkFormulaDirtyCommand

MarkFormulaDirtyCommand: SheetCommandDefinition<readonly number[], SheetCommandResult>

Marks formula dependencies dirty after an external result or function changes.

variableResumeFormulaWorkCommand

ResumeFormulaWorkCommand: SheetCommandDefinition<void, SheetCommandResult>

Resumes pending formula work when the visible viewport changes.

variableRunFormulaBatchCommand

RunFormulaBatchCommand: SheetCommandDefinition<void, SheetCommandResult>

Executes one scheduled, time-bounded formula calculation batch.

Formula references

Reference highlighting follows the draft formula and colors referenced ranges while the user edits it.

classFormulaCrossSheetHighlightSource

Optional workbook-owned source for cross-sheet formula reference overlays.

constructorFormulaCrossSheetHighlightSource(): FormulaCrossSheetHighlightSource

propertyreadonly symbol: typeof symbolstatic

methodgetReferences(selectionRevision: number, selectionSource?: string): readonly FormulaCrossSheetReference[]

classFormulaRefShifter

Rewrites formula references after Sheet structure changes.

constructorFormulaRefShifter(parser: IFormulaParser): FormulaRefShifter

propertyreadonly symbol: typeof symbolstatic

DI token for resolving FormulaRefShifter.

methodshiftAll(formulas: Map<number, FormulaAST>, changes: StructureChange[]): { key: number; newAst: FormulaAST }[]

Handles structural changes by traversing all formula ASTs and shifting references.

ReturnsFormula list that needs updates (key -> new AST).

formulas: Current AST cache for all formulas (CellKey -> AST).
changes: Structural change list for row/column insertion and deletion.

classSheetFormulaReferenceHighlightPlugin

class SheetFormulaReferenceHighlightPlugin extends Plugin<SearCoreSheet, CellProperties, Record<string, never>>

Highlights formula precedents and dependents for the active cell.

This intentionally remains separate from Selection: formula dependency status is optional, while Selection itself must stay independent of formula support.

constructor

SheetFormulaReferenceHighlightPlugin(statusProvider: IFormulaStatusProvider, configEngine: ConfigEngine, highlightRegistry: SheetHighlightRegistry, interactionStore: SheetInteractionStore): SheetFormulaReferenceHighlightPlugin

propertydepth: number

Draw above regular cells and below Selection's edit overlay.

propertyinterestedIn: string[]

Declares which Sheet OT action names this plugin is interested in. The engine will only call apply when a transaction contains at least one operation matching these action names, unless the transaction is owned by this plugin.

['uc', 'rr', 'rc'] — only called for UpdateCell, ResizeRow, ResizeCol
['*'] — called for any transaction (wildcard)
[] — only called for this plugin's own transactions

propertyreadonly highlightProviderKey: "formula-selection-references"static

Stable key for the formula-reference highlight contribution.

propertyreadonly pluginKey: PluginKeystatic

Stable plugin key for SheetFormulaReferenceHighlightPlugin.

propertyreadonly symbol: typeof symbolstatic

DI token for resolving SheetFormulaReferenceHighlightPlugin.

methodapply(_state: Record<string, never>, _transaction: Transaction): Record<string, never> | null

Applies a transaction to SheetFormulaReferenceHighlightPlugin state.

methodbindCrossSheetSource(source: FormulaCrossSheetHighlightSource): void

Binds an optional workbook-owned reference source for this Sheet instance.

methodgetHighlights(context: SheetHighlightContext): SheetRangeHighlight[]

The provider contract consumed by SheetHighlightPlugin.

methodgetPluginConfig(): unknown

Returns the plugin config.

methodregisterState(): { key: PluginKey; state: Record<string, never> }

Registers the state.

methodrender(_searCore: SearCoreSheet): Node<CellProperties>[]

Renders SheetFormulaReferenceHighlightPlugin scene output.

Inherited members 27

Inherited from Plugin.

interfaceFormulaCrossSheetReference

One workbook-qualified reference projected onto the currently mounted sheet.

propertyreadonly end: [number, number]

propertyreadonly index: number

propertyreadonly start: [number, number]

interfaceFormulaReferenceColorPalette

Named palette entries stay compatible with the reactive configuration engine.

propertyazure: string

propertyblue: string

propertybrown: string

propertycyan: string

propertyemerald: string

propertygreen: string

propertyindigo: string

propertyorange: string

propertyrose: string

propertyslate: string

propertyteal: string

propertyviolet: string

interfaceFormulaReferenceHighlightConfig

Formula-reference overlay settings used while editing a formula.

propertyactiveReferenceFillOpacity: number

Opacity of the referenced-cell overlay under the formula cursor.

propertyreferenceColors: FormulaReferenceColorPalette

Stable, high-contrast colors assigned to formula references.

propertyreferenceFillOpacity: number

Opacity of referenced-cell overlays when the cursor is elsewhere.

typeFormulaDependencyReference

type FormulaDependencyReference = FormulaDependencyCellRef & { kind: typeof FormulaNodeKind.Cell } | { end: FormulaDependencyCellRef; kind: typeof FormulaNodeKind.Range; ref: string; start: FormulaDependencyCellRef } | FormulaDependencyCellRef & { kind: typeof FormulaNodeKind.WorkbookCell; sheetName: string } | { end: FormulaDependencyCellRef; kind: typeof FormulaNodeKind.WorkbookRange; ref: string; sheetName: string; start: FormulaDependencyCellRef } | { endCol: number; kind: typeof FormulaNodeKind.ColumnRange; ref: string; startCol: number } | { endRow: number; kind: typeof FormulaNodeKind.RowRange; ref: string; startRow: number }

Product-facing dependency edge that preserves range-level formula semantics.

variableformulaReferenceHighlightConfig

formulaReferenceHighlightConfig: FormulaReferenceHighlightConfig

functiongetFormulaReferenceColor

getFormulaReferenceColor(referenceIndex: number, colors?: FormulaReferenceColorPalette): string

Assigns a formula reference its Excel-style, position-based palette color.