themelia-react-ui 2.0.5 → 2.0.6

package/dist/components/base/navigation/language-switcher.d.ts

@@ -1,15 +1,23 @@
 import type { LocaleOption } from '../../../types/locale.types';
+type LanguageSwitcherLocale = Omit<LocaleOption, 'active'> & {
+    active?: boolean;
+};
 export interface LanguageSwitcherProps {
-    /** Locales to offer, in order. The entry with `active: true` is marked as current. */
-    locales: LocaleOption[];
+    /** Locales to offer, in order. Their active flags apply when value is omitted. */
+    locales: LanguageSwitcherLocale[];
+    /** Controlled current locale. Takes precedence over the option flags. */
+    value?: string;
+    /** Requests another locale. Takes precedence over onSelect. */
+    onValueChange?: (value: string) => void;
     /** Custom label for each locale. Defaults to `nativeLabel`. */
     onRenderLabel?: (options: LocaleOption) => string;
-    /** Layout: `buttons` (default) for a row of buttons, `inline` for compact dot-separated text links. */
+    /** Layout: `buttons` (default) for a row of buttons, `inline` for compact dot-separated text buttons. */
     variant?: 'buttons' | 'inline';
     /** Called with the chosen locale's value. Not called for the current locale. */
     onSelect?: (value: string) => void;
 }
-export declare function LanguageSwitcher({ locales, onRenderLabel, variant, onSelect, }: LanguageSwitcherProps): import("react").JSX.Element | null;
+export declare function LanguageSwitcher({ locales, value, onValueChange, onRenderLabel, variant, onSelect, }: LanguageSwitcherProps): import("react").JSX.Element | null;
 export declare namespace LanguageSwitcher {
     var displayName: string;
 }
+export {};

package/dist/components/base/repeaters/key-value-editor.d.ts

@@ -1,3 +1,4 @@
+import { type FieldControlAttributes } from '../../../lib/field-control-attributes';
 import { type StringsProp } from '../../../lib/strings';
 export type KeyValuePair = {
     key: string;
@@ -13,7 +14,7 @@ export interface KeyValueEditorStrings {
     emptyState: string;
 }
 export declare const defaultKeyValueEditorStrings: KeyValueEditorStrings;
-export interface KeyValueEditorProps {
+export interface KeyValueEditorProps extends FieldControlAttributes {
     /** Current value. Controlled. */
     value?: Record<string, string>;
     onValueChange?: (val: Record<string, string>) => void;

package/dist/components/base/sidebar/sidebar.d.ts

@@ -152,6 +152,8 @@ declare function SidebarGroupLabel({ className, children, ...props }: SidebarGro
 export { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRegion, SidebarRail, SidebarSeparator, SidebarTrigger, };
 /** Internal bridge for the layout layer; not part of the base package entrypoint. */
 export declare const useBaseSidebarContext: typeof useSidebarPrimitive;
+/** Lets composed layouts omit a sidebar control when no provider is present. */
+export declare function useHasSidebarProvider(): boolean;
 /** Internal density bridge for composed navigation; not a base entrypoint export. */
 export declare function useBaseSidebarMenuDensity(): SidebarMenuDensity | undefined;
 export type { SidebarPanelId, SidebarPresentation };

package/dist/components/base/upload/avatar-upload.d.ts

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import { type StringsProp } from '../../../lib/strings';
 import { type ComponentScale } from '../../../lib/ui-provider';
+import { type FieldControlAttributes } from '../../../lib/field-control-attributes';
 export type AvatarUploadSize = ComponentScale;
 export interface AvatarUploadStrings {
     change: string;
@@ -15,7 +16,7 @@ export interface AvatarUploadStrings {
     customValidationFailed: (fileName: string) => string;
 }
 export declare const defaultAvatarUploadStrings: AvatarUploadStrings;
-export interface AvatarUploadProps {
+export interface AvatarUploadProps extends FieldControlAttributes {
     /** Selected file. Controlled. */
     value?: File;
     onValueChange?: (file?: File) => void;

package/dist/components/base/upload/image-upload.d.ts

@@ -1,5 +1,6 @@
 import React from 'react';
 import { type StringsProp } from '../../../lib/strings';
+import { type FieldControlAttributes } from '../../../lib/field-control-attributes';
 type ImageUploadAspectRatio = 'square' | 'standard' | 'widescreen' | 'portrait';
 type ImageUploadLayout = 'stacked' | 'inline';
 type ImageUploadFit = 'cover' | 'contain';
@@ -28,7 +29,7 @@ export interface ImageUploadStrings {
     moreFiles: (count: number) => string;
 }
 export declare const defaultImageUploadStrings: ImageUploadStrings;
-export interface ImageUploadProps {
+export interface ImageUploadProps extends FieldControlAttributes {
     /** Accepted MIME types or extensions, as the native `accept` attribute. */
     accept?: string;
     /** Allows more than one file to be chosen. */

package/dist/components/blocks/ai/ai-citation/types.d.ts

@@ -16,7 +16,9 @@ export interface AiCitationStrings {
     title: string;
     sourceCount: (n: number) => string;
     hiddenCount: (n: number) => string;
+    /** Supplied overrides describe how to open the source list. */
     expand: string;
+    /** Supplied overrides describe how to close the source list. */
     collapse: string;
     visit: string;
     relevance: string;

package/dist/components/blocks/ai/ai-reasoning/types.d.ts

@@ -7,7 +7,9 @@ export interface AiReasoningStrings {
     thoughtFor: string;
     /** Header label when no duration is available. */
     thoughtDone: string;
+    /** Supplied overrides describe how to open the reasoning trace. */
     expandAria: string;
+    /** Supplied overrides describe how to close the reasoning trace. */
     collapseAria: string;
 }
 export declare const defaultAiReasoningStrings: AiReasoningStrings;

package/dist/components/blocks/ai/ai-sources/types.d.ts

@@ -16,7 +16,9 @@ export interface AiSourceItem {
 export interface AiSourcesStrings {
     /** Header title — `{{count}}` placeholder for the source count. */
     title: string;
+    /** Supplied overrides describe how to open the source list. */
     expand: string;
+    /** Supplied overrides describe how to close the source list. */
     collapse: string;
     visit: string;
 }

package/dist/components/blocks/ai/ai-tool-call/types.d.ts

@@ -7,7 +7,9 @@ export interface AiToolCallStrings {
     running: string;
     success: string;
     error: string;
+    /** Supplied overrides describe how to open the details. */
     expand: string;
+    /** Supplied overrides describe how to close the details. */
     collapse: string;
     args: string;
     result: string;

package/dist/components/blocks/analytics/metric/metric.d.ts

@@ -1,3 +1,4 @@
+import type { SemanticTone } from '../../../../lib/component-vocabulary';
 import type { MetricColorScheme, MetricData, MetricSize, MetricVariant } from '../types';
 export interface MetricProps {
     /** Records to render. */
@@ -6,6 +7,9 @@ export interface MetricProps {
     variant?: MetricVariant;
     /** Size preset. */
     size?: MetricSize;
+    /** Tone for bordered surfaces and colored progress. Takes precedence over colorScheme. */
+    tone?: SemanticTone;
+    /** @deprecated Use tone. */
     colorScheme?: MetricColorScheme;
     /** Renders the sparkline. */
     showSparkline?: boolean;

package/dist/components/blocks/analytics/metric-comparison/metric-comparison.d.ts

@@ -6,6 +6,8 @@ export interface MetricComparisonStrings {
     currentLabel: string;
     previousLabel: string;
     suffix: string;
+    /** Copy shown when the relative change cannot be calculated. */
+    noBaseline?: string;
     /** Unit for the absolute change between two percentages. Additive; defaults to `pp`. */
     pointsUnit?: string;
 }

package/dist/components/blocks/analytics/metric-grid/metric-grid.d.ts

@@ -1,13 +1,12 @@
-import type { MetricColorScheme, MetricData, MetricSize, MetricVariant } from '../types';
-export interface MetricGridProps {
+import { type MetricProps } from '../metric/metric';
+import type { MetricData, MetricSize, MetricVariant } from '../types';
+export interface MetricGridProps extends Pick<MetricProps, 'tone' | 'colorScheme'> {
     /** Metrics rendered as one responsive peer collection. */
     metrics: MetricData[];
     /** Cell variant. `card` composes the canonical Card surface. */
     variant?: Extract<MetricVariant, 'card' | 'compact' | 'bordered' | 'accent' | 'colored'>;
     /** Shared visual size forwarded to every metric. */
     size?: MetricSize;
-    /** Shared semantic color recipe forwarded to every metric. */
-    colorScheme?: MetricColorScheme;
     /** Maximum column count; narrower parents use fewer tracks. `auto` chooses from the cell count. */
     columns?: 'auto' | 1 | 2 | 3 | 4 | 6;
     /** Peer spacing. Defaults to `xl`; use denser gaps explicitly for compact lists. */
@@ -27,7 +26,7 @@ export interface MetricGridProps {
      */
     className?: string;
 }
-export declare function MetricGrid({ metrics, variant, size, colorScheme, columns, gap, showSparklines, showChanges, showIcons, loading, className, }: MetricGridProps): import("react").JSX.Element;
+export declare function MetricGrid({ metrics, variant, size, tone, colorScheme, columns, gap, showSparklines, showChanges, showIcons, loading, className, }: MetricGridProps): import("react").JSX.Element;
 export declare namespace MetricGrid {
     var displayName: string;
 }

package/dist/components/blocks/analytics/types.d.ts

@@ -15,7 +15,7 @@ export type MetricDirection = 'up' | 'down' | 'neutral';
  * for some metrics "down" is good (e.g. churn), so consumers can override.
  */
 export type MetricTrend = 'positive' | 'negative' | 'neutral';
-/** Colour scheme used by Metric variants that support tinting. */
+/** @deprecated Use the shared semantic tone through the tone prop. */
 export type MetricColorScheme = 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
 /** Visual layout variant for the canonical `Metric` component. */
 export type MetricVariant = 
@@ -27,7 +27,7 @@ export type MetricVariant =
  | 'compact'
 /** Inline `Label: value ↑12%` chip. Pure inline copy. */
  | 'minimal'
-/** Border + soft tint based on `colorScheme`. */
+/** Border and soft tint based on `tone`. */
  | 'bordered'
 /** Dark surface card with bottom-aligned area sparkline. Hero-row variant. */
  | 'accent'

package/dist/components/blocks/commerce/order-status/types.d.ts

@@ -11,6 +11,10 @@ export interface OrderStatusEvent {
 export interface OrderStatusStrings {
     /** Surface title. */
     title: string;
+    /** Labels for each supported fulfilment stage. */
+    status?: Partial<Record<OrderStatusKind, string>>;
+    /** Formats the human-facing reference displayed below the title. */
+    formatOrderNumber?: (orderNumber: string) => string;
     /** Not rendered: the title badge states the status. Kept for existing overrides. */
     statusLabel: string;
     /** Label of the delivery-estimate fact. */

package/dist/components/blocks/data-display/empty-state/empty-state.types.d.ts

@@ -3,13 +3,14 @@ import type { ComponentScale } from '../../../../lib/component-vocabulary';
 import type { StringsProp } from '../../../../lib/strings';
 import type { EmptyStateStrings } from './empty-state.strings';
 /**
- * Vertical breathing room.
+ * Surface inset.
  *
+ * `none` — flush inside a parent that already owns the inset.
  * `sm` — compact cards, table cells, and side panels.
  * `md` — normal table, list, and card empty states.
  * `lg` — large page-level empty states.
  */
-export type EmptyStatePadding = ComponentScale;
+export type EmptyStatePadding = ComponentScale | 'none';
 /**
  * How the `media` slot renders.
  *
@@ -66,7 +67,7 @@ export interface EmptyStateProps {
      * keyboard hints, etc.
      */
     footer?: ReactNode;
-    /** Vertical breathing. Defaults to the provider density scale; tune values through CSS variables. */
+    /** Surface inset. Defaults to the provider density scale. Use `none` inside an already padded surface. */
     padding?: EmptyStatePadding;
     /**
      * `border` toggles the dashed-border look on/off. Defaults to `false`

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

@@ -61,26 +61,27 @@ export interface ActivityResourceConfig {
     /** Free-form note exposed via tooltip. */
     note?: string;
 }
-/** A single piece of the headline — blocks inline by the renderer. */
-export type ActivityHeadlineSegment = {
-    type: 'text';
+type ActivityHeadlineText = {
     text: string;
-} | {
+    /** React content rendered in place of the text fallback. */
+    content?: ReactNode;
+};
+/** A single inline piece of the headline. */
+export type ActivityHeadlineSegment = ({
+    type: 'text';
+} & ActivityHeadlineText) | {
     type: 'actor';
     text: string;
     actorId?: string;
     href?: string;
-} | {
+} | ({
     type: 'field';
-    text: string;
-} | {
+} & ActivityHeadlineText) | ({
     type: 'value';
-    text: string;
-} | {
+} & ActivityHeadlineText) | ({
     type: 'status';
-    text: string;
     tone?: ActivityTone;
-} | {
+} & ActivityHeadlineText) | {
     type: 'resource';
     text?: string;
     resource: ActivityResourceRef;
@@ -106,6 +107,8 @@ export interface ActivityItem<TData = unknown> {
     event: string;
     /** Optional source bucket — drives the source-badge label. */
     source?: string;
+    /** React content for the source badge. Takes precedence over the source label. */
+    sourceContent?: ReactNode;
     actor?: ActivityActor;
     /** Pre-built segments — preferred over `headline`. */
     segments?: readonly ActivityHeadlineSegment[];
@@ -325,8 +328,11 @@ export interface ActivityLogActivityEntry<TResource extends string = string> {
     /** The action this surface performs. */
     action?: string;
     target?: ReactNode;
+    /** Status badge content. Takes precedence over the target value. */
+    status?: ReactNode;
     /** Display label. */
     label?: ReactNode;
+    /** Fallback headline when no action or target is supplied. Accepts inline React content. */
     headline?: ReactNode;
     /** Supporting copy shown under the label. */
     description?: ReactNode;
@@ -435,3 +441,4 @@ export interface ActivityLogProps<TUser extends CommentUser = CommentUser, TMeta
     className?: string;
 }
 export type ActivityLogSubmit<TResource extends string = string> = (values: CommentFormValues<TResource>, helpers: CommentSubmitHelpers) => void | Promise<void>;
+export {};

package/dist/components/features/activities/hooks/use-activity-resources.d.ts

@@ -1,6 +1,7 @@
 import type { ActivityResourceConfig, ActivityResourceRef } from '../activities.types';
 export type ActivityResourceRegistry = Readonly<Record<string, ActivityResourceConfig>>;
 export interface UseActivityResourcesOptions {
+    /** Registry seed. Equivalent resource values preserve local edits. */
     resources?: ActivityResourceRegistry;
     onResourcesChange?: (registry: ActivityResourceRegistry) => void;
 }
@@ -16,7 +17,7 @@ export interface UseActivityResourcesReturn {
     remove: (key: string) => void;
     /** Replace the entire registry. */
     setAll: (registry: ActivityResourceRegistry) => void;
-    /** Reset to the original `resources` prop (or empty if none). */
+    /** Reset to the latest resource seed. */
     reset: () => void;
 }
 export declare function useActivityResources({ resources, onResourcesChange, }?: UseActivityResourcesOptions): UseActivityResourcesReturn;

package/dist/components/features/ai-chat/hooks/use-ai-chat-scroll.d.ts

@@ -1,7 +1,7 @@
 export interface UseAiChatScrollOptions {
     /** Distance (px) from bottom counted as "at bottom". */
     threshold?: number;
-    /** Re-evaluate on these dependencies (typically the message count). */
+    /** Re-evaluate when content changes, including updates to existing messages. */
     dependency?: unknown;
     /** Disable auto-scroll-on-update behaviour. */
     disableAutoScroll?: boolean;

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

@@ -1,5 +1,5 @@
 import { type Appointment, type AppointmentCalendarProps } from './appointment-calendar.types';
-export declare function AppointmentCalendar<T extends Appointment = Appointment>({ appointments, categories, staff: staffProp, title, date: dateProp, defaultDate, onDateChange, view: viewProp, defaultView, onViewChange, category: categoryProp, defaultCategory, onCategoryChange, staffId: staffIdProp, defaultStaffId, onStaffChange, onAppointmentClick, appointmentActions, renderAppointment, onRangeChange, onCreateAppointment, onConflictsDismiss, loading, error, onRetry, weekStartsOn: weekStartsOnProp, strings: stringsProp, className, }: AppointmentCalendarProps<T>): import("react").JSX.Element;
+export declare function AppointmentCalendar<T extends Appointment = Appointment>({ appointments, categories, staff: staffProp, title, date: dateProp, defaultDate, onDateChange, view: viewProp, defaultView, onViewChange, category: categoryProp, defaultCategory, onCategoryChange, staffId: staffIdProp, defaultStaffId, onStaffIdChange, onStaffChange, onAppointmentClick, appointmentActions, renderAppointment, onRangeChange, onCreateAppointment, onConflictsDismiss, loading, error, onRetry, weekStartsOn: weekStartsOnProp, strings: stringsProp, className, }: AppointmentCalendarProps<T>): import("react").JSX.Element;
 export declare namespace AppointmentCalendar {
     var displayName: string;
 }

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

@@ -174,11 +174,13 @@ export interface AppointmentCalendarProps<T extends Appointment = Appointment> {
     defaultCategory?: string;
     /** Fired when a category chip is chosen. */
     onCategoryChange?: (category: string) => void;
-    /** Staff filter: a staff id, or `all`. Controlled with `onStaffChange`. */
+    /** Staff filter: a staff id, or `all`. Controlled with `onStaffIdChange`. */
     staffId?: string;
     /** Staff filter for uncontrolled use. Defaults to `all`. */
     defaultStaffId?: string;
-    /** Fired when the staff filter changes. */
+    /** Fired when the staff filter changes. Takes precedence over `onStaffChange`. */
+    onStaffIdChange?: (staffId: string) => void;
+    /** Legacy alias for `onStaffIdChange`. */
     onStaffChange?: (staffId: string) => void;
     /** Fired when an appointment is activated. Without it, rows are not interactive. */
     onAppointmentClick?: (appointment: T) => void;

package/dist/components/features/combobox/async-resource-combobox.d.ts

@@ -21,7 +21,7 @@ export interface AsyncResourceComboboxRenderErrorContext {
     query: string;
     retry: () => void;
 }
-export interface AsyncResourceComboboxProps<T> extends Omit<ComboboxProps<T>, 'items' | 'selectedValue' | 'onSelectedValueChange' | 'clearSearchOnClose' | 'searchValue' | 'onSearchValueChange' | 'getItemLabel' | 'getItemKey' | 'loading' | 'showListContent' | 'renderItem' | 'strings' | 'error' | 'debounceMs'> {
+export interface AsyncResourceComboboxProps<T> extends Omit<ComboboxProps<T>, 'items' | 'selectedValue' | 'onSelectedValueChange' | 'clearSearchOnClose' | 'getItemLabel' | 'getItemKey' | 'loading' | 'showListContent' | 'renderItem' | 'strings' | 'error' | 'debounceMs'> {
     /**
      * Loads options for the current query. This component owns the request
      * lifecycle: calls are debounced by `debounceMs`, the previous request is
@@ -88,7 +88,7 @@ export interface AsyncResourceComboboxProps<T> extends Omit<ComboboxProps<T>, 'i
     /** Trigger density. Falls back to `UIProvider.density.defaultScale`, then `md`. */
     size?: ComboboxSize;
 }
-export declare function AsyncResourceCombobox<T>({ fetcher, value, defaultValue, onValueChange, onAfterFetch, onError, getKey, getLabel, getDescription, getMeta, renderOption, limit, debounceMs, preload, minSearchLength, errorMessage, renderError, strings: stringsProp, disabled, size, ...props }: AsyncResourceComboboxProps<T>): import("react").JSX.Element;
+export declare function AsyncResourceCombobox<T>({ fetcher, value, defaultValue, onValueChange, searchValue: controlledSearch, defaultSearchValue, onSearchValueChange, onAfterFetch, onError, getKey, getLabel, getDescription, getMeta, renderOption, limit, debounceMs, preload, minSearchLength, errorMessage, renderError, strings: stringsProp, disabled, size, ...props }: AsyncResourceComboboxProps<T>): import("react").JSX.Element;
 export declare namespace AsyncResourceCombobox {
     var displayName: string;
 }

package/dist/components/features/combobox/combobox.d.ts

@@ -10,11 +10,11 @@
  */
 import * as React from 'react';
 import type { ComboboxProps, MultiComboboxProps } from './types';
-export declare function Combobox<T>({ items, selectedValue, onSelectedValueChange, clearSearchOnClose, searchValue, onSearchValueChange, getItemLabel, getItemKey, loading, showListContent, minSearchLength, strings: stringsProp, disabled, className, clearable, renderItem, portalContainer, name, invalid, error, required, onBlur, onSearch, debounceMs, creatable, onCreate, getItemGroup, renderGroupLabel, hasMore, onLoadMore, loadingMore, getItemDisabled, highlightMatch, size: sizeProp, open, onOpenChange, }: ComboboxProps<T>): React.ReactElement;
+export declare function Combobox<T>({ items, value, defaultValue, onValueChange, selectedValue: legacyValue, onSelectedValueChange: onLegacyValueChange, clearSearchOnClose, searchValue: controlledSearch, defaultSearchValue, onSearchValueChange: onSearchChange, getItemLabel, getItemKey, getItemValue, loading, showListContent, minSearchLength, strings: stringsProp, disabled, className, clearable, renderItem, portalContainer, id, ref, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, 'aria-required': ariaRequired, name, invalid, error, required, onBlur, onSearch, debounceMs, creatable, onCreate, getItemGroup, renderGroupLabel, hasMore, onLoadMore, loadingMore, getItemDisabled, highlightMatch, size: sizeProp, open, defaultOpen, onOpenChange, }: ComboboxProps<T>): React.ReactElement;
 export declare namespace Combobox {
     var displayName: string;
 }
-export declare function MultiCombobox<T>({ items, selectedValues, onSelectedValuesChange, searchValue, onSearchValueChange, getItemLabel, getItemKey, loading, showListContent, minSearchLength, strings: stringsProp, disabled, className, renderItem, portalContainer, name, invalid, error, required, onBlur, onSearch, debounceMs, creatable, onCreate, getItemGroup, renderGroupLabel, hasMore, onLoadMore, loadingMore, getItemDisabled, highlightMatch, size: sizeProp, open, onOpenChange, closeOnSelect, applyButton, onApply, onCancel, }: MultiComboboxProps<T>): React.ReactElement;
+export declare function MultiCombobox<T>({ items, values, defaultValues, onValuesChange, selectedValues: legacyValues, onSelectedValuesChange: onLegacyValuesChange, searchValue: controlledSearch, defaultSearchValue, onSearchValueChange: onSearchChange, getItemLabel, getItemKey, getItemValue, loading, showListContent, minSearchLength, strings: stringsProp, disabled, className, renderItem, portalContainer, id, ref, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, 'aria-required': ariaRequired, name, invalid, error, required, onBlur, onSearch, debounceMs, creatable, onCreate, getItemGroup, renderGroupLabel, hasMore, onLoadMore, loadingMore, getItemDisabled, highlightMatch, size: sizeProp, open, defaultOpen, onOpenChange, closeOnSelect, applyButton, onApply, onCancel, }: MultiComboboxProps<T>): React.ReactElement;
 export declare namespace MultiCombobox {
     var displayName: string;
 }

package/dist/components/features/combobox/hooks/use-combobox-core.d.ts

@@ -24,7 +24,8 @@ export interface UseComboboxCoreReturn<T> {
     showCreateOption: boolean;
     renderItemContent: (item: T) => React.ReactNode;
     itemToStringLabel: (item: T) => string;
+    itemToStringValue: (item: T) => string;
     getItemReactKey: (item: T) => string;
     handleScroll: (event: Event) => void;
 }
-export declare function useComboboxCore<T>({ items, searchValue, getItemLabel, getItemKey, loading, showListContent, minSearchLength, strings: stringsProp, renderItem, onSearch, debounceMs, creatable, onCreate, getItemGroup, hasMore, onLoadMore, loadingMore, highlightMatch, ensuredItems, }: UseComboboxCoreOptions<T>): UseComboboxCoreReturn<T>;
+export declare function useComboboxCore<T>({ items, searchValue, getItemLabel, getItemKey, getItemValue, loading, showListContent, minSearchLength, strings: stringsProp, renderItem, onSearch, debounceMs, creatable, onCreate, getItemGroup, hasMore, onLoadMore, loadingMore, highlightMatch, ensuredItems, }: UseComboboxCoreOptions<T>): UseComboboxCoreReturn<T>;

package/dist/components/features/combobox/hooks/use-combobox-state.d.ts

@@ -0,0 +1 @@
+export declare function useComboboxState<T>(controlled: T | undefined, defaultValue: T, onChange?: (value: T) => void): readonly [T, (next: T) => void];

package/dist/components/features/combobox/hooks/use-load-more.d.ts

@@ -8,5 +8,6 @@ export interface UseLoadMoreOptions {
 }
 export interface UseLoadMoreReturn {
     handleScroll: (event: Event) => void;
+    cancelPendingLoad: () => void;
 }
 export declare function useLoadMore({ hasMore, onLoadMore, loadingMore, }: UseLoadMoreOptions): UseLoadMoreReturn;

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

@@ -22,7 +22,7 @@ export type ComboboxStrings = {
     apply: string;
     cancel: string;
 };
-export type ComboboxSharedProps<T> = {
+export type ComboboxSharedProps<T> = Pick<React.AriaAttributes, 'aria-label' | 'aria-labelledby' | 'aria-describedby' | 'aria-invalid' | 'aria-required'> & {
     /**
      * Options to display, in display order.
      *
@@ -87,8 +87,14 @@ export type ComboboxSharedProps<T> = {
     renderItem?: (item: T) => React.ReactNode;
     /** Mounts the dropdown inside this element instead of the default portal root. */
     portalContainer?: React.RefObject<HTMLElement | null>;
-    /** Form field name, forwarded to the hidden input for uncontrolled submits. */
+    /** ID of the editable input, for an external label. */
+    id?: string;
+    /** Ref to the editable input, for focus management and form adapters. */
+    ref?: React.Ref<HTMLInputElement>;
+    /** Name for native form submission. Selected items submit their key, or their label if no key is supplied. */
     name?: string;
+    /** Overrides the serialized native form value without changing item identity or display. */
+    getItemValue?: (item: T) => string;
     /** Applies the invalid styling to the trigger. */
     invalid?: boolean;
     /** Validation message rendered beneath the trigger. */
@@ -134,6 +140,8 @@ export type ComboboxSharedProps<T> = {
     size?: ComboboxSize;
     /** Controls dropdown visibility. Pair with `onOpenChange`. */
     open?: boolean;
+    /** Initial dropdown visibility when `open` is omitted. Defaults to false. */
+    defaultOpen?: boolean;
     /** Fired when the dropdown wants to open or close. */
     onOpenChange?: (open: boolean) => void;
     /**
@@ -153,16 +161,30 @@ export type ComboboxSharedProps<T> = {
     /** Fired when the user clicks Cancel (closes without committing). */
     onCancel?: () => void;
 };
-export type ComboboxProps<T> = ComboboxSharedProps<T> & {
+type ComboboxInteractiveProps<T> = Omit<ComboboxSharedProps<T>, 'searchValue' | 'onSearchValueChange'> & {
+    /** Controls the raw search text. Omit to let the component own the query. */
+    searchValue?: string;
+    /** Initial search text for uncontrolled use. Defaults to an empty string. */
+    defaultSearchValue?: string;
+    /** Reports raw search edits and resets in either mode. */
+    onSearchValueChange?: (value: string) => void;
+};
+export type ComboboxProps<T> = ComboboxInteractiveProps<T> & {
+    /** Selected item for controlled use. Takes precedence over `selectedValue`, including null. */
+    value?: T | null;
+    /** Initial selected item for uncontrolled use. Defaults to null. */
+    defaultValue?: T | null;
+    /** Reports the next selection. Takes precedence over `onSelectedValueChange`. */
+    onValueChange?: (value: T | null) => void;
     /**
      * The selected item, or `null` when empty. Controlled.
      *
      * Held as the item itself rather than a key, so a selection stays rendered
      * even after `items` is replaced by the next search result set.
      */
-    selectedValue: T | null;
+    selectedValue?: T | null;
     /** Fired with the new selection, or `null` when cleared. */
-    onSelectedValueChange: (value: T | null) => void;
+    onSelectedValueChange?: (value: T | null) => void;
     /**
      * Clears the typed query when the popup closes. Defaults to `true`.
      * Async wrappers disable this so focus can move to an external error or
@@ -170,19 +192,26 @@ export type ComboboxProps<T> = ComboboxSharedProps<T> & {
      */
     clearSearchOnClose?: boolean;
 };
-export type MultiComboboxProps<T> = ComboboxSharedProps<T> & {
+export type MultiComboboxProps<T> = ComboboxInteractiveProps<T> & {
+    /** Selected items for controlled use. Takes precedence over `selectedValues`. */
+    values?: T[];
+    /** Initial selected items for uncontrolled use. Defaults to an empty array. */
+    defaultValues?: T[];
+    /** Reports the next committed selection. Takes precedence over `onSelectedValuesChange`. */
+    onValuesChange?: (values: T[]) => void;
     /**
      * The selected items. Controlled.
      *
      * These are merged ahead of `items` and de-duplicated by key, so selections
      * remain visible and checked even when absent from the current result set.
      */
-    selectedValues: T[];
+    selectedValues?: T[];
     /**
      * Fired with the next selection array.
      *
      * With `applyButton`, edits accumulate in an internal draft and this fires
      * only on Apply; without it, each toggle commits immediately.
      */
-    onSelectedValuesChange: (values: T[]) => void;
+    onSelectedValuesChange?: (values: T[]) => void;
 };
+export {};

package/dist/components/features/email-composer/types.d.ts

@@ -139,11 +139,13 @@ export type EmailComposerProps<C = Record<string, never>, K extends string = str
     onClose?: () => void;
     /** Immutable live context passed to pure variable resolvers; changing it does not edit the draft. */
     context: C;
-    /** Authoritative controlled draft. onChange proposes changes for the parent to accept. */
+    /** Authoritative controlled draft. onValueChange proposes changes for the parent to accept. */
     value?: ComposerDraft<K>;
     /** Initial uncontrolled draft and discard baseline; remount with a new key for another message. */
     defaultValue?: Partial<ComposerDraft<K>>;
     /** Receives a detached draft proposal; treat it immutably when persisting controlled state. */
+    onValueChange?: (draft: ComposerDraft<K>) => void;
+    /** Legacy alias for onValueChange, used when onValueChange is omitted. */
     onChange?: (draft: ComposerDraft<K>) => void;
     /** Per-field editing mode and independent add/remove permissions. */
     recipients?: Partial<Record<"to" | "cc" | "bcc", RecipientOptions>>;

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. */
@@ -28,3 +29,14 @@ export interface RangeFacetProps {
  * and provides a user-friendly interface for range selection.
  */
 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;
+}
+/** The public facet and the Confirm editor share the same field anatomy. */
+export declare function RangeFacetFields({ min, max, onMinChange, onMaxChange, className, invalid }: RangeFacetFieldsProps): import("react").JSX.Element;
+export {};

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

@@ -135,9 +135,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;
 }
 /**
@@ -196,7 +196,7 @@ export interface ActiveFilter {
     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/partials/date-filter-content.d.ts

@@ -1,7 +1,8 @@
-import type { FilterConfig, FilterTriggerSource } from '../filters.types';
+import type { FilterConfig, FilterOperator, FilterTriggerSource } from '../filters.types';
 interface DateFilterContentProps {
     /** Definition of the filter this control edits. */
     filter: FilterConfig;
+    operator?: FilterOperator;
     /** Current value. */
     value: string[];
     /** Fired when the change filters change. */
@@ -10,5 +11,5 @@ interface DateFilterContentProps {
     /** Origin of the editor, which determines back-button behavior. */
     triggerSource?: FilterTriggerSource;
 }
-export declare function DateFilterContent({ filter, value, onFilterChange, onBackToFilterList, triggerSource, }: DateFilterContentProps): import("react").JSX.Element;
+export declare function DateFilterContent({ filter, operator, value, onFilterChange, onBackToFilterList, triggerSource, }: DateFilterContentProps): import("react").JSX.Element;
 export {};