@lumx/core 4.9.0-next.3 → 4.9.0-next.5

package/components-and-utils.css

@@ -5005,6 +5005,38 @@ table {
   text-overflow: ellipsis;
 }
 
+/* ==========================================================================
+   Combobox
+   ========================================================================== */
+.lumx-combobox-popover {
+  overflow-y: auto;
+}
+
+.lumx-combobox-popover:empty, .lumx-combobox-popover:not(:has(.lumx-combobox-option)):not(:has(.lumx-combobox-state)):not(:has(.lumx-combobox-option-skeleton)),
+.lumx-combobox-list:empty,
+.lumx-combobox-list:not(:has(.lumx-combobox-option)):not(:has(.lumx-combobox-state)):not(:has(.lumx-combobox-option-skeleton)) {
+  display: none;
+}
+
+.lumx-combobox-state {
+  text-align: center;
+}
+
+.lumx-combobox-option-skeleton .lumx-skeleton-typography {
+  width: min(65%, 200px);
+}
+.lumx-combobox-option-skeleton:nth-child(3n+1) .lumx-skeleton-typography {
+  width: min(70%, 230px);
+}
+.lumx-combobox-option-skeleton:nth-child(3n+2) .lumx-skeleton-typography {
+  width: min(55%, 170px);
+}
+
+.lumx-combobox-option-more-info__popover {
+  max-width: 256px;
+  padding: 16px;
+}
+
 /* ==========================================================================
    Comment block
    ========================================================================== */
@@ -8104,7 +8136,7 @@ table {
   color: var(--lumx-color-dark-N);
   background-color: transparent;
 }
-.lumx-list-item__link[data-focus-visible-added] {
+.lumx-list-item__link[data-focus-visible-added], .lumx-list-item__link:has([data-focus-visible-added]) {
   outline: 2px solid var(--lumx-color-dark-N);
   outline-offset: -2px;
 }
@@ -8201,14 +8233,14 @@ table {
 
 /* Section
    ========================================================================== */
-.lumx-list-section:not(:first-child):not(.lumx-list-section + .lumx-list-section):not(.lumx-list-divider + .lumx-list-section)::before {
+.lumx-list-section:not(:first-child):not(.lumx-list-section:not([hidden]) + .lumx-list-section):not(.lumx-list-divider + .lumx-list-section)::before {
   content: "";
   display: block;
   height: 1px;
   margin: 8px 0;
   background-color: var(--lumx-color-dark-L5);
 }
-.lumx-list-section:not(:last-child):not(:has(+ .lumx-list-divider))::after {
+.lumx-list-section:not(:last-child):not(:has(+ .lumx-list-divider)):not(:has(+ [hidden]))::after {
   content: "";
   display: block;
   height: 1px;
@@ -9855,7 +9887,7 @@ table {
   color: var(--lumx-color-dark-N);
   background-color: transparent;
 }
-.lumx-side-navigation-item__link[data-focus-visible-added] {
+.lumx-side-navigation-item__link[data-focus-visible-added], .lumx-side-navigation-item__link:has([data-focus-visible-added]) {
   outline: 2px solid var(--lumx-color-dark-N);
   outline-offset: -2px;
 }

package/js/components/Combobox/ComboboxButton.d.ts

@@ -0,0 +1,54 @@
+import type { CommonRef, HasClassName, LumxClassName } from '../../types';
+/**
+ * Label display mode for the ComboboxButton.
+ * - `'show-selection'`: Show the selected value if available, otherwise the label.
+ * - `'show-label'`: Always show the label.
+ * - `'show-tooltip'`: Show nothing in the button; label appears only in tooltip.
+ */
+export type ComboboxButtonLabelDisplayMode = 'show-selection' | 'show-label' | 'show-tooltip';
+/**
+ * Defines the props for the core ComboboxButton template.
+ */
+export interface ComboboxButtonProps extends HasClassName {
+    /** The label for the button (used for ARIA and tooltip). */
+    label: string;
+    /** The currently selected value to display. */
+    value?: string;
+    /** Controls how the label/value is displayed. */
+    labelDisplayMode?: ComboboxButtonLabelDisplayMode;
+    /** The ID of the listbox element (for aria-controls). */
+    listboxId?: string;
+    /** Whether the combobox is open. */
+    isOpen?: boolean;
+    /** ref to the root button element. */
+    ref?: CommonRef;
+}
+/**
+ * Injected framework-specific components for ComboboxButton rendering.
+ */
+export interface ComboboxButtonComponents {
+    /** Button component (framework-specific, e.g. React Button with theme/disabled handling). */
+    Button: any;
+    /** Tooltip wrapper component. */
+    Tooltip: any;
+}
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "ComboboxButton";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * ComboboxButton core template.
+ * Renders a Button with combobox ARIA attributes, wrapped in a Tooltip.
+ *
+ * Framework-specific components (Tooltip) are passed as a second argument
+ * by the React/Vue wrappers.
+ *
+ * @param props      Component props.
+ * @param components Injected framework-specific components.
+ * @return JSX element.
+ */
+export declare const ComboboxButton: (props: ComboboxButtonProps, { Button, Tooltip }: ComboboxButtonComponents) => import("react").JSX.Element;

package/js/components/Combobox/ComboboxInput.d.ts

@@ -0,0 +1,49 @@
+import type { CommonRef, HasClassName, LumxClassName } from '../../types';
+/**
+ * Defines the props for the core ComboboxInput template.
+ */
+export interface ComboboxInputProps extends HasClassName {
+    /** The ID of the listbox element (for aria-controls). */
+    listboxId?: string;
+    /** Whether the combobox is open. */
+    isOpen?: boolean;
+    /** ref to the root element. */
+    ref?: CommonRef;
+    /** Reference to the input element. */
+    inputRef?: CommonRef;
+    /** Reference to the text field wrapper element. */
+    textFieldRef?: CommonRef;
+    /** Props for the toggle button (when provided, a chevron button is rendered). */
+    toggleButtonProps?: Record<string, any>;
+    /** Toggle callback for the chevron button. */
+    handleToggle?(): void;
+}
+/**
+ * Injected framework-specific components for ComboboxInput rendering.
+ */
+export interface ComboboxInputComponents {
+    /** TextField component (framework-specific, e.g. React TextField with controlled input). */
+    TextField: any;
+    /** IconButton component (framework-specific, e.g. React IconButton with theme/disabled). */
+    IconButton: any;
+}
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "ComboboxInput";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * ComboboxInput core template.
+ * Renders a TextField with combobox ARIA attributes and an optional toggle button.
+ *
+ * Framework-specific components (TextField, IconButton) are passed as a second argument
+ * by the React/Vue wrappers.
+ *
+ * @param props      Component props.
+ * @param components Injected framework-specific components.
+ * @return JSX element.
+ */
+export declare const ComboboxInput: (props: ComboboxInputProps, { TextField, IconButton }: ComboboxInputComponents) => import("react").JSX.Element;

package/js/components/Combobox/ComboboxList.d.ts

@@ -0,0 +1,47 @@
+import type { CommonRef, HasClassName, JSXElement, LumxClassName } from '../../types';
+/**
+ * Popup type for the combobox listbox.
+ * - `'listbox'`: Standard listbox with `role="listbox"` and `role="option"` items.
+ * - `'grid'`: Grid mode with `role="grid"` and `role="gridcell"` items, enabling 2D keyboard navigation.
+ */
+export type ComboboxListType = 'listbox' | 'grid';
+/**
+ * Defines the props for the core ComboboxList template.
+ */
+export interface ComboboxListProps extends HasClassName {
+    /** Accessible label for the listbox (required for accessibility). */
+    'aria-label': string;
+    /**
+     * Indicates that the listbox content is incomplete (loading).
+     * Set to `true` when skeleton placeholders are present and no real options have loaded yet.
+     * Omit (or set to `undefined`) when not loading — the attribute is not rendered as `"false"`.
+     */
+    'aria-busy'?: boolean;
+    /** Content (should be ComboboxOption elements). */
+    children?: JSXElement;
+    /** The ID of the listbox element. */
+    id?: string;
+    /** ref to the root element */
+    ref?: CommonRef;
+    /**
+     * The popup type. Set to "grid" when options have action buttons.
+     * @default 'listbox'
+     */
+    type?: ComboboxListType;
+}
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "ComboboxList";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * ComboboxList core template.
+ * Renders a List with combobox-specific ARIA attributes and styling.
+ *
+ * @param props Component props.
+ * @return JSX element.
+ */
+export declare const ComboboxList: (props: ComboboxListProps) => import("react").JSX.Element;

package/js/components/Combobox/ComboboxOption.d.ts

@@ -0,0 +1,72 @@
+import type { CommonRef, HasClassName, JSXElement, LumxClassName } from '../../types';
+/**
+ * Injected framework-specific components for ComboboxOption rendering.
+ */
+export interface ComboboxOptionComponents {
+    /** Tooltip wrapper component (optional). Used when `tooltipProps` is provided. */
+    Tooltip?: any;
+}
+/**
+ * Defines the props for the core ComboboxOption template.
+ */
+export interface ComboboxOptionProps extends HasClassName {
+    /** A component to be rendered before the content (e.g. an icon or avatar). */
+    before?: JSXElement;
+    /** A component to be rendered after the content (e.g. ComboboxOptionAction elements). */
+    after?: JSXElement;
+    /** Content (option label). */
+    children?: JSXElement;
+    /** Props forwarded to a Tooltip wrapping the role="option" / role="gridcell" element. */
+    tooltipProps?: Record<string, any>;
+    /** Helper description. */
+    description?: string;
+    /** Unique ID for the option element. */
+    id?: string;
+    /** Unique ID for the description element (for aria-describedby). */
+    descriptionId?: string;
+    /** Whether the option is disabled. */
+    isDisabled?: boolean;
+    /** Whether the option is selected. */
+    isSelected?: boolean;
+    /** Whether the parent list is in grid mode. */
+    isGrid?: boolean;
+    /**
+     * Whether the option is hidden (filtered out by auto-filter).
+     * When true, renders a bare `<li hidden>` with only the children text — no ARIA roles,
+     * no classes, no visual structure. This keeps the element in the DOM so its textContent
+     * can be read for future filter evaluations, while naturally excluding it from
+     * `[role="option"]` queries (focus navigation) and `.lumx-combobox-option` CSS rules
+     * (section/popover auto-hide).
+     */
+    hidden?: boolean;
+    /** On click callback. */
+    handleClick?(): void;
+    /** ref to the root <li> element. */
+    ref?: CommonRef;
+    /** The value for this option (used for selection). */
+    value?: string;
+}
+/**
+ * Props that React/Vue wrappers need to re-declare with framework-specific types.
+ * Used by `ReactToJSX<ComboboxOptionProps, ComboboxOptionPropsToOverride>`.
+ */
+export type ComboboxOptionPropsToOverride = 'before' | 'after' | 'children' | 'tooltipProps';
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "ComboboxOption";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * ComboboxOption core template.
+ * Renders a ListItem with combobox-specific ARIA attributes and structure.
+ *
+ * In grid mode, the ListItem renders with `role="row"` and the option content
+ * uses `role="gridcell"` instead of `role="option"`.
+ *
+ * @param props Component props.
+ * @return JSX element.
+ */
+export declare const ComboboxOption: (props: ComboboxOptionProps, { Tooltip }?: ComboboxOptionComponents) => import("react").JSX.Element;

package/js/components/Combobox/ComboboxOptionAction.d.ts

@@ -0,0 +1,35 @@
+import type { CommonRef, HasClassName, HasPolymorphicAs, HasRequiredLinkHref, JSXElement, LumxClassName } from '../../types';
+import { ClickableElement } from '../RawClickable';
+/**
+ * Defines the props for the core ComboboxOptionAction template.
+ */
+export type ComboboxOptionActionProps<E extends ClickableElement = 'button'> = HasPolymorphicAs<E> & HasClassName & HasRequiredLinkHref<E> & {
+    /** Content of the action (icon, label, etc.). */
+    children?: JSXElement;
+    /** Unique ID for the action element. */
+    id?: string;
+    /** Whether the action is disabled. */
+    isDisabled?: boolean;
+    /** On click callback. */
+    handleClick?(evt: any): void;
+    /** ref to the root element. */
+    ref?: CommonRef;
+};
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "ComboboxOptionAction";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * ComboboxOptionAction core template.
+ * Renders a secondary action button within a combobox option row (grid mode).
+ * Each action renders as a `role="gridcell"` element, enabling 2D keyboard
+ * navigation (ArrowLeft/Right to move between the option and its actions).
+ *
+ * @param props Component props.
+ * @return JSX element.
+ */
+export declare const ComboboxOptionAction: <E extends ClickableElement = "button">(props: ComboboxOptionActionProps<E>) => import("react").JSX.Element;

package/js/components/Combobox/ComboboxOptionMoreInfo.d.ts

@@ -0,0 +1,52 @@
+import type { CommonRef, HasClassName, JSXElement, LumxClassName } from '../../types';
+/**
+ * Defines the props for the core ComboboxOptionMoreInfo template.
+ */
+export interface ComboboxOptionMoreInfoProps extends HasClassName {
+    /** Popover content (additional details about the option). */
+    children?: JSXElement;
+    /** Whether the popover is open. */
+    isOpen?: boolean;
+    /** ID for the popover element (used for aria-describedby on the parent option). */
+    popoverId: string;
+    /** Ref for the anchor element (icon button). */
+    ref?: CommonRef;
+    /** Mouse enter callback. */
+    onMouseEnter?(): void;
+    /** Mouse leave callback. */
+    onMouseLeave?(): void;
+}
+/**
+ * Props that React/Vue wrappers need to re-declare with framework-specific types.
+ */
+export type ComboboxOptionMoreInfoPropsToOverride = 'children' | 'popoverId' | 'isOpen';
+/**
+ * Injected framework-specific components for ComboboxOptionMoreInfo rendering.
+ */
+export interface ComboboxOptionMoreInfoComponents {
+    /** IconButton component (framework-specific). */
+    IconButton: any;
+    /** Popover component (framework-specific). */
+    Popover: any;
+}
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "ComboboxOptionMoreInfo";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * ComboboxOptionMoreInfo core template.
+ * Renders an info icon button with a popover that shows additional details about a combobox option.
+ * The popover opens on mouse hover or when the parent option is keyboard-highlighted.
+ *
+ * Framework-specific components (IconButton, Popover) are passed as a second argument
+ * by the React/Vue wrappers.
+ *
+ * @param props      Component props.
+ * @param components Injected framework-specific components.
+ * @return JSX element.
+ */
+export declare const ComboboxOptionMoreInfo: (props: ComboboxOptionMoreInfoProps, { IconButton, Popover }: ComboboxOptionMoreInfoComponents) => import("react").JSX.Element;

package/js/components/Combobox/ComboboxOptionSkeleton.d.ts

@@ -0,0 +1,41 @@
+import type { CommonRef, HasClassName, JSXElement, LumxClassName } from '../../types';
+/**
+ * Defines the props for the core ComboboxOptionSkeleton template.
+ */
+export interface ComboboxOptionSkeletonProps extends HasClassName {
+    /** Content rendered before the skeleton text (e.g. SkeletonCircle for avatar placeholders). */
+    before?: JSXElement;
+    /** Content rendered after the skeleton text. */
+    after?: JSXElement;
+    /** Show a secondary skeleton line (mirrors ComboboxOption's `description` prop). */
+    hasDescription?: boolean;
+    /** Override the default SkeletonTypography content entirely. */
+    children?: JSXElement;
+    /** ref to the root <li> element. */
+    ref?: CommonRef;
+}
+/**
+ * Props that React/Vue wrappers need to re-declare with framework-specific types.
+ * Used by `ReactToJSX<ComboboxOptionSkeletonProps, ComboboxOptionSkeletonPropsToOverride>`.
+ */
+export type ComboboxOptionSkeletonPropsToOverride = 'before' | 'after' | 'children';
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "ComboboxOptionSkeleton";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * ComboboxOptionSkeleton core template.
+ * Renders a skeleton placeholder `<li>` inside a combobox list, styled to match
+ * option dimensions. Uses `role="none"` so screen readers ignore it.
+ *
+ * Width variation across sibling skeletons is handled by SCSS `:nth-child` rules,
+ * not by props — the component itself does not need a `width` prop.
+ *
+ * @param props Component props.
+ * @return JSX element.
+ */
+export declare const ComboboxOptionSkeleton: (props: ComboboxOptionSkeletonProps) => import("react").JSX.Element;

package/js/components/Combobox/ComboboxPopover.d.ts

@@ -0,0 +1,50 @@
+import type { CommonRef, HasClassName, JSXElement, LumxClassName } from '../../types';
+import type { FitAnchorWidth, Placement } from '../Popover/constants';
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "ComboboxPopover";
+/**
+ * Component default class name.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * Defines the props for the core ComboboxPopover template.
+ */
+export interface ComboboxPopoverProps extends HasClassName {
+    /** Content (should contain a ComboboxList). */
+    children?: JSXElement;
+    /** Whether a click anywhere out of the popover would close it. */
+    closeOnClickAway?: boolean;
+    /** Whether an escape key press would close the popover. */
+    closeOnEscape?: boolean;
+    /** Manage popover width relative to anchor. Defaults to `true` (minWidth). */
+    fitToAnchorWidth?: FitAnchorWidth | boolean;
+    /** Whether the combobox is open. */
+    isOpen?: boolean;
+    /** Placement relative to anchor. Defaults to `'bottom-start'`. */
+    placement?: Placement;
+    /** Reference to the anchor element for popover positioning. */
+    anchorRef?: CommonRef;
+    /** Callback invoked when the popover requests to close (click away, escape). */
+    handleClose?(): void;
+}
+/**
+ * Injected framework-specific components for ComboboxPopover rendering.
+ */
+export interface ComboboxPopoverComponents {
+    /** Popover component (framework-specific). */
+    Popover: any;
+}
+/**
+ * ComboboxPopover core template.
+ * Renders a Popover with combobox-specific defaults (className, closeMode, closeOnClickAway, closeOnEscape).
+ *
+ * Framework-specific components (Popover) are passed as a second argument
+ * by the React/Vue wrappers.
+ *
+ * @param props      Component props.
+ * @param components Injected framework-specific components.
+ * @return JSX element.
+ */
+export declare const ComboboxPopover: (props: ComboboxPopoverProps, { Popover }: ComboboxPopoverComponents) => import("react").JSX.Element;

package/js/components/Combobox/ComboboxSection.d.ts

@@ -0,0 +1,58 @@
+import type { CommonRef, HasClassName, JSXElement, LumxClassName } from '../../types';
+/**
+ * Defines the props for the core ComboboxSection template.
+ */
+export interface ComboboxSectionProps extends HasClassName {
+    /** Section label displayed as the group title. */
+    label?: string;
+    /** Section icon */
+    icon?: string;
+    /** Section content (should be ComboboxOption elements). */
+    children: JSXElement;
+    /** ref to the root element. */
+    ref?: CommonRef;
+    /**
+     * When true, the section renders as a bare `<li hidden>` wrapper, keeping children
+     * mounted (so option registrations stay alive) but invisible to the user and screen readers.
+     * Set automatically by the React/Vue wrapper when all child options are filtered out.
+     */
+    hidden?: boolean;
+    /**
+     * When true, the section is visually rendered (label + content) but hidden from assistive
+     * technology. Used for skeleton-only sections: the visual skeleton provides feedback to
+     * sighted users, while the live region (`ComboboxState`) handles the loading announcement.
+     */
+    'aria-hidden'?: boolean;
+}
+/**
+ * Props that React/Vue wrappers need to re-declare with framework-specific types.
+ * Used by `ReactToJSX<ComboboxSectionProps, ComboboxSectionPropsToOverride>`.
+ */
+export type ComboboxSectionPropsToOverride = 'children';
+/**
+ * Injected framework-specific components for ComboboxSection rendering.
+ */
+export interface ComboboxSectionComponents {
+    /** ListSection component (framework-specific). */
+    ListSection: any;
+}
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "ComboboxSection";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * ComboboxSection core template.
+ * Renders a ListSection with combobox-specific ARIA roles.
+ *
+ * Framework-specific components (ListSection) are passed as a second argument
+ * by the React/Vue wrappers.
+ *
+ * @param props      Component props.
+ * @param components Injected framework-specific components.
+ * @return JSX element.
+ */
+export declare const ComboboxSection: (props: ComboboxSectionProps, { ListSection }: ComboboxSectionComponents) => import("react").JSX.Element;

package/js/components/Combobox/ComboboxState.d.ts

@@ -0,0 +1,84 @@
+import type { LumxClassName } from '../../types';
+import type { TextProps } from '../Text';
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "ComboboxState";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * Defines the props for the core ComboboxState template.
+ */
+export interface ComboboxStateProps {
+    /**
+     * Message to display when the list has no visible options.
+     * Can be a plain string or a function receiving the current input value (for dynamic messages).
+     * When omitted, the empty state is not shown.
+     */
+    emptyMessage?: string | ((inputValue: string) => string);
+    /**
+     * Error state title message.
+     * When provided, the error state is active (takes priority over the empty state).
+     * When omitted, the error state is not shown.
+     */
+    errorMessage?: string;
+    /**
+     * Secondary error message (e.g. "Please try again").
+     * Only rendered when `errorMessage` is provided.
+     */
+    errorTryReloadMessage?: string;
+    /**
+     * Message to announce when loading persists (after a 500ms debounce).
+     * When omitted, no loading announcement is made.
+     */
+    loadingMessage?: string;
+    /**
+     * List state
+     */
+    state?: {
+        /**
+         * Whether the list currently has no visible options.
+         * Driven by the framework wrapper via the combobox handle's `emptyChange` event.
+         */
+        isEmpty?: boolean;
+        /**
+         * The current value of the combobox input.
+         * Passed to `emptyMessage` when it is a function.
+         */
+        inputValue?: string;
+        /**
+         * Whether loading is active (immediate, from `loadingChange` event).
+         * Used to suppress false "empty" state while data is loading.
+         */
+        isLoading?: boolean;
+    };
+}
+/**
+ * Components injected by the framework wrapper (dependency injection).
+ */
+export interface ComboboxStateComponents {
+    /**
+     * GenericBlock component (framework-specific, e.g. React GenericBlock with FlexBox handling).
+     */
+    GenericBlock: any;
+    /**
+     * Text component (framework-specific, e.g. React Text or Vue Text).
+     */
+    Text: (props: TextProps) => any;
+}
+/**
+ * ComboboxState core template.
+ * Renders empty/error state messages inside the combobox popover.
+ * The block itself acts as a screen reader live region (`role="status" aria-live="polite"`).
+ *
+ * Activation rules:
+ * - Error state: active when `errorMessage` is provided (presence-based).
+ * - Empty state: active when `isEmpty` is true and `emptyMessage` is provided, and there is no error.
+ *
+ * @param props Component props.
+ * @param components Injected framework-specific components.
+ * @return JSX element or null when no state is active.
+ */
+export declare const ComboboxState: (props: ComboboxStateProps, { GenericBlock, Text }: ComboboxStateComponents) => import("react").JSX.Element;

package/js/components/Combobox/index.d.ts

@@ -0,0 +1,23 @@
+export { setupComboboxInput } from './setupComboboxInput';
+export { setupComboboxButton } from './setupComboboxButton';
+export type { ComboboxCallbacks, ComboboxHandle } from './types';
+export { ComboboxList } from './ComboboxList';
+export type { ComboboxListProps, ComboboxListType } from './ComboboxList';
+export { ComboboxPopover } from './ComboboxPopover';
+export type { ComboboxPopoverProps, ComboboxPopoverComponents } from './ComboboxPopover';
+export { ComboboxOption } from './ComboboxOption';
+export type { ComboboxOptionProps, ComboboxOptionPropsToOverride } from './ComboboxOption';
+export { ComboboxOptionAction } from './ComboboxOptionAction';
+export type { ComboboxOptionActionProps } from './ComboboxOptionAction';
+export { ComboboxOptionSkeleton } from './ComboboxOptionSkeleton';
+export type { ComboboxOptionSkeletonProps, ComboboxOptionSkeletonPropsToOverride } from './ComboboxOptionSkeleton';
+export { ComboboxOptionMoreInfo } from './ComboboxOptionMoreInfo';
+export type { ComboboxOptionMoreInfoProps, ComboboxOptionMoreInfoPropsToOverride, ComboboxOptionMoreInfoComponents, } from './ComboboxOptionMoreInfo';
+export { ComboboxButton } from './ComboboxButton';
+export type { ComboboxButtonProps, ComboboxButtonComponents, ComboboxButtonLabelDisplayMode } from './ComboboxButton';
+export { ComboboxInput } from './ComboboxInput';
+export type { ComboboxInputProps, ComboboxInputComponents } from './ComboboxInput';
+export { ComboboxSection } from './ComboboxSection';
+export type { ComboboxSectionProps, ComboboxSectionPropsToOverride, ComboboxSectionComponents, } from './ComboboxSection';
+export { ComboboxState } from './ComboboxState';
+export type { ComboboxStateProps } from './ComboboxState';

package/js/components/Combobox/setupCombobox.d.ts

@@ -0,0 +1,24 @@
+import type { ComboboxCallbacks, ComboboxHandle, OnTriggerAttach } from './types';
+/** Options for configuring the shared combobox behavior. */
+interface ComboboxOptions {
+    /** When true, ArrowDown/ArrowUp wrap around in listbox mode (input pattern). Default: false. */
+    wrapNavigation?: boolean;
+}
+/**
+ * Set up combobox behavior (WAI-ARIA combobox pattern) on a trigger + listbox pair.
+ *
+ * The trigger and listbox are registered separately via the returned handle,
+ * allowing framework components to register them on mount. The behavior is
+ * fully attached once both are registered.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+ *
+ * @param callbacks Callbacks for select and open/close events.
+ * @param options Options for configuring the shared combobox behavior.
+ * @param onTriggerAttach Optional callback invoked when the trigger is registered and the signal is ready.
+ *                        Used by mode-specific wrappers (setupComboboxInput/Button) to automatically
+ *                        attach the appropriate controller.
+ * @returns A ComboboxHandle for interacting with the combobox.
+ */
+export declare function setupCombobox(callbacks: ComboboxCallbacks, options?: ComboboxOptions, onTriggerAttach?: OnTriggerAttach): ComboboxHandle;
+export {};