SearSuite
← All packages

@searsuite/sear-plugin-selection

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.

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.

enumSheetAdditionalSelectionMode

How a selection command updates disjoint local selections.

enum memberAppendCurrent: "append-current"
enum memberClear: "clear"
enum memberPreserve: "preserve"
enumSheetSelectionInteractionName

Enumerates SheetSelectionInteractionName values.

enum memberChanged: "selection-changed"
enumSheetSelectionPipelineName

Observable pipeline and step names owned by the Selection module.

enum memberSelectionChange: "selection-change"
enumSheetSelectionPointerAction

Pointer-session transitions owned by the Sheet selection plugin.

enum memberDown: "down"
enum memberMove: "move"
enum memberTick: "tick"
enum memberUp: "up"
enumSheetSelectionSource

Enumerates SheetSelectionSource values.

enum memberApi: "api"
enum memberKeyboard: "keyboard"
enum memberPointer: "pointer"
classSheetSelectionPlugin
class SheetSelectionPlugin extends Plugin<SearCoreSheet, CellProperties, [RectRange, RectRange]>

Owns Sheet selections, navigation, commands, and observations.

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

Draw and event ordering hint; lower values run earlier.

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 pluginKey: PluginKeystatic

Stable plugin key for SheetSelectionPlugin.

propertyreadonly symbol: symbolstatic

DI token for resolving SheetSelectionPlugin.

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

Applies a transaction to SheetSelectionPlugin state.

methodbindCore(core: SearCoreSheet): void

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

methodextendForDownwardEntry(): void

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

methodextendForRightwardEntry(): void

Adds a destination column only when Tab would otherwise keep the active cell in place.

methodgetPluginConfig(searCore: SearCoreSheet): null

Returns the plugin config.

methodisInMergedCell(rangeRect: Rect): Rect | null

Returns whether in merged cell.

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

Locks committed selection rectangles while transaction clones remain writable.

methodnavigate(direction: "left" | "right" | "up" | "down", shiftKey?: boolean, metaKey?: boolean): void

Moves the current Sheet selection according to the requested direction.

methodnavigateDown(): void

Moves the current Sheet selection to the next selectable row.

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

Handles the dbl click lifecycle event.

methodonEditorDestroy(): void

Cancels transient pointer work before this editor is released.

methodonFillHandleDoubleClick(event: EventWithOffsetAndTarget<CellProperties>): boolean

Lets the editor distinguish the fill handle from a cell-body double click.

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

Handles the mouse down lifecycle event.

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

Handles the mouse move lifecycle event.

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

Handles the mouse up lifecycle event.

methodonTransactionCommitted(transaction: Transaction): void

Rebases local keyboard anchors only after structural transactions commit.

methodregisterCommands(commands: SheetCommandBus): void

Registers the commands.

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

Registers default configuration values owned by this plugin.

methodregisterQueries(queries: SheetQueryRegistry): void

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

methodregisterSessionState(registry: SessionStateRegistry): void

Registers selection-owned local remount state.

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

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

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

Renders SheetSelectionPlugin scene output.

methodrestartNavigation(): void

Restarts selection navigation from the current active cell.

Inherited members 20

Inherited from Plugin.

interfaceSelectionChangedInteractionSignal
interface SelectionChangedInteractionSignal extends SheetInteractionSignal
propertyanchor: Point
propertyfocus: Point
propertysource: SheetSelectionSource
propertytype: SheetSelectionInteractionName
interfaceSheetEnsureSelectionVisibleInput
interface SheetEnsureSelectionVisibleInput extends SheetSelectRangeInput
Inherited members 8

Inherited from SheetSelectRangeInput.

interfaceSheetSelectRangeInput

Public programmatic input for selecting a rectangular sheet range.

propertyreadonly activeAnchor?: Point

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

propertyreadonly activeFocus?: Point

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

propertyreadonly additionalSelectionMode?: SheetAdditionalSelectionMode

Transition applied to disjoint local selections at commit.

propertyreadonly anchor: Point

Final selected range anchor.

propertyreadonly ensureVisible?: boolean

Whether the command should also scroll the selection into view.

propertyreadonly focus: Point

Final selected range focus.

propertyreadonly navigation?: { cursor: Point; origin: Point }

Keyboard navigation anchor and cursor to publish with this selection.

propertyreadonly source?: SheetSelectionSource

Origin of this selection change.

typeSheetSelectionSessionState
type SheetSelectionSessionState = readonly [RectRange, RectRange]

Local selection state retained while remounting one workbook sheet.

variableEnsureSelectionVisibleCommand
EnsureSelectionVisibleCommand: SheetCommandDefinition<SheetEnsureSelectionVisibleInput, SheetCommandResult>
variableGetActiveCell
GetActiveCell: SheetQueryDefinition<void, readonly [number, number] | null>

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

variableGetSelection
GetSelection: SheetQueryDefinition<void, SheetRangeBounds | null>

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

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

Detached keyboard navigation anchors for diagnostics and extensions.

variableGetSelections
GetSelections: SheetQueryDefinition<void, readonly SheetRangeBounds[]>

All disjoint selections, with the current active rectangle last.

variableHandleSheetSelectionPointerCommand
HandleSheetSelectionPointerCommand: SheetCommandDefinition<SheetSelectionPointerInput, SheetCommandResult>

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

variableRestartSheetSelectionNavigationCommand
RestartSheetSelectionNavigationCommand: SheetCommandDefinition<void, SheetCommandResult>

Restarts selection keyboard navigation after another editor releases focus.

variableSelectRangeCommand
SelectRangeCommand: SheetCommandDefinition<SheetSelectRangeInput, SheetCommandResult>
variableSheetSelectionRenderSemantics
SheetSelectionRenderSemantics: { outlineRole: "selection-outline"; owner: "sheet-selection" }

Stable semantic attributes emitted by retained render targets for Selection.

variableSheetSelectionSessionStateDefinition
SheetSelectionSessionStateDefinition: SessionStateDefinition<SheetSelectionSessionState>

Stable session-state identity owned by SheetSelectionPlugin.

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

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

functionregisterSheetSelectionInteractionReducers
registerSheetSelectionInteractionReducers(registry: SheetInteractionReducerRegistry): void

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

Dragging and moving

Drag and move commands update the selected range or fill it, while conflict queries check proposed moves.

classSheetRangeDrag

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

constructorSheetRangeDrag(commands: SheetCommandBus, queries: SheetQueryRegistry, coordinates: CoordinateEngine, pointer: PointerCapture, keyboard: KeyboardRouter, cursorRules: CursorRegistry, cursor: CursorEngine, highlights: SheetHighlightRegistry, platform: Platform, interactions: SheetInteractionStore, inputValidation: SheetCellInputValidationRegistry): SheetRangeDrag
propertyreadonly symbol: typeof symbolstatic
methodbind(core: SearCoreSheet, readSelection: (): Rect, ownerToken: object): void

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

methoddestroy(ownerToken?: object): void

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

methodisActive(): boolean
methodonFillHandleDoubleClick(event: EventWithOffsetAndTarget<CellProperties>): boolean

Fills down to the end of a continuous adjacent column when the handle is double-clicked.

methodonMouseDown(event: EventWithOffsetAndTarget<CellProperties>): boolean

Starts on selection borders or already selected axis headers.

methodregisterCommands(commands: SheetCommandBus): void

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

methodsetUserInteraction(service: UserInteractionService | undefined): void

Binds the optional host-owned confirmation service during assembly.

interfaceMoveSheetRangeInput

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

propertyreadonly overwrite?: boolean

Explicit authorization to replace existing destination data.

propertyreadonly source: SheetMoveRange
propertyreadonly target: readonly [number, number]
typeSheetDragAxis
type SheetDragAxis = typeof SheetDragAxis[keyof typeof SheetDragAxis] SheetDragAxis: { Column: 1; Row: 0 }

Canonical axes for complete row/column selection gestures.

typeSheetRangeDragInput
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.

variableAnalyzeSheetRangeMove
AnalyzeSheetRangeMove: SheetQueryDefinition<MoveSheetRangeInput, SheetRangeMoveAnalysis>

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

variableClearSelectedContentsCommand
ClearSelectedContentsCommand: SheetCommandDefinition<void, SheetCommandResult>

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

variableFillSheetRangeCommand
FillSheetRangeCommand: SheetCommandDefinition<SheetFillRangeInput, SheetCommandResult>

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

variableGetSheetRangeMoveConflict
GetSheetRangeMoveConflict: SheetQueryDefinition<MoveSheetRangeInput, boolean>

Validates a move and reports whether replacement requires user authorization.

variableHandleSheetRangeDragCommand
HandleSheetRangeDragCommand: SheetCommandDefinition<SheetRangeDragInput, SheetCommandResult>
variableMoveSheetRangeCommand
MoveSheetRangeCommand: SheetCommandDefinition<MoveSheetRangeInput, SheetCommandResult>
variableSheetRangeDragAction
SheetRangeDragAction: { Begin: "begin"; Cancel: "cancel"; FillBegin: "fill-begin"; Release: "release"; Tick: "tick"; Update: "update" }

Canonical phases of a local range-border gesture.

variableSheetRangeMoveErrorCode
SheetRangeMoveErrorCode: { DestinationOccupied: "SHEET_MOVE_DESTINATION_OCCUPIED"; InvalidRange: "SHEET_MOVE_INVALID_RANGE" }

Stable range-move validation failures exposed to hosts.

Highlights

Highlight providers paint selection-related ranges without changing the committed selection.

enumSheetHighlightPipelineStepName

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

enum memberRefresh: "sheet-highlight.refresh"
classSheetHighlightPlugin
class SheetHighlightPlugin extends Plugin<SearCoreSheet, CellProperties, Record<string, never>>

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

constructorSheetHighlightPlugin(registry: SheetHighlightRegistry): SheetHighlightPlugin
propertyreadonly pluginKey: PluginKeystatic

Stable plugin key for SheetHighlightPlugin.

propertyreadonly symbol: typeof symbolstatic

DI token for resolving SheetHighlightPlugin.

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

Applies a transaction to SheetHighlightPlugin state.

methodgetPluginConfig(): unknown

Returns the plugin config.

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

Registers the state.

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

Renders SheetHighlightPlugin scene output.

Inherited members 29

Inherited from Plugin.

classSheetHighlightRegistry

Registry for independently replaceable sheet-range highlighters.

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

constructorSheetHighlightRegistry(platform?: Platform): SheetHighlightRegistry
propertyreadonly symbol: typeof symbolstatic

DI token for resolving SheetHighlightRegistry.

methodgetHighlights(context: SheetHighlightContext): SheetRangeHighlight[]

Returns the highlights.

methodinvalidate(): void

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

methodregister(provider: SheetHighlightProvider): (): void

Registers the value.

methodsetEnabled(providerKey: string, enabled: boolean): void

Updates the enabled.

methodsubscribe(listener: (): void): (): void

Subscribes to state changes and returns an idempotent disposer.

interfaceSheetHighlightContext

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

propertysearCore: SearCoreSheet
interfaceSheetHighlightProvider

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

propertykey: string
methodgetHighlights(context: SheetHighlightContext): SheetRangeHighlight[]
interfaceSheetRangeHighlight

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

propertydepth?: number
propertyedge?: SheetHighlightEdge
propertyend: Point
propertyfill?: string
propertyinset?: number

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

propertyoverlay?: boolean

Paints a transient range above the grid in the final overlay pass.

propertyskipHit?: boolean
propertystart: Point
propertystroke?: string
propertystrokeWidth?: number
propertytype?: string
typeSheetHighlightEdge
type SheetHighlightEdge = typeof SheetHighlightEdge[keyof typeof SheetHighlightEdge] SheetHighlightEdge: { Bottom: "bottom"; Left: "left"; Right: "right"; Top: "top" }

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