@searsuite/sear-plugin-data-validation

Set and read rules

SetDataValidationRuleCommand changes a range’s rule. Queries return the current rules and any issue for a cell.

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

Removes every rule, or only rule fragments within a range.
variableDataValidationWarningObservation: DataValidationWarningObservation: EventObservationDefinition<DataValidationWarning>
variableReadDataValidationCellRulesQuery: ReadDataValidationCellRulesQuery: SheetQueryDefinition<readonly [number, number], readonly PositionedDataValidationRule[]>

Reads the rules that cover one cell.
variableReadDataValidationIssueQuery: ReadDataValidationIssueQuery: SheetQueryDefinition<readonly [number, number], DataValidationIssue | null>

Reads a definite validation failure for the current value of one cell.
variableReadDataValidationRulesQuery: ReadDataValidationRulesQuery: SheetQueryDefinition<void, readonly PositionedDataValidationRule[]>

Reads all persisted validation rules and their range anchors.
variableRemoveDataValidationRuleCommand: RemoveDataValidationRuleCommand: SheetCommandDefinition<{ id: string }, SheetCommandResult>

Removes a rule by its stable identifier.
variableSetDataValidationRuleCommand: SetDataValidationRuleCommand: SheetCommandDefinition<SetDataValidationRuleInput, SheetCommandResult>

Creates or updates a validation rule for a sheet range.
variableSheetDataValidationFieldKey: SheetDataValidationFieldKey: "sheet.dataValidation"

Sheet data-view field contributed by the validation plugin.
variableUnregisterDataValidationEvaluatorCommand: UnregisterDataValidationEvaluatorCommand: SheetCommandDefinition<number, SheetCommandResult>

Removes one editor-local external data-validation evaluator.
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.
functionreadSheetDataValidations: readSheetDataValidations(dataEngine: DataEngine): DataValidationMatrix | null

Reads the current validation matrix from the sheet data view.
functionresolveDropdownSelection: resolveDropdownSelection(text: string, availableLabels: readonly string[]): string[]

Uses an exact option label when comma parsing cannot describe valid choices.

Evaluate input

evaluateDataValidation checks a candidate value against a rule. Register an external evaluator for conditions the built-in evaluator cannot resolve.

classDataValidationEvaluatorRegistry

Host extension point for structured values and custom formulas.

constructorDataValidationEvaluatorRegistry(): DataValidationEvaluatorRegistry

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

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

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

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

methodunregister(id: number): void

Removes a registration through the owning command after assembly.

classDataValidationMatrix

class DataValidationMatrix extends CSRMatrix<DataValidationRule[] | null>

Sparse range anchors for validation rules.

constructor

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

methodaddItem(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: The row index.

methodclone(): this

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

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

methodgetItem(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: The row index.

methodgetRules(): PositionedDataValidationRule[]

methodreplaceRules(entries: readonly PositionedDataValidationRule[]): void

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

Inherited members 32

Inherited from CSRMatrix.

classSheetDataValidationPlugin

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.

constructor

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

propertyreadonly documentState: PluginDocumentStateContribution<SheetDataValidationPluginState, SheetDataValidationPluginState>

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.

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

property

readonly 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<SheetDataValidationPluginState, SheetDataValidationPluginState>static

propertyreadonly pluginKey: PluginKeystatic

propertyreadonly symbol: typeof symbolstatic

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

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

methoddispose(): void

methodgetPluginConfig(): null

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

methodonTransactionCommitted(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: A committed transaction from the completed pipeline.

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

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

methodregisterCapabilities(registry: RuntimeCapabilityRegistry): void

methodregisterCellVisualReaders(registry: SheetCellVisualReaderRegistry): void

methodregisterCommands(commands: SheetCommandBus): void

methodregisterCommitStrategies(registry: CellCommitStrategyRegistry): void

methodregisterObservations(registry: ObservationRegistry): void

methodregisterQueries(queries: SheetQueryRegistry): void

methodregisterRangeMoves(registry: SheetRangeMoveRegistry): void

method

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(): Node<CellProperties>[]

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

methodsealRuntimeWrites(): void

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

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

Inherited members 23

Inherited from Plugin.

interfaceDataValidationCondition

Type-specific settings used to evaluate a cell value.

propertyreadonly dropdownMode?: DataValidationDropdownMode

propertyreadonly formula?: string

propertyreadonly integerOnly?: boolean

propertyreadonly kind: DataValidationKind

propertyreadonly operator?: DataValidationOperator

propertyreadonly options?: readonly DataValidationOption[]

propertyreadonly secondValue?: string

propertyreadonly showDropdownArrow?: boolean

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

propertyreadonly textMode?: DataValidationTextMode

propertyreadonly value?: string

interfaceDataValidationEvaluationContext

propertyreadonly column: number

propertyreadonly currentDateTime?: number

property

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

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

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

propertyreadonly row: number

interfaceDataValidationIssue

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

propertyreadonly column: number

propertyreadonly message: string

propertyreadonly row: number

propertyreadonly ruleId: string

interfaceDataValidationOption

One displayable dropdown choice and its optional color.

propertyreadonly color?: string

propertyreadonly label: string

interfaceDataValidationRule

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

propertyreadonly condition: DataValidationCondition

propertyreadonly endColumn: number

propertyreadonly endRow: number

propertyreadonly errorMessage?: string

propertyreadonly id: string

propertyreadonly inputMessage?: string

propertyreadonly inputPolicy: DataValidationInputPolicy

interfaceDataValidationWarning

propertyreadonly column: number

propertyreadonly message: string

propertyreadonly row: number

propertyreadonly ruleId: string

interfacePositionedDataValidationRule

A rule with its persisted range anchor.

propertyreadonly column: number

propertyreadonly row: number

propertyreadonly rule: DataValidationRule

interfaceSetDataValidationRuleInput

interface SetDataValidationRuleInput extends SheetRangeInput

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

propertyreadonly id?: string

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

Inherited members 2

Inherited from SheetRangeInput.

anchor
focus

interfaceSheetDataValidationDependencies

propertyreadonly createId: (): string

propertyreadonly currentDateTime?: (): number

propertyreadonly evaluators: DataValidationEvaluatorRegistry

propertyreadonly inputValidation: SheetCellInputValidationRegistry

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

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

propertyreadonly requestRender?: (): void

interfaceSheetDataValidationPluginState

propertyreadonly dataValidations: DataValidationMatrix

typeDataValidationDropdownMode

type DataValidationDropdownMode = typeof DataValidationDropdownMode[keyof typeof DataValidationDropdownMode] DataValidationDropdownMode: { Multiple: "multiple"; Single: "single" }

Dropdown selection mode stored with a rule.

typeDataValidationExternalEvaluator

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

typeDataValidationInputPolicy

type DataValidationInputPolicy = typeof DataValidationInputPolicy[keyof typeof DataValidationInputPolicy] DataValidationInputPolicy: { Reject: "reject"; Warn: "warn" }

Invalid input policy stored with a rule.

typeDataValidationKind

type DataValidationKind = typeof DataValidationKind[keyof typeof DataValidationKind]

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

One supported validation value family.

typeDataValidationOperator

type DataValidationOperator = typeof DataValidationOperator[keyof typeof DataValidationOperator]

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

One comparison operator for a validation condition.

typeDataValidationTextMode

type DataValidationTextMode = typeof DataValidationTextMode[keyof typeof DataValidationTextMode] DataValidationTextMode: { Content: "content"; Length: "length" }

Text comparison mode stored with a rule.

variableDataValidationEvaluatorRegistryCapability

DataValidationEvaluatorRegistryCapability: RuntimeCapability<DataValidationEvaluatorRegistry>

functionevaluateDataValidation

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

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

functionhasIntegerSolution

hasIntegerSolution(operator: DataValidationOperator, first: number, second?: number): boolean

Whether an integer can satisfy a numeric comparison. Bounds must already be finite.

functionparseDataValidationDate

parseDataValidationDate(value: string): number | null

Parses a real calendar date in the validation rule's YYYY-MM-DD format.