@searsuite/sear-plugin-filter

Filter rules and values

A filter definition names the range and its column rules. Value queries provide the choices shown in a filter menu.

interfaceReadSheetFilterValuesInput: Parameters for a bounded distinct-value query.

propertyreadonly column: number

propertyreadonly includeBlank?: boolean

Includes blank cells even when a host's visible blank label matches the search text.

propertyreadonly limit?: number

propertyreadonly search?: string
interfaceSheetFilterColumnRule: A rule attached to one column within a filter range.

propertyreadonly column: number

Zero-based sheet column index.

propertyreadonly predicate: SheetFilterPredicate

Predicate applied to values in the column.
interfaceSheetFilterDefinition: Document or private-session filter configuration for one sheet range.

propertyreadonly firstRowIsHeader: boolean

Whether the first row is always visible as a header.

propertyreadonly privateView: boolean

Whether this definition belongs to the current editor session.

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

Inclusive sheet coordinates covered by the filter.

propertyreadonly rules: readonly SheetFilterColumnRule[]

Active column predicates.
interfaceSheetFilterValueCount: One distinct displayed value and its occurrence count.

propertyreadonly count: number

propertyreadonly value: string
interfaceSheetFilterValuePage: Bounded distinct-value query result for a filter column.

propertyreadonly items: readonly SheetFilterValueCount[]

Matching values returned within the requested limit.

propertyreadonly truncated: boolean

Whether additional matching values were omitted.
typeSheetFilterCategory: type SheetFilterCategory = typeof SheetFilterCategory[keyof typeof SheetFilterCategory] SheetFilterCategory: { Date: "date"; Number: "number"; Text: "text" }

A condition filter's value category.
typeSheetFilterColorProperty: type SheetFilterColorProperty = typeof SheetFilterColorProperty[keyof typeof SheetFilterColorProperty] SheetFilterColorProperty: { Fill: "fill"; Text: "textColor" }

A cell visual property used by a color filter.
typeSheetFilterKind: type SheetFilterKind = typeof SheetFilterKind[keyof typeof SheetFilterKind] SheetFilterKind: { Color: "color"; Condition: "condition"; Values: "values" }

Supported filter rule kinds.
typeSheetFilterOperator: type SheetFilterOperator = typeof SheetFilterOperator[keyof typeof SheetFilterOperator] SheetFilterOperator: { Between: "between"; Contains: "contains"; EndsWith: "endsWith"; Equal: "equal"; Greater: "greater"; GreaterEqual: "greaterEqual"; Less: "less"; LessEqual: "lessEqual"; … }

A comparison operator supported by the filter plugin.
typeSheetFilterPredicate: type SheetFilterPredicate = { excluded?: boolean; kind: typeof SheetFilterKind.Values; values: readonly string[] } | { category: SheetFilterCategory; kind: typeof SheetFilterKind.Condition; operator: SheetFilterOperator; secondValue?: string; value: string } | { color: string | null; kind: typeof SheetFilterKind.Color; property: SheetFilterColorProperty }

Serializable rule used to decide whether a row remains visible.
variableReadSheetFilterQuery: ReadSheetFilterQuery: SheetQueryDefinition<void, SheetFilterDefinition | null>

Reads the active filter definition.
variableReadSheetFilterValuesQuery: ReadSheetFilterValuesQuery: SheetQueryDefinition<ReadSheetFilterValuesInput, SheetFilterValuePage>

Reads a bounded page of distinct displayed values in one column.
functionsheetFilterValueKey: sheetFilterValueKey(value: unknown): string

Uses display values for distinct-value selection, including an explicit blank key.

Apply and update filters

CreateSheetFilterCommand installs a filter, SetSheetColumnFilterCommand changes one column, and ReapplySheetFilterCommand refreshes row visibility.

classSheetFilterMatrix

class SheetFilterMatrix extends CSRMatrix<SheetFilterDefinition | null>

One sparse anchor holds the current range and its column rules.

constructor

SheetFilterMatrix(data?: { data: SheetFilterDefinition | null[]; indices: number[]; indptr: number[] }): SheetFilterMatrix

methodaddItem(row: number, column: number, value: SheetFilterDefinition | null): this

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

ReturnsThe current instance for chaining.

row: The row index.
value: The value to add.

methodclone(): this

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

methodgetItem(row: number, column: number): SheetFilterDefinition | 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.

Inherited members 32

Inherited from CSRMatrix.

classSheetFilterPlugin

class SheetFilterPlugin extends Plugin<unknown, CellProperties, SheetFilterPluginState>, SheetRowVisibility

Owns persisted filter rules and a derived, editor-local row visibility view.

constructorSheetFilterPlugin(state: SheetFilterPluginState, dependencies: SheetFilterDependencies): SheetFilterPlugin

propertyreadonly documentState: PluginDocumentStateContribution<SheetFilterPluginState, SheetFilterPluginState>

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<SheetFilterPluginState, SheetFilterPluginState>static

propertyreadonly pluginKey: PluginKeystatic

propertyreadonly symbol: typeof symbolstatic

memberactive

active: unknown

memberversion

version: unknown

methodapply(state: SheetFilterPluginState, transaction: Transaction): SheetFilterPluginState | 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.

methodisRowFiltered(row: number): boolean

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.

methodregisterCommands(commands: SheetCommandBus): void

methodregisterQueries(queries: SheetQueryRegistry): void

methodregisterSessionState(registry: SessionStateRegistry): void

method

registerState(): { dataEngine: { dataView: { fieldKey: string; select: (): SheetRowVisibility; viewKey: string }[] }; key: PluginKey; state: SheetFilterPluginState }

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

methodrender(): []

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

Inherited members 24

Inherited from Plugin.

interfaceCreateSheetFilterInput

Sheet range and header policy for a new filter or private view.

propertyreadonly firstRowIsHeader?: boolean

Treat the first row as a header when true.

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

Inclusive range to filter.

interfaceSetSheetColumnFilterInput

Sets or clears a predicate for one column.

propertyreadonly column: number

propertyreadonly predicate: SheetFilterPredicate | null

interfaceSheetFilterDependencies

interface SheetFilterDependencies extends Omit<SheetFilterCommandSource, "target" | "readMatrix" | "readActiveDefinition" | "readPrivateDefinition" | "setPrivateDefinition" | "normalizeSearch">

Host-neutral dependencies supplied by a Sheet composition root.

propertyreadonly dataTarget?: PluginKey

propertyreadonly displayedValueChanges?: Pick<SheetDisplayedValueChanges, "subscribe">

propertyreadonly invalidateVisibilityAggregates?: (): void

propertyreadonly parseDate?: (value: unknown): number | null

propertyreadonly platform: Pick<Platform, "toLowerCase">

propertyreadonly readColor: (row: number, column: number, property: "fill" | "textColor"): string | null

propertyreadonly requestRenderAll?: (): void

Inherited members 4