@searsuite/sear-plugin-data-validation API reference

classDataValidationEvaluatorRegistry source ↗

class DataValidationEvaluatorRegistry

Host extension point for structured values and custom formulas.

constructorconstructor

DataValidationEvaluatorRegistry(): DataValidationEvaluatorRegistry

methodenforceCommandBoundary

enforceCommandBoundary(isExecuting: (): boolean, dispatchRemoval: (id: number): void): void

Seals post-assembly writes without adding work to evaluator reads.

isExecuting: (): boolean
dispatchRemoval: (id: number): void

methodevaluate

evaluate(condition: DataValidationCondition, text: string, row: number, column: number): boolean | null

condition: DataValidationCondition
text: string
row: number
column: number

methodregister

register(kind: DataValidationKind, evaluator: DataValidationExternalEvaluator): (): void

kind: DataValidationKind
evaluator: DataValidationExternalEvaluator

methodunregister

unregister(id: number): void

Removes a registration through the owning command after assembly.

id: number

classDataValidationMatrix source ↗

class DataValidationMatrix extends CSRMatrix<DataValidationRule[] | null>

Sparse range anchors for validation rules.

constructorconstructor

DataValidationMatrix(data?: { data: DataValidationRule[] | null[]; indices: number[]; indptr: number[] }, shape?: [number, number]): DataValidationMatrix

data: { data: DataValidationRule[] | null[]; indices: number[]; indptr: number[] }
shape: [number, number]

methodaddItem

addItem(row: number, column: number, rules: DataValidationRule[] | null): this

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

ReturnsThe current instance for chaining.

row: number: The row index.
column: number
rules: DataValidationRule[] | null

methodclone

clone(): this

Creates an independent copy of this value and its mutable data.

methodfindRules

findRules(row: number, column: number): PositionedDataValidationRule[]

row: number
column: number

methodgetItem

getItem(row: number, column: number): DataValidationRule[] | null

Retrieves an item from the matrix at the specified row and column.

ReturnsThe item at the specified position or null if not present.

row: number: The row index.
column: number

methodgetRules

getRules(): PositionedDataValidationRule[]

methodreplaceRules

replaceRules(entries: readonly PositionedDataValidationRule[]): void

entries: readonly PositionedDataValidationRule[]

methodsetItem

setItem(row: number, column: number, rules: DataValidationRule[] | null): this

row: number
column: number
rules: DataValidationRule[] | null

Inherited members 32

Inherited from CSRMatrix.

classSheetDataValidationPlugin source ↗

class SheetDataValidationPlugin extends Plugin<unknown, CellProperties, SheetDataValidationPluginState>

Base contract implemented by sheet and document plugins.

Plugins own their state, declare lifecycle hooks, transform transactions into state, and render scene nodes for their host core. Runtime packages should extend this contract rather than reaching into Core internals.

constructorconstructor

SheetDataValidationPlugin(state: SheetDataValidationPluginState, dependencies: SheetDataValidationDependencies): SheetDataValidationPlugin

state: SheetDataValidationPluginState
dependencies: SheetDataValidationDependencies

propertydocumentState

readonly documentState: PluginDocumentStateContribution<SheetDataValidationPluginState, SheetDataValidationPluginState>

Document-state export modules owned by this plugin state.

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.

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

propertytransactionOT

readonly transactionOT: { collaborative: boolean; definition: TransactionOTDefinition<MatrixOTOperation<unknown>>; ownerId: string; relations: OTTransformRelation<MatrixOTOperation<unknown>, MatrixOTOperation<unknown>>[] }

Shared transaction algebra used by history and collaboration.

propertywarnOnDuplicateDepth

readonly warnOnDuplicateDepth: false

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

propertydocumentStatestatic

readonly documentState: PluginDocumentStateContribution<SheetDataValidationPluginState, SheetDataValidationPluginState>

propertypluginKeystatic

readonly pluginKey: PluginKey

propertysymbolstatic

readonly symbol: typeof symbol

methodapply

apply(state: SheetDataValidationPluginState, transaction: Transaction): SheetDataValidationPluginState | null

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

state: SheetDataValidationPluginState
transaction: Transaction

methoddispose

dispose(): void

methodgetPluginConfig

getPluginConfig(): null

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

methodonTransactionCommitted

onTransactionCommitted(transaction: Transaction): void

Runs only after every step in the enclosing pipeline has succeeded and all staged plugin state has been committed. Use it for derived caches, notifications, persistence, and transport; never perform those effects in apply, because a later pipeline step may still fail.

transaction: Transaction: A committed transaction from the completed pipeline.

methodreadIssue

readIssue(row: number, column: number): DataValidationIssue | null

Returns a definite failure for the cell's current value, including values predating the rule.

row: number
column: number

methodregisterCapabilities

registerCapabilities(registry: RuntimeCapabilityRegistry): void

registry: RuntimeCapabilityRegistry

methodregisterCellVisualReaders

registerCellVisualReaders(registry: SheetCellVisualReaderRegistry): void

registry: SheetCellVisualReaderRegistry

methodregisterCommands

registerCommands(commands: SheetCommandBus): void

commands: SheetCommandBus

methodregisterObservations

registerObservations(registry: ObservationRegistry): void

registry: ObservationRegistry

methodregisterQueries

registerQueries(queries: SheetQueryRegistry): void

queries: SheetQueryRegistry

methodregisterRangeMoves

registerRangeMoves(registry: SheetRangeMoveRegistry): void

registry: SheetRangeMoveRegistry

methodregisterState

registerState(): { dataEngine: { dataView: { fieldKey: string; select: (state: unknown): DataValidationMatrix; viewKey: string }[] }; key: PluginKey; state: SheetDataValidationPluginState }

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

methodrender

render(): Node<CellProperties>[]

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

methodsealRuntimeWrites

sealRuntimeWrites(): void

Closes runtime-owned extension writes after every plugin has initialized and started.

methodvalidate

validate(row: number, column: number, text: string): SheetCellInputValidationResult

row: number
column: number
text: string

Inherited members 24

Inherited from Plugin.

interfaceDataValidationCondition source ↗

interface DataValidationCondition

Type-specific settings used to evaluate a cell value.

propertydropdownMode

readonly dropdownMode?: DataValidationDropdownMode

propertyformula

readonly formula?: string

propertyintegerOnly

readonly integerOnly?: boolean

propertykind

readonly kind: DataValidationKind

propertyoperator

readonly operator?: DataValidationOperator

propertyoptions

readonly options?: readonly DataValidationOption[]

propertysecondValue

readonly secondValue?: string

propertyshowDropdownArrow

readonly showDropdownArrow?: boolean

propertysourceRange

readonly sourceRange?: { end: readonly [number, number]; start: readonly [number, number] }

propertytextMode

readonly textMode?: DataValidationTextMode

propertyvalue

readonly value?: string

interfaceDataValidationEvaluationContext source ↗

interface DataValidationEvaluationContext

propertycolumn

readonly column: number

propertyevaluateExternal

readonly evaluateExternal?: (condition: DataValidationCondition, text: string, row: number, column: number): boolean | null

Host contribution for formula results and structured cell types. Null means unavailable.

propertyreadSourceValues

readonly readSourceValues?: (start: readonly [number, number], end: readonly [number, number]): readonly string[]

propertyrow

readonly row: number

interfaceDataValidationIssue source ↗

interface DataValidationIssue

A definite failure of the current cell value against a validation rule.

propertycolumn

readonly column: number

propertymessage

readonly message: string

propertyrow

readonly row: number

propertyruleId

readonly ruleId: string

interfaceDataValidationOption source ↗

interface DataValidationOption

One displayable dropdown choice and its optional color.

propertycolor

readonly color?: string

propertylabel

readonly label: string

interfaceDataValidationRule source ↗

interface DataValidationRule

One independently editable rule stored at the top-left cell of its range.

propertycondition

readonly condition: DataValidationCondition

propertyendColumn

readonly endColumn: number

propertyendRow

readonly endRow: number

propertyerrorMessage

readonly errorMessage?: string

propertyid

readonly id: string

propertyinputMessage

readonly inputMessage?: string

propertyinputPolicy

readonly inputPolicy: DataValidationInputPolicy

interfaceDataValidationWarning source ↗

interface DataValidationWarning

propertycolumn

readonly column: number

propertymessage

readonly message: string

propertyrow

readonly row: number

propertyruleId

readonly ruleId: string

interfacePositionedDataValidationRule source ↗

interface PositionedDataValidationRule

A rule with its persisted range anchor.

propertycolumn

readonly column: number

propertyrow

readonly row: number

propertyrule

readonly rule: DataValidationRule

interfaceSetDataValidationRuleInput source ↗

interface SetDataValidationRuleInput extends SheetRangeInput

Target range and rule settings for creating or editing a rule.

propertyid

readonly id?: string

propertyrule

readonly rule: Omit<DataValidationRule, "id" | "endRow" | "endColumn">

Inherited members 2

Inherited from SheetRangeInput.

anchor
focus

interfaceSheetDataValidationDependencies source ↗

interface SheetDataValidationDependencies

propertycreateId

readonly createId: (): string

propertyevaluators

readonly evaluators: DataValidationEvaluatorRegistry

propertyinputValidation

readonly inputValidation: SheetCellInputValidationRegistry

propertyreadSourceValues

readonly readSourceValues?: (start: readonly [number, number], end: readonly [number, number]): readonly string[]

propertyreadValue

readonly readValue?: (row: number, column: number): unknown

propertyrequestRender

readonly requestRender?: (): void

interfaceSheetDataValidationPluginState source ↗

interface SheetDataValidationPluginState

propertydataValidations

readonly dataValidations: DataValidationMatrix

typeDataValidationDropdownMode source ↗

type DataValidationDropdownMode = typeof DataValidationDropdownMode[keyof typeof DataValidationDropdownMode]

Dropdown selection mode stored with a rule.

typeDataValidationExternalEvaluator source ↗

type DataValidationExternalEvaluator = (condition: DataValidationCondition, text: string, row: number, column: number): boolean | null

typeDataValidationInputPolicy source ↗

type DataValidationInputPolicy = typeof DataValidationInputPolicy[keyof typeof DataValidationInputPolicy]

Invalid input policy stored with a rule.

typeDataValidationKind source ↗

type DataValidationKind = typeof DataValidationKind[keyof typeof DataValidationKind]

One supported validation value family.

typeDataValidationOperator source ↗

type DataValidationOperator = typeof DataValidationOperator[keyof typeof DataValidationOperator]

One comparison operator for a validation condition.

typeDataValidationTextMode source ↗

type DataValidationTextMode = typeof DataValidationTextMode[keyof typeof DataValidationTextMode]

Text comparison mode stored with a rule.

variableClearDataValidationRulesCommand source ↗

ClearDataValidationRulesCommand: SheetCommandDefinition<{ range?: SheetRangeInput }, SheetCommandResult>

Removes every rule, or only rule fragments within a range.

variableDataValidationDropdownMode source ↗

DataValidationDropdownMode: { Multiple: "multiple"; Single: "single" }

Selection modes for dropdown validation.

variableDataValidationEvaluatorRegistryCapability source ↗

DataValidationEvaluatorRegistryCapability: RuntimeCapability<DataValidationEvaluatorRegistry>

variableDataValidationInputPolicy source ↗

DataValidationInputPolicy: { Reject: "reject"; Warn: "warn" }

Action to take when an entered value does not satisfy a rule.

variableDataValidationKind source ↗

DataValidationKind: { Attachment: "attachment"; Checkbox: "checkbox"; Date: "date"; Document: "document"; Dropdown: "dropdown"; Formula: "formula"; IdentityCard: "identityCard"; Image: "image"; … }

Supported validation value families.

variableDataValidationOperator source ↗

DataValidationOperator: { Between: "between"; Contains: "contains"; EndsWith: "endsWith"; Equal: "equal"; Greater: "greater"; GreaterOrEqual: "greaterOrEqual"; Less: "less"; LessOrEqual: "lessOrEqual"; … }

Comparison operators shared by numeric, date, and text validation.

variableDataValidationTextMode source ↗

DataValidationTextMode: { Content: "content"; Length: "length" }

Whether text validation compares content or character count.

variableDataValidationWarningObservation source ↗

DataValidationWarningObservation: EventObservationDefinition<DataValidationWarning>

variableReadDataValidationCellRulesQuery source ↗

ReadDataValidationCellRulesQuery: SheetQueryDefinition<readonly [number, number], readonly PositionedDataValidationRule[]>

Reads the rules that cover one cell.

variableReadDataValidationIssueQuery source ↗

ReadDataValidationIssueQuery: SheetQueryDefinition<readonly [number, number], DataValidationIssue | null>

Reads a definite validation failure for the current value of one cell.

variableReadDataValidationRulesQuery source ↗

ReadDataValidationRulesQuery: SheetQueryDefinition<void, readonly PositionedDataValidationRule[]>

Reads all persisted validation rules and their range anchors.

variableRemoveDataValidationRuleCommand source ↗

RemoveDataValidationRuleCommand: SheetCommandDefinition<{ id: string }, SheetCommandResult>

Removes a rule by its stable identifier.

variableSetDataValidationRuleCommand source ↗

SetDataValidationRuleCommand: SheetCommandDefinition<SetDataValidationRuleInput, SheetCommandResult>

Creates or updates a validation rule for a sheet range.

variableSheetDataValidationFieldKey source ↗

SheetDataValidationFieldKey: "sheet.dataValidation"

Sheet data-view field contributed by the validation plugin.

variableUnregisterDataValidationEvaluatorCommand source ↗

UnregisterDataValidationEvaluatorCommand: SheetCommandDefinition<number, SheetCommandResult>

Removes one editor-local external data-validation evaluator.

functionevaluateDataValidation source ↗

evaluateDataValidation(condition: DataValidationCondition, text: string, context: DataValidationEvaluationContext): boolean | null

Returns null when a host-owned value type has no evaluator. Empty input is allowed.

condition: DataValidationCondition
text: string
context: DataValidationEvaluationContext

functionformatDropdownSelection source ↗

formatDropdownSelection(values: readonly string[]): string

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

values: readonly string[]

functionparseDropdownSelection source ↗

parseDropdownSelection(text: string): string[]

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

text: string

functionreadSheetDataValidations source ↗

readSheetDataValidations(dataEngine: DataEngine): DataValidationMatrix | null

Reads the current validation matrix from the sheet data view.

dataEngine: DataEngine