themelia-react-ui 2.0.5 → 3.0.0

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

@@ -40,18 +40,34 @@ export interface CalendarEvent {
     url?: string;
 }
 /**
- * Canonical category palette tokens. Map to a small fixed set of colours so
- * the calendar can render dots/strokes without parsing arbitrary class names.
- * Add new tokens here when the design palette grows.
+ * Category colour names. Each name draws the categorical series of its own
+ * hue (`--chart-1…8`), so a name looks like what it says in any theme:
+ *
+ * | Name | Swatch |
+ * | --- | --- |
+ * | `red` | series 6 |
+ * | `orange`, `amber` | series 5: **these two share a swatch** |
+ * | `yellow` | series 7 |
+ * | `green` | series 8 |
+ * | `blue` | series 2 |
+ * | `purple` | series 3 |
+ * | `gray` | neutral ink |
+ *
+ * Eight names draw seven swatches. The theme has one series between red and
+ * yellow, so use `orange` or `amber` in a legend, not both. Series 1 (which
+ * follows the brand colour in derived themes) and series 4 (magenta) have no
+ * name here.
+ *
+ * A colour is a marker: the dot on an event chip, the overflow dot and the
+ * legend swatch. It is never a text colour or a chip fill, so event labels
+ * keep the chip's readable ink whichever name is used; the light yellow
+ * series in particular is too pale to carry text.
  */
 export type CalendarColorToken = 'gray' | 'red' | 'orange' | 'amber' | 'yellow' | 'green' | 'blue' | 'purple';
 /**
- * Tailwind class lookups for each canonical token. Used by day-cell dots and
- * event-badge dots so we never string-parse `category.color`.
- *
- * A category is a kind, not a status, so each hue family takes the nearest
- * categorical chart series (`--chart-1…5`) rather than a success, warning,
- * destructive or info tone; `gray` stays the neutral marker.
+ * Tailwind class lookups for each colour name. Used by day-cell dots and
+ * event-badge dots so we never string-parse `category.color`. The mapping and
+ * the one shared swatch are documented on `CalendarColorToken`.
  */
 export declare const calendarTokenDot: Record<CalendarColorToken, string>;
 /**
@@ -114,9 +130,46 @@ export interface EventCalendarStrings {
         week: string;
         agenda: string;
     };
+    /**
+     * Weekday headings, Sunday first. Without an override the calendar derives
+     * them from its `locale`; the English defaults apply when there is none.
+     */
     weekdaysShort: [string, string, string, string, string, string, string];
+    /** Accessible name of the legend's filter group. */
+    categoryFilterLabel?: string;
+    /**
+     * Accessible name of a day. Receives the date already formatted for the
+     * locale and the number of events on it. Defaults to the date, followed by
+     * the count with `booking`/`bookings` when the day has events.
+     */
+    formatDayLabel?: (date: string, count: number) => string;
+    /** Accessible name and tooltip of a timed event: "Massage at 14:00". Receives the formatted time. */
+    formatEventLabel?: (title: string, time: string) => string;
+    /** Hint under a day's visible events. Defaults to the count with `booking`/`bookings`. */
+    formatOverflow?: (count: number) => string;
+    /**
+     * Start time shown on an event. Defaults to the locale's short time, or a
+     * 24-hour `HH:mm` when the calendar has no locale.
+     */
+    formatTime?: (date: Date) => string;
+    /**
+     * Shown in place of the day grid when the visible period has no events
+     * after the category and runtime filters. Unset by default, so empty days
+     * stay selectable for creating events; header navigation stays available.
+     */
+    emptyState?: string;
+    /** Title of the default error state. */
+    errorTitle?: string;
+    /** Description of the default error state, when `error` carries no message. */
+    errorDescription?: string;
+    /** Retry command in the default error state. */
+    retry?: string;
 }
-export declare const defaultEventCalendarStrings: EventCalendarStrings;
+/** The copy that always has an English default, including the keys added after the first release. */
+type EventCalendarDefaultStrings = EventCalendarStrings & Required<Pick<EventCalendarStrings, 'categoryFilterLabel' | 'formatEventLabel' | 'errorTitle' | 'errorDescription' | 'retry'>>;
+export declare const defaultEventCalendarStrings: EventCalendarDefaultStrings;
+/** Copy the day cell and its event chips read; every key is optional there. */
+export type EventCalendarCellStrings = Partial<Pick<EventCalendarStrings, 'booking' | 'bookings' | 'formatDayLabel' | 'formatEventLabel' | 'formatOverflow' | 'formatTime'>>;
 /**
  * Visual variant for the weekday-header strip ("Sun Mon Tue …").
  *  - `default` — muted text on transparent (matches body)
@@ -167,6 +220,12 @@ export interface EventCalendarProps {
     defaultViewMode?: CalendarViewMode;
     /** Fired when the user switches view from the header. */
     onViewModeChange?: (mode: CalendarViewMode) => void;
+    /**
+     * Shows the Month/Week/Agenda switcher in the header. Defaults to on. A
+     * controlled `viewMode` without `onViewModeChange` is read-only, so it never
+     * shows one.
+     */
+    showViewSwitcher?: boolean;
     /** Visible date. Controlled when paired with `onDateChange`. */
     date?: Date;
     /** Month shown on first render. Defaults to today. */
@@ -189,16 +248,28 @@ export interface EventCalendarProps {
     weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
     /** Optional date-fns Locale object passed to inner date pickers. */
     locale?: import('date-fns').Locale;
-    /** Lets the legend filter which categories are drawn. */
+    /** Lets the legend filter which categories are drawn. Each chip shows or hides its own category. */
     enableCategoryFilter?: boolean;
-    /** Category ids currently shown. Controlled when paired with the change handler. */
+    /**
+     * Category ids currently shown. An empty list shows every category.
+     * Controlled when paired with the change handler.
+     */
     visibleCategories?: string[];
-    /** Fired when the legend toggles a category. */
+    /**
+     * Fired when the legend toggles a category, with the ids left on screen. It
+     * receives an empty list once every category is shown again, and when the
+     * last visible category is hidden, since an empty calendar filters nothing.
+     */
     onVisibleCategoriesChange?: (categories: string[]) => void;
-    /** Replaces the grid with the loading state. */
+    /** Replaces the grid with the loading state. The header and legend stay in place. */
     loading?: boolean;
-    /** Copy shown when no events fall in the visible period. */
-    emptyStateMessage?: string;
+    /**
+     * Replaces the grid with the error state. A string or Error becomes its
+     * description; any other element replaces the default state.
+     */
+    error?: ReactNode | Error;
+    /** Adds Retry to the default error state. */
+    onRetry?: () => void;
     /** Merged onto the outermost node. */
     className?: string;
     /** Tightens row heights and event chips for dense dashboards. */
@@ -219,9 +290,9 @@ export interface EventCalendarProps {
      *  - `month-year`  — MonthYearPicker (compact month/year jump)
      */
     rangeMode?: EventCalendarRangeMode;
-    /** Earliest date the user can navigate to. Earlier nav is disabled. */
+    /** Earliest day the user can reach, inclusive whatever time it carries. Earlier navigation is disabled. */
     minDate?: Date;
-    /** Latest date the user can navigate to. Later nav is disabled. */
+    /** Latest day the user can reach, inclusive whatever time it carries. Later navigation is disabled. */
     maxDate?: Date;
     /**
      * Dates that should render in the calendar but be marked as disabled
@@ -235,7 +306,12 @@ export interface EventCalendarProps {
     filterEvent?: EventFilter;
     /** Per-event renderer override. */
     renderEvent?: RenderEventFn;
-    /** Per-day-cell renderer override. */
+    /**
+     * Per-day-cell renderer override. The month and week grids keep one day in
+     * the tab order and move between days with the arrow keys; that model lives
+     * on the built-in cell, so a renderer that drops `defaultRender()` (and its
+     * date button) takes its days out of it. The output is used as written.
+     */
     renderDayCell?: RenderDayCellFn;
 }
 /**
@@ -254,9 +330,24 @@ export interface EventCalendarDayCellProps {
     /** Tightens spacing for dense surfaces. */
     compact?: boolean;
     /** Overrides this surface's own copy. */
-    strings?: Pick<EventCalendarStrings, 'booking' | 'bookings'>;
+    strings?: EventCalendarCellStrings;
     /** Per-event renderer override. */
     renderEvent?: RenderEventFn;
+    /**
+     * Marks the day and its events as unavailable: they stay focusable and are
+     * announced as disabled, and activating them does nothing.
+     */
+    disabled?: boolean;
+    /** date-fns locale for the day's accessible name and its event times. */
+    locale?: import('date-fns').Locale;
+    /**
+     * Roving focus, set by `EventCalendar` in its month and week grids. `true`
+     * keeps this day's date button and built-in event chips in the tab order;
+     * `false` takes them out, though they stay focusable from script and by
+     * pointer. Omit it and every control is a tab stop. Chips from `renderEvent`
+     * are left as written.
+     */
+    tabStop?: boolean;
 }
 /**
  * Event badge props
@@ -269,6 +360,14 @@ export interface EventCalendarEventBadgeProps {
     /** Tightens spacing for dense surfaces. */
     compact?: boolean;
     onClick?: () => void;
+    /** Announces the chip as unavailable and ignores its activation. It stays focusable. */
+    disabled?: boolean;
+    /** date-fns locale for the start time. */
+    locale?: import('date-fns').Locale;
+    /** Tab order of the chip; `-1` keeps it focusable from script and by pointer only. */
+    tabIndex?: number;
+    /** Overrides the chip's accessible name and time format. */
+    strings?: Pick<EventCalendarCellStrings, 'formatEventLabel' | 'formatTime'>;
 }
 /**
  * Event card props
@@ -286,11 +385,14 @@ export interface EventCalendarEventCardProps {
 export interface EventCalendarLegendProps {
     /** Category definitions supplying each entry's colour. */
     categories: EventCategory[];
-    /** Ids of the categories currently shown. */
+    /** Ids of the categories currently shown. An empty list shows every category. */
     visibleCategories?: string[];
+    /** Fired with the id of the chip that was pressed; the owner works out the next visible set. */
     onToggleCategory?: (categoryId: string) => void;
     /** Lets the legend toggle category visibility. */
     enableFiltering?: boolean;
+    /** Overrides the legend's own copy. */
+    strings?: Pick<EventCalendarStrings, 'categoryFilterLabel'>;
 }
 /**
  * Header props
@@ -323,6 +425,8 @@ export interface EventCalendarHeaderProps {
     prevDisabled?: boolean;
     /** Forces the next control off. */
     nextDisabled?: boolean;
+    /** Forces the Today control off, for a today outside the navigable range. */
+    todayDisabled?: boolean;
 }
 /**
  * Hook return type
@@ -352,3 +456,4 @@ export interface UseEventCalendarDataOptions {
     /** Ids of the categories currently shown. */
     visibleCategories?: string[];
 }
+export {};

package/dist/components/features/filters/facets/date-facet.d.ts

@@ -1,7 +1,9 @@
-import type { FilterConfig } from '../filters.types';
+import type { FilterConfig, FilterOperator } from '../filters.types';
 export interface DateFacetProps {
     /** Definition of the filter this control edits. */
     filter: FilterConfig;
+    /** Active operator. When omitted, the standalone facet uses the filter configuration. */
+    operator?: FilterOperator;
     /** Current value. */
     value: {
         start?: Date;
@@ -15,4 +17,4 @@ export interface DateFacetProps {
     /** Merged onto the outermost node. */
     className?: string;
 }
-export declare function DateFacet({ filter, value, onValueChange, className, }: DateFacetProps): import("react").JSX.Element;
+export declare function DateFacet({ filter, operator, value, onValueChange, className, }: DateFacetProps): import("react").JSX.Element;

package/dist/components/features/filters/facets/range-facet.d.ts

@@ -1,3 +1,4 @@
+import { type ChangeEvent } from 'react';
 import type { FilterConfig } from '../filters.types';
 export interface RangeFacetProps {
     /** Definition of the filter this control edits. */
@@ -18,13 +19,29 @@ export interface RangeFacetProps {
 /**
  * Range Filter Facet
  *
- * This component implements a numeric range filter that allows users to:
- * - Set minimum and maximum values
- * - Configure step size and precision
- * - Set value constraints (min/max allowed values)
- * - Customize the range input appearance
+ * A numeric range with a minimum and a maximum bound. Either bound may be
+ * left open, and negative and decimal numbers are accepted. The facet emits
+ * `{ min, max }` after the filter's `delay`, with `undefined` for an open
+ * bound, and follows external changes to `value` while it is not focused
+ * and the provider is not navigating.
  *
- * The component integrates with the filter context to manage the range values
- * and provides a user-friendly interface for range selection.
+ * A range whose minimum exceeds its maximum, or that falls outside
+ * `filter.validation.min`/`max`, is marked invalid with its message and is
+ * not emitted.
  */
 export declare function RangeFacet({ filter, value, onValueChange, className, }: RangeFacetProps): import("react").JSX.Element;
+interface RangeFacetFieldsProps {
+    min: string;
+    max: string;
+    onMinChange: (event: ChangeEvent<HTMLInputElement>) => void;
+    onMaxChange: (event: ChangeEvent<HTMLInputElement>) => void;
+    className?: string;
+    invalid?: boolean;
+    /** Message for an invalid range, announced under the fields and tied to both inputs. */
+    error?: string;
+    /** Reports whether focus is inside the fields. */
+    onFocusChange?: (focused: boolean) => void;
+}
+/** The public facet and the Confirm editor share the same field anatomy. */
+export declare function RangeFacetFields({ min, max, onMinChange, onMaxChange, className, invalid, error, onFocusChange }: RangeFacetFieldsProps): import("react").JSX.Element;
+export {};

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

@@ -40,7 +40,16 @@ export interface FilterContextValue {
     isFilterActive: (key: string) => boolean;
     getFilterOperator: (key: string) => FilterOperator | undefined;
     setFilterOperator: (key: string, operator: FilterOperator) => void;
+    /**
+     * Checks a value against the filter's `validation`: `true`, or the message
+     * to show. Array values are checked entry by entry. The built-in editors
+     * call this before applying a draft.
+     */
     validateFilter: (key: string, value: unknown) => boolean | string;
+    /**
+     * Filters whose `dependencies` name this key. A headless helper for custom
+     * layouts: FilterLayout does not hide or clear dependent filters itself.
+     */
     getDependentFilters: (key: string) => FilterConfig[];
     /** Whether a filter change is still being applied. */
     isNavigating: boolean;

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

@@ -19,6 +19,10 @@ export interface FilterOperatorStrings {
     has: string;
     hasAny: string;
     hasAll: string;
+    /** Set membership, the `in` operator. Optional so existing complete overrides keep compiling. */
+    in?: string;
+    /** Set exclusion, the `not_in` operator. Optional so existing complete overrides keep compiling. */
+    notIn?: string;
 }
 export interface FilterStrings {
     loading: string;
@@ -31,10 +35,9 @@ export interface FilterStrings {
     selectDate: string;
     selectDateRange: string;
     calendar: {
-        dateSelected: string;
         notDateSelected: string;
         notDateRangeSelected: string;
-        selectedEndDate: string;
+        /** Shortcut labels. `today`, `thisMonth` and `lastThirtyDays` name the default set; the rest are offered through `datePickerConfig.shortcuts`. */
         today: string;
         yesterday: string;
         lastSevenDays: string;
@@ -43,7 +46,12 @@ export interface FilterStrings {
         lastMonth: string;
         thisYear: string;
         lastYear: string;
-        customRange: string;
+        /** "This week" shortcut in the range editor. Falls back to the date picker's copy. */
+        thisWeek?: string;
+        /** Label before the start of the range summary. Falls back to the date picker's copy. */
+        from?: string;
+        /** Label before the end of the range summary. Falls back to the date picker's copy. */
+        to?: string;
     };
     selectValues: string;
     searchPlaceholder: string;
@@ -57,6 +65,12 @@ export interface FilterStrings {
     tag: string;
     tags: string;
     enterTags: string;
+    /**
+     * Tag count above the chosen tags. A template with `{count}` and `{label}`
+     * (the `tag` or `tags` string), or a function for languages with more
+     * plural forms or a different order. Defaults to "{count} {label}".
+     */
+    tagCount?: string | ((count: number) => string);
     searchFilters: string;
     noFiltersAvailable: string;
     availableFilters: string;
@@ -69,6 +83,12 @@ export interface FilterStrings {
     selectCurrentLevel: string;
     select: string;
     options: string;
+    /**
+     * Option count under a filter in the Add filter list. A template with
+     * `{count}` and `{label}` (the `options` string), or a function for other
+     * plural rules. Defaults to "{count} {label}".
+     */
+    optionCount?: string | ((count: number) => string);
     operator: string;
     operators: FilterOperatorStrings;
     min: string;
@@ -77,11 +97,19 @@ export interface FilterStrings {
     retryFetch: string;
     minQueryHint: string;
     searching: string;
+    /**
+     * Result count announced to assistive technology when an async search
+     * settles. A function, so each locale applies its own plural rules.
+     * Defaults to "1 option found" / "{count} options found".
+     */
+    optionsFound?: (count: number) => string;
     error: {
         title: string;
         descriptionWithKey: string;
         generic: string;
         unknown: string;
+        /** Name of the button that dismisses a failed filter. Falls back to `clear`. */
+        dismiss?: string;
     };
     validation: {
         required: string;
@@ -100,6 +128,11 @@ export declare const defaultFilterStrings: FilterStrings;
  * Replaces {key} with the corresponding value from the params object.
  */
 export declare function interpolateFilterString(template: string, params: Record<string, string | number>): string;
+/**
+ * A count string that is either a `{count} {label}` template or a function,
+ * so a locale can reorder the words or apply its own plural rules.
+ */
+export declare function formatFilterCount(template: string | ((count: number) => string) | undefined, count: number, label: string): string;
 /**
  * Helper function to get a string from a strings object
  * with dot notation support.

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

@@ -1,4 +1,5 @@
 import type { ReactNode } from 'react';
+import type { DatePickerProps, PresetDateRange } from '../../base/date-pickers';
 /** Shared height class for all filter control elements. */
 export declare const FILTER_ELEMENT_HEIGHT = "h-control";
 /**
@@ -70,27 +71,39 @@ export interface FilterOption {
     disabled?: boolean;
     /** Supporting copy shown under the label. */
     description?: string;
+    /** Layout metadata only: the built-in editors and pills do not read it. */
     color?: string;
 }
 export interface DisplayConfig {
-    /** Replaces the default config rendering. */
+    /** Layout metadata only: for custom layouts. FilterLayout does not read it. */
     renderConfig?: {
         desktop: string;
         mobile?: string;
         tablet?: string;
     };
     display?: FilterDisplay;
+    /** Layout metadata only: for custom layouts. FilterLayout does not read it. */
     category?: FilterCategory;
+    /** Layout metadata only: for custom layouts. FilterLayout keeps the order of `filters`. */
     priority?: number;
     hidden?: boolean;
     /** Merged onto the outermost node. */
     className?: string;
 }
+/**
+ * Checked by `validateFilter` and by the built-in editors before a draft is
+ * applied; an invalid draft shows its message and cannot be confirmed.
+ */
 export interface ValidationConfig {
+    /** Lowest number allowed. Applies to numbers and to each RANGE bound. */
     min?: number;
+    /** Highest number allowed. Applies to numbers and to each RANGE bound. */
     max?: number;
+    /** Tested against a string, or against every entry of an array value. */
     pattern?: RegExp;
+    /** Rejects an empty value. */
     required?: boolean;
+    /** Receives the whole value. Return `true`, or `false` or a message to reject it. */
     custom?: (value: unknown) => boolean | string;
 }
 export interface FilterDependency {
@@ -127,6 +140,16 @@ export interface AsyncSelectConfig<TItem = unknown> {
     mapToOption: {
         bivarianceHack(item: TItem): FilterOption;
     }['bivarianceHack'];
+    /**
+     * Loads the items for values that are already applied, such as ids restored
+     * from a URL, so their pill and editor show labels even when they fall
+     * outside the first page. Without it the provider preloads the first page
+     * and an unresolved value is listed by its raw value.
+     */
+    resolveOptions?: (args: {
+        values: string[];
+        signal?: AbortSignal;
+    }) => Promise<TItem[]>;
     /** Max items to fetch per request (default: 10) */
     limit?: number;
     /** Minimum characters before fetching (default: 0) */
@@ -135,9 +158,9 @@ export interface AsyncSelectConfig<TItem = unknown> {
     preload?: boolean;
     /** Debounce delay in ms (default: 300) */
     debounceMs?: number;
-    /** Freshness window in ms before a cached result refetches (default: 60_000). */
+    /** Freshness window in ms for cached results within one mounted editor (default: 60_000). */
     staleTime?: number;
-    /** Retention window in ms before a cached result is discarded (default: 300_000). */
+    /** Retention window in ms within one mounted editor (default: 300_000). Closing the editor discards its cache. */
     gcTime?: number;
 }
 /**
@@ -152,25 +175,52 @@ export interface FilterConfig {
     /** Plural form of the label, used in "{count} {label} selected" when count > 1 */
     pluralLabel?: string;
     type: FilterType;
-    /** Supporting copy shown under the label. */
+    /** Supporting copy under an inline SEARCH field. Pills and popover editors do not show it. */
     description?: string;
-    /** Comparison currently chosen. */
+    /** Operator the filter starts with. Wins over `operators[0]` and the type default. */
     operator?: FilterOperator;
-    /** Comparisons this filter offers. */
+    /** Comparisons this filter offers. The first one is the default when `operator` is not set. */
     operators?: OperatorOption[];
+    /**
+     * MULTI_SELECT only. Compares by set membership: the filter starts with
+     * `in` ("is any of") and its pill offers `in` and `not_in`, instead of
+     * starting with `equals` and offering is / is not / is any of / is none of.
+     * `operator` and `operators` still win. Defaults to `false`.
+     *
+     * Migration, before turning it on for a filter that already has stored
+     * state:
+     * - The default operator is not written to the query string, so a link
+     *   saved as `?status=paid` used to parse as `equals` and now parses as
+     *   `in`. Have the backend read a missing operator for this key as `in`,
+     *   or re-serialize stored links first with `includeOperators: 'always'`
+     *   so they carry `status__op=equals`.
+     * - A stored `ActiveFilter` or saved view with `operator: 'equals'` keeps
+     *   it. Its pill reads "is", the query now carries `status__op=equals`
+     *   because it is no longer the default, and the user can switch it to
+     *   `in` or `not_in` but not back. Map stored `equals` to `in` when the
+     *   two mean the same to the backend.
+     * - Filter tab presets without an `operator` apply `in`.
+     */
+    membershipOperators?: boolean;
     options?: FilterOption[];
     placeholder?: string;
     delay?: number;
     /** Leading glyph. */
     icon: ReactNode;
     displayConfig: DisplayConfig;
+    /** Layout metadata only: for the consumer's initial state. The provider is controlled and does not apply it. */
     defaultValue?: string | string[];
     validation?: ValidationConfig;
+    /**
+     * Layout metadata only: for custom layouts, read through
+     * `getDependentFilters`. FilterLayout does not hide or clear dependent filters.
+     */
     dependencies?: FilterDependency[];
     multiple?: boolean;
     /** For nested options: only leaves can be chosen (default), or any option, including a branch. */
     selectableOptions?: 'leaf' | 'any';
     closeOnSelect?: boolean;
+    /** Most values a multi-value select may hold; further options are disabled once it is reached. */
     maxSelected?: number;
     /** Async option loading config for ASYNC_SELECT filters. */
     asyncConfig?: AsyncSelectConfig;
@@ -181,22 +231,39 @@ export interface FilterConfig {
     datePickerConfig?: {
         showConfirmButton?: boolean;
         showShortcuts?: boolean;
-        fullWidth?: boolean;
         noDatePlaceholder?: string;
         noRangePlaceholder?: string;
         autoApply?: boolean;
+        /** Copy passed to the date picker, over the provider's `calendar` strings. */
+        strings?: DatePickerProps['strings'];
+        /** Replaces the range shortcuts. `showShortcuts: false` still hides them. */
+        presets?: PresetDateRange[];
+        /**
+         * Range shortcuts to offer, in order, labelled from the provider's
+         * `calendar` strings. Omit to keep the date picker's default set
+         * (today, this week, this month, last 30 days). `presets` wins when both
+         * are passed, and `showShortcuts: false` hides either.
+         */
+        shortcuts?: FilterDateShortcut[];
+        /**
+         * date-fns locale for weekday and month names and the trigger text.
+         * Falls back to `UIProvider` `dates.locale`.
+         */
+        locale?: DatePickerProps['locale'];
     };
     format?: (value: unknown) => string;
     parse?: (value: string) => unknown;
     transform?: (value: unknown) => unknown;
 }
+/** A built-in range shortcut of the DATE editor. Each one is labelled by the `calendar` string of the same name. */
+export type FilterDateShortcut = 'today' | 'yesterday' | 'thisWeek' | 'lastSevenDays' | 'lastThirtyDays' | 'thisMonth' | 'lastMonth' | 'thisYear' | 'lastYear';
 export interface ActiveFilter {
     /** Stable identity for this entry. */
     id: string;
     key: string;
     /** Comparison currently chosen. */
     operator: FilterOperator;
-    /** Current value of the filter. */
+    /** Current value of the filter. RANGE uses [min, max], with an empty string for an open bound. */
     value: string[];
 }
 export interface FilterGroup {

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

@@ -0,0 +1 @@
+export declare function useFilterDraft(value: string[] | undefined): [draft: string[], setDraft: (next: string[]) => void];

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

@@ -2,12 +2,12 @@ export { FilterProvider, useFilters } from './filter-context';
 export type { FilterContextValue, FilterProviderProps } from './filter-context';
 export { FilterLayout } from './filter-layout';
 export type { FilterLayoutProps } from './filter-layout';
-export type { FilterConfig, FilterOption, ActiveFilter, FilterOperator, OperatorOption, FilterDependency, ValidationConfig, DisplayConfig, FilterTab, FilterTabPreset, AsyncSelectConfig, FilterErrorContext, FilterErrorHandler, } from './filters.types';
+export type { FilterConfig, FilterDateShortcut, FilterOption, ActiveFilter, FilterOperator, OperatorOption, FilterDependency, ValidationConfig, DisplayConfig, FilterTab, FilterTabPreset, AsyncSelectConfig, FilterErrorContext, FilterErrorHandler, } from './filters.types';
 export { FilterType, FilterOperatorEnum, defineAsyncSelectConfig, } from './filters.types';
 export { mergeFilterQuery, parseFiltersFromQuery, serializeFiltersToQuery, type FilterQueryArrayFormat, type FilterQueryInput, type FilterQueryOperatorMode, type FilterQueryOptions, type FilterQueryRecord, type FilterQueryValue, } from './filter-query';
 export { defaultFilterStrings, getFilterString, interpolateFilterString, } from './filters.strings';
 export type { FilterOperatorStrings, FilterStrings, } from './filters.strings';
-export { getTextOperators, getSelectOperators, getNumberOperators, getDateOperators, getBooleanOperators, getOperatorsForType, getDefaultOperatorForType, } from './operator-options';
+export { getTextOperators, getSelectOperators, getNumberOperators, getDateOperators, getBooleanOperators, getMultiSelectOperators, getOperatorsForType, getOperatorsForFilter, getDefaultOperatorForType, getOperatorLabel, resolveDefaultOperator, } from './operator-options';
 export { SearchFacet } from './facets/search-facet';
 export type { SearchFacetProps } from './facets/search-facet';
 export { SelectFacet } from './facets/select-facet';

package/dist/components/features/filters/operator-options.d.ts

@@ -1,9 +1,32 @@
-import { type FilterOperator, type OperatorOption, FilterType } from './filters.types';
-import type { FilterOperatorStrings } from './filters.strings';
+import { type FilterConfig, type FilterOperator, type OperatorOption, FilterType } from './filters.types';
+import { type FilterOperatorStrings } from './filters.strings';
 export declare function getTextOperators(strings: FilterOperatorStrings): OperatorOption[];
 export declare function getSelectOperators(strings: FilterOperatorStrings): OperatorOption[];
 export declare function getNumberOperators(strings: FilterOperatorStrings): OperatorOption[];
 export declare function getDateOperators(strings: FilterOperatorStrings): OperatorOption[];
+/**
+ * Operators for a MULTI_SELECT filter. `equals` and `not` stay first because
+ * `equals` is the stored default; `in` and `not_in` name the set comparison.
+ */
+export declare function getMultiSelectOperators(strings: FilterOperatorStrings): OperatorOption[];
 export declare function getBooleanOperators(strings: FilterOperatorStrings): OperatorOption[];
 export declare function getOperatorsForType(type: FilterType, strings: FilterOperatorStrings): OperatorOption[];
 export declare function getDefaultOperatorForType(type: FilterType): FilterOperator;
+/**
+ * The operator a filter starts with: its configured `operator`, then the
+ * first of its `operators`, then `in` for a MULTI_SELECT that set
+ * `membershipOperators`, then the default for its type. The provider, the
+ * query helpers and filter tabs all resolve the default through this.
+ */
+export declare function resolveDefaultOperator(config: Pick<FilterConfig, 'type' | 'operator' | 'operators' | 'membershipOperators'> | undefined): FilterOperator;
+/**
+ * The operators a filter's pill offers: its own `operators`, then `in` and
+ * `not_in` for a MULTI_SELECT that set `membershipOperators`, then the list
+ * for its type.
+ */
+export declare function getOperatorsForFilter(config: Pick<FilterConfig, 'type' | 'operators' | 'membershipOperators'>, strings: FilterOperatorStrings): OperatorOption[];
+/**
+ * Localised label for an operator that is not in the list a pill offers, such
+ * as one restored from a URL. `gte` and `lte` have no copy and return undefined.
+ */
+export declare function getOperatorLabel(operator: FilterOperator, strings: FilterOperatorStrings): string | undefined;

package/dist/components/features/filters/partials/active-filter-item.d.ts

@@ -21,17 +21,4 @@ export interface ActiveFilterItemProps {
     /** Opens the value editor from either segment; the optional event identifies its focus origin. */
     onFilterClick: (event?: React.MouseEvent<HTMLButtonElement>) => void;
 }
-/**
- * Active Filter Item Component
- *
- * This component displays a single active filter in the filter list.
- * It provides:
- * - Display of filter label and value
- * - Remove filter functionality
- * - Visual feedback for active state
- * - Support for different filter types
- *
- * The component is used in the filter list to show currently active filters
- * and allow users to remove them.
- */
 export declare function ActiveFilterItem({ filter, value, active, popoverOpen, triggerRef, operators, operator, onOperatorChange, onFilterClear, onFilterClick, }: ActiveFilterItemProps): React.JSX.Element;