themelia-ui 2.0.0 → 3.0.0

package/.agents/skills/themelia-ui/references/components/features--filters.md

@@ -1,924 +0,0 @@
-<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
-
-# `features/filters`
-
-Users build predicates over fields, with operators, editors and pills.
-
-## Selection
-
-- **Use when:** Users build predicates over fields, with operators, editors and pills.
-- **Avoid when:** Filtering is one search box, or the choices are fixed tabs.
-- **Consider instead:** `features/data-view`, `base/text-inputs`
-- **Stability:** stable.
-
-## Import
-
-```tsx fragment — import-only example
-import { AsyncFilterEditor } from "themelia-ui/features/filters"
-import "themelia-ui/features/filters.css"
-```
-
-## Composition
-
-This family composes `base/badge`, `base/buttons`, `base/choice-inputs`, `base/command`, `base/date-pickers`, `base/dropdown-menu`, `base/feedback`, `base/item`, `base/navigation`, `base/overlay`, `base/popover`, `base/popover-menu`, `base/sheet`, `base/spinner`, `base/text-inputs`, `base/typography`, `base/value-inputs`.
-
-Application policy—routing, fetching, persistence, permissions, and translation—stays
-outside the package and arrives through the public props, callbacks, slots, or accessors below.
-
-## Public declarations
-
-### `ActiveFilter`
-
-Kind: interface.
-
-One filter, applied.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `key` | yes | `string` |  |
-| `operator` | yes | `FilterOperator` |  |
-| `value` | yes | `string[]` |  |
-
-### `AsyncFilterEditor`
-
-Kind: callable.
-
-```text
-(props: FilterEditorProps) => import("react").JSX.Element
-```
-
-### `AsyncSelectConfig`
-
-Kind: interface.
-
-Async options for an `async_select`: one config owning search, caching, abort and preload.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `fetcher` | yes | `(args: { query: string; limit: number; signal?: AbortSignal; }) => Promise<TItem[]>` |  |
-| `mapToOption` | yes | `{ bivarianceHack(item: TItem): FilterOption; }["bivarianceHack"]` | Turns a fetched item into something the list can draw. |
-| `limit` | no | `number` |  |
-| `minQueryLength` | no | `number` | Below this many characters nothing is fetched. |
-| `preload` | no | `boolean` | Fetch with an empty query as soon as the list opens. |
-| `debounceMs` | no | `number` |  |
-| `staleTime` | no | `number` | How long a cached result stays fresh. |
-
-### `createFilterCache`
-
-Kind: callable.
-
-A cache with its own lifetime.
-
-```tsx fragment — declaration JSDoc excerpt
-// One cache for the whole session, so filters survive navigation:
-const cache = useMemo(() => createFilterCache(), [])
-<FilterProvider cache={cache} …>
-```
-
-Passing none is the ordinary case — `FilterProvider` makes one per mount.
-
-```text
-() => FilterCache
-```
-
-### `DateFilterEditor`
-
-Kind: callable.
-
-```text
-({ filter, value, onValueChange, onBack, triggerSource, }: FilterEditorProps) => import("react").JSX.Element
-```
-
-### `defaultFilterStrings`
-
-Kind: const.
-
-```text
-FilterStrings
-```
-
-### `defineAsyncSelectConfig`
-
-Kind: callable.
-
-Infers the item type once across `fetcher` and `mapToOption`, which a heterogeneous `FilterConfig[]` would widen to `unknown`.
-
-```text
-(config: AsyncSelectConfig<TItem>) => AsyncSelectConfig<TItem>
-```
-
-### `DisplayConfig`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `display` | no | `FilterDisplay` |  |
-| `priority` | no | `number` | Lower sorts earlier in the bar. |
-| `hidden` | no | `boolean` |  |
-| `className` | no | `string` |  |
-
-### `FilterCache`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `getOptions` | yes | `FilterOption[] \| undefined` | Cached options for a `(filter, query)` key, or `undefined` when there are none. |
-| `setOptions` | yes | `void` | Remember a query's options and schedule their expiry `staleTime` ms from now. |
-| `deleteOptions` | yes | `void` | Forget one query's options — what `refetch` does before asking again. |
-| `getLabel` | yes | `FilterOption \| undefined` | The option behind a value a pill is displaying, if this cache ever saw it. |
-| `rememberLabels` | yes | `boolean` | Remember the labels in a result set. Returns whether any were new, so callers can skip re-rendering pills. |
-| `clear` | yes | `void` | Drop everything and cancel every pending expiry. |
-
-### `FilterConfig`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `key` | yes | `string` |  |
-| `label` | yes | `string` |  |
-| `pluralLabel` | no | `string` | Used in "3 statuses selected". Falls back to `label`. |
-| `type` | yes | `FilterType` |  |
-| `description` | no | `string` |  |
-| `operator` | no | `FilterOperator` |  |
-| `operators` | no | `OperatorOption[]` |  |
-| `options` | no | `FilterOption[]` |  |
-| `placeholder` | no | `string` |  |
-| `delay` | no | `number` | Debounce for a `search` filter, in ms. |
-| `icon` | no | `ReactNode` |  |
-| `displayConfig` | no | `DisplayConfig` |  |
-| `defaultValue` | no | `string[]` |  |
-| `validation` | no | `ValidationConfig` |  |
-| `dependencies` | no | `FilterDependency[]` |  |
-| `multiple` | no | `boolean` |  |
-| `closeOnSelect` | no | `boolean` | Closes the editor as soon as one option is picked. Single-select only. |
-| `maxSelected` | no | `number` |  |
-| `asyncConfig` | no | `AsyncSelectConfig` |  |
-| `dateFormat` | no | `{ display?: string; param?: string; }` |  |
-| `format` | no | `(value: string[]) => string` | Replaces the default rendering of the value in the pill. |
-
-### `FilterContextValue`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `activeFilters` | yes | `ActiveFilter[]` |  |
-| `filters` | yes | `FilterConfig[]` |  |
-| `addFilter` | yes | `(filter: ActiveFilter) => void` |  |
-| `removeFilter` | yes | `(key: string) => void` |  |
-| `updateFilter` | yes | `(key: string, updates: Partial<ActiveFilter>) => void` |  |
-| `clearFilters` | yes | `() => void` |  |
-| `replaceFilters` | yes | `(filters: ActiveFilter[]) => void` |  |
-| `getFilterByKey` | yes | `(key: string) => FilterConfig \| undefined` |  |
-| `getFilterValue` | yes | `(key: string) => string[]` |  |
-| `setFilterValue` | yes | `(key: string, value: string[]) => void` |  |
-| `isFilterActive` | yes | `(key: string) => boolean` |  |
-| `getFilterOperator` | yes | `(key: string) => FilterOperator` |  |
-| `setFilterOperator` | yes | `(key: string, operator: FilterOperator) => void` |  |
-| `validateFilter` | yes | `(key: string, value: unknown) => boolean \| string` |  |
-| `getDependentFilters` | yes | `(key: string) => FilterConfig[]` |  |
-| `isNavigating` | yes | `boolean` | A change is in flight — the bar dims rather than pretending it has applied. |
-| `strings` | yes | `FilterStrings` |  |
-| `cacheAsyncOptions` | yes | `(filterKey: string, options: FilterOption[]) => void` | Remembers labels an async filter resolved, so a pill can name its own value. |
-| `getAsyncOptionLabel` | yes | `(filterKey: string, value: string) => string \| undefined` |  |
-| `reportError` | yes | `FilterErrorHandler` |  |
-
-### `FilterDependency`
-
-Kind: interface.
-
-This filter only applies once another one has a value.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `key` | yes | `string` |  |
-| `operator` | yes | `FilterOperator` |  |
-| `value` | yes | `string \| string[]` |  |
-
-### `FilterDisplay`
-
-Kind: type.
-
-Where a filter lives in the bar: `always` shows its pill even without a value; `collapsed`
-hides it behind the add button until it has one; `hidden` applies without any UI.
-
-```text
-"always" | "collapsed" | "hidden"
-```
-
-### `FilterEditor`
-
-Kind: callable.
-
-Dispatches on the filter's type. One place that knows which editor a type gets.
-
-```text
-(props: FilterEditorProps) => import("react").JSX.Element
-```
-
-### `FilterEditorProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `filter` | yes | `FilterConfig` |  |
-| `value` | yes | `string[]` |  |
-| `onValueChange` | yes | `(value: string[]) => void` |  |
-| `onBack` | yes | `() => void` |  |
-| `onClose` | yes | `() => void` |  |
-| `triggerSource` | no | `FilterTriggerSource` | Only a toolbar-opened editor has a list to go back to. |
-
-### `FilterErrorBoundary`
-
-Kind: callable.
-
-```text
-(props: FilterErrorBoundaryProps) => import("react").JSX.Element
-```
-
-### `FilterErrorBoundaryProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `children` | yes | `ReactNode` |  |
-| `filterKey` | no | `string` | Which filter this content edits. Names the filter in the message. |
-| `fallback` | no | `ReactNode` | Replaces the default message entirely. |
-| `className` | no | `string` |  |
-
-### `FilterErrorContext`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `phase` | yes | `"fetch-options" \| "apply" \| "validate" \| "render"` |  |
-| `filterKey` | no | `string` |  |
-| `info` | no | `string` | React's component stack, when the error came from a render. |
-
-### `FilterErrorHandler`
-
-Kind: type.
-
-```text
-(error: unknown, context: FilterErrorContext) => void
-```
-
-### `FilterLayout`
-
-Kind: callable.
-
-```text
-({ className, dynamicFilterOptions, loadingFilters, variant, showClearFilters, tabs, mobilePresentation, }: FilterLayoutProps) => import("react").JSX.Element
-```
-
-### `FilterLayoutProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `className` | no | `string` |  |
-| `dynamicFilterOptions` | no | `Record<string, FilterConfig["options"]>` | Options loaded by the parent, keyed by filter. Overrides `filter.options`. |
-| `loadingFilters` | no | `Record<string, boolean>` | Per-filter pending state — a chip stands in while its options load. |
-| `variant` | no | `"default" \| "compact"` |  |
-| `showClearFilters` | no | `boolean` |  |
-| `tabs` | no | `FilterTab[]` |  |
-| `mobilePresentation` | no | `"sheet" \| "inline"` | Narrow viewports use a sheet; opt into inline controls for a custom mobile layout. |
-
-### `FilterOperator`
-
-Kind: type.
-
-```text
-(typeof FilterOperator)[keyof typeof FilterOperator]
-```
-
-### `FilterOperatorSelect`
-
-Kind: callable.
-
-```text
-({ operator, operators, onOperatorChange, }: FilterOperatorSelectProps) => import("react").JSX.Element
-```
-
-### `FilterOperatorSelectProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `operator` | yes | `FilterOperator` |  |
-| `operators` | yes | `OperatorOption[]` |  |
-| `onOperatorChange` | yes | `(operator: FilterOperator) => void` |  |
-
-### `FilterOperatorStrings`
-
-Kind: interface.
-
-Filter copy. Interpolated strings are functions, not templates, so translations can reorder parts.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `contains` | yes | `string` |  |
-| `equals` | yes | `string` |  |
-| `notContains` | yes | `string` |  |
-| `is` | yes | `string` |  |
-| `isNot` | yes | `string` |  |
-| `greaterThan` | yes | `string` |  |
-| `lessThan` | yes | `string` |  |
-| `before` | yes | `string` |  |
-| `after` | yes | `string` |  |
-| `between` | yes | `string` |  |
-| `has` | yes | `string` |  |
-| `hasAny` | yes | `string` |  |
-| `hasAll` | yes | `string` |  |
-
-### `FilterOption`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `label` | yes | `string` |  |
-| `value` | yes | `string` |  |
-| `icon` | no | `ReactNode` |  |
-| `description` | no | `string` |  |
-| `disabled` | no | `boolean` |  |
-
-### `FilterPill`
-
-Kind: callable.
-
-```text
-({ filter, value, active, operator, operators, onOperatorChange, onValueChange, onClear, className, }: FilterPillProps) => import("react").JSX.Element
-```
-
-### `FilterPillProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `filter` | yes | `FilterConfig` |  |
-| `value` | yes | `string[]` |  |
-| `active` | yes | `boolean` | Whether the filter currently applies. Drives the clear segment. |
-| `operator` | yes | `FilterOperator` |  |
-| `operators` | yes | `OperatorOption[]` |  |
-| `onOperatorChange` | yes | `(operator: FilterOperator) => void` |  |
-| `onValueChange` | yes | `(value: string[]) => void` |  |
-| `onClear` | yes | `() => void` |  |
-| `className` | no | `string` |  |
-
-### `FilterProvider`
-
-Kind: callable.
-
-```text
-({ children, filters, activeFilters, onFilterChange, navigating, strings, onError, cache, }: FilterProviderProps) => import("react").JSX.Element
-```
-
-### `FilterProviderProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `children` | yes | `ReactNode` |  |
-| `filters` | yes | `FilterConfig[]` |  |
-| `activeFilters` | yes | `ActiveFilter[]` |  |
-| `onFilterChange` | yes | `(filters: ActiveFilter[]) => void` |  |
-| `navigating` | no | `boolean` | A change is in flight. The bar dims rather than pretending it has applied. |
-| `strings` | no | `Partial<FilterStrings>` |  |
-| `onError` | no | `FilterErrorHandler` | Receives fetch, validation, apply, and render failures. |
-| `cache` | no | `FilterCache` | The async option and label cache. Defaults to one per mounted provider; pass a<br>`createFilterCache()` instance to keep results and pill labels across navigation. |
-
-### `FilterQueryArrayFormat`
-
-Kind: type.
-
-`repeat` writes `tag=a&tag=b`; `comma` writes `tag=a,b`.
-
-```text
-"repeat" | "comma"
-```
-
-### `FilterQueryInput`
-
-Kind: type.
-
-```text
-URLSearchParams | Record<string, FilterQueryValue>
-```
-
-### `FilterQueryOperatorMode`
-
-Kind: type.
-
-```text
-"changed" | "always" | "never"
-```
-
-### `FilterQueryOptions`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `operatorSuffix` | no | `string` |  |
-| `arrayFormat` | no | `FilterQueryArrayFormat` |  |
-| `preserveUnrelated` | no | `boolean` | Keeps query keys this does not own. |
-| `resetPageKeys` | no | `readonly string[]` | Dropped whenever the filters change — page 4 of the old result set is meaningless. |
-| `includeOperators` | no | `FilterQueryOperatorMode` |  |
-
-### `FilterQueryRecord`
-
-Kind: type.
-
-```text
-Record<string, string | string[] | undefined>
-```
-
-### `FilterQueryValue`
-
-Kind: type.
-
-```text
-string | number | boolean | null | undefined | readonly (string | number | boolean | null | undefined)[]
-```
-
-### `FiltersButton`
-
-Kind: callable.
-
-**Use when:** A compact entry point to filters in an overlay, especially on mobile.
-
-**Avoid when:** Always-visible filter controls with sufficient room.
-
-**Compose:** Use inside the filter provider so desktop and mobile share the same filter state.
-
-**Capabilities:** mobile filters overlay; compact responsive filter trigger.
-
-**Alternatives:** SearchFilters.
-
-```text
-({ availableFilters, labelVisibility, className }: FiltersButtonProps) => import("react").JSX.Element
-```
-
-### `FiltersButtonProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `availableFilters` | yes | `FilterConfig[]` | Filters with no value yet. |
-| `labelVisibility` | no | `"hidden" \| "visible"` | Icon-only is the compact toolbar default; visible suits a standalone call to action. |
-| `className` | no | `string` |  |
-
-### `FilterState`
-
-Kind: interface.
-
-No own members are present in the normalized public snapshot.
-
-### `FilterStrings`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `loading` | yes | `string` |  |
-| `loadingOptions` | yes | `(filterLabel: string) => string` |  |
-| `applying` | yes | `string` |  |
-| `savedViews` | yes | `string` |  |
-| `customView` | yes | `string` |  |
-| `mobileFilters` | no | `string` | Mobile filter sheet copy. Optional for existing complete translations. |
-| `filterSummary` | no | `(count: number) => string` |  |
-| `done` | no | `string` |  |
-| `clearFilter` | no | `(filterLabel: string) => string` |  |
-| `addFilter` | yes | `string` |  |
-| `clear` | yes | `string` |  |
-| `edit` | yes | `string` | Names the pill's value segment, which opens the editor. |
-| `confirm` | yes | `string` |  |
-| `clearFilters` | yes | `string` |  |
-| `selectDate` | yes | `string` |  |
-| `searchPlaceholder` | yes | `(filterLabel: string) => string` |  |
-| `noOptionsFound` | yes | `string` |  |
-| `selected` | yes | `(count: number, filterLabel: string) => string` |  |
-| `nothingSelected` | yes | `string` | The pill's value segment before anything has been picked. |
-| `enterTags` | yes | `string` |  |
-| `searchFilters` | yes | `string` |  |
-| `noFiltersAvailable` | yes | `string` |  |
-| `availableFilters` | yes | `string` |  |
-| `activeFilters` | yes | `string` |  |
-| `backToFilters` | yes | `string` |  |
-| `options` | yes | `(count: number) => string` |  |
-| `operator` | yes | `string` |  |
-| `operators` | yes | `FilterOperatorStrings` |  |
-| `min` | yes | `string` |  |
-| `max` | yes | `string` |  |
-| `fetchError` | yes | `string` |  |
-| `retryFetch` | yes | `string` |  |
-| `minQueryHint` | yes | `(min: number) => string` |  |
-| `searching` | yes | `string` |  |
-| `error` | yes | `{ title: string; describe: (filterKey?: string) => string; retry: string; }` |  |
-| `validation` | yes | `{ required: string; minValue: (min: number) => string; maxValue: (max: number) => string; invalidFormat: string; }` |  |
-
-### `FilterTab`
-
-Kind: interface.
-
-A saved set of filters, offered as a tab above the bar.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `label` | yes | `string` |  |
-| `presets` | yes | `FilterTabPreset[]` |  |
-| `count` | no | `number` |  |
-
-### `FilterTabPreset`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `key` | yes | `string` |  |
-| `value` | yes | `string[]` |  |
-| `operator` | no | `FilterOperator` |  |
-
-### `FilterTabs`
-
-Kind: callable.
-
-```text
-({ tabs, display, label, className }: FilterTabsProps) => import("react").JSX.Element
-```
-
-### `FilterTabsProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `tabs` | yes | `FilterTab[]` |  |
-| `display` | no | `"tabs" \| "select"` | Compact saved-view control using the same presets and matching as the tab row. |
-| `label` | no | `string` | Accessible name for either presentation. |
-| `className` | no | `string` |  |
-
-### `FilterTriggerSource`
-
-Kind: type.
-
-Where the editor was opened from, which decides whether there is a way back.
-
-```text
-"toolbar" | "chip"
-```
-
-### `FilterType`
-
-Kind: type.
-
-```text
-(typeof FilterType)[keyof typeof FilterType]
-```
-
-### `FilterValueDisplay`
-
-Kind: callable.
-
-```text
-({ filter, value, className }: FilterValueDisplayProps) => import("react").JSX.Element
-```
-
-### `FilterValueDisplayProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `filter` | yes | `FilterConfig` |  |
-| `value` | yes | `string[]` |  |
-| `className` | no | `string` |  |
-
-### `formatFilterValue`
-
-Kind: callable.
-
-The value as the pill says it: the consumer's `format`, else option labels, else the raw strings.
-
-```text
-(filter: FilterConfig, value: string[], strings: FilterStrings, resolveAsyncLabel?: (value: string) => string | undefined) => string
-```
-
-### `getDateOperators`
-
-Kind: callable.
-
-```text
-(strings: FilterOperatorStrings) => OperatorOption[]
-```
-
-### `getDefaultOperatorForType`
-
-Kind: callable.
-
-The comparison a filter type starts on (e.g. search → contains).
-
-```text
-(type: FilterType) => FilterOperator
-```
-
-### `getFilterOption`
-
-Kind: callable.
-
-```text
-(filter: FilterConfig, value: string) => FilterOption | undefined
-```
-
-### `getNumberOperators`
-
-Kind: callable.
-
-```text
-(strings: FilterOperatorStrings) => OperatorOption[]
-```
-
-### `getOperatorsForType`
-
-Kind: callable.
-
-```text
-(type: FilterType, strings: FilterOperatorStrings) => OperatorOption[]
-```
-
-### `getSelectOperators`
-
-Kind: callable.
-
-```text
-(strings: FilterOperatorStrings) => OperatorOption[]
-```
-
-### `getTagsOperators`
-
-Kind: callable.
-
-```text
-(strings: FilterOperatorStrings) => OperatorOption[]
-```
-
-### `getTextOperators`
-
-Kind: callable.
-
-```text
-(strings: FilterOperatorStrings) => OperatorOption[]
-```
-
-### `mergeFilterQuery`
-
-Kind: callable.
-
-Lays one query over another, dropping the page keys.
-
-```text
-(currentQuery: FilterQueryInput, nextFilterQuery: FilterQueryInput, options?: Pick<FilterQueryOptions, "preserveUnrelated" | "resetPageKeys">) => FilterQueryRecord
-```
-
-### `OperatorOption`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `label` | yes | `string` |  |
-| `value` | yes | `FilterOperator` |  |
-
-### `parseFiltersFromQuery`
-
-Kind: callable.
-
-```text
-(filterConfigs: readonly FilterConfig[], query: FilterQueryInput, options?: FilterQueryOptions) => ActiveFilter[]
-```
-
-### `predicateValidator`
-
-Kind: callable.
-
-```text
-(predicate: (value: unknown) => boolean, message: string) => NonNullable<ValidationConfig["custom"]>
-```
-
-### `RangeFilterEditor`
-
-Kind: callable.
-
-```text
-({ filter, value, onValueChange, onBack, onClose, triggerSource, }: FilterEditorProps) => import("react").JSX.Element
-```
-
-### `SafeParseSchema`
-
-Kind: interface.
-
-Anything with Zod's `safeParse`. Zod 3, Zod 4, and a thin Valibot wrapper all fit.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `safeParse` | yes | `{ success: boolean; error?: { message?: string; issues?: { message: string; }[]; }; }` |  |
-
-### `SearchFilter`
-
-Kind: callable.
-
-```text
-({ filter, className }: SearchFilterProps) => import("react").JSX.Element
-```
-
-### `SearchFilterProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `filter` | yes | `FilterConfig` |  |
-| `className` | no | `string` |  |
-
-### `SearchFilters`
-
-Kind: callable.
-
-**Use when:** Search and filter controls for a resource collection.
-
-**Avoid when:** Owning a whole resource table or using a tab bar for filter editing.
-
-**Compose:** Compose with FilterProvider and public editors; reuse FiltersButton for compact overlay access.
-
-**Capabilities:** mobile filter overlay; filter operators pending validation; search resource filters.
-
-**Alternatives:** DataView, FiltersButton.
-
-```text
-({ filters, className }: SearchFiltersProps) => import("react").JSX.Element | null
-```
-
-### `SearchFiltersProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `filters` | yes | `FilterConfig[]` |  |
-| `className` | no | `string` |  |
-
-### `SelectFilterEditor`
-
-Kind: callable.
-
-```text
-(props: FilterEditorProps) => import("react").JSX.Element
-```
-
-### `serializeFiltersToQuery`
-
-Kind: callable.
-
-```text
-(filterConfigs: readonly FilterConfig[], activeFilters: readonly ActiveFilter[], currentQuery?: FilterQueryInput, options?: FilterQueryOptions) => FilterQueryRecord
-```
-
-### `TagsFilterEditor`
-
-Kind: callable.
-
-```text
-({ filter, value, onValueChange, onBack, onClose, triggerSource, }: FilterEditorProps) => import("react").JSX.Element
-```
-
-### `useAsyncOptions`
-
-Kind: callable.
-
-```text
-(filter: FilterConfig, search: string, isActive: boolean, options?: { onError?: FilterErrorHandler; }) => UseAsyncOptionsResult
-```
-
-### `UseAsyncOptionsResult`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `options` | yes | `FilterOption[]` |  |
-| `isLoading` | yes | `boolean` | The first load, with nothing to show yet. |
-| `isFetching` | yes | `boolean` | Any load, including a refresh over results already on screen. |
-| `isError` | yes | `boolean` |  |
-| `refetch` | yes | `() => void` |  |
-| `isBelowMinQuery` | yes | `boolean` | The query is too short to search on. |
-| `minQueryLength` | yes | `number` |  |
-
-### `useFilterCache`
-
-Kind: callable.
-
-The filter cache in scope, or `null` (then `useAsyncOptions` makes its own short-lived one).
-
-```text
-() => FilterCache | null
-```
-
-### `useFilterGroups`
-
-Kind: callable.
-
-```text
-({ dynamicFilterOptions, }?: UseFilterGroupsOptions) => UseFilterGroupsResult
-```
-
-### `UseFilterGroupsOptions`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `dynamicFilterOptions` | no | `Record<string, FilterConfig["options"]>` | Swaps a filter's options at render time, for options loaded by the parent. |
-
-### `UseFilterGroupsResult`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `processedFilters` | yes | `FilterConfig[]` |  |
-| `searchFilters` | yes | `FilterConfig[]` | Always inline, never in a pill — a search box IS its own control. |
-| `alwaysVisibleFilters` | yes | `FilterConfig[]` | `display: "always"`, and currently empty. |
-| `activeFilters` | yes | `FilterConfig[]` |  |
-| `popoverFilters` | yes | `FilterConfig[]` | Everything else that is empty: behind the add button. |
-| `activeFilterKeys` | yes | `string[]` |  |
-| `hasActive` | yes | `boolean` |  |
-
-### `useFilters`
-
-Kind: callable.
-
-```text
-() => FilterContextValue
-```
-
-### `validateFilterValue`
-
-Kind: callable.
-
-```text
-(filter: FilterConfig, value: unknown, strings: FilterStrings) => boolean | string
-```
-
-### `ValidationConfig`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `min` | no | `number` |  |
-| `max` | no | `number` |  |
-| `pattern` | no | `RegExp` |  |
-| `required` | no | `boolean` |  |
-| `custom` | no | `(value: unknown) => boolean \| string` | `true` passes; a string is the message; `false` is a generic failure. |
-
-### `zodValidator`
-
-Kind: callable.
-
-```text
-(schema: SafeParseSchema<TInput>) => NonNullable<ValidationConfig["custom"]>
-```
-
-## Preview recipes
-
-Preview route: Filters — `/filters`
-
-### The bar
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<FilterProvider
-  filters={filters}
-  activeFilters={active}
-  onFilterChange={setActive}
-  navigating={pending}
->
-  <FilterLayout tabs={savedViews} showClearFilters />
-</FilterProvider>
-
-// And when a change lands, hand the query to your own router:
-const query = serializeFiltersToQuery(filters, active)
-```