themelia-react-ui 2.0.6 → 3.0.0

package/dist/components/features/ai-chat/ai-chat.strings.d.ts

@@ -4,6 +4,18 @@
  * Consumers override via the `strings` prop on the relevant component; values
  * are deep-merged over the defaults so partial overrides are safe.
  */
+import type { StringsProp } from '../../../lib/strings';
+import type { AiAgentStrings } from '../../blocks/ai/ai-agent';
+import type { AiArtifactStrings } from '../../blocks/ai/ai-artifact';
+import type { AiAttachmentStrings } from '../../blocks/ai/ai-attachment';
+import type { AiChainOfThoughtStrings } from '../../blocks/ai/ai-chain-of-thought';
+import type { AiCodeBlockStrings } from '../../blocks/ai/ai-code-block';
+import type { AiConfirmationStrings } from '../../blocks/ai/ai-confirmation';
+import type { AiMessageBubbleStrings } from '../../blocks/ai/ai-message-bubble';
+import type { AiReasoningStrings } from '../../blocks/ai/ai-reasoning';
+import type { AiSourcesStrings } from '../../blocks/ai/ai-sources';
+import type { AiTaskStrings } from '../../blocks/ai/ai-task';
+import type { AiToolCallStrings } from '../../blocks/ai/ai-tool-call';
 export interface AiChatPromptInputStrings {
     /** Placeholder copy for the textarea. */
     placeholder: string;
@@ -13,10 +25,10 @@ export interface AiChatPromptInputStrings {
     submitAria: string;
     /** Aria label for the stop button (replaces submit while streaming). */
     stopAria: string;
-    /** Aria label for the model picker button (when `modelPicker` is provided). */
-    modelPickerAria: string;
     /** Hint shown under the input. Supports `{{key}}` for the submit shortcut. */
     hint: string;
+    /** Copy for staged attachment chips: remove, upload progress and failure. Omitted keys keep the chip's defaults. */
+    attachment?: StringsProp<AiAttachmentStrings>;
 }
 export declare const defaultAiChatPromptInputStrings: AiChatPromptInputStrings;
 export interface AiChatConversationStrings {
@@ -38,8 +50,33 @@ export interface AiChatSuggestionsStrings {
     header: string;
 }
 export declare const defaultAiChatSuggestionsStrings: AiChatSuggestionsStrings;
+/**
+ * Message copy. `pending` is the placeholder shown before any part arrives;
+ * the optional groups localize the parts a message renders, and each is
+ * forwarded to its `blocks/ai` surface, whose own defaults fill omitted keys.
+ */
 export interface AiChatMessageStrings {
     pending: string;
+    /** The bubble's copy, copied, regenerate and loading labels. */
+    bubble?: StringsProp<AiMessageBubbleStrings>;
+    /** Tool-call status and detail labels. */
+    toolCall?: StringsProp<AiToolCallStrings>;
+    /** Approve, reject and outcome labels of a confirmation part. */
+    confirmation?: StringsProp<AiConfirmationStrings>;
+    /** Reasoning header and disclosure labels. */
+    reasoning?: StringsProp<AiReasoningStrings>;
+    /** Sources title and visit labels. */
+    sources?: StringsProp<AiSourcesStrings>;
+    /** Code block copy labels. */
+    codeBlock?: StringsProp<AiCodeBlockStrings>;
+    /** Artifact open, copy and download labels. */
+    artifact?: StringsProp<AiArtifactStrings>;
+    /** Task status and subtask disclosure labels. */
+    task?: StringsProp<AiTaskStrings>;
+    /** Attachment chips inside a message: open and failure labels. */
+    attachment?: StringsProp<AiAttachmentStrings>;
+    /** Chain-of-thought title and streaming hint. */
+    chainOfThought?: StringsProp<AiChainOfThoughtStrings>;
 }
 export declare const defaultAiChatMessageStrings: AiChatMessageStrings;
 export interface AiChatStrings {
@@ -48,6 +85,8 @@ export interface AiChatStrings {
     queue: AiChatQueueStrings;
     suggestions: AiChatSuggestionsStrings;
     message: AiChatMessageStrings;
+    /** Status labels of the agent shown in the header. Omitted keys keep the agent's defaults. */
+    agent?: StringsProp<AiAgentStrings>;
     emptyTitle: string;
     emptyDescription: string;
     /** Screen-reader announcement emitted while the composer is disabled. */

package/dist/components/features/ai-chat/ai-chat.types.d.ts

@@ -91,6 +91,12 @@ export type AiChatMessagePart = {
     details?: ReactNode;
     onApprove?: () => void;
     onReject?: () => void;
+    /** Names this decision's approve action, such as "Delete rows". */
+    approveLabel?: ReactNode;
+    /** Names this decision's reject action. */
+    rejectLabel?: ReactNode;
+    /** Leading glyph that identifies the kind of decision. */
+    icon?: LucideIcon;
 } | {
     type: 'custom';
     render: () => ReactNode;

package/dist/components/features/ai-chat/partials/ai-chat-attachments-strip.d.ts

@@ -1,3 +1,5 @@
+import type { AiAttachmentStrings } from '../../../blocks/ai/ai-attachment';
+import type { StringsProp } from '../../../../lib/strings';
 import type { AiChatAttachment } from '../ai-chat.types';
 export interface AiChatAttachmentsStripProps {
     /** Files staged on the draft. */
@@ -8,8 +10,10 @@ export interface AiChatAttachmentsStripProps {
     onOpen?: (att: AiChatAttachment) => void;
     /** Merged onto the outermost node. */
     className?: string;
+    /** Overrides each chip's own copy. */
+    strings?: StringsProp<AiAttachmentStrings>;
 }
-export declare function AiChatAttachmentsStrip({ attachments, onRemove, onOpen, className, }: AiChatAttachmentsStripProps): import("react").JSX.Element | null;
+export declare function AiChatAttachmentsStrip({ attachments, onRemove, onOpen, className, strings, }: AiChatAttachmentsStripProps): import("react").JSX.Element | null;
 export declare namespace AiChatAttachmentsStrip {
     var displayName: string;
 }

package/dist/components/features/ai-chat/partials/ai-chat-prompt-input.d.ts

@@ -20,9 +20,9 @@ export interface AiChatPromptInputProps {
     onValueChange: (value: string) => void;
     /** Submit callback — fires on Enter or send-button click. */
     onSubmit?: (values: AiChatSubmitValues) => void;
-    /** Stop callback — wired to the stop button while `streaming`. */
+    /** Stop callback — wired to the stop button while `streaming`. Without it no stop button is offered. */
     onStop?: () => void;
-    /** Streaming flag — flips submit ↔ stop and disables the submit button. */
+    /** Streaming flag — disables submit and, when `onStop` is set, replaces it with stop. */
     streaming?: boolean;
     /** Disable the entire composer (e.g. while waiting for an upload). */
     disabled?: boolean;

package/dist/components/features/ai-chat/partials/ai-chat-queue.d.ts

@@ -8,12 +8,14 @@ export interface AiChatQueueProps {
     hideHeader?: boolean;
     /** Fired when entry editing is cancelled. */
     onCancel?: (id: string) => void;
+    /** Makes every cancel control unavailable. `AiChat` sets it from its own `disabled`. */
+    disabled?: boolean;
     /** Merged onto the outermost node. */
     className?: string;
     /** Overrides this surface's own copy. */
     strings?: StringsProp<AiChatQueueStrings>;
 }
-export declare function AiChatQueue({ items, hideHeader, onCancel, className, strings: stringsProp, }: AiChatQueueProps): import("react").JSX.Element | null;
+export declare function AiChatQueue({ items, hideHeader, onCancel, disabled, className, strings: stringsProp, }: AiChatQueueProps): import("react").JSX.Element | null;
 export declare namespace AiChatQueue {
     var displayName: string;
 }

package/dist/components/features/ai-chat/partials/ai-chat-suggestions-row.d.ts

@@ -5,6 +5,11 @@ export interface AiChatSuggestionsRowProps<TData = unknown> {
     /** Matches for the current query. */
     suggestions: ReadonlyArray<AiChatSuggestion<TData>>;
     onPick?: (s: AiChatSuggestion<TData>) => void;
+    /**
+     * Makes every chip unavailable. `AiChat` sets it from its own `disabled`;
+     * chips stay available while a response streams, so a pick can be queued.
+     */
+    disabled?: boolean;
     /** Hides the header region. */
     hideHeader?: boolean;
     /** Merged onto the outermost node. */
@@ -12,7 +17,7 @@ export interface AiChatSuggestionsRowProps<TData = unknown> {
     /** Overrides this surface's own copy. */
     strings?: StringsProp<AiChatSuggestionsStrings>;
 }
-export declare function AiChatSuggestionsRow<TData = unknown>({ suggestions, onPick, hideHeader, className, strings: stringsProp, }: AiChatSuggestionsRowProps<TData>): import("react").JSX.Element | null;
+export declare function AiChatSuggestionsRow<TData = unknown>({ suggestions, onPick, disabled, hideHeader, className, strings: stringsProp, }: AiChatSuggestionsRowProps<TData>): import("react").JSX.Element | null;
 export declare namespace AiChatSuggestionsRow {
     var displayName: string;
 }

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, onStaffIdChange, 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, onAppointmentClick, appointmentActions, renderAppointment, onRangeChange, onCreateAppointment, onConflictsDismiss, loading, error, onRetry, weekStartsOn: weekStartsOnProp, locale: localeProp, surface, 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

@@ -9,9 +9,11 @@ export type AppointmentCalendarView = 'day' | 'week';
 /**
  * Categorical colour for a service category. Categories are kinds, not
  * statuses, so they draw from the chart series palette and never from the
- * success, warning or destructive tones that status chips own.
+ * success, warning or destructive tones that status chips own. Series 6, 7
+ * and 8 are the theme's red, yellow and green series. The colour is a marker
+ * (a dot or stripe), never a text colour: the yellow series is too pale for text.
  */
-export type AppointmentCategoryColor = 'chart-1' | 'chart-2' | 'chart-3' | 'chart-4' | 'chart-5';
+export type AppointmentCategoryColor = 'chart-1' | 'chart-2' | 'chart-3' | 'chart-4' | 'chart-5' | 'chart-6' | 'chart-7' | 'chart-8';
 /** A service category: its label, filter chip and marker colour. */
 export interface AppointmentCategory {
     /** Stable identity, referenced by `Appointment.category`. */
@@ -120,6 +122,8 @@ export interface AppointmentCalendarStrings {
     formatActionsLabel: (title: string) => string;
 }
 export declare const defaultAppointmentCalendarStrings: AppointmentCalendarStrings;
+/** Whether the calendar draws its own frame (`card`) or sits inside another surface (`flat`). */
+export type AppointmentCalendarSurface = 'card' | 'flat';
 /** What the calendar has worked out for one appointment, handed to `renderAppointment`. */
 export interface AppointmentRenderContext {
     /** The appointment's category, when one matches. */
@@ -178,10 +182,8 @@ export interface AppointmentCalendarProps<T extends Appointment = Appointment> {
     staffId?: string;
     /** Staff filter for uncontrolled use. Defaults to `all`. */
     defaultStaffId?: string;
-    /** Fired when the staff filter changes. Takes precedence over `onStaffChange`. */
+    /** Fired when the staff filter changes. */
     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;
     /**
@@ -215,6 +217,18 @@ export interface AppointmentCalendarProps<T extends Appointment = Appointment> {
     onRetry?: () => void;
     /** First column of the month and first day of the week. Defaults to the provider, then Sunday. */
     weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * BCP 47 locale for weekday and month names, dates and times ("de-DE").
+     * Defaults to the provider's formatting locale.
+     */
+    locale?: string;
+    /**
+     * `card` (default) draws the calendar's own frame: one surface whose header,
+     * notice, month and agenda are regions, never cards of their own. `flat`
+     * draws no frame or outer inset, for a calendar placed inside a `Card` or
+     * another surface that already owns them.
+     */
+    surface?: AppointmentCalendarSurface;
     /** Overrides this calendar's own copy. */
     strings?: StringsProp<AppointmentCalendarStrings>;
     /** Merged onto the root. */

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

@@ -1,3 +1,3 @@
 export { AppointmentCalendar } from './appointment-calendar';
-export { defaultAppointmentCalendarStrings, type Appointment, type AppointmentCalendarProps, type AppointmentCalendarStrings, type AppointmentCalendarView, type AppointmentCategory, type AppointmentCategoryColor, type AppointmentConflict, type AppointmentDateRange, type AppointmentPerson, type AppointmentRenderContext, type AppointmentStatus, } from './appointment-calendar.types';
+export { defaultAppointmentCalendarStrings, type Appointment, type AppointmentCalendarProps, type AppointmentCalendarStrings, type AppointmentCalendarSurface, type AppointmentCalendarView, type AppointmentCategory, type AppointmentCategoryColor, type AppointmentConflict, type AppointmentDateRange, type AppointmentPerson, type AppointmentRenderContext, type AppointmentStatus, } from './appointment-calendar.types';
 export { appointmentsOn, filterAppointments, findConflicts, } from './appointment-calendar.utils';

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

@@ -1,14 +1,18 @@
 /**
- * AppointmentAgenda — the list beside the month: one day's appointments, or
- * the selected week grouped by day. Each row shows its category stripe, the
- * service with its status chip (or the conflict chip when it overlaps another
- * booking for the same staff member), the time range and client, and the
- * staff member's avatar. A row opens only when the app can open it: a
- * transparent button stretched over the row takes the click, and the actions
- * menu sits above it, since a button cannot hold another. Private to the
- * appointment calendar.
+ * AppointmentAgenda — the agenda pane: one day's appointments, or the selected
+ * week listed day by day. It is a region of the calendar's surface, not a card.
+ *
+ * Rows are flush base `Item`s separated by one quiet rule. Each reads left to
+ * right: a fixed-width time column (start over end, tabular figures) so every
+ * title starts on the same line; a slim category marker in the category's
+ * chart colour; the service with its status chip (or the conflict chip when it
+ * overlaps another booking for the same staff member); the client and staff
+ * names; then the staff avatar and the actions menu. A conflict washes the
+ * whole row. A row opens only when the app can open it: a transparent button
+ * stretched over the row takes the press, and the actions menu sits above it,
+ * since a button cannot hold another. Private to the appointment calendar.
  */
-import { type ReactNode } from 'react';
+import { type ReactNode, type Ref } from 'react';
 import { type ActionMenuAction } from '../../../base/action-menu';
 import type { Appointment, AppointmentCalendarStrings, AppointmentCategory, AppointmentRenderContext } from '../appointment-calendar.types';
 export interface AppointmentAgendaProps {
@@ -28,5 +32,9 @@ export interface AppointmentAgendaProps {
     appointmentActions?: (appointment: Appointment) => readonly ActionMenuAction[];
     renderAppointment?: (appointment: Appointment, context: AppointmentRenderContext) => ReactNode;
     strings: AppointmentCalendarStrings;
+    /** The pane's inset, which the calendar's surface decides. */
+    className?: string;
+    /** The agenda's own node: a stable place to return focus to when a control above it goes away. */
+    regionRef?: Ref<HTMLDivElement>;
 }
-export declare function AppointmentAgenda({ days, appointments, categories, conflicts, heading, loading, error, onRetry, locale, onAppointmentClick, appointmentActions, renderAppointment, strings }: AppointmentAgendaProps): import("react").JSX.Element;
+export declare function AppointmentAgenda({ days, appointments, categories, conflicts, heading, loading, error, onRetry, locale, onAppointmentClick, appointmentActions, renderAppointment, strings, regionRef, className }: AppointmentAgendaProps): import("react").JSX.Element;

package/dist/components/features/async-preview/async-preview.d.ts

@@ -12,7 +12,7 @@ declare function AsyncPreviewRoot<TData, TContext = unknown, TType extends strin
 declare namespace AsyncPreviewRoot {
     var displayName: string;
 }
-declare function AsyncPreviewTrigger<TData = unknown, TContext = unknown, TType extends string = string>({ render, children }: AsyncPreviewTriggerProps<TData, TContext, TType>): import("react").JSX.Element;
+declare function AsyncPreviewTrigger<TData = unknown, TContext = unknown, TType extends string = string>({ render, children, openOnHover, delay, closeDelay }: AsyncPreviewTriggerProps<TData, TContext, TType>): import("react").JSX.Element;
 declare namespace AsyncPreviewTrigger {
     var displayName: string;
 }
@@ -46,7 +46,7 @@ declare function createAsyncPreview<TData, TContext = unknown, TType extends str
         displayName: string;
     };
     Trigger: {
-        ({ render, children }: AsyncPreviewTriggerProps<TData, TContext, TType>): import("react").JSX.Element;
+        ({ render, children, openOnHover, delay, closeDelay }: AsyncPreviewTriggerProps<TData, TContext, TType>): import("react").JSX.Element;
         displayName: string;
     };
     Content: typeof AsyncPreviewContent;

package/dist/components/features/async-preview/async-preview.types.d.ts

@@ -66,8 +66,26 @@ export interface AsyncPreviewRootBaseProps<TData, TContext = unknown, TType exte
 export interface AsyncPreviewDynamicRootProps<TData, TContext = unknown, TType extends string = string> extends AsyncPreviewRootBaseProps<TData, TContext, TType> {
     onShow: (args: AsyncPreviewShowArgs<TContext, TType>) => Promise<TData | null | undefined> | TData | null | undefined;
     data?: never;
-    /** Stable cache key. When omitted, every open fetches fresh data. */
+    /**
+     * Stable cache key. When omitted, every open fetches fresh data, except
+     * that the open following a completed `prefetchOn` request shows that
+     * result instead of fetching twice.
+     *
+     * It also decides what closing or unmounting does to a pending request.
+     * Without a key the request is aborted and the next open fetches again.
+     * With a key it is left to finish and its result is written to the shared
+     * cache only (no state change, no `onData`/`onSettled`), so the next open
+     * with that key reads it within `staleTime`. A failure caches nothing and
+     * is reported once through `onError`.
+     */
     cacheKey?: string;
+    /**
+     * Identifies the record behind an object `context` when no `cacheKey` is
+     * set. A changed key while the preview is open loads the new record. A
+     * string, number or boolean `context` is its own key; `cacheKey` wins
+     * when both are passed.
+     */
+    contextKey?: string | number;
     /** Default `cache-first`; set `network-only` to fetch on every open. */
     cachePolicy?: AsyncPreviewCachePolicy;
     /** Keep cache entries warm for this duration. Default 5 minutes. */
@@ -80,6 +98,7 @@ export interface AsyncPreviewStaticRootProps<TData, TContext = unknown, TType ex
      */
     data: TData | null | undefined;
     onShow?: never;
+    contextKey?: never;
     cacheKey?: never;
     cachePolicy?: never;
     staleTime?: never;
@@ -103,6 +122,16 @@ export interface AsyncPreviewTriggerProps<TData = unknown, TContext = unknown, T
     render?: ReactElement | ((props: AsyncPreviewTriggerRenderProps<TData, TContext, TType>) => ReactElement);
     /** Ordinary content for the package-owned default button. */
     children?: ReactNode;
+    /**
+     * Also open the preview on pointer hover. Default false: the trigger
+     * opens on click, Enter or Space, and hover only prefetches when the root
+     * sets `prefetchOn="hover"`. Keyboard opening is unchanged.
+     */
+    openOnHover?: boolean;
+    /** Milliseconds the pointer rests on the trigger before a hover open. Needs `openOnHover`. */
+    delay?: number;
+    /** Milliseconds after the pointer leaves before a hover-opened preview closes. Needs `openOnHover`. */
+    closeDelay?: number;
 }
 export interface AsyncPreviewContentProps extends Omit<ComponentProps<typeof PopoverContent>, 'children' | 'inset'> {
     children: ReactNode;

package/dist/components/features/async-preview/preview-trigger-cell.d.ts

@@ -4,6 +4,8 @@
  * It renders a button only when preview interaction exists. Empty, disabled,
  * or explicitly non-previewable values keep the same table rhythm without a
  * caret, pointer cursor, popup ARIA, or trigger padding that implies action.
+ * A `disabledReason` keeps the cell focusable as an unavailable button, so
+ * keyboard, touch and pointer users reach the reason through the shared Tooltip.
  */
 import { type LucideIcon } from 'lucide-react';
 import React, { type ReactNode } from 'react';
@@ -28,11 +30,14 @@ export interface PreviewTriggerCellProps extends PreviewTriggerCellRootProps {
     };
     /** Leading glyph. */
     icon?: LucideIcon;
-    /** Copy shown when the value is empty. */
+    /** Copy shown when the value is empty. Defaults to the shared em dash. */
     emptyLabel?: ReactNode;
     /** Whether this row has a preview to open. */
     hasPreview?: boolean;
-    /** Explains why the preview is unavailable, shown as a tooltip. */
+    /**
+     * Explains why the preview is unavailable. The cell stays focusable as an
+     * unavailable button and shows this in a tooltip on hover and focus.
+     */
     disabledReason?: ReactNode;
     /** Applies name casing to the value regardless of how it arrives. */
     forceNameCase?: boolean;

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' | 'getItemLabel' | 'getItemKey' | 'loading' | 'showListContent' | 'renderItem' | 'strings' | 'error' | 'debounceMs'> {
+export interface AsyncResourceComboboxProps<T> extends Omit<ComboboxProps<T>, 'items' | 'hasMore' | 'onLoadMore' | 'loadingMore' | 'clearSearchOnClose' | 'getItemLabel' | 'getItemKey' | 'loading' | '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, 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 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, ref, ...props }: AsyncResourceComboboxProps<T>): import("react").JSX.Element;
 export declare namespace AsyncResourceCombobox {
     var displayName: string;
 }

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

@@ -9,12 +9,21 @@
  * between single and multiple selection variants.
  */
 import * as React from 'react';
-import type { ComboboxProps, MultiComboboxProps } from './types';
-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;
+import type { ComboboxListControl, ComboboxProps, MultiComboboxProps } from './types';
+/**
+ * The single-selection combobox with the list control the async wrappers in
+ * this package need. Not exported from the family entry; `Combobox` is the
+ * public component.
+ */
+export declare function ComboboxWithListControl<T>({ items, value, defaultValue, onValueChange, 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> & ComboboxListControl): React.ReactElement;
+export declare namespace ComboboxWithListControl {
+    var displayName: string;
+}
+export declare function Combobox<T>(props: ComboboxProps<T>): React.ReactElement;
 export declare namespace Combobox {
     var displayName: string;
 }
-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 function MultiCombobox<T>({ items, values, defaultValues, onValuesChange, searchValue: controlledSearch, defaultSearchValue, onSearchValueChange: onSearchChange, getItemLabel, getItemKey, getItemValue, loading, 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/components/error-message.d.ts

@@ -4,12 +4,14 @@
 import * as React from 'react';
 import type { ComboboxSize } from '../types';
 export interface ErrorMessageProps {
+    /** Id the owning input references through `aria-describedby`. */
+    id?: string;
     error?: string;
     /** Size preset. */
     size: ComboboxSize;
     className?: string;
 }
-export declare function ErrorMessage({ error, size: _size, className, }: ErrorMessageProps): React.ReactElement | null;
+export declare function ErrorMessage({ id, error, size: _size, className, }: ErrorMessageProps): React.ReactElement | null;
 export declare namespace ErrorMessage {
     var displayName: string;
 }

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

@@ -5,8 +5,8 @@
  * to reduce duplication and ensure consistent behavior.
  */
 import * as React from 'react';
-import type { ComboboxStrings, ComboboxSharedProps } from '../types';
-export interface UseComboboxCoreOptions<T> extends ComboboxSharedProps<T> {
+import type { ComboboxListControl, ComboboxStrings, ComboboxSharedProps } from '../types';
+export interface UseComboboxCoreOptions<T> extends ComboboxSharedProps<T>, ComboboxListControl {
     /** Items that should always be included (selected items) */
     ensuredItems?: T[];
 }

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

@@ -9,5 +9,5 @@
 export { Combobox, MultiCombobox } from './combobox';
 export { AsyncResourceCombobox, defaultAsyncResourceComboboxStrings, type AsyncResourceComboboxFetcher, type AsyncResourceComboboxFetcherArgs, type AsyncResourceComboboxProps, type AsyncResourceComboboxRenderErrorContext, type AsyncResourceComboboxRenderOptionContext, type AsyncResourceComboboxStrings, } from './async-resource-combobox';
 export { defaultComboboxStrings, } from './constants';
-export type { ComboboxSize, ComboboxStrings, ComboboxSharedProps, ComboboxProps, MultiComboboxProps, } from './types';
+export type { ComboboxSize, ComboboxStrings, ComboboxSharedProps, ComboboxListControl, ComboboxProps, MultiComboboxProps, } from './types';
 export { useComboboxCore, type UseComboboxCoreOptions, type UseComboboxCoreReturn, } from './hooks';

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

@@ -17,6 +17,12 @@ export type ComboboxStrings = {
     noResults: string;
     typeToSearch: string;
     typeMore: string;
+    /**
+     * Builds the remaining-characters hint from the count, for languages whose
+     * plural forms the `{remaining}` / `{s}` template cannot express. Wins over
+     * `typeMore` when supplied.
+     */
+    formatTypeMore?: (remaining: number) => string;
     createNew: string;
     loadingMore: string;
     apply: string;
@@ -53,14 +59,6 @@ export type ComboboxSharedProps<T> = Pick<React.AriaAttributes, 'aria-label' | '
     getItemKey?: (item: T) => string;
     /** Shows the loading status row and suppresses lower-priority list rows. */
     loading?: boolean;
-    /**
-     * Whether list-owned content may render. Defaults to `true`.
-     *
-     * Async wrappers disable this while presenting a mutually exclusive error.
-     * That suppresses statuses, selected/results, create, empty, pagination, and
-     * apply rows without clearing the controlled selection.
-     */
-    showListContent?: boolean;
     /**
      * Characters required before the list becomes active. Default: `3`.
      *
@@ -75,8 +73,6 @@ export type ComboboxSharedProps<T> = Pick<React.AriaAttributes, 'aria-label' | '
     disabled?: boolean;
     /** Merged onto the trigger's outermost node. */
     className?: string;
-    /** Shows a clear affordance that resets the selection to `null` / `[]`. */
-    clearable?: boolean;
     /**
      * Custom renderer for an option's content.
      *
@@ -144,22 +140,6 @@ export type ComboboxSharedProps<T> = Pick<React.AriaAttributes, 'aria-label' | '
     defaultOpen?: boolean;
     /** Fired when the dropdown wants to open or close. */
     onOpenChange?: (open: boolean) => void;
-    /**
-     * Whether the dropdown should close after selecting an item.
-     * Default: `true` for single, `false` for multiple.
-     */
-    closeOnSelect?: boolean;
-    /**
-     * Render an "Apply" / "Cancel" footer instead of committing each
-     * selection immediately. Only meaningful for multi-select. The
-     * working selection lives internally as a draft until `onApply`
-     * commits it to the controlled value.
-     */
-    applyButton?: boolean;
-    /** Fired when the user clicks Apply (or presses Enter on apply). */
-    onApply?: () => void;
-    /** Fired when the user clicks Cancel (closes without committing). */
-    onCancel?: () => void;
 };
 type ComboboxInteractiveProps<T> = Omit<ComboboxSharedProps<T>, 'searchValue' | 'onSearchValueChange'> & {
     /** Controls the raw search text. Omit to let the component own the query. */
@@ -170,48 +150,70 @@ type ComboboxInteractiveProps<T> = Omit<ComboboxSharedProps<T>, 'searchValue' |
     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.
+     * Selected item for controlled use, or `null` when empty.
      *
      * 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;
+    value?: T | null;
+    /** Initial selected item for uncontrolled use. Defaults to null. */
+    defaultValue?: T | null;
     /** Fired with the new selection, or `null` when cleared. */
-    onSelectedValueChange?: (value: T | null) => void;
+    onValueChange?: (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
      * retry action without discarding the failed query.
      */
-    clearSearchOnClose?: boolean;
+    clearSearchOnClose?: boolean; /** Shows a clear affordance that resets the selection to `null`. Defaults to `true`. */
+    clearable?: boolean;
 };
+/**
+ * Lets a wrapper in this package withhold everything the list owns while it
+ * presents its own exclusive state, such as a fetch error. Not part of the
+ * public component props; the headless `useComboboxCore` takes the same option.
+ */
+export interface ComboboxListControl {
+    /**
+     * Whether list-owned content may render. Defaults to `true`. `false`
+     * suppresses statuses, results, create, empty and pagination rows without
+     * clearing the selection.
+     */
+    showListContent?: boolean;
+}
 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.
+     * Selected items for controlled use.
      *
      * 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[];
+    values?: T[];
+    /** Initial selected items for uncontrolled use. Defaults to an empty array. */
+    defaultValues?: 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;
+    onValuesChange?: (values: T[]) => void; /** Closes the list after each pick. Default: `false`. */
+    closeOnSelect?: boolean;
+    /**
+     * Render an "Apply" / "Cancel" footer instead of committing each
+     * selection immediately. The working selection lives internally as a
+     * draft until Apply commits it.
+     *
+     * Closing by Cancel, Escape or an outside press discards the draft. With
+     * `closeOnSelect`, each pick closes the list before Apply can be reached,
+     * so the pick is committed immediately and the footer has nothing to apply;
+     * leave `closeOnSelect` off when the footer is the point.
+     */
+    applyButton?: boolean;
+    /** Fired when the user clicks Apply. */
+    onApply?: () => void;
+    /** Fired when the user clicks Cancel (closes without committing). */
+    onCancel?: () => void;
 };
 export {};