Filter Builder

InstallCopy Anchor Link

pnpm exec vegastack-design verify filter-bar-managed

pnpm dlx shadcn@4.21.0 add @vegastack/filter-bar-managed

UsageCopy Anchor Link

import {
  FilterBuilder,
  type FilterField,
  type FilterNode,
} from "@/components/ui/filter-bar-managed";

const VOCABULARY: FilterField<string>[] = [
  {
    key: "stage",
    label: "Stage",
    type: "text",
    operators: [{ value: "is", label: "is" }],
  },
];

const [tree, setTree] = useState<
  Extract<FilterNode<string>, { type: "group" }>
>({
  type: "group",
  op: "and",
  children: [],
});

<FilterBuilder vocabulary={VOCABULARY} value={tree} onValueChange={setTree} />;

This is the condition builder a list's advanced filters open, beside the FilterRow. The grammar is host-injected: the component owns the tree shape (FilterNode — nested and/or groups and condition rows) and its editing surface; your app supplies the vocabulary (which fields exist, which operators each accepts, which editor type renders the value) and the editors registry. The component never validates a field's semantics and never serialises — the moment it did either, it would have adopted one app's AST.

ScopeCopy Anchor Link

AnatomyCopy Anchor Link

FilterBuilder is the component; the five value editors (TextValueEditor, NumberValueEditor, NumberRangeEditor, OptionValueEditor, OptionsValueEditor) are the parts it renders a condition's value with, exported so a host can register or reuse them.

ExamplesCopy Anchor Link

Chip summaryCopy Anchor Link

readOnly collapses the builder to a flat FilterChip row (the and/or grouping is not visualised in the summary — reopen the builder to see structure). Chips stay removable — removing one prunes that condition from the tree — unless the builder is also disabled, which makes the summary inert.

One levelCopy Anchor Link

maxDepth={1} is a flat list of conditions: there is no "Add condition group" control, and no reason to explain one.

Operators and value shapesCopy Anchor Link

Give each operator a valueShape — none, scalar, list or range. Switching between two operators of the same shape keeps the value; switching to another shape clears it, so a single value never survives into "is any of". requiresValue: false is shorthand for none. A missing value shows "Value required" only after its control was left, or when the enclosing form is submitted — never on a row that was just added.

Condition rules (no groups)Copy Anchor Link

For a rule editor — "Required when …", "Shown when …" — allowGroups={false} keeps the conditions flat, prefix names the builder ("Required when" is the fieldset's name and leads the sentence), and labels renames its own words (addCondition, remove, matchAll, matchAny, empty, valueRequired, field, operator). conditionError(condition, path) returns a row's own message: it shows under the row and is read as its value editor's description, beside the built-in "Value required".

Sentence summaryCopy Anchor Link

summary="sentence" makes the read-only summary one sentence instead of chips. The same text comes from describeFilter(tree, vocabulary, { prefix }) — for a list cell, a tooltip or an audit line. Option values read by their labels, numbers carry the field's unit, ranges read as 10–20 W, ≥ 10 W or ≤ 20 W (formatRange), and nested groups read in parentheses.

Value editorsCopy Anchor Link

Five editors ship with the item, for the editors registry or on their own: TextValueEditor, NumberValueEditor (a NumberField with the field's unit), NumberRangeEditor (Minimum and Maximum; either may be empty, and a minimum above the maximum is an error on the Minimum field), OptionValueEditor and OptionsValueEditor (one or several of the field's options — one on a Select up to seven options and a SearchableSelect above seven, several always on a SearchableSelect multiple; both take placeholder and searchLabel). Without an entry in editors, a range operator gets NumberRangeEditor, a list operator on a field with options gets OptionsValueEditor, a field with options gets OptionValueEditor, and the rest get TextValueEditor. editors.range and editors.list override the shape defaults. A range operator ("is between") always gets two boxes — editors.range, else NumberRangeEditor — even when editors registers a single-value editor for the field's type, so "between" never stores one number. A minimum above the maximum reads "Minimum can't be more than maximum." under the pair.

For a long vocabulary, fieldPicker="searchable" makes each row's field picker a SearchableSelect; fieldPickerProps reaches it, so remote with useAsyncSearch searches the fields on the server (every field it offers must also be in vocabulary).

Dates, people, checkboxes and linksCopy Anchor Link

Four more editors cover a table's field types. DateValueEditor takes an exact day from the calendar or a relative date — Today, This week, Last N days ({ relative, days }), stored as ISO calendar days so no time zone moves them; for a range operator it takes two days ({ from, to }). PersonValueEditor offers the field's people (or its search) on PeoplePicker, with Me first, stored as FILTER_ME so a saved view means whoever opens it; a list operator picks several. CheckboxValueEditor stores true or false. LinkValueEditor searches records through the field's search (keyset paged, debounced, race-safe) and stores { id, label }.

A <type>:range or <type>:list key in editors ("date:range", "person:list") wins over the shape defaults for that type alone, so one editor can serve a type's every operator.

Sort and groupCopy Anchor Link

SortBuilder edits up to three sort keys ({ key, dir }, first one first) and GroupByPicker up to two grouping levels (outermost first), both from the same field vocabulary. Rows reorder by drag or SortableList's keyboard move mode, × removes one, and "Add sort" appends the next free field. GroupByPicker's button reads "Group by" while no level is set and "Add level" once one is, so it never shares a name with FilterBuilder's "Add condition group" (both are in labels). With readOnly both show removable FilterChips. They edit data; the host sorts and groups.

Depth and condition capsCopy Anchor Link

At a cap the add affordance stays focusable with aria-disabled (FRM-4), and the reason renders as visible text beside it.

API ReferenceCopy Anchor Link

Field definitionCopy Anchor Link

Value editor contractCopy Anchor Link

AccessibilityCopy Anchor Link

• The tree is nested <fieldset>/<legend> structure — deliberately not role="tree", where editing controls inside tree items are a known screen-reader trap. Every control stays an ordinary labelled form control.
• Removing a condition moves focus to the next condition in the same group, or to the group's add-condition button when it was the last — never back to the top of the page.
• A value-requiring condition without a value is flagged with visible text ("Value required") and data-invalid, never colour alone.
• A row's own error (conditionError) is read as the field picker's description, with aria-invalid — so it is announced even for an operator that takes no value.
• At the depth or condition cap the add affordances disable and the reason renders as visible text beside them.

Do / Don'tCopy Anchor Link