themelia-ui 2.0.1 → 3.1.0

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

@@ -123,7 +123,11 @@ export interface CommentsAttachmentsConfig {
     /** Passed straight to the file input. */
     accept?: string;
     disabled?: boolean;
-    /** Receives a refusal before any upload starts. */
+    /**
+     * Receives a refusal before any upload starts, as a code and the number behind it — never a
+     * sentence. The hook has no idea what language the reader speaks, and “too large” is useless
+     * without the limit.
+     */
     onReject?: (rejection: CommentAttachmentRejection) => void;
 }
 export interface CommentsConfig<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string> extends CommentsAccessors {
@@ -161,7 +165,12 @@ export interface CommentsSlots<TUser extends CommentUser = CommentUser, TMeta =
     emptySlot?: ReactNode;
     headerSlot?: ReactNode;
     footerSlot?: ReactNode;
+    /**
+     * Replaces a comment. It receives `defaultItem`, so a consumer can wrap the kit's comment
+     * rather than rebuild it.
+     */
     renderItem?: (context: CommentRenderItemContext<TUser, TMeta, TResource>) => ReactNode;
+    /** Replaces an attachment's chip. */
     renderAttachment?: (attachment: CommentAttachment) => ReactNode;
     /** Overrides the mention registry's own `renderChip`. */
     renderReference?: (reference: Mention<TResource>) => ReactNode;
@@ -169,12 +178,15 @@ export interface CommentsSlots<TUser extends CommentUser = CommentUser, TMeta =
 /** How a thread reads: what folds away and what a reader can do beyond reply and react. Shared by `Comments`, `CommentTimeline` and `CommentItem`. */
 export interface CommentThreadOptions<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string> {
     /**
-     * Extra entries for each comment's overflow menu, bound to the comment (`visible`,
-     * `disabled` and `onClick` receive it). Listed above pin, edit and delete; `destructive` sorts last.
+     * Extra entries for each comment's overflow menu — copy a link, report, resolve. Bound to the
+     * comment like a table row's actions: `visible` and `disabled` may be predicates, and
+     * `onClick` receives the comment. They sit after pin and edit, before delete; a
+     * `destructive` entry still sorts last.
      */
     commentActions?: ContextActionSource<CommentData<TUser, TMeta, TResource>>;
     /**
-     * Latest replies shown before earlier ones fold behind "Show N earlier replies". `0` shows all.
+     * Replies an open thread shows; the earlier ones fold behind "Show N earlier replies". The
+     * LAST ones are kept, so list replies oldest first. `0` shows them all.
      * @default 3
      */
     maxVisibleReplies?: number;
@@ -184,12 +196,14 @@ export interface CommentThreadOptions<TUser extends CommentUser = CommentUser, T
      */
     clampLines?: number;
     /**
-     * Attachments shown before the rest fold behind "Show N more". `0` shows every file.
+     * Attachments shown before the rest fold behind "Show N more". Folding one file saves
+     * nothing, so the fold starts at two hidden. `0` shows every file.
      * @default 3
      */
     maxVisibleAttachments?: number;
     /**
-     * The reactions "Add reaction" offers. One reacts immediately; more open a picker.
+     * The reactions "Add reaction" offers. One reacts at once; more open a picker that marks the
+     * reader's own. Every choice arrives through `onReact`.
      * @default ["👍"]
      */
     reactionChoices?: readonly string[];
@@ -251,11 +265,25 @@ export interface CommentComposerProps<TResource extends string = string> {
     className?: string;
 }
 export interface CommentsProps<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string> extends CommentsAccessors, CommentThreadOptions<TUser, TMeta, TResource>, CommentsSlots<TUser, TMeta, TResource> {
+    /**
+     * What the thread hangs off: an `id` and a `type`, and a `moduleKey` where one record carries
+     * several threads. Passed straight through to `onSubmit`. Changing it clears the draft — a
+     * composer that stays mounted must not carry one record's text to the next.
+     */
     context: CommentableContext;
-    /** In display order. Replies are nested by `replyToId`, not by position. */
+    /**
+     * Flat, in display order. Replies nest by `replyToId`, not by position, so one posted an hour
+     * late still appears under its parent. A reply whose parent is not in the array is promoted
+     * rather than dropped.
+     */
     comments: ReadonlyArray<CommentData<TUser, TMeta, TResource>>;
     canComment?: boolean;
     canModerate?: boolean;
+    /**
+     * Where the composer sits — a real per-thread decision: an activity log reads newest-first
+     * and a discussion reads like a chat, and the same page can want both. Replies and edits open
+     * inside the thread either way.
+     */
     composerPosition?: CommentsComposerPosition;
     maxAttachments?: number;
     allowAttachments?: boolean;
@@ -263,21 +291,44 @@ export interface CommentsProps<TUser extends CommentUser = CommentUser, TMeta =
     allowReplies?: boolean;
     /** Drops the card chrome, for a thread already inside a panel. */
     bare?: boolean;
-    /** `false` hides the title outright. */
+    /** The heading. `false` hides it outright. */
     title?: ReactNode | false;
+    /**
+     * Posts a comment or a reply. `helpers.reset()` is what clears the composer — a resolved
+     * promise is not proof of success, and a server answering validation with a 200 would
+     * otherwise throw away what the writer typed.
+     */
     onSubmit?: CommentsConfig<TUser, TMeta, TResource>["onSubmit"];
+    /** Deletes a comment, after a confirmation unless `confirmDelete` is off. */
     onDelete?: CommentsConfig<TUser, TMeta, TResource>["onDelete"];
-    /** Asks before deleting. Off when the app already confirms upstream. */
+    /**
+     * Asks before deleting. The confirmation is opt-out because deleting takes the replies with
+     * it; turn it off when the app already asks upstream.
+     */
     confirmDelete?: boolean;
     onAttachmentRemove?: (commentId: string, attachmentId: string) => void | Promise<void>;
+    /** Saves an edit. As with `onSubmit`, `helpers.reset()` is what clears the composer. */
     onUpdate?: CommentsConfig<TUser, TMeta, TResource>["onUpdate"];
     onAfterMutate?: CommentsConfig<TUser, TMeta, TResource>["onAfterMutate"];
     onError?: CommentsConfig<TUser, TMeta, TResource>["onError"];
     onPinToggle?: CommentsConfig<TUser, TMeta, TResource>["onPinToggle"];
     onReact?: CommentsConfig<TUser, TMeta, TResource>["onReact"];
     onReply?: CommentsConfig<TUser, TMeta, TResource>["onReply"];
+    /**
+     * The mention registry, as `useMentions` takes it. Without it the reference control does not
+     * appear.
+     */
     resources?: CommentsConfig<TUser, TMeta, TResource>["resources"];
+    /**
+     * The fallback search, for a mention kind that registers neither `search` nor
+     * `suggestions`.
+     */
     onResourceSearch?: CommentsConfig<TUser, TMeta, TResource>["onResourceSearch"];
+    /**
+     * Uploads: `onUpload`, `maxSize`, `maxFiles`, `accept`. Without `onUpload` there is no
+     * attachment control. The uploader resolves to a `CommentAttachment` with a permanent `url`;
+     * the composer submits what it returns, not the file it was given.
+     */
     attachments?: CommentsAttachmentsConfig;
     sanitizer?: CommentsConfig<TUser, TMeta, TResource>["sanitizer"];
     strings?: Partial<CommentsStrings>;

package/dist/components/features/comments/use-attachment-upload.d.ts

@@ -16,4 +16,9 @@ export interface UseAttachmentUploadReturn {
     setAttachments: (attachments: ReadonlyArray<CommentAttachment>) => void;
     reset: () => void;
 }
+/**
+ * The files staged on a draft and their uploads — the part with three things that are easy to
+ * get wrong: cancelling in flight, retrying one of several, and discarding a draft that still
+ * has uploads running.
+ */
 export declare function useAttachmentUpload(options?: UseAttachmentUploadOptions): UseAttachmentUploadReturn;

package/dist/components/features/comments/use-comments.d.ts

@@ -33,4 +33,9 @@ export interface UseCommentsReturn<TUser extends CommentUser = CommentUser, TMet
     /** Passed to `onSubmit` and `onUpdate`. */
     helpers: CommentSubmitHelpers;
 }
+/**
+ * The state machine on its own — `composerMode`, `submit`, `deleteComment`, `resetKey` — for a
+ * fully custom thread. The mode is one union rather than three booleans, so “editing a reply
+ * while replying” cannot be represented.
+ */
 export declare function useComments<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string>(options?: UseCommentsOptions<TUser, TMeta, TResource>): UseCommentsReturn<TUser, TMeta, TResource>;

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

@@ -1,9 +1,33 @@
 import { RowData } from '@tanstack/react-table';
 import { DataViewPaginationProps, DataViewProps, DataViewShellProps, DataViewTableFrameProps, DataViewToolbarProps, SavedViewTabsProps } from './data-view.types.js';
+/** The plain shell, for composing the same rhythm around something that is not a DataTable. */
 export declare function DataViewShell({ children, header, toolbar, footer, emptySlot, empty, className, contentClassName, }: DataViewShellProps): import("react").JSX.Element;
+/**
+ * The filter bar. In a DataView it lives inside the table's topbar rather than above it, so
+ * filtering and the data it filters are one surface and scroll as one. It works bare too,
+ * around something that is not a DataTable.
+ */
 export declare function DataViewToolbar({ leading, search, filters, views, actions, className, }: DataViewToolbarProps): import("react").JSX.Element;
+/**
+ * The table frame the filter bar sits in, with the bar in the table's topbar so filtering and
+ * the data it filters scroll as one. It works bare too, around something that is not a
+ * DataTable.
+ */
 export declare function DataViewTableFrame({ toolbar, children, footer, className, toolbarClassName, contentClassName, footerClassName, }: DataViewTableFrameProps): import("react").JSX.Element;
-/** A saved-view row that is NOT filter-driven — for a consumer holding views themselves. */
+/**
+ * A compact select of saved views that is NOT filter-driven — for a consumer holding views
+ * themselves. The caller controls the selected view and applies its state through
+ * `onValueChange`. For filter-driven tabs, or a select with exact preset matching, use
+ * DataView's `filtering.tabs` or FilterTabs.
+ */
 export declare function SavedViewTabs({ views, value, onValueChange, className }: SavedViewTabsProps): import("react").JSX.Element;
+/**
+ * Keeps the result summary visible, including zero results. Page controls appear only above
+ * one page; `disabled` makes every control unavailable to pointer and keyboard users.
+ */
 export declare function DataViewPagination({ page, pageCount, total, onPageChange, disabled, className, strings, }: DataViewPaginationProps): import("react").JSX.Element | null;
+/**
+ * The filter bar and the table as one surface: filter state, row filtering, the bar inside the
+ * table's topbar, and pagination, all against one row set.
+ */
 export declare function DataView<TData extends RowData, TValue = unknown>({ data, columns, filtering, strings, table, slots, className, }: DataViewProps<TData, TValue>): import("react").JSX.Element;

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

@@ -1,6 +1,7 @@
 import { ReactNode } from 'react';
 import { Locale } from 'date-fns';
 import { ActionDefinition } from '../../base/action-menu/index.js';
+import { SemanticTone } from '../../../lib/component-vocabulary.js';
 import { EventCalendarStrings, EventCalendarEventCardStrings } from './event-calendar.strings.js';
 export interface CalendarEvent {
     id: string;
@@ -26,6 +27,8 @@ export interface EventCategory {
 }
 /** The only fallback: a category that is missing entirely. */
 export declare function resolveCategoryColorToken(category?: EventCategory | null): CalendarColorToken;
+/** The shared tone a category's marks render as `data-tone`: `amber` and `yellow` name warning. */
+export declare function resolveCategoryTone(category?: EventCategory | null): Extract<SemanticTone, CalendarColorToken>;
 export type CalendarViewMode = "month" | "week" | "agenda";
 /** One day, after the events have been placed on it. */
 export interface CalendarDayData {
@@ -52,29 +55,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 +114,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;