SearSuite
← All packages

@searsuite/sear-plugin-dropdown

Read and change a cell

Cell readers obtain the value and available options from validation-owned rules; clear and pick commands write the chosen value.

interfaceDropdownCellInput

Absolute target cell; all picker reads are editor-local.

propertyreadonly column: number

Zero-based column.

propertyreadonly row: number

Zero-based row.

interfaceDropdownCellSnapshot
interface DropdownCellSnapshot extends DropdownCellInput

Immutable current rule and cell projection.

propertyreadonly inputMessage?: string

Selection prompt from the validation owner.

propertyreadonly multiple: boolean

Whether choices accumulate.

propertyreadonly options: readonly DataValidationOption[]

Ordered, distinct current choices.

propertyreadonly ruleId: string

Stable validation owner id.

propertyreadonly selected: readonly string[]

Current selected labels, including values absent from the rule.

propertyreadonly showArrow: boolean

Whether the cell shows its arrow.

Inherited members 2

Inherited from DropdownCellInput.

variableClearDropdownValueCommand
ClearDropdownValueCommand: SheetCommandDefinition<DropdownCellInput, SheetCommandResult>

Clears the cell value while retaining validation rules.

variableReadDropdownCellQuery
ReadDropdownCellQuery: SheetQueryDefinition<DropdownCellInput, DropdownCellSnapshot | null>

Reads the current dropdown without exposing a feature matrix.

functionassertDropdownCell
assertDropdownCell(input: DropdownCellInput, shape: readonly number[]): void

Validates a cell before any source traversal or mutation.

functionplanDropdownValue
planDropdownValue(state: DropdownCellSnapshot | null, input: PickDropdownOptionInput): string | null

Computes a selection without mutating state; stale or removed choices fail explicitly.

functionreadDropdownCell
readDropdownCell(input: DropdownCellInput, options: SheetDropdownOptions): DropdownCellSnapshot | null

Resolves the last covering dropdown rule and bounded, distinct choices.

functionformatDropdownSelection
formatDropdownSelection(values: readonly string[]): string

Serializes labels without losing embedded commas, quotes or surrounding spaces.

functionparseDropdownSelection
parseDropdownSelection(text: string): string[]

Reads comma-separated labels with doubled-quote escaping; malformed input remains a single literal.

Open the picker

OpenDropdownPickerCommand asks the host to show a picker. The picker request carries the cell and option data it needs.

classDropdownError
class DropdownError extends SearError

Structured feature diagnostic.

constructorDropdownError(code: DropdownErrorCode, message: string, details?: SearErrorDetails): DropdownError

Creates a public dropdown diagnostic.

Inherited members 10

Inherited from SearError.

classSheetDropdownPlugin
class SheetDropdownPlugin extends Plugin<unknown, CellProperties, null>

Stateless dropdown interaction; rules and values retain their existing document owners.

constructorSheetDropdownPlugin(options: SheetDropdownOptions): SheetDropdownPlugin

Receives owner-scoped projections and semantic transaction factories.

propertyreadonly depth: -24

Handles arrows before ordinary selection.

propertyreadonly warnOnDuplicateDepth: false

Several stateless interaction extensions may share depth.

propertyreadonly symbol: typeof symbolstatic

Editor-local service token.

methodapply(): null

Mutations belong to validation and cell owners.

methoddestroy(): void

Releases transient host subscriptions.

methodgetPluginConfig(): null

No independent render configuration.

methodonMouseDown(_core: unknown, event: EventWithOffsetAndTarget<CellProperties>): boolean | void

Activates the trailing cell arrow through the public command bus.

methodonMouseUp(_core: unknown, event: EventWithOffsetAndTarget<CellProperties>): boolean | void

Keeps an arrow release from returning focus to the cell text editor.

methodregisterCellVisualReaders(registry: SheetCellVisualReaderRegistry): void

Adds viewport-bounded arrows and option color layers without taking fill ownership.

methodregisterCommands(commands: SheetCommandBus): void

Registers value changes and a transient picker request command.

methodregisterObservations(registry: ObservationRegistry): void

Host listener failures are isolated by the editor observation registry.

methodregisterQueries(queries: SheetQueryRegistry): void

Publishes a typed, current-cell query.

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

No duplicate document field is created.

methodrender(): null

Cell visual readers supply all adornments.

Inherited members 26

Inherited from Plugin.

interfacePickDropdownOptionInput
interface PickDropdownOptionInput extends DropdownCellInput

Target and choice to set, or toggle in multiple-selection mode.

propertyreadonly label: string

Option label, matched exactly against current choices.

propertyreadonly ruleId?: string

Optional rule identity guards stale picker actions after configuration changes.

Inherited members 2

Inherited from DropdownCellInput.

interfaceSheetDropdownOptions

Dependencies supplied by the composition root; persistent data stays with its original owners.

propertyreadonly queries: SheetQueryRegistry

Editor-local query bus for validation-owner projections.

propertyreadonly validation: SheetCellInputValidationRegistry

Shared edit validation, including overlapping rules.

methodbeforeOpen(): boolean

Commits active editing before pointer activation; false leaves the edit active.

methodcreateValueTransaction(row: number, column: number, text: string | null): Transaction

Plans a text or empty replacement as an ordinary cell-owner transaction.

methodforEachSourceValue(start: readonly [number, number], end: readonly [number, number], visit: (value: unknown): void): void

Visits nonempty source values in provider order, including formula projections.

methodreadShape(): readonly [number, number]

Reads dimensions for coordinate validation.

methodreadText(row: number, column: number): string

Reads display text, including formula results and structured cells.

typeDropdownErrorCode
type DropdownErrorCode = typeof DropdownErrorCode[keyof typeof DropdownErrorCode] DropdownErrorCode: { Conflict: "DROPDOWN_CONFLICT"; Invalid: "DROPDOWN_INVALID"; Limit: "DROPDOWN_LIMIT"; Stale: "DROPDOWN_STALE" }

One public dropdown error code.

variableDropdownLimits
DropdownLimits: { Options: 1000; SourceValues: 10000 }

Shared option and source traversal budgets.

variableDropdownPickerRequest
DropdownPickerRequest: EventObservationDefinition<DropdownCellInput>

Transient host request; no document or remount session state is stored.

variableOpenDropdownPickerCommand
OpenDropdownPickerCommand: SheetCommandDefinition<DropdownCellInput, SheetCommandResult>

Requests the host picker for one current dropdown cell.

variablePickDropdownOptionCommand
PickDropdownOptionCommand: SheetCommandDefinition<PickDropdownOptionInput, SheetCommandResult>

Picks one valid option through a cell-owner transaction.

variableDropdownMode
DropdownMode: { Multiple: "multiple"; Single: "single" }

Selection modes for dropdown validation.

interfaceDropdownOption

One displayable dropdown choice and its optional color.

propertyreadonly color?: string
propertyreadonly label: string