SearSuite
← All packages

@searsuite/sear-plugin-cell-merge

Merge and unmerge

Merge commands change the range structure. The matrix and read helper expose merged ranges to other features.

classCellMergeMatrix
class CellMergeMatrix extends CSRMatrix<SheetCellMerge | null>

Sparse matrix containing one end coordinate at every merged-range anchor.

constructorCellMergeMatrix(data?: CellMergeMatrixData, shape?: [number, number]): CellMergeMatrix
methodaddItem(row: number, column: number, value: SheetCellMerge | null): this

Adds an item to the matrix at the specified row and column.

ReturnsThe current instance for chaining.

row

The row index.

value

The value to add.

methodclone(): this

Deep-clones stored merge values.

methodfindRange(row: number, column: number): Rect | null

Finds the merged range containing one sheet cell.

methodforEachStored(callback: (value: SheetCellMerge | null, row: number, col: number): void): void

Visits actual anchors only, locating their rows through CSR pointer binary search.

methodgetItem(row: number, column: number): SheetCellMerge | null

Returns an isolated value so callers cannot mutate persisted matrix state.

methodgetRanges(): Rect[]

Returns all merged ranges in matrix traversal order.

methodreplaceRanges(ranges: readonly Rect[]): this

Rebuilds sparse entries from normalized ranges while preserving matrix shape.

methodsetItem(row: number, column: number, value: SheetCellMerge | null): this

Stores or clears a merged range anchored at the supplied cell.

Inherited members 31

Inherited from CSRMatrix.

classSheetCellMergeConfirmationError
class SheetCellMergeConfirmationError extends SearError

Base class for errors intentionally exposed by SearSuite packages.

Packages may throw this generic form while they do not need a more specific public error type. Domain-specific subclasses override code.

constructorSheetCellMergeConfirmationError(reason: "required" | "changed"): SheetCellMergeConfirmationError
propertyreadonly code: "SHEET_MERGE_CONFIRMATION_REQUIRED"

Stable machine-readable identifier for this error category.

Inherited members 9

Inherited from SearError.

classSheetCellMergePlugin
class SheetCellMergePlugin extends Plugin<unknown, CellProperties, SheetCellMergePluginState>

Owns sparse merged-cell state, commands, structure projection, collaboration, and export.

constructorSheetCellMergePlugin(state: SheetCellMergePluginState, cellContent?: SheetCellMergeContentSource): SheetCellMergePlugin
propertyreadonly documentState: PluginDocumentStateContribution<SheetCellMergePluginState, SheetCellMergePluginState>

Document-state export modules owned by this plugin state.

propertyinterestedIn: MatrixOTActionName[]

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.

  • [&#39;uc&#39;, &#39;rr&#39;, &#39;rc&#39;] — only called for UpdateCell, ResizeRow, ResizeCol
  • [&#39;*&#39;] — called for any transaction (wildcard)
  • [] — only called for this plugin's own transactions
propertyreadonly transactionOT: { collaborative: boolean; definition: TransactionOTDefinition<MatrixOTOperation<unknown>>; ownerId: string; relations: OTTransformRelation<MatrixOTOperation<unknown>, MatrixOTOperation<unknown>>[] }

Shared transaction algebra used by history and collaboration.

propertyreadonly warnOnDuplicateDepth: false

Whether PluginManager should warn when another ordered plugin shares this depth.

propertyreadonly documentState: PluginDocumentStateContribution<SheetCellMergePluginState, SheetCellMergePluginState>static
propertyreadonly pluginKey: PluginKeystatic
propertyreadonly symbol: typeof symbolstatic
methodapply(pluginState: SheetCellMergePluginState, transaction: Transaction): SheetCellMergePluginState | null

Applies a transaction to plugin-owned state and returns the next state.

methodgetPluginConfig(): null

Returns this plugin's runtime configuration view for the current core.

methodisMergedCell(row: number, column: number): Rect | null
methodregisterCommands(commands: SheetCommandBus): void
methodregisterQueries(queries: SheetQueryRegistry): void
methodregisterRangeMoves(registry: SheetRangeMoveRegistry): void

Moves complete merged ranges and rejects moves that split a merge.

methodregisterRangeReorders(registry: SheetRangeReorderRegistry): void
methodregisterState(): { dataEngine: { dataView: { fieldKey: string; select: (state: unknown): CellMergeMatrix; viewKey: string }[] }; key: PluginKey; state: SheetCellMergePluginState }

Registers one or more plugin-owned state records with the host manager.

methodrender(): Node<CellProperties>[]

Produces scene nodes owned by this plugin for the current core state.

Inherited members 25

Inherited from Plugin.

interfaceCellMergeMatrixData

Serialized CSR entries accepted by CellMergeMatrix.

propertyreadonly data: SheetCellMerge | null[]
propertyreadonly indices: number[]
propertyreadonly indptr: number[]
interfaceSheetCellMerge

Sparse value stored only at the top-left cell of a merged range.

propertyreadonly endColumn: number
propertyreadonly endRow: number
interfaceSheetCellMergeActionDataSource
interface SheetCellMergeActionDataSource extends SheetCellMergeCommandDataSource
propertyreadonly cellContent: SheetCellMergeContentSource
Inherited members 2

Inherited from SheetCellMergeCommandDataSource.

interfaceSheetMergeInput
interface SheetMergeInput extends SheetRangeInput

Common range input accepted by explicit range commands.

propertyreadonly confirmation?: SheetMergeAnalysis
Inherited members 2

Inherited from SheetRangeInput.

variableAnalyzeMergeCellsQuery
AnalyzeMergeCellsQuery: SheetQueryDefinition<SheetRangeInput, SheetMergeAnalysis | null>
variableMergeCellsCommand
MergeCellsCommand: SheetCommandDefinition<SheetMergeInput, SheetCommandResult>
variableSheetCellMergeFieldKey
SheetCellMergeFieldKey: "sheet.cellMerge"

DataEngine field owned by SheetCellMergePlugin.

variableToggleMergeCellsCommand
ToggleMergeCellsCommand: SheetCommandDefinition<SheetMergeInput, SheetCommandResult>
variableUnmergeCellsCommand
UnmergeCellsCommand: SheetCommandDefinition<SheetRangeInput, SheetCommandResult>
functionanalyzeMergeCells
analyzeMergeCells(input: SheetRangeInput, dataSource: SheetCellMergeActionDataSource): SheetMergeAnalysis | null
functioncreateMergeCellsOperations
createMergeCellsOperations(input: SheetRangeInput, dataSource: SheetCellMergeCommandDataSource): UpdateCellOTOperation<SheetCellMerge>[]
functioncreateUnmergeCellsOperations
createUnmergeCellsOperations(input: SheetRangeInput, dataSource: SheetCellMergeCommandDataSource): UpdateCellOTOperation<SheetCellMerge>[]
functionreadSheetCellMerges
readSheetCellMerges(dataEngine: DataEngine): CellMergeMatrix | null

Reads merged-cell state published by SheetCellMergePlugin.

functionregisterSheetCellMergeCommands
registerSheetCellMergeCommands(commands: SheetCommandBus, dataSource: SheetCellMergeActionDataSource): void

Registers every command owned by SheetCellMergePlugin.

functionregisterSheetCellMergeQueries
registerSheetCellMergeQueries(queries: SheetQueryRegistry, dataSource: SheetCellMergeActionDataSource): void

Analysis and conflicts

analyzeMergeCells checks a proposed merge before it is committed. The error types describe conflicts with content or structural moves.

classSheetMergeRangeMoveError
class SheetMergeRangeMoveError extends SearError

A cell move that would split an existing merged range.

constructorSheetMergeRangeMoveError(context: SheetRangeMoveContext): SheetMergeRangeMoveError
propertyreadonly code: "SHEET_MOVE_SPLIT_MERGE"

Stable machine-readable identifier for this error category.

Inherited members 9

Inherited from SearError.

classSheetMergeStructureMoveError
class SheetMergeStructureMoveError extends SearError

A structure permutation would leave a merged range noncontiguous.

constructorSheetMergeStructureMoveError(range: readonly readonly number[][]): SheetMergeStructureMoveError
propertyreadonly code: "SHEET_STRUCTURE_MOVE_SPLIT_MERGE"

Stable machine-readable identifier for this error category.

Inherited members 9

Inherited from SearError.