Filters API

FilterValue discriminated union, operator arrays + factories, evaluateFilter, advancedFilterFn, DateFilterPreset, and the built-in filter components. For tutorial-style how-to see ../guides/filters.md.

FilterValue Types#

import {type FilterValue, type FilterOperator} from '@workspace/active-grid';

FilterValue is a discriminated union based on the operator:

type FilterValue = NoValueFilter | SingleValueFilter | RangeFilter;
type NoValueFilter = {  operator: 'isEmpty' | 'isNotEmpty';};
type SingleValueFilter = {  operator: TextOperator | NumberOperator | DateOperator;  value: string | number | boolean;};
type RangeFilter = {  operator: 'between' | 'inRange';  value: string | number;  valueTo: string | number;};

Operator Types#

Operator Factories#

import {  getTextOperators,  getNumberOperators,  getDateOperators,  getBooleanOperators,  getOperatorsForType,} from '@workspace/active-grid';

Each factory takes a required GridTranslateFunction for the labels; there is no English default (pass englishGridTranslator for English).

type FilterOperatorOption = {  value: FilterOperator;  label: string;  requiresValue: boolean;  requiresSecondValue?: boolean;};
const operators: FilterOperatorOption[] = getNumberOperators(t);// → [{value: 'equals', label: t('grid.operators.equals'), requiresValue: true}, …]

DateFilterPreset#

import {  type DateFilterPreset,  DEFAULT_DATE_PRESETS,} from '@workspace/active-grid';

interface DateFilterPreset {  key: string; // Translation key (e.g., 'grid.filter.datePreset.today')  label?: string; // Optional display label — used instead of t(key) when provided  type: 'single' | 'range';  getValue: (presentation?: GridPresentation) => {from: Date; to?: Date};}

DEFAULT_DATE_PRESETS provides 8 built-in presets: today, yesterday, last 7 days, last 30 days, this month, last month, this quarter, this year. Relative presets require an explicit presentation time zone. Their dates carry calendar days, which the date filter serializes as yyyy-MM-dd. Pass a custom array via meta.dateFilterPresets or false to disable. How to write a custom preset without reading the browser's time zone: ../guides/filters.md § Date Filter Configuration.

evaluateFilter / advancedFilterFn / evaluateFilterExpression#

import {  evaluateFilter,  evaluateFilterExpression,  advancedFilterFn,} from '@workspace/active-grid';

createLocaleSortFn#

import {createLocaleSortFn} from '@workspace/active-grid';

Factory that produces a sort function using Intl.Collator for locale-aware string sorting. Default sort uses ASCII codepoints; for locale-correct ordering pass sortFn: createLocaleSortFn(locale) on relevant columns.

createLocaleSortFn(locale: string, options?: Intl.CollatorOptions)

• locale is required and must be a non-empty string; there is no host default. An empty or missing locale throws a TypeError.

• The collator defaults to {numeric: true, sensitivity: 'base'}; options are merged over those defaults.

• The returned function compares row.getValue(columnId) of two rows and returns a negative number, zero or a positive number. A string is compared as written, a finite number as its string form, and every other value (absent, NaN, ±Infinity, boolean, date, object) as the empty string.

Filter Components#

For custom filter UIs, the package exports the five built-in filter components plus a set of popover primitives.

import {  TextFilter,  NumberFilter,  DateFilter,  SelectFilter,  BooleanFilter,  FilterPopover,  FilterPopoverTrigger,  FilterPopoverContent,  FilterPopoverHeader,  FilterPopoverBody,  FilterIcon,  FilterClearButton,  FilterCheckboxItem,  FilterDateInput,  FilterNumberInput,  FilterOperatorSelect,  FilterSearchInput,  FilterTextInput,  FilterWrapper,} from '@workspace/active-grid';

In most cases the built-in filter row handles everything automatically based on meta.filterType — these exports are for custom filter-builder UIs and advanced consumers.

The layout contract of the filter row#

All six built-in filters share one internal anatomy, with one rule: the value gives way, the controls never do. That anatomy is an internal component and not a public export -- consumers do not compose it and do not need to know it.

[ value / input            ][ clear 24px ][ menu 24px ]  min-w-0, shrinks to zero     shrink-0      shrink-0

A filterable column automatically gets an effective minimum width of 80px. That floor is derived from the cell padding, the two targets and the gaps between them, and protects only the CONTROLS. It deliberately does not keep translated values readable: the same state needs 122px in English and 161px in Spanish, and the count in it is dynamic, so a floor that guarantees text does not exist.

The floor only RAISES. A column with a larger minSize of its own, or a grid with a larger defaultMinSize, is left alone; with settings.showFilterRow: false it does not apply.

A consumer does not need to declare anything for this. There is no prop, no opt-in and no migration, and there is no reason to add an own minWidth or a local CSS workaround for the clear button. A meta.customFilter deliberately falls outside the shell and owns its own anatomy.

Grounds and trade-off: DECISIONS.md ADR-027.

Filter Expression Tree#

For the AND/OR composite-filter UI, the package exports a small typed tree:

import {  type FilterExpression,  type FilterCondition,  type FilterGroup,  type FilterExpressionNode,  isFilterGroup,  evaluateFilterExpression,} from '@workspace/active-grid';

evaluateFilterExpression ignores an incomplete condition: one without an operator, or without a value its operator reads (undefined, null, '' or a non-finite number; 0 and false are values; a range needs both ends). isEmpty and isNotEmpty need no value. A group judges only its complete children, and a group without any matches every row.

Tutorial: ../guides/filter-builder.md.

Server-mode filtering#

active-grid does not build database queries. In mode="server" the filter and global-search state is forwarded verbatim in ServerFetchParams, and the resource view in @workspace/active-resources translates it into a query server-side (see ./resource-mode.md). The evaluateFilter / advancedFilterFn helpers above apply only to mode="client" in-memory filtering.