themelia-react-ui 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,84 @@
+import { type AsyncPreviewStrings } from './async-preview.strings';
+import type { AsyncPreviewBodyProps, AsyncPreviewContentProps, AsyncPreviewEmptyProps, AsyncPreviewErrorProps, AsyncPreviewLoadingProps, AsyncPreviewRootProps, AsyncPreviewState as AsyncPreviewStateValue, AsyncPreviewStateProps, AsyncPreviewTriggerProps } from './async-preview.types';
+interface AsyncPreviewContextValue<TData, TContext, TType extends string> {
+    state: AsyncPreviewStateValue<TData, TContext, TType>;
+    setOpen: (open: boolean) => void;
+    /** Overrides this surface's own copy. */
+    strings: AsyncPreviewStrings;
+    prefetchOn: false | 'hover' | 'focus';
+}
+declare function useAsyncPreviewContext<TData = unknown, TContext = unknown, TType extends string = string>(): AsyncPreviewContextValue<TData, TContext, TType>;
+declare function AsyncPreviewRoot<TData, TContext = unknown, TType extends string = string>({ children, strings: stringsProp, prefetchOn, ...options }: AsyncPreviewRootProps<TData, TContext, TType>): import("react").JSX.Element;
+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 namespace AsyncPreviewTrigger {
+    var displayName: string;
+}
+declare function AsyncPreviewContent({ className, children, align, sideOffset, finalFocus, ...props }: AsyncPreviewContentProps): import("react").JSX.Element;
+declare namespace AsyncPreviewContent {
+    var displayName: string;
+}
+declare function AsyncPreviewState<TData = unknown, TContext = unknown, TType extends string = string>({ children }: AsyncPreviewStateProps<TData, TContext, TType>): import("react").JSX.Element;
+declare namespace AsyncPreviewState {
+    var displayName: string;
+}
+declare function AsyncPreviewBody<TData = unknown, TContext = unknown, TType extends string = string>({ children }: AsyncPreviewBodyProps<TData, TContext, TType>): import("react").JSX.Element | null;
+declare namespace AsyncPreviewBody {
+    var displayName: string;
+}
+declare function AsyncPreviewLoading<TData = unknown, TContext = unknown, TType extends string = string>({ children, className }: AsyncPreviewLoadingProps<TData, TContext, TType>): import("react").JSX.Element | null;
+declare namespace AsyncPreviewLoading {
+    var displayName: string;
+}
+declare function AsyncPreviewError<TData = unknown, TContext = unknown, TType extends string = string>({ children, className }: AsyncPreviewErrorProps<TData, TContext, TType>): import("react").JSX.Element | null;
+declare namespace AsyncPreviewError {
+    var displayName: string;
+}
+declare function AsyncPreviewEmpty<TData = unknown, TContext = unknown, TType extends string = string>({ children, className }: AsyncPreviewEmptyProps<TData, TContext, TType>): import("react").JSX.Element | null;
+declare namespace AsyncPreviewEmpty {
+    var displayName: string;
+}
+declare function createAsyncPreview<TData, TContext = unknown, TType extends string = string>(): {
+    Root: {
+        ({ children, strings: stringsProp, prefetchOn, ...options }: AsyncPreviewRootProps<TData, TContext, TType>): import("react").JSX.Element;
+        displayName: string;
+    };
+    Trigger: {
+        ({ render, children }: AsyncPreviewTriggerProps<TData, TContext, TType>): import("react").JSX.Element;
+        displayName: string;
+    };
+    Content: typeof AsyncPreviewContent;
+    State: {
+        ({ children }: AsyncPreviewStateProps<TData, TContext, TType>): import("react").JSX.Element;
+        displayName: string;
+    };
+    Body: {
+        ({ children }: AsyncPreviewBodyProps<TData, TContext, TType>): import("react").JSX.Element | null;
+        displayName: string;
+    };
+    Loading: {
+        ({ children, className }: AsyncPreviewLoadingProps<TData, TContext, TType>): import("react").JSX.Element | null;
+        displayName: string;
+    };
+    Error: {
+        ({ children, className }: AsyncPreviewErrorProps<TData, TContext, TType>): import("react").JSX.Element | null;
+        displayName: string;
+    };
+    Empty: {
+        ({ children, className }: AsyncPreviewEmptyProps<TData, TContext, TType>): import("react").JSX.Element | null;
+        displayName: string;
+    };
+};
+declare const AsyncPreview: {
+    Root: typeof AsyncPreviewRoot;
+    Trigger: typeof AsyncPreviewTrigger;
+    Content: typeof AsyncPreviewContent;
+    State: typeof AsyncPreviewState;
+    Body: typeof AsyncPreviewBody;
+    Loading: typeof AsyncPreviewLoading;
+    Error: typeof AsyncPreviewError;
+    Empty: typeof AsyncPreviewEmpty;
+};
+export { AsyncPreview, AsyncPreviewRoot, AsyncPreviewTrigger, AsyncPreviewContent, AsyncPreviewState, AsyncPreviewBody, AsyncPreviewLoading, AsyncPreviewError, AsyncPreviewEmpty, createAsyncPreview, useAsyncPreviewContext, };

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

@@ -0,0 +1,14 @@
+/**
+ * Strings for AsyncPreview. Consumers override with `strings={{ ... }}` on
+ * `<AsyncPreview.Root />`; all user-facing copy is deep-merged via
+ * `useStrings`.
+ */
+export interface AsyncPreviewStrings {
+    loading: string;
+    errorTitle: string;
+    errorDescription: string;
+    retry: string;
+    emptyTitle: string;
+    emptyDescription: string;
+}
+export declare const defaultAsyncPreviewStrings: AsyncPreviewStrings;

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

@@ -0,0 +1,133 @@
+import type { ComponentProps, ReactElement, ReactNode } from 'react';
+import type { PopoverContent } from '../../base/popover';
+import type { ComponentScale } from '../../../lib/component-vocabulary';
+import type { StringsProp } from '../../../lib/strings';
+import type { AsyncPreviewStrings } from './async-preview.strings';
+export type AsyncPreviewStatus = 'idle' | 'loading' | 'success' | 'error' | 'empty';
+export type AsyncPreviewReason = 'open' | 'refresh' | 'prefetch';
+export type AsyncPreviewLoadingState = boolean | {
+    /** Display label. */
+    label?: ReactNode;
+    phase?: string;
+    progress?: number;
+};
+export type AsyncPreviewCachePolicy = 'cache-first' | 'network-only';
+export interface AsyncPreviewShowArgs<TContext, TType extends string> {
+    /** Discriminator naming which preview to render. */
+    type: TType;
+    /** Input the preview resolves against — usually the row it was opened from. */
+    context: TContext;
+    signal: AbortSignal;
+    reason: AsyncPreviewReason;
+    cached: boolean;
+    setLoading: (loading: AsyncPreviewLoadingState) => void;
+    setMeta: (meta: Record<string, unknown>) => void;
+}
+export interface AsyncPreviewState<TData, TContext, TType extends string> {
+    /** Discriminator naming which preview to render. */
+    type: TType;
+    /** Input the preview resolves against — usually the row it was opened from. */
+    context: TContext;
+    /** Records to render. */
+    data: TData | null;
+    error: unknown;
+    loading: false | Exclude<AsyncPreviewLoadingState, false>;
+    status: AsyncPreviewStatus;
+    meta: Record<string, unknown>;
+    /** Whether the surface is showing. Controlled. */
+    open: boolean;
+    cached: boolean;
+    refresh: () => void;
+    prefetch: () => void;
+    close: () => void;
+}
+export interface AsyncPreviewRootBaseProps<TData, TContext = unknown, TType extends string = string> {
+    /** Discriminator naming which preview to render. */
+    type: TType;
+    /** Input the preview resolves against — usually the row it was opened from. */
+    context: TContext;
+    children: ReactNode;
+    /** Controlled open state. */
+    open?: boolean;
+    /** Initial uncontrolled open state. */
+    defaultOpen?: boolean;
+    onOpenChange?: (
+    /** Whether the surface is showing. Controlled. */
+    open: boolean, state: AsyncPreviewState<TData, TContext, TType>) => void;
+    onBeforeShow?: (state: AsyncPreviewState<TData, TContext, TType>) => void;
+    onData?: (data: TData, state: AsyncPreviewState<TData, TContext, TType>) => void;
+    onError?: (error: unknown, state: AsyncPreviewState<TData, TContext, TType>) => void;
+    onSettled?: (state: AsyncPreviewState<TData, TContext, TType>) => void;
+    onRefresh?: (state: AsyncPreviewState<TData, TContext, TType>) => void;
+    /** Trigger prefetch without opening. Default false. Ignored for static `data`. */
+    prefetchOn?: false | 'hover' | 'focus';
+    strings?: StringsProp<AsyncPreviewStrings>;
+}
+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. */
+    cacheKey?: string;
+    /** Default `cache-first`; set `network-only` to fetch on every open. */
+    cachePolicy?: AsyncPreviewCachePolicy;
+    /** Keep cache entries warm for this duration. Default 5 minutes. */
+    staleTime?: number;
+}
+export interface AsyncPreviewStaticRootProps<TData, TContext = unknown, TType extends string = string> extends AsyncPreviewRootBaseProps<TData, TContext, TType> {
+    /**
+     * Static preview data. Pass this when the row/card already has the extra
+     * information and no fetcher is needed. `null` / `undefined` render Empty.
+     */
+    data: TData | null | undefined;
+    onShow?: never;
+    cacheKey?: never;
+    cachePolicy?: never;
+    staleTime?: never;
+}
+export type AsyncPreviewRootProps<TData, TContext = unknown, TType extends string = string> = AsyncPreviewDynamicRootProps<TData, TContext, TType> | AsyncPreviewStaticRootProps<TData, TContext, TType>;
+export interface AsyncPreviewTriggerRenderProps<TData, TContext, TType extends string> {
+    state: AsyncPreviewState<TData, TContext, TType>;
+    triggerProps: {
+        'aria-busy'?: true;
+        'data-state': 'open' | 'closed';
+        'data-loading'?: true;
+        onPointerEnter?: () => void;
+        onFocus?: () => void;
+    };
+}
+export interface AsyncPreviewTriggerProps<TData = unknown, TContext = unknown, TType extends string = string> {
+    /**
+     * Base UI-style trigger composition. Pass an existing interactive element,
+     * or a function when the element needs preview state and prefetch props.
+     */
+    render?: ReactElement | ((props: AsyncPreviewTriggerRenderProps<TData, TContext, TType>) => ReactElement);
+    /** Ordinary content for the package-owned default button. */
+    children?: ReactNode;
+}
+export interface AsyncPreviewContentProps extends Omit<ComponentProps<typeof PopoverContent>, 'children' | 'inset'> {
+    children: ReactNode;
+    /** Width preset for the preview surface. Default is `md`. */
+    size?: ComponentScale;
+    /** Tokenized inner padding for package-owned preview chrome. Default `none`. */
+    padding?: 'none' | ComponentScale;
+}
+export interface AsyncPreviewStateProps<TData = unknown, TContext = unknown, TType extends string = string> {
+    children: (state: AsyncPreviewState<TData, TContext, TType>) => ReactNode;
+}
+export interface AsyncPreviewBodyProps<TData = unknown, TContext = unknown, TType extends string = string> {
+    children: (state: AsyncPreviewState<TData, TContext, TType> & {
+        data: TData;
+    }) => ReactNode;
+}
+export interface AsyncPreviewLoadingProps<TData = unknown, TContext = unknown, TType extends string = string> {
+    children?: (state: AsyncPreviewState<TData, TContext, TType>) => ReactNode;
+    className?: string;
+}
+export interface AsyncPreviewErrorProps<TData = unknown, TContext = unknown, TType extends string = string> {
+    children?: (state: AsyncPreviewState<TData, TContext, TType>) => ReactNode;
+    className?: string;
+}
+export interface AsyncPreviewEmptyProps<TData = unknown, TContext = unknown, TType extends string = string> {
+    children?: (state: AsyncPreviewState<TData, TContext, TType>) => ReactNode;
+    className?: string;
+}

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

@@ -0,0 +1 @@
+export { clearAsyncPreviewCache, useAsyncPreview, type UseAsyncPreviewOptions, type UseAsyncPreviewReturn, } from './use-async-preview';

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

@@ -0,0 +1,8 @@
+import type { AsyncPreviewRootProps, AsyncPreviewState } from '../async-preview.types';
+export interface UseAsyncPreviewOptions<TData, TContext = unknown, TType extends string = string> extends Omit<AsyncPreviewRootProps<TData, TContext, TType>, 'children' | 'strings'> {
+}
+export type UseAsyncPreviewReturn<TData, TContext = unknown, TType extends string = string> = AsyncPreviewState<TData, TContext, TType> & {
+    setOpen: (open: boolean) => void;
+};
+export declare function useAsyncPreview<TData, TContext = unknown, TType extends string = string>(options: UseAsyncPreviewOptions<TData, TContext, TType>): UseAsyncPreviewReturn<TData, TContext, TType>;
+export declare function clearAsyncPreviewCache(cacheKey?: string): void;

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

@@ -0,0 +1,6 @@
+export { AsyncPreview, AsyncPreviewBody, AsyncPreviewContent, AsyncPreviewEmpty, AsyncPreviewError, AsyncPreviewLoading, AsyncPreviewRoot, AsyncPreviewState, AsyncPreviewTrigger, createAsyncPreview, useAsyncPreviewContext, } from './async-preview';
+export { PreviewTriggerCell } from './preview-trigger-cell';
+export { defaultAsyncPreviewStrings, type AsyncPreviewStrings, } from './async-preview.strings';
+export type { AsyncPreviewBodyProps, AsyncPreviewCachePolicy, AsyncPreviewContentProps, AsyncPreviewDynamicRootProps, AsyncPreviewEmptyProps, AsyncPreviewErrorProps, AsyncPreviewLoadingProps, AsyncPreviewLoadingState, AsyncPreviewReason, AsyncPreviewRootBaseProps, AsyncPreviewRootProps, AsyncPreviewShowArgs, AsyncPreviewState as AsyncPreviewStateValue, AsyncPreviewStateProps, AsyncPreviewStaticRootProps, AsyncPreviewStatus, AsyncPreviewTriggerProps, AsyncPreviewTriggerRenderProps, } from './async-preview.types';
+export type { PreviewTriggerCellProps } from './preview-trigger-cell';
+export { clearAsyncPreviewCache, useAsyncPreview, type UseAsyncPreviewOptions, type UseAsyncPreviewReturn, } from './hooks';

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

@@ -0,0 +1 @@
+export { AsyncPreviewBody, AsyncPreviewContent, AsyncPreviewEmpty, AsyncPreviewError, AsyncPreviewLoading, AsyncPreviewRoot, AsyncPreviewState, AsyncPreviewTrigger, } from '../async-preview';

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

@@ -0,0 +1,45 @@
+/**
+ * PreviewTriggerCell — table-cell trigger chrome for AsyncPreview.
+ *
+ * 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.
+ */
+import { type LucideIcon } from 'lucide-react';
+import React, { type ReactNode } from 'react';
+import { type BadgeProps } from '../../base/badge';
+type PreviewTriggerCellRootProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'disabled' | 'name' | 'value'>;
+export interface PreviewTriggerCellProps extends PreviewTriggerCellRootProps {
+    /** Primary text of the cell. */
+    value?: ReactNode | null;
+    /** Display name. */
+    name?: string | null;
+    /** Supporting text under the value. */
+    secondary?: ReactNode | null;
+    /** Content before the value. */
+    leading?: ReactNode;
+    /** Content after the value. */
+    trailing?: ReactNode;
+    /** Chip rendered beside the label. */
+    badge?: ReactNode | {
+        label: ReactNode;
+        tone?: BadgeProps['tone'];
+        size?: BadgeProps['size'];
+    };
+    /** Leading glyph. */
+    icon?: LucideIcon;
+    /** Copy shown when the value is empty. */
+    emptyLabel?: ReactNode;
+    /** Whether this row has a preview to open. */
+    hasPreview?: boolean;
+    /** Explains why the preview is unavailable, shown as a tooltip. */
+    disabledReason?: ReactNode;
+    /** Applies name casing to the value regardless of how it arrives. */
+    forceNameCase?: boolean;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Merged onto the content. */
+    contentClassName?: string;
+}
+export declare const PreviewTriggerCell: React.ForwardRefExoticComponent<PreviewTriggerCellProps & React.RefAttributes<HTMLButtonElement>>;
+export {};

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

@@ -0,0 +1,94 @@
+import { type ReactNode } from 'react';
+import { type StringsProp } from '../../../lib/strings';
+import type { ComboboxSize, ComboboxStrings, ComboboxProps } from './types';
+export interface AsyncResourceComboboxFetcherArgs {
+    query: string;
+    limit: number;
+    signal?: AbortSignal;
+}
+export type AsyncResourceComboboxFetcher<T> = (args: AsyncResourceComboboxFetcherArgs) => Promise<T[]>;
+export interface AsyncResourceComboboxStrings extends ComboboxStrings {
+    error: string;
+    retry: string;
+}
+export declare const defaultAsyncResourceComboboxStrings: AsyncResourceComboboxStrings;
+export interface AsyncResourceComboboxRenderOptionContext {
+    query: string;
+    isSelected: boolean;
+}
+export interface AsyncResourceComboboxRenderErrorContext {
+    error: unknown;
+    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'> {
+    /**
+     * Loads options for the current query. This component owns the request
+     * lifecycle: calls are debounced by `debounceMs`, the previous request is
+     * aborted through `args.signal`, and out-of-order responses are discarded, so
+     * the fetcher only needs to resolve or reject.
+     *
+     * A rejection clears the fetched list and presents the localized error as an
+     * exclusive state, suppressing the ordinary no-results row. Honour
+     * `args.signal` so aborts do not surface as errors.
+     */
+    fetcher: AsyncResourceComboboxFetcher<T>;
+    /** Selected item, for controlled use. Omit entirely to let the component own selection. */
+    value?: T | null;
+    /** Initial selection for uncontrolled use. Ignored once `value` is passed. */
+    defaultValue?: T | null;
+    /** Fired with the new selection in both controlled and uncontrolled modes. */
+    onValueChange?: (value: T | null) => void;
+    /** Fired after a successful fetch with the items received and the request that produced them. */
+    onAfterFetch?: (items: T[], context: AsyncResourceComboboxFetcherArgs) => void;
+    /** Fired when the fetcher rejects. Aborted and superseded requests never reach this. */
+    onError?: (error: unknown, context: AsyncResourceComboboxFetcherArgs) => void;
+    /** Stable identity for an item. Also decides which option reads as selected. */
+    getKey: (item: T) => string;
+    /** Primary display label for an item. */
+    getLabel: (item: T) => string;
+    /** Secondary text beside the label in the default option row. */
+    getDescription?: (item: T) => ReactNode;
+    /** Tertiary, dimmed text after the description in the default option row. */
+    getMeta?: (item: T) => ReactNode;
+    /**
+     * Replaces the entire default option row, including the label. When set,
+     * `getLabel`, `getDescription`, and `getMeta` no longer affect rendering
+     * (`getLabel` is still used for the input's text value).
+     */
+    renderOption?: (item: T, context: AsyncResourceComboboxRenderOptionContext) => ReactNode;
+    /**
+     * Page size passed to the fetcher as `args.limit`. Default: `10`.
+     *
+     * Advisory only — the component does not truncate the returned array, so the
+     * fetcher is responsible for honouring it.
+     */
+    limit?: number;
+    /** Quiet period before a query is issued, in milliseconds. Default: `300`. */
+    debounceMs?: number;
+    /**
+     * Characters required before a query is issued. Default: `0` here, rather
+     * than the `3` used by the synchronous comboboxes — resource lookup is
+     * expected to be browsable from the first keystroke alongside `preload`.
+     *
+     * An empty input is governed by `preload`, not by this threshold.
+     */
+    minSearchLength?: number;
+    /**
+     * Fetches with an empty query so options are available before typing.
+     * Default: `true`. Set `false` to require a query first.
+     */
+    preload?: boolean;
+    /** Replaces the default error copy shown when the fetcher rejects. */
+    errorMessage?: ReactNode;
+    /** Replaces the package error state while retaining the failed query and retry action. */
+    renderError?: (context: AsyncResourceComboboxRenderErrorContext) => ReactNode;
+    /** Overrides the combobox copy, including the async-only `error` message. */
+    strings?: StringsProp<AsyncResourceComboboxStrings>;
+    /** 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 namespace AsyncResourceCombobox {
+    var displayName: string;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Combobox Components
+ *
+ * A feature-rich, API-driven combobox built on Base UI with shadcn styling.
+ * Supports single and multiple selection, form integration, debounced search,
+ * grouping, pagination, and more.
+ *
+ * This version uses shared hooks and components to eliminate duplication
+ * between single and multiple selection variants.
+ */
+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 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 namespace MultiCombobox {
+    var displayName: string;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Default user-facing strings for `<Combobox>`.
+ *
+ * Consumers wire backend i18n at the call site:
+ *
+ *   <Combobox strings={{ noResults: t('search.empty') }} … />
+ *
+ * Templates use `{placeholder}` tokens — the component substitutes them at
+ * render time. Function-valued strings would also work; we keep templates
+ * here for the constants file.
+ */
+import type { ComboboxStrings } from './types';
+export declare const defaultComboboxStrings: ComboboxStrings;
+export type { ComboboxStrings };

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

@@ -0,0 +1,57 @@
+/**
+ * Shared ComboboxDropdown Component
+ *
+ * Renders the dropdown content for both single and multiple selection variants.
+ * Extracts shared rendering logic to reduce duplication.
+ */
+import * as React from 'react';
+import type { ComboboxStrings, ComboboxSize } from '../types';
+export interface ComboboxDropdownProps<T> {
+    /** Whether results are being fetched. */
+    loading: boolean;
+    /** Whether the status row replaces the list — while loading, or below `minSearchLength`. */
+    showStatus: boolean;
+    /** Whether the no-results row shows. */
+    showEmpty: boolean;
+    /** Current search text, used to highlight matches. */
+    searchValue: string;
+    /** Characters required before the list becomes active. */
+    minSearchLength: number;
+    /** Options to render, including the create row when offered. */
+    items: T[];
+    /** Options bucketed by group name, or `null` when grouping is off. */
+    groupedItems: Map<string, T[]> | null;
+    /** The synthetic create row, or `null` when it is not offered. */
+    createOptionItem: T | null;
+    /** Renders one option's content. */
+    renderItemContent: (item: T) => React.ReactNode;
+    /** Returns the React key for an option. */
+    getItemReactKey: (item: T) => string;
+    /** Marks individual options unselectable while still rendering them. */
+    getItemDisabled?: (item: T) => boolean;
+    /** Renders a group heading. */
+    renderGroupLabel?: (group: string) => React.ReactNode;
+    /** Whether the next page is being fetched. */
+    loadingMore?: boolean;
+    /** Resolved copy for the status, empty, and create rows. */
+    strings: ComboboxStrings;
+    /** Row density, matching the trigger's size. */
+    size?: ComboboxSize;
+    /** Mounts the dropdown inside this element instead of the default portal root. */
+    portalContainer?: React.RefObject<HTMLElement | null>;
+    /** Ref to the scrollable list, used for scroll-triggered pagination. */
+    listRef: React.RefObject<HTMLDivElement | null>;
+    /** Element the dropdown positions against. */
+    anchor?: React.RefObject<HTMLElement | null>;
+    /** Optional apply / cancel footer for the apply-button workflow. */
+    applyFooter?: {
+        applyLabel: string;
+        cancelLabel: string;
+        onApply: () => void;
+        onCancel: () => void;
+    };
+}
+export declare function ComboboxDropdown<T>({ loading, showStatus, showEmpty, searchValue, minSearchLength, items, groupedItems, createOptionItem, renderItemContent, getItemReactKey, getItemDisabled, renderGroupLabel, loadingMore, strings, size, portalContainer, listRef, anchor, applyFooter, }: ComboboxDropdownProps<T>): React.ReactElement | null;
+export declare namespace ComboboxDropdown {
+    var displayName: string;
+}

package/dist/components/features/combobox/components/error-message.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ErrorMessage Component
+ */
+import * as React from 'react';
+import type { ComboboxSize } from '../types';
+export interface ErrorMessageProps {
+    error?: string;
+    /** Size preset. */
+    size: ComboboxSize;
+    className?: string;
+}
+export declare function ErrorMessage({ error, size, className, }: ErrorMessageProps): React.ReactElement | null;
+export declare namespace ErrorMessage {
+    var displayName: string;
+}

package/dist/components/features/combobox/components/highlighted-text.d.ts

@@ -0,0 +1,14 @@
+/**
+ * HighlightedText Component
+ */
+import * as React from 'react';
+export interface HighlightedTextProps {
+    /** Visible label. */
+    text: string;
+    highlight: string;
+    highlightClassName?: string;
+}
+export declare function HighlightedText({ text, highlight, highlightClassName, }: HighlightedTextProps): React.ReactNode;
+export declare namespace HighlightedText {
+    var displayName: string;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Sub-components for the Combobox
+ */
+export { HighlightedText } from './highlighted-text';
+export type { HighlightedTextProps } from './highlighted-text';
+export { StatusContent } from './status-content';
+export type { StatusContentProps } from './status-content';
+export { ErrorMessage } from './error-message';
+export type { ErrorMessageProps } from './error-message';
+export { LoadingMore } from './loading-more';
+export type { LoadingMoreProps } from './loading-more';
+export { ComboboxDropdown } from './combobox-dropdown';
+export type { ComboboxDropdownProps } from './combobox-dropdown';

package/dist/components/features/combobox/components/loading-more.d.ts

@@ -0,0 +1,15 @@
+/**
+ * LoadingMore Component
+ */
+import * as React from 'react';
+export interface LoadingMoreProps {
+    /** Shows the pending indicator. */
+    loading: boolean;
+    /** Visible label. */
+    text: string;
+    className?: string;
+}
+export declare function LoadingMore({ loading, text, className, }: LoadingMoreProps): React.ReactElement | null;
+export declare namespace LoadingMore {
+    var displayName: string;
+}

package/dist/components/features/combobox/components/status-content.d.ts

@@ -0,0 +1,21 @@
+/**
+ * StatusContent Component
+ */
+import * as React from 'react';
+import type { ComboboxStrings } from '../types';
+export interface StatusContentProps {
+    /** Whether results are being fetched. */
+    loading?: boolean;
+    /** Current search text. */
+    searchValue: string;
+    /** Characters required before the list becomes active. */
+    minSearchLength: number;
+    /** How many options matched, deciding between the empty and results copy. */
+    itemCount: number;
+    /** Resolved copy for the status rows. */
+    strings: ComboboxStrings;
+}
+export declare function StatusContent({ loading, searchValue, minSearchLength, itemCount, strings, }: StatusContentProps): React.ReactNode;
+export declare namespace StatusContent {
+    var displayName: string;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Constants and default values for the Combobox component.
+ *
+ * Default strings live in `./combobox.strings.ts` per rule 19.
+ */
+export { defaultComboboxStrings } from './combobox.strings';
+export declare const DEFAULT_MIN_SEARCH_LENGTH = 3;
+/** Re-exported so the combobox shares the library-wide debounce window. */
+export { DEFAULT_DEBOUNCE_MS } from '../../../hooks/use-debounced-callback';
+export declare const DEFAULT_SIZE = "md";
+export declare const LOAD_MORE_THRESHOLD = 0.8;
+export declare const LOAD_MORE_DEBOUNCE_MS = 100;
+export declare const LOAD_MORE_COOLDOWN_MS = 500;
+export declare const CREATE_OPTION_SYMBOL: unique symbol;
+export declare function isCreateOption<T>(item: T): item is T & {
+    [CREATE_OPTION_SYMBOL]: string;
+};
+export declare function getCreateOptionValue<T>(item: T): string;
+export declare function createCreateOption<T>(inputValue: string): T;

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

@@ -0,0 +1,2 @@
+export { useComboboxCore } from './use-combobox-core';
+export type { UseComboboxCoreOptions, UseComboboxCoreReturn, } from './use-combobox-core';

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

@@ -0,0 +1,30 @@
+/**
+ * Headless state and rendering contract shared by the canonical comboboxes.
+ *
+ * Extracts shared logic between single and multiple selection variants
+ * 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> {
+    /** Items that should always be included (selected items) */
+    ensuredItems?: T[];
+}
+export interface UseComboboxCoreReturn<T> {
+    strings: ComboboxStrings;
+    getKey: (item: T) => string;
+    trimmedSearch: string;
+    listRef: React.RefObject<HTMLDivElement | null>;
+    baseItems: T[];
+    allItems: T[];
+    groupedItems: Map<string, T[]> | null;
+    createOptionItem: T | null;
+    showStatus: boolean;
+    showEmpty: boolean;
+    showCreateOption: boolean;
+    renderItemContent: (item: T) => React.ReactNode;
+    itemToStringLabel: (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>;

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

@@ -0,0 +1,10 @@
+/**
+ * Hook for debounced search functionality
+ */
+export interface UseDebouncedSearchOptions {
+    searchValue: string;
+    onSearch: ((value: string) => void) | undefined;
+    debounceMs?: number;
+    minSearchLength?: number;
+}
+export declare function useDebouncedSearch({ searchValue, onSearch, debounceMs, minSearchLength, }: UseDebouncedSearchOptions): void;