themelia-ui 2.0.0 → 3.0.0

package/dist/components/features/data-view/data-view.types.d.ts

@@ -45,13 +45,28 @@ export interface DataViewFilteringConfig<TData extends RowData> {
     filters: FilterConfig[];
     activeFilters: ActiveFilter[];
     onFilterChange: (filters: ActiveFilter[]) => void;
+    /**
+     * Replaces the built-in matching entirely. What a server-filtered index passes: the rows are
+     * already right, so nothing local runs.
+     */
     filterRows?: DataViewFilterRows<TData>;
+    /**
+     * Reads the value a filter compares against, for a nested or computed field. Without it the
+     * filter's key is read as a path.
+     */
     getFilterValue?: DataViewFilterValueGetter<TData>;
     tabs?: FilterTab[];
-    /** A tab row, or a select — the same saved views, at two widths. */
+    /**
+     * A tab row, or a select — the same saved views, at two widths. A tab row is better when it
+     * fits and useless when it does not, and a bar carrying five pills often does not.
+     */
     tabsDisplay?: "tabs" | "select";
     tabsLabel?: string;
-    /** Narrow viewports use the filters sheet by default. */
+    /**
+     * Below 768px, `sheet` keeps search inline and opens filter editors in an inset sheet.
+     * Choose `inline` for a caller-owned mobile layout.
+     * @default "sheet"
+     */
     mobilePresentation?: "sheet" | "inline";
     /** A change is in flight; the bar dims. */
     isFiltering?: boolean;
@@ -65,6 +80,7 @@ export interface DataViewSlots {
     topbarContent?: ReactNode;
     /** Leading content in the auxiliary row, beside the saved-view select. */
     toolbarStart?: ReactNode;
+    /** Content in the auxiliary row, after the saved-view select. */
     toolbarAfterFilters?: ReactNode;
     /** Trailing content in the table's topbar, beside its own controls. */
     topbarEnd?: ReactNode;
@@ -72,11 +88,30 @@ export interface DataViewSlots {
     footer?: ReactNode;
 }
 export interface DataViewProps<TData extends RowData, TValue = unknown> {
+    /** The rows, passed straight through to DataTable after the filters have run. */
     data: readonly TData[];
+    /** Passed straight through to DataTable. */
     columns: DataTableProps<TData, TValue>["columns"];
+    /**
+     * `filters`, `activeFilters` and `onFilterChange` are meaningless apart — two of the three
+     * describe a state nobody can read — so they travel as one object the whole feature can be
+     * optional on. Without it a DataView is a table in a frame.
+     */
     filtering?: DataViewFilteringConfig<TData>;
+    /**
+     * Customizes the filter failure warning, `filterError`. Filter-control copy belongs to
+     * `filtering.strings`; pager copy belongs to `DataViewPagination`'s `strings`.
+     */
     strings?: Partial<DataViewStrings>;
+    /**
+     * Everything DataTable takes except `columns`, `data`, `surface`, `headerTransparent`, and
+     * the two topbar slots — the view owns those.
+     */
     table?: DataViewTableOptions<TData, TValue>;
+    /**
+     * `topbarContent` above the bar, `toolbarStart` and `toolbarAfterFilters` around the
+     * saved-view select, `topbarEnd` beside the table's controls, `footer` below the table.
+     */
     slots?: DataViewSlots;
     className?: string;
 }

package/dist/components/features/data-view/use-data-view.d.ts

@@ -1,2 +1,8 @@
 import { UseDataViewOptions, UseDataViewResult } from './data-view.types.js';
+/**
+ * The rows after filtering, plus `failed` and the `error` for a custom surface. If a matcher
+ * throws, the unfiltered rows come back with `failed` set and `onError` called, rather than a
+ * misleading empty list; DataView shows a warning for this fallback, which `strings.filterError`
+ * customizes.
+ */
 export declare function useDataView<TData extends object>({ data, filtering, }: UseDataViewOptions<TData>): UseDataViewResult<TData>;

package/dist/components/features/event-calendar/event-calendar-day-cell.d.ts

@@ -1,2 +1,7 @@
 import { EventCalendarDayCellProps } from './event-calendar.types.js';
+/**
+ * One day in the grid. Deliberately not a button: a cell holds events that are themselves
+ * pressable, and nesting controls makes both unreachable by keyboard. The day number is the
+ * keyboard affordance; the cell's click only widens the pointer target.
+ */
 export declare function EventCalendarDayCell({ data, categories, maxEvents, onClick, onEventClick, compact, strings, renderEvent, }: EventCalendarDayCellProps): import("react").JSX.Element;

package/dist/components/features/event-calendar/event-calendar-event-badge.d.ts

@@ -1,2 +1,6 @@
 import { EventCalendarEventBadgeProps } from './event-calendar.types.js';
+/**
+ * One event as a chip in a day cell: a category dot, the title and the start time. At the
+ * narrowest widths only the dot remains.
+ */
 export declare function EventCalendarEventBadge({ event, category, compact, onClick, strings, }: EventCalendarEventBadgeProps): import("react").JSX.Element;

package/dist/components/features/event-calendar/event-calendar-event-card.d.ts

@@ -4,4 +4,9 @@ export interface EventCalendarEventCardPropsWithStrings extends EventCalendarEve
     strings?: Partial<EventCalendarEventCardStrings>;
     className?: string;
 }
+/**
+ * One event in full, for an agenda row or a popover. The card reads its metadata by name —
+ * `customerName`, `guestCount`, `serviceName` — so a consumer's own fields appear without a
+ * mapping step.
+ */
 export declare function EventCalendarEventCard({ event, category, onClick, strings, className, }: EventCalendarEventCardPropsWithStrings): import("react").JSX.Element;

package/dist/components/features/event-calendar/event-calendar-header.d.ts

@@ -1,2 +1,6 @@
 import { EventCalendarHeaderProps } from './event-calendar.types.js';
+/**
+ * The period and the controls that move it. The month jump is icon-only because the label
+ * beside it already names the month — spelling it on the button too is the same word twice.
+ */
 export declare function EventCalendarHeader({ currentDate, viewMode, displayLabel, onPrevious, onNext, onToday, onViewModeChange, onDateChange, actions, strings, rangeMode, minDate, maxDate, prevDisabled, nextDisabled, className, }: EventCalendarHeaderProps): import("react").JSX.Element;

package/dist/components/features/event-calendar/event-calendar-legend.d.ts

@@ -1,2 +1,6 @@
 import { EventCalendarLegendProps } from './event-calendar.types.js';
+/**
+ * The category key, and the filter when one is wired. The WHOLE chip toggles rather than a
+ * checkbox beside a swatch — the swatch is the target a reader aims at anyway.
+ */
 export declare function EventCalendarLegend({ categories, visibleCategories, onToggleCategory, enableFiltering, strings, className, }: EventCalendarLegendProps): import("react").JSX.Element | null;

package/dist/components/features/event-calendar/event-calendar.d.ts

@@ -1,2 +1,6 @@
 import { EventCalendarProps } from './event-calendar.types.js';
+/**
+ * A month grid, a week strip, or an agenda over one list of events. Views change only the day
+ * range and layout; placing events onto days is shared.
+ */
 export declare function EventCalendar({ events, categories, viewMode, defaultViewMode, onViewModeChange, date, defaultDate, onDateChange, onEventClick, onDayClick, maxEventsPerDay, showLegend, showHeader, showWeekends, weekStartsOn: weekStartsOnProp, locale, enableCategoryFilter, visibleCategories: controlledVisibleCategories, onVisibleCategoriesChange, loading, emptyStateMessage, className, compact, actions, strings, dayHeadingVariant, dayHeadingClassName, renderDayHeading, rangeMode, minDate, maxDate, disabledDates, filterEvent, renderEvent, renderDayCell, }: EventCalendarProps): import("react").JSX.Element;

package/dist/components/features/event-calendar/event-calendar.types.d.ts

@@ -52,29 +52,50 @@ export type RenderDayCellFn = (day: CalendarDayData, defaultRender: () => ReactN
 export type EventCalendarRangeMode = "date" | "month-year";
 export type EventCalendarDayHeadingVariant = "default" | "accent" | "tinted" | "bordered";
 export interface EventCalendarProps {
-    /** The calendar does no fetching of its own. */
+    /**
+     * The calendar does no fetching of its own. An event with an `endDate` appears on every day
+     * it spans, not only its first.
+     */
     events: CalendarEvent[];
+    /** The categories events name. Each owns its colour, so colour is defined once. */
     categories: EventCategory[];
+    /**
+     * Controlled. The switcher works either way. Week steps by weeks; month and agenda step by
+     * months.
+     */
     viewMode?: CalendarViewMode;
+    /** Uncontrolled: the view to start in. */
     defaultViewMode?: CalendarViewMode;
     onViewModeChange?: (mode: CalendarViewMode) => void;
+    /** Where the calendar is looking. Controlled, like the view. */
     date?: Date;
+    /** Uncontrolled: where the calendar starts looking. */
     defaultDate?: Date;
     onDateChange?: (date: Date) => void;
+    /** A chip press calls this and stops there. */
     onEventClick?: (event: CalendarEvent) => void;
-    /** Fires with the day and everything on it. */
+    /** A press anywhere else in a day's cell calls this, with the day and everything on it. */
     onDayClick?: (date: Date, events: CalendarEvent[]) => void;
-    /** Chips drawn per day before the rest collapse into an overflow line. */
+    /**
+     * Chips drawn per day before the rest collapse into an overflow line. The overflow dots are
+     * the categories of the HIDDEN events, not the first three in the list.
+     */
     maxEventsPerDay?: number;
     showLegend?: boolean;
     showHeader?: boolean;
     showWeekends?: boolean;
-    /** 0 is Sunday. Falls back to the provider's dates config, then Monday. */
+    /**
+     * 0 is Sunday. Falls back to the provider's dates config, then Monday — the same source the
+     * kit's own pickers read.
+     */
     weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
     locale?: Locale;
     /** Makes the legend chips toggle their category. */
     enableCategoryFilter?: boolean;
-    /** Ids currently shown. Empty means all. */
+    /**
+     * Ids currently shown. An EMPTY list means all are shown — a filter nobody has touched hides
+     * nothing.
+     */
     visibleCategories?: string[];
     onVisibleCategoriesChange?: (categories: string[]) => void;
     loading?: boolean;
@@ -90,11 +111,23 @@ export interface EventCalendarProps {
     rangeMode?: EventCalendarRangeMode;
     /** Navigation stops here, and days beyond it are drawn but not clickable. */
     minDate?: Date;
+    /** Navigation stops here, and days beyond it are drawn but not clickable. */
     maxDate?: Date;
+    /**
+     * Days drawn but not clickable. A `DateRule` takes dates, a predicate, or both, combined
+     * with OR.
+     */
     disabledDates?: DateRule;
-    /** Hides events at render time without touching `events`. */
+    /**
+     * Hides events at render time without touching `events`. Counts and the overflow line
+     * follow it, so what is drawn and what is counted agree.
+     */
     filterEvent?: EventFilter;
+    /** Replaces how an event draws: its chip in a day cell, its card in the agenda. */
     renderEvent?: RenderEventFn;
+    /**
+     * Replaces a day's cell. It receives `defaultRender`, so decorating is as easy as replacing.
+     */
     renderDayCell?: RenderDayCellFn;
 }
 export interface EventCalendarDayCellProps {

package/dist/components/features/event-calendar/use-event-calendar.d.ts

@@ -9,4 +9,9 @@ export interface UseEventCalendarOptions {
     onViewModeChange?: (mode: CalendarViewMode) => void;
     dataOptions?: UseEventCalendarDataOptions;
 }
+/**
+ * The date, the view, and the days — for a calendar whose surface is entirely yours. Each is
+ * independently controllable: the prop wins when given, and setters always call the consumer's
+ * handler.
+ */
 export declare function useEventCalendar({ events, date, defaultDate, viewMode, defaultViewMode, onDateChange, onViewModeChange, dataOptions, }: UseEventCalendarOptions): UseEventCalendarResult;

package/dist/components/features/filters/filter-cache.d.ts

@@ -14,18 +14,24 @@ export interface FilterCache {
     clear(): void;
 }
 /**
- * A cache with its own lifetime.
+ * The async option and label cache, with its own lifetime. FilterProvider makes one per
+ * mount, which is the isolating default: two roots on a page, or two users in a session, never
+ * see each other's results. Create one and pass it as FilterProvider's `cache` when results
+ * and pill labels should survive a navigation. A Map at module scope would be one cache for
+ * the whole realm — an embedded widget would be served the host application's options, and
+ * signing in as somebody else would keep the first user's labels.
  *
- * ```tsx
- * // One cache for the whole session, so filters survive navigation:
- * const cache = useMemo(() => createFilterCache(), [])
- * <FilterProvider cache={cache} …>
- * ```
+ * One cache for the whole session, so filters survive navigation:
  *
- * Passing none is the ordinary case — `FilterProvider` makes one per mount.
+ *   const cache = useMemo(() => createFilterCache(), [])
+ *   <FilterProvider cache={cache} …>
  */
 export declare function createFilterCache(): FilterCache;
 /** The cache the nearest provider owns. `null` outside one, which is a valid place to be. */
 export declare const FilterCacheContext: import('react').Context<FilterCache | null>;
-/** The filter cache in scope, or `null` (then `useAsyncOptions` makes its own short-lived one). */
+/**
+ * The filter cache in scope, or `null` outside a provider (then `useAsyncOptions` makes its own
+ * short-lived one). For a caller writing their own editor that wants to read or seed the same
+ * store `useAsyncOptions` uses.
+ */
 export declare function useFilterCache(): FilterCache | null;

package/dist/components/features/filters/filter-context.d.ts

@@ -4,10 +4,20 @@ import { FilterStrings } from './filters.strings.js';
 import { ActiveFilter, FilterConfig, FilterErrorHandler } from './filters.types.js';
 export interface FilterProviderProps {
     children: ReactNode;
+    /**
+     * Every filter the surface offers. A filter's `type` decides its editor and which
+     * comparisons it offers.
+     */
     filters: FilterConfig[];
+    /** The applied filters. Controlled: the provider never writes to its own state. */
     activeFilters: ActiveFilter[];
+    /** Receives every change to `activeFilters`, which the provider never makes itself. */
     onFilterChange: (filters: ActiveFilter[]) => void;
-    /** A change is in flight. The bar dims rather than pretending it has applied. */
+    /**
+     * A change is in flight. Controls are disabled, open editors close, and an updating status
+     * appears while the current results remain visible — the bar dims rather than pretending it
+     * has applied.
+     */
     navigating?: boolean;
     strings?: Partial<FilterStrings>;
     /** Receives fetch, validation, apply, and render failures. */
@@ -18,4 +28,8 @@ export interface FilterProviderProps {
      */
     cache?: FilterCache;
 }
+/**
+ * The state every part of a filter bar reads: the filters on offer, the applied ones, and the
+ * async option cache.
+ */
 export declare function FilterProvider({ children, filters, activeFilters, onFilterChange, navigating, strings, onError, cache, }: FilterProviderProps): import("react").JSX.Element;

package/dist/components/features/filters/filter-editors.d.ts

@@ -8,10 +8,34 @@ export interface FilterEditorProps {
     /** Only a toolbar-opened editor has a list to go back to. */
     triggerSource?: FilterTriggerSource;
 }
+/**
+ * The editor for a `select` or `multi_select` filter. A multi-select STAGES its value and
+ * commits on Apply — one that committed on each tick would be one request per tick; a single
+ * select with `closeOnSelect` commits at once.
+ */
 export declare function SelectFilterEditor(props: FilterEditorProps): import("react").JSX.Element;
+/**
+ * The editor for an `async_select` filter: the select editor's staging, with options fetched
+ * through `useAsyncOptions`.
+ */
 export declare function AsyncFilterEditor(props: FilterEditorProps): import("react").JSX.Element;
+/**
+ * The editor for a `date` filter: one date, or a range for `between`. A date commits as it is
+ * picked.
+ */
 export declare function DateFilterEditor({ filter, value, onValueChange, onBack, triggerSource, }: FilterEditorProps): import("react").JSX.Element;
+/** The editor for a `tags` filter. It stages the tags and commits them on Apply. */
 export declare function TagsFilterEditor({ filter, value, onValueChange, onBack, onClose, triggerSource, }: FilterEditorProps): import("react").JSX.Element;
+/**
+ * The editor for a `range` filter: a minimum, and a maximum for `between`. It stages the
+ * bounds and commits them on Apply.
+ */
 export declare function RangeFilterEditor({ filter, value, onValueChange, onBack, onClose, triggerSource, }: FilterEditorProps): import("react").JSX.Element;
-/** Dispatches on the filter's type. One place that knows which editor a type gets. */
+/**
+ * Dispatches on the filter's type to one of the five typed editors — SelectFilterEditor,
+ * DateFilterEditor, RangeFilterEditor, TagsFilterEditor and AsyncFilterEditor — behind one
+ * popover: the one place that knows which editor a type gets. Most editors STAGE their value
+ * and commit it on Apply — a multi-select that committed on each tick would be one request per
+ * tick; a date commits as it is picked.
+ */
 export declare function FilterEditor(props: FilterEditorProps): import("react").JSX.Element;

package/dist/components/features/filters/filter-error-boundary.d.ts

@@ -7,4 +7,9 @@ export interface FilterErrorBoundaryProps {
     fallback?: ReactNode;
     className?: string;
 }
+/**
+ * Keeps one broken filter from taking the page with it. A filter's editor is the most
+ * consumer-owned surface in the feature — custom renders, fetched options, consumer value
+ * shapes — so it is the one most likely to throw.
+ */
 export declare function FilterErrorBoundary(props: FilterErrorBoundaryProps): import("react").JSX.Element;

package/dist/components/features/filters/filter-layout.d.ts

@@ -8,7 +8,16 @@ export interface FilterLayoutProps {
     variant?: "default" | "compact";
     showClearFilters?: boolean;
     tabs?: FilterTab[];
-    /** Narrow viewports use a sheet; opt into inline controls for a custom mobile layout. */
+    /**
+     * `sheet` uses an inset filter sheet and a saved-view select below 768px; search stays
+     * inline. In the sheet an editor's Apply commits values, Back discards unapplied edits, and
+     * Done closes it; `mobileFilters`, `filterSummary` and `done` in `strings` localize it. Opt
+     * into `inline` controls for a custom mobile layout.
+     */
     mobilePresentation?: "sheet" | "inline";
 }
+/**
+ * The default bar: saved tabs, search boxes, active pills, always-shown pills, the add button,
+ * then Clear. For a custom bar, place the exported parts using `useFilterGroups()`.
+ */
 export declare function FilterLayout({ className, dynamicFilterOptions, loadingFilters, variant, showClearFilters, tabs, mobilePresentation, }: FilterLayoutProps): import("react").JSX.Element;

package/dist/components/features/filters/filter-operator-select.d.ts

@@ -4,4 +4,9 @@ export interface FilterOperatorSelectProps {
     operators: OperatorOption[];
     onOperatorChange: (operator: FilterOperator) => void;
 }
+/**
+ * The comparison segment of a pill. It renders as plain text when there is only one operator,
+ * because a menu offering a single choice is a control that cannot be used and still costs a
+ * chevron and a tab stop.
+ */
 export declare function FilterOperatorSelect({ operator, operators, onOperatorChange, }: FilterOperatorSelectProps): import("react").JSX.Element;

package/dist/components/features/filters/filter-pill.d.ts

@@ -11,4 +11,9 @@ export interface FilterPillProps {
     onClear: () => void;
     className?: string;
 }
+/**
+ * One applied filter, as three segments in a group rather than one button. “Status · is ·
+ * Confirmed ✕” is three separate decisions with three separate targets, and a single button
+ * makes two of them unreachable.
+ */
 export declare function FilterPill({ filter, value, active, operator, operators, onOperatorChange, onValueChange, onClear, className, }: FilterPillProps): import("react").JSX.Element;

package/dist/components/features/filters/filter-query.d.ts

@@ -14,7 +14,17 @@ export interface FilterQueryOptions {
     resetPageKeys?: readonly string[];
     includeOperators?: FilterQueryOperatorMode;
 }
+/**
+ * A plain query record → the active filters, for whichever router you have. Driven by the
+ * CONFIGS, not the query: an undeclared key is somebody else's parameter.
+ */
 export declare function parseFiltersFromQuery(filterConfigs: readonly FilterConfig[], query: FilterQueryInput, options?: FilterQueryOptions): ActiveFilter[];
+/**
+ * The active filters → a plain query record, laid over `currentQuery`, for whichever router
+ * you have. Driven by the CONFIGS, not the query: an undeclared key is somebody else's
+ * parameter, and is left alone. The operator travels in a companion key
+ * (`status=confirmed&status__op=not`), written only when it differs from the type's default.
+ */
 export declare function serializeFiltersToQuery(filterConfigs: readonly FilterConfig[], activeFilters: readonly ActiveFilter[], currentQuery?: FilterQueryInput, options?: FilterQueryOptions): FilterQueryRecord;
 /** Lays one query over another, dropping the page keys. */
 export declare function mergeFilterQuery(currentQuery: FilterQueryInput, nextFilterQuery: FilterQueryInput, options?: Pick<FilterQueryOptions, "preserveUnrelated" | "resetPageKeys">): FilterQueryRecord;

package/dist/components/features/filters/filter-tabs.d.ts

@@ -1,5 +1,9 @@
 import { FilterTab } from './filters.types.js';
 export interface FilterTabsProps {
+    /**
+     * Saved sets. A tab is active only when every preset is applied AND nothing else is — so it
+     * stops looking selected the moment the reader narrows further.
+     */
     tabs: FilterTab[];
     /** Compact saved-view control using the same presets and matching as the tab row. */
     display?: "tabs" | "select";
@@ -7,4 +11,9 @@ export interface FilterTabsProps {
     label?: string;
     className?: string;
 }
+/**
+ * Saved filter sets as tabs, or as a compact select via `display`. Both compare values and
+ * operators exactly, preserve range endpoint order, and replace previous narrowing. `label`
+ * names the control; `strings.customView` describes a changed selection.
+ */
 export declare function FilterTabs({ tabs, display, label, className }: FilterTabsProps): import("react").JSX.Element;

package/dist/components/features/filters/filter-value-display.d.ts

@@ -4,4 +4,9 @@ export interface FilterValueDisplayProps {
     value: string[];
     className?: string;
 }
+/**
+ * The value segment of a pill: up to two overlapped icons, then a count, before the label.
+ * Icons come before words — a reader scanning five pills recognises the status colours before
+ * reading any label.
+ */
 export declare function FilterValueDisplay({ filter, value, className }: FilterValueDisplayProps): import("react").JSX.Element;

package/dist/components/features/filters/filters-button.d.ts

@@ -6,4 +6,9 @@ export interface FiltersButtonProps {
     labelVisibility?: "hidden" | "visible";
     className?: string;
 }
+/**
+ * The add-filter button and its two-step popup: the filters not yet applied, then that
+ * filter's editor with a way back. Two steps rather than nested submenus, which cannot be
+ * operated by touch and close under a date picker.
+ */
 export declare function FiltersButton({ availableFilters, labelVisibility, className }: FiltersButtonProps): import("react").JSX.Element;

package/dist/components/features/filters/filters.types.d.ts

@@ -1,5 +1,9 @@
 import { ReactNode } from 'react';
 import { FilterStrings } from './filters.strings.js';
+/**
+ * The filter types, exported as values rather than a type alone so a consumer can build a
+ * filter definition without spelling the strings and can switch on them exhaustively.
+ */
 export declare const FilterType: {
     readonly SELECT: "select";
     readonly MULTI_SELECT: "multi_select";
@@ -10,7 +14,10 @@ export declare const FilterType: {
     readonly TAGS: "tags";
 };
 export type FilterType = (typeof FilterType)[keyof typeof FilterType];
-/** Named rather than a bare union, so a consumer writes `FilterOperator.IN` not `"in"`. */
+/**
+ * The comparisons, named rather than a bare union so a consumer writes `FilterOperator.IN` not
+ * `"in"`, and exported as values so a filter definition can switch on them exhaustively.
+ */
 export declare const FilterOperator: {
     readonly EQUALS: "equals";
     readonly CONTAINS: "contains";
@@ -48,8 +55,17 @@ export interface FilterOption {
     disabled?: boolean;
 }
 export interface DisplayConfig {
+    /**
+     * Where the filter lives in the bar. `always` keeps a pill on screen with no value, for the
+     * one or two filters a screen is really about. `collapsed` hides it behind the add button
+     * until it has one. `hidden` still applies but never draws — which is how a screen scopes a
+     * list to the current account.
+     */
     display?: FilterDisplay;
-    /** Lower sorts earlier in the bar. */
+    /**
+     * Sort order in the bar: lower first. Ties keep the authored order, so pills do not
+     * reshuffle as values come and go.
+     */
     priority?: number;
     hidden?: boolean;
     className?: string;
@@ -113,12 +129,20 @@ export interface FilterConfig {
     icon?: ReactNode;
     displayConfig?: DisplayConfig;
     defaultValue?: string[];
+    /**
+     * `min` / `max` / `pattern` / `required`, plus a `custom` returning true or a message.
+     * `zodValidator` and `predicateValidator` bridge the two shapes you probably already have.
+     */
     validation?: ValidationConfig;
     dependencies?: FilterDependency[];
     multiple?: boolean;
     /** Closes the editor as soon as one option is picked. Single-select only. */
     closeOnSelect?: boolean;
     maxSelected?: number;
+    /**
+     * Options for an `async_select`: one channel owning search, caching, abort, and preload —
+     * rather than a `loading` prop and an `options` prop the consumer keeps in step by hand.
+     */
     asyncConfig?: AsyncSelectConfig;
     dateFormat?: {
         /** date-fns pattern for the pill. */

package/dist/components/features/filters/search-filters.d.ts

@@ -3,9 +3,15 @@ export interface SearchFilterProps {
     filter: FilterConfig;
     className?: string;
 }
+/**
+ * One inline search box. A `search` filter never becomes a pill: typing is the interaction,
+ * and burying a text field two presses deep is how a search box stops being used. It debounces
+ * locally, so the URL is not rewritten on every keystroke.
+ */
 export declare function SearchFilter({ filter, className }: SearchFilterProps): import("react").JSX.Element;
 export interface SearchFiltersProps {
     filters: FilterConfig[];
     className?: string;
 }
+/** The inline search boxes, one per `search` filter. A search filter never becomes a pill. */
 export declare function SearchFilters({ filters, className }: SearchFiltersProps): import("react").JSX.Element | null;

package/dist/components/features/filters/use-async-options.d.ts

@@ -11,6 +11,11 @@ export interface UseAsyncOptionsResult {
     isBelowMinQuery: boolean;
     minQueryLength: number;
 }
+/**
+ * The fetch, debounce and cache behind AsyncFilterEditor, for a caller supplying their own
+ * editor against the same lifecycle. Results are cached by filter and query for `staleTime`,
+ * each keystroke aborts the previous request, and only the newest response may land.
+ */
 export declare function useAsyncOptions(filter: FilterConfig, search: string, isActive: boolean, options?: {
     onError?: FilterErrorHandler;
 }): UseAsyncOptionsResult;

package/dist/components/features/filters/use-filter-groups.d.ts

@@ -15,4 +15,10 @@ export interface UseFilterGroupsResult {
     activeFilterKeys: string[];
     hasActive: boolean;
 }
+/**
+ * Partitions the filter list into the four groups a bar draws differently — search, always,
+ * active, and behind the add button — for a consumer laying out their own bar. Exported so
+ * that consumer does not have to re-derive “which filters belong behind the add button”: a
+ * rule that is easy to get subtly wrong and impossible to notice when you do.
+ */
 export declare function useFilterGroups({ dynamicFilterOptions, }?: UseFilterGroupsOptions): UseFilterGroupsResult;

package/dist/components/features/global-search/global-search-dialog.d.ts

@@ -6,4 +6,8 @@ export interface GlobalSearchDialogProps<TGroup extends string = string> extends
     /** Merged onto the dialog surface that positions the palette. */
     contentClassName?: string;
 }
+/**
+ * The palette presentation over ActionDialog: focus trap, portal, scroll lock, and a dialog
+ * role — none of which a hand-rolled fixed backdrop has.
+ */
 export declare function GlobalSearchDialog<TGroup extends string = string>({ open, onOpenChange, contentClassName, className, strings, autoFocus, ...search }: GlobalSearchDialogProps<TGroup>): import("react").JSX.Element;

package/dist/components/features/global-search/global-search-empty-state.d.ts

@@ -5,4 +5,5 @@ export interface GlobalSearchEmptyStateProps {
     hint?: ReactNode;
     className?: string;
 }
+/** What the palette shows after a search that found nothing. */
 export declare function GlobalSearchEmptyState({ title, hint, className }: GlobalSearchEmptyStateProps): import("react").JSX.Element;

package/dist/components/features/global-search/global-search-footer.d.ts

@@ -9,4 +9,8 @@ export interface GlobalSearchFooterProps {
     trailing?: ReactNode;
     className?: string;
 }
+/**
+ * The keyboard-hint strip under the list. It is the only place a reader is told which three
+ * keys the palette answers to.
+ */
 export declare function GlobalSearchFooter({ navigateLabel, openLabel, closeLabel, escKey, trailing, className, }: GlobalSearchFooterProps): import("react").JSX.Element;

package/dist/components/features/global-search/global-search-idle-state.d.ts

@@ -9,4 +9,8 @@ export interface GlobalSearchIdleStateProps {
     };
     className?: string;
 }
+/**
+ * What the palette shows before there is anything to search: recent queries and curated
+ * suggestions, both supplied by the consumer — the palette does not remember anything itself.
+ */
 export declare function GlobalSearchIdleState({ sections, fallbackIcons, className, }: GlobalSearchIdleStateProps): import("react").JSX.Element;

package/dist/components/features/global-search/global-search-input.d.ts

@@ -10,4 +10,8 @@ export interface GlobalSearchInputProps {
     autoFocus?: boolean;
     className?: string;
 }
+/**
+ * The search row. Thin on purpose — base Input already owns the leading icon, the clear and the
+ * sizing, so this only wires the palette's key handling to it.
+ */
 export declare const GlobalSearchInput: import('react').ForwardRefExoticComponent<GlobalSearchInputProps & import('react').RefAttributes<HTMLInputElement>>;

package/dist/components/features/global-search/global-search-result-row.d.ts

@@ -10,4 +10,8 @@ export interface GlobalSearchResultRowProps<TGroup extends string = string> {
     onFocus?: () => void;
     className?: string;
 }
+/**
+ * One rich result — its media, title, context and trailing figure. Exported so a consumer
+ * rendering their own groups keeps the row's highlight and keyboard behaviour.
+ */
 export declare function GlobalSearchResultRow<TGroup extends string = string>({ result, active, query, onSelect, onMouseEnter, onFocus, className, }: GlobalSearchResultRowProps<TGroup>): import("react").JSX.Element;

package/dist/components/features/global-search/global-search-tabs.d.ts

@@ -7,4 +7,8 @@ export interface GlobalSearchTabsProps<TGroup extends string = string> {
     counts: Record<string, number>;
     className?: string;
 }
+/**
+ * The group filter strip, built on OverflowTabBar rather than Tabs: these narrow one list
+ * rather than switching between panels, and the distinction decides what the arrow keys do.
+ */
 export declare function GlobalSearchTabs<TGroup extends string = string>({ value, onValueChange, tabs, counts, className, }: GlobalSearchTabsProps<TGroup>): import("react").JSX.Element;

package/dist/components/features/global-search/global-search.d.ts

@@ -1,2 +1,7 @@
 import { GlobalSearchProps } from './global-search.types.js';
+/**
+ * The command palette's panel. It does not search: `query` is controlled and `results` are
+ * given; debounce, endpoint and ranking belong to the app. It owns the regions, grouping, and
+ * an arrow-key highlight.
+ */
 export declare function GlobalSearch<TGroup extends string = string>({ results, query, onQueryChange, onResultSelect, onClose, loading, idleSections, groupLabels, autoFocus, strings, slots, tabs, className, }: GlobalSearchProps<TGroup>): import("react").JSX.Element;