FilterBar

Filters is garn's agent-native filter system — a headless useFilters<T> engine plus a FilterBar compound, the same shape as Sortable (an engine + a composed UI that re-skins nothing). The reliable unit is an editable pill: field · operator · value, where the operator set is a pure function of the field's type, so an impossible query — a comparison on an enum, contains on a number — simply can't be authored. Below the pills, useFilters owns a serializable, nestable FilterModel ({ id, conjunction, rules }, recursive), compiles it to a memoized pure predicate for the client (or a query object for a server seam), and round-trips through the URL with validate-and-repair so a shared link that references a since-removed field drops the stale rule instead of crashing.

On top of the pills sit the layers best-in-class products ship: faceted counts (count-annotated multi-selects, recomputed with the disjunctive two-query trick so OR-siblings don't zero out), a relative-date engine that ships rolling windows AND calendar buckets labelled distinctly (the reliability win — a rolling "past week" is 7 days; a calendar "this week" is Mon–Sun), first-class date between, saved views from an injectable store, nested AND/OR groups (one conjunction per group, ~3-level cap), and the 2026 headline — a natural-language Ask bar that returns editable chips, never a black-box answer. A FilterApi handle (addRule / setModel / fromNaturalLanguage / toQuery / …) is the seam an agent, an MCP tool, or the Ask parser drives.

Give it a field schema, and let type derive the rest. Each FilterField is { id, label, type, … } — the type picks the operator set and the value editor automatically. Reach for the escapes (operators to restrict by id, getOperators to derive functionally) only when the type defaults don't fit; the whole point is that impossible queries are unrepresentable.

Two ways to wire it. For a self-contained bar, pass fields (+ records for the live count) to <FilterBar> and it owns its own engine. For a data-table or CollectionView, create the engine yourself with useFilters and pass it via engine, then read engine.matches / engine.predicate to drive the rows — the bar and the table share one model.

A pending chip doesn't filter. A rule with no valid value renders neutral + dashed (data-state="pending") and is excluded from the predicate; it earns its field tone and starts filtering only once complete. That neutral rendering is deliberate — tone means "this condition is live."

Label rolling vs calendar dates for your users, and don't promise exact counts at scale. The engine ships both relative families distinctly on purpose. Faceted counts are the highest-leverage feature (they prevent zero-result dead-ends) but degrade to approximate on large sets — surface that, don't imply precision.

The URL is the source of truth for the active filter. Use the serialize/deserialize helpers (or the optional useFilterUrlState hook) so a filtered view is shareable and back-button-safe; saved views are named objects that set it.

Date rule values are yyyy-MM-dd calendar dates. The date editors (and the NL parser) commit zoneless yyyy-MM-dd strings — the same shape the engine's own asDate coercion local-parses back — never UTC ISO instants, so a stored or shared filter can't drift a day across timezones. Values you inject via addRule/setModel should use the same format (a Date or epoch number is also accepted on input).