SearSuite
← All packages

API reference

@searsuite/sear-plugin-selection

Sheet selection state, navigation, observations, highlights, and commands.

47 exportsderived from source

Concept 1

Select a range, then read the committed selection

SheetSelectionPlugin owns Sheet selection state. SelectRangeCommand requests a new anchor and focus; the plugin expands a range when it intersects a merged cell, stages selection operations, and publishes a selection change after commit. GetSelection and GetSelections read the resulting state, while observations notify a host that needs to update its interface.

import { GetSelection, SelectRangeCommand } from '@searsuite/sear-plugin-selection';

editor.commands.run(SelectRangeCommand, { anchor: [2, 3], focus: [2, 3] });
const selection = editor.queries.run(GetSelection, undefined);

Use when: responding to pointer, keyboard, or application navigation. Coordinates are zero-based. A host should run the command rather than writing the selection matrix or highlight state directly.

Concept 2

Distinguish selection state from its visual highlight

Selection has document-facing operations, local navigation state, and a render projection. SheetHighlightPlugin draws the current range and can combine additional highlight providers; it does not become the owner of the selected range. EnsureSelectionVisibleCommand asks the viewport to reveal the selection after navigation.

Workbook remounting captures the local selection session through SheetSelectionSessionStateDefinition. The feature's command and query contracts remain the same when the active Sheet is recreated.

enumSheetAdditionalSelectionModesource ↗
enum SheetAdditionalSelectionMode

How a selection command updates disjoint local selections.

enum memberAppendCurrent
AppendCurrent: "append-current"
enum memberClear
Clear: "clear"
enum memberPreserve
Preserve: "preserve"
enumSheetHighlightPipelineStepNamesource ↗
enum SheetHighlightPipelineStepName

Observable pipeline steps owned by the generic range-highlight host.

enum memberRefresh
Refresh: "sheet-highlight.refresh"
enumSheetSelectionInteractionNamesource ↗
enum SheetSelectionInteractionName

Enumerates SheetSelectionInteractionName values.

enum memberChanged
Changed: "selection-changed"
enumSheetSelectionPipelineNamesource ↗
enum SheetSelectionPipelineName

Observable pipeline and step names owned by the Selection module.

enum memberSelectionChange
SelectionChange: "selection-change"
enumSheetSelectionPipelineStepNamesource ↗
enum SheetSelectionPipelineStepName

Enumerates SheetSelectionPipelineStepName values.

enum memberEnsureSelectionVisible
EnsureSelectionVisible: "selection.ensure-selection-visible"
enum memberRecordSelectionChange
RecordSelectionChange: "selection.record-selection-change"
enum memberUpdateSelection
UpdateSelection: "selection.update-selection"
enumSheetSelectionPointerActionsource ↗
enum SheetSelectionPointerAction

Pointer-session transitions owned by the Sheet selection plugin.

enum memberDown
Down: "down"
enum memberMove
Move: "move"
enum memberTick
Tick: "tick"
enum memberUp
Up: "up"
enumSheetSelectionSourcesource ↗
enum SheetSelectionSource

Enumerates SheetSelectionSource values.

enum memberApi
Api: "api"
enum memberKeyboard
Keyboard: "keyboard"
enum memberPointer
Pointer: "pointer"
classSheetHighlightPluginsource ↗
class SheetHighlightPlugin extends Plugin<SearCoreSheet, CellProperties, Record<string, never>>

Renders registered range-highlighter output as a single managed scene layer.

constructorconstructor
SheetHighlightPlugin(registry: SheetHighlightRegistry): SheetHighlightPlugin

Creates a SheetHighlightPlugin instance.

registry: SheetHighlightRegistry
propertypluginKeystatic
readonly pluginKey: PluginKey

Stable plugin key for SheetHighlightPlugin.

propertysymbolstatic
readonly symbol: typeof symbol

DI token for resolving SheetHighlightPlugin.

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

Applies a transaction to SheetHighlightPlugin state.

_state: Record<string, never>
_transaction: Transaction
methodgetPluginConfig
getPluginConfig(): unknown

Returns the plugin config.

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

Registers the state.

methodrender
render(searCore: SearCoreSheet): Node<CellProperties>[]

Renders SheetHighlightPlugin scene output.

searCore: SearCoreSheet
Inherited members 30

Inherited from Plugin.

classSheetHighlightRegistrysource ↗
class SheetHighlightRegistry

Registry for independently replaceable sheet-range highlighters.

The registry owns provider activation and change notification; the paired SheetHighlightPlugin owns scene-node creation and teardown.

constructorconstructor
SheetHighlightRegistry(platform?: Platform): SheetHighlightRegistry
platform: Platform
propertysymbolstatic
readonly symbol: typeof symbol

DI token for resolving SheetHighlightRegistry.

methodgetHighlights
getHighlights(context: SheetHighlightContext): SheetRangeHighlight[]

Returns the highlights.

context: SheetHighlightContext
methodinvalidate
invalidate(): void

Requests a new provider evaluation when state read by a provider (for example selection, search terms, or remote cursors) changes externally.

methodregister
register(provider: SheetHighlightProvider): (): void

Registers the value.

provider: SheetHighlightProvider
methodsetEnabled
setEnabled(providerKey: string, enabled: boolean): void

Updates the enabled.

providerKey: string
enabled: boolean
methodsubscribe
subscribe(listener: (): void): (): void

Subscribes to state changes and returns an idempotent disposer.

listener: (): void
classSheetRangeDragsource ↗
class SheetRangeDrag

Owns one local range-border gesture; document changes enter through the move command.

constructorconstructor
SheetRangeDrag(commands: SheetCommandBus, queries: SheetQueryRegistry, coordinates: CoordinateEngine, pointer: PointerCapture, keyboard: KeyboardRouter, cursorRules: CursorRegistry, cursor: CursorEngine, highlights: SheetHighlightRegistry, platform: Platform, interactions: SheetInteractionStore): SheetRangeDrag
commands: SheetCommandBus
queries: SheetQueryRegistry
coordinates: CoordinateEngine
pointer: PointerCapture
keyboard: KeyboardRouter
cursorRules: CursorRegistry
cursor: CursorEngine
highlights: SheetHighlightRegistry
platform: Platform
interactions: SheetInteractionStore
propertysymbolstatic
readonly symbol: typeof symbol
methodbind
bind(core: SearCoreSheet, readSelection: (): Rect, ownerToken: object): void

Installs editor-local cursor and preview contributions once Core is available.

core: SearCoreSheet
readSelection: (): Rect
ownerToken: object
methoddestroy
destroy(ownerToken?: object): void

Idempotently releases preview, cursor, pointer capture and animation resources.

ownerToken: object
methodisActive
isActive(): boolean
methodonMouseDown
onMouseDown(event: EventWithOffsetAndTarget<CellProperties>): boolean

Starts on selection borders or already selected axis headers.

event: EventWithOffsetAndTarget<CellProperties>
methodregisterCommands
registerCommands(commands: SheetCommandBus): void

Routes local pointer and animation inputs through the editor command boundary.

commands: SheetCommandBus
methodsetUserInteraction
setUserInteraction(service: UserInteractionService | undefined): void

Binds the optional host-owned confirmation service during assembly.

service: UserInteractionService | undefined
classSheetRangeMoveErrorsource ↗
class SheetRangeMoveError extends SearError

A range move rejected before any document state was staged.

constructorconstructor
SheetRangeMoveError(code: "SHEET_MOVE_INVALID_RANGE" | "SHEET_MOVE_DESTINATION_OCCUPIED", message: string, details: SearErrorDetails): SheetRangeMoveError
code: "SHEET_MOVE_INVALID_RANGE" | "SHEET_MOVE_DESTINATION_OCCUPIED"
message: string
details: SearErrorDetails
Inherited members 10

Inherited from SearError.

classSheetSelectionPluginsource ↗
class SheetSelectionPlugin extends Plugin<SearCoreSheet, CellProperties, [RectRange, RectRange]>

Owns Sheet selections, navigation, commands, and observations.

constructorconstructor
SheetSelectionPlugin(sheetCellMergePlugin: SheetCellMergePlugin, keyboardRouter: KeyboardRouter, platform?: Platform, interactionReducers?: SheetInteractionReducerRegistry, commands?: SheetCommandBus, rangeMoves?: SheetRangeMoveRegistry, rangeDrag?: SheetRangeDrag, highlights?: SheetHighlightRegistry): SheetSelectionPlugin

Creates a SheetSelectionPlugin instance.

sheetCellMergePlugin: SheetCellMergePlugin
keyboardRouter: KeyboardRouter
platform: Platform
interactionReducers: SheetInteractionReducerRegistry
commands: SheetCommandBus
rangeMoves: SheetRangeMoveRegistry
rangeDrag: SheetRangeDrag
highlights: SheetHighlightRegistry
propertydepth
depth: number

Draw and event ordering hint; lower values run earlier.

propertyinterestedIn
interestedIn: 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
propertypluginKeystatic
readonly pluginKey: PluginKey

Stable plugin key for SheetSelectionPlugin.

propertysymbolstatic
readonly symbol: symbol

DI token for resolving SheetSelectionPlugin.

methodapply
apply(pluginState: [Rect, Rect], transaction: Transaction): [Rect, Rect] | null

Applies a transaction to SheetSelectionPlugin state.

pluginState: [Rect, Rect]
transaction: Transaction
methodbindCore
bindCore(core: SearCoreSheet): void

Binds this plugin to the core owned by its editor-local container.

core: SearCoreSheet
methodextendForDownwardEntry
extendForDownwardEntry(): void

Adds a destination row only when Enter would otherwise keep the active cell in place.

methodgetPluginConfig
getPluginConfig(searCore: SearCoreSheet): null

Returns the plugin config.

searCore: SearCoreSheet
methodisInMergedCell
isInMergedCell(rangeRect: Rect): Rect | null

Returns whether in merged cell.

rangeRect: Rect
methodlockCommittedState
lockCommittedState(state: [Rect, Rect]): void

Locks committed selection rectangles while transaction clones remain writable.

state: [Rect, Rect]
methodnavigate
navigate(direction: "left" | "right" | "up" | "down", shiftKey?: boolean, metaKey?: boolean): void

Moves the current Sheet selection according to the requested direction.

direction: "left" | "right" | "up" | "down"
shiftKey: boolean
metaKey: boolean
methodnavigateDown
navigateDown(): void

Moves the current Sheet selection to the next selectable row.

methodonDblClick
onDblClick(searCore: SearCoreSheet, event: EventWithOffsetAndTarget<CellProperties>): boolean | void

Handles the dbl click lifecycle event.

searCore: SearCoreSheet
event: EventWithOffsetAndTarget<CellProperties>
methodonEditorDestroy
onEditorDestroy(): void

Cancels transient pointer work before this editor is released.

methodonMouseDown
onMouseDown(searCore: SearCoreSheet, event: EventWithOffsetAndTarget<CellProperties>): boolean | void

Handles the mouse down lifecycle event.

searCore: SearCoreSheet
event: EventWithOffsetAndTarget<CellProperties>
methodonMouseMove
onMouseMove(searCore: SearCoreSheet, event: EventWithOffsetAndTarget<CellProperties>): boolean | void

Handles the mouse move lifecycle event.

searCore: SearCoreSheet
event: EventWithOffsetAndTarget<CellProperties>
methodonMouseUp
onMouseUp(_searCore: SearCoreSheet, _event: EventWithOffsetAndTarget<CellProperties>): boolean | void

Handles the mouse up lifecycle event.

_searCore: SearCoreSheet
_event: EventWithOffsetAndTarget<CellProperties>
methodonTransactionCommitted
onTransactionCommitted(transaction: Transaction): void

Rebases local keyboard anchors only after structural transactions commit.

transaction: Transaction
methodregisterCommands
registerCommands(commands: SheetCommandBus): void

Registers the commands.

commands: SheetCommandBus
methodregisterConfig
registerConfig(): { config: ConfigUnit<{ defaultBorderColor: string }>; key: PluginKey }[]

Registers default configuration values owned by this plugin.

methodregisterQueries
registerQueries(queries: SheetQueryRegistry): void

Registers the active selection as a typed query rather than a DataEngine field.

queries: SheetQueryRegistry
methodregisterSessionState
registerSessionState(registry: SessionStateRegistry): void

Registers selection-owned local remount state.

registry: SessionStateRegistry
methodregisterState
registerState(): { key: PluginKey; state: [Rect, Rect] }

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

methodrender
render(searCore: SearCoreSheet, offset?: { x: number; y: number }): Node<CellProperties>[]

Renders SheetSelectionPlugin scene output.

searCore: SearCoreSheet
offset: { x: number; y: number }
methodrestartNavigation
restartNavigation(): void

Restarts selection navigation from the current active cell.

Inherited members 21

Inherited from Plugin.

interfaceMoveSheetRangeInputsource ↗
interface MoveSheetRangeInput

Moves a single rectangle to a new top-left coordinate on the same sheet.

propertyoverwrite
readonly overwrite?: boolean

Explicit authorization to replace existing destination data.

propertysource
readonly source: SheetMoveRange
propertytarget
readonly target: readonly [number, number]
interfaceSelectionChangedInteractionSignalsource ↗
interface SelectionChangedInteractionSignal extends SheetInteractionSignal

Public contract for SelectionChangedInteractionSignal.

propertyanchor
anchor: Point
propertyfocus
focus: Point
propertysource
source: SheetSelectionSource
propertytype
type: SheetSelectionInteractionName
interfaceSheetEnsureSelectionVisibleInputsource ↗
interface SheetEnsureSelectionVisibleInput extends SheetSelectRangeInput

Public contract for SheetEnsureSelectionVisibleInput.

Inherited members 8

Inherited from SheetSelectRangeInput.

interfaceSheetFillRangeInputsource ↗
interface SheetFillRangeInput
propertysource
readonly source: { end: readonly [number, number]; start: readonly [number, number] }
propertytarget
readonly target: readonly [number, number]
interfaceSheetHighlightContextsource ↗
interface SheetHighlightContext

Read-only sheet state made available to every range-highlight provider.

propertysearCore
searCore: SearCoreSheet
interfaceSheetHighlightProvidersource ↗
interface SheetHighlightProvider

Extension point for range decorations such as formula precedents, search results, validation errors, collaboration selections, and audit trails.

propertykey
key: string
methodgetHighlights
getHighlights(context: SheetHighlightContext): SheetRangeHighlight[]
context: SheetHighlightContext
interfaceSheetRangeHighlightsource ↗
interface SheetRangeHighlight

A visual-only cell range supplied by an independently registered provider.

propertydepth
depth?: number
propertyedge
edge?: SheetHighlightEdge
propertyend
end: Point
propertyfill
fill?: string
propertyinset
inset?: number

Insets the visual box from the resolved cell-range boundary.

propertyskipHit
skipHit?: boolean
propertystart
start: Point
propertystroke
stroke?: string
propertystrokeWidth
strokeWidth?: number
propertytype
type?: string
interfaceSheetSelectionPointerInputsource ↗
interface SheetSelectionPointerInput

Detached input coordinates for a selection pointer transition.

propertyaction
readonly action: SheetSelectionPointerAction
propertyctrlKey
readonly ctrlKey?: boolean
propertymetaKey
readonly metaKey?: boolean
propertyshiftKey
readonly shiftKey?: boolean
propertytarget
readonly target?: { endColIndex: number | undefined; endRowIndex: number | undefined; region: CellRegion | undefined; startColIndex: number | undefined; startRowIndex: number | undefined } | null
propertyview
readonly view?: { x: number; y: number }
interfaceSheetSelectRangeInputsource ↗
interface SheetSelectRangeInput

Public programmatic input for selecting a rectangular sheet range.

propertyactiveAnchor
readonly activeAnchor?: Point

Optional active anchor stored for in-progress pointer or keyboard interactions.

propertyactiveFocus
readonly activeFocus?: Point

Optional active focus stored for in-progress pointer or keyboard interactions.

propertyadditionalSelectionMode
readonly additionalSelectionMode?: SheetAdditionalSelectionMode

Transition applied to disjoint local selections at commit.

propertyanchor
readonly anchor: Point

Final selected range anchor.

propertyensureVisible
readonly ensureVisible?: boolean

Whether the command should also scroll the selection into view.

propertyfocus
readonly focus: Point

Final selected range focus.

propertynavigation
readonly navigation?: { cursor: Point; origin: Point }

Keyboard navigation anchor and cursor to publish with this selection.

propertysource
readonly source?: SheetSelectionSource

Origin of this selection change.

typeSheetDragAxissource ↗
type SheetDragAxis = typeof SheetDragAxis[keyof typeof SheetDragAxis]

Canonical axes for complete row/column selection gestures.

typeSheetHighlightEdgesource ↗
type SheetHighlightEdge = typeof SheetHighlightEdge[keyof typeof SheetHighlightEdge]

Viewport-spanning overlay guide anchored to a cell-range edge.

typeSheetRangeDragInputsource ↗
type SheetRangeDragInput = { action: typeof SheetRangeDragAction.Begin | typeof SheetRangeDragAction.FillBegin | typeof SheetRangeDragAction.Update | typeof SheetRangeDragAction.Release; point: PointerCapturePoint } | { action: typeof SheetRangeDragAction.Cancel | typeof SheetRangeDragAction.Tick }

Portable inputs for one local gesture, never persisted as document state.

typeSheetSelectionSessionStatesource ↗
type SheetSelectionSessionState = readonly [RectRange, RectRange]

Local selection state retained while remounting one workbook sheet.

variableAnalyzeSheetRangeMovesource ↗
AnalyzeSheetRangeMove: SheetQueryDefinition<MoveSheetRangeInput, SheetRangeMoveAnalysis>

Reads the latest legal destination and owner constraints for a range move.

variableClearSelectedContentsCommandsource ↗
ClearSelectedContentsCommand: SheetCommandDefinition<void, SheetCommandResult>

Clears every rectangle of a disjoint selection in one data transaction.

variableEnsureSelectionVisibleCommandsource ↗
EnsureSelectionVisibleCommand: SheetCommandDefinition<SheetEnsureSelectionVisibleInput, SheetCommandResult>
variableFillSheetRangeCommandsource ↗
FillSheetRangeCommand: SheetCommandDefinition<SheetFillRangeInput, SheetCommandResult>

Fills cells from a selected source rectangle through the pointer destination.

variableGetActiveCellsource ↗
GetActiveCell: SheetQueryDefinition<void, readonly [number, number] | null>

Reads the cell where the current selection began, including reversed ranges.

variableGetSelectionsource ↗
GetSelection: SheetQueryDefinition<void, SheetRangeBounds | null>

Typed query for the active rectangular selection, independent of selection storage.

variableGetSelectionNavigationsource ↗
GetSelectionNavigation: SheetQueryDefinition<void, { cursor: Point | null; origin: Point | null }>

Detached keyboard navigation anchors for diagnostics and extensions.

variableGetSelectionssource ↗
GetSelections: SheetQueryDefinition<void, readonly SheetRangeBounds[]>

All disjoint selections, with the current active rectangle last.

variableGetSheetRangeMoveConflictsource ↗
GetSheetRangeMoveConflict: SheetQueryDefinition<MoveSheetRangeInput, boolean>

Validates a move and reports whether replacement requires user authorization.

variableHandleSheetRangeDragCommandsource ↗
HandleSheetRangeDragCommand: SheetCommandDefinition<SheetRangeDragInput, SheetCommandResult>
variableHandleSheetSelectionPointerCommandsource ↗
HandleSheetSelectionPointerCommand: SheetCommandDefinition<SheetSelectionPointerInput, SheetCommandResult>

Routes selection pointer-session changes through the editor command bus.

variableMoveSheetRangeCommandsource ↗
MoveSheetRangeCommand: SheetCommandDefinition<MoveSheetRangeInput, SheetCommandResult>
variableRestartSheetSelectionNavigationCommandsource ↗
RestartSheetSelectionNavigationCommand: SheetCommandDefinition<void, SheetCommandResult>

Restarts selection keyboard navigation after another editor releases focus.

variableSelectRangeCommandsource ↗
SelectRangeCommand: SheetCommandDefinition<SheetSelectRangeInput, SheetCommandResult>
variableSheetDragAxissource ↗
SheetDragAxis: { Column: 1; Row: 0 }

Canonical axes for complete row/column selection gestures.

variableSheetHighlightEdgesource ↗
SheetHighlightEdge: { Bottom: "bottom"; Left: "left"; Right: "right"; Top: "top" }

Viewport-spanning overlay guide anchored to a cell-range edge.

variableSheetRangeDragActionsource ↗
SheetRangeDragAction: { Begin: "begin"; Cancel: "cancel"; FillBegin: "fill-begin"; Release: "release"; Tick: "tick"; Update: "update" }

Canonical phases of a local range-border gesture.

variableSheetRangeMoveErrorCodesource ↗
SheetRangeMoveErrorCode: { DestinationOccupied: "SHEET_MOVE_DESTINATION_OCCUPIED"; InvalidRange: "SHEET_MOVE_INVALID_RANGE" }

Stable range-move validation failures exposed to hosts.

variableSheetSelectionRenderSemanticssource ↗
SheetSelectionRenderSemantics: { outlineRole: "selection-outline"; owner: "sheet-selection" }

Stable semantic attributes emitted by retained render targets for Selection.

variableSheetSelectionSessionStateDefinitionsource ↗
SheetSelectionSessionStateDefinition: SessionStateDefinition<SheetSelectionSessionState>

Stable session-state identity owned by SheetSelectionPlugin.

functionregisterSelectionQueriessource ↗
registerSelectionQueries(queries: SheetQueryRegistry, readSelection: (): SheetRangeBounds | null): void

Registers the selection query against an editor-local query registry.

queries: SheetQueryRegistry
readSelection: (): SheetRangeBounds | null
functionregisterSheetSelectionInteractionReducerssource ↗
registerSheetSelectionInteractionReducers(registry: SheetInteractionReducerRegistry): void

Registers Selection's local interaction projection once per DI container.

registry: SheetInteractionReducerRegistry