@lumx/react 4.12.0-next.6 → 4.12.1-next.0

package/index.d.ts

@@ -1776,22 +1776,119 @@ interface ComboboxOptionProps extends GenericProps$1, ReactToJSX<ComboboxOptionP
  * - `'grid'`: Grid mode with `role="grid"` and `role="gridcell"` items, enabling 2D keyboard navigation.
  */
 type ComboboxListType = 'listbox' | 'grid';
-
 /**
- * Props for Combobox.List component.
- * Note: role, id are set internally and cannot be overridden.
+ * Defines the props for the core ComboboxList template.
  */
-interface ComboboxListProps extends ListProps {
+interface ComboboxListProps$1 extends HasClassName {
     /** Accessible label for the listbox (required for accessibility). */
-    'aria-label': string;
+    '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 (Combobox.OptionAction).
-     * Enables 2D keyboard navigation and switches ARIA roles from listbox/option to grid/gridcell.
+     * The popup type. Set to "grid" when options have action buttons.
      * @default 'listbox'
      */
     type?: ComboboxListType;
 }
 
+/** Props for Combobox.List component. */
+interface ComboboxListProps extends ReactToJSX<ComboboxListProps$1, 'aria-busy'> {
+}
+
+/** Map of combobox event names to their payload types. */
+interface ComboboxEventMap {
+    /** Fired when the combobox open state changes. Payload: whether the combobox is open. */
+    open: boolean;
+    /** Fired when the active descendant changes (visual focus). Payload: the option id or null. */
+    activeDescendantChange: string | null;
+    /**
+     * Fired when the visible option count changes.
+     * Payload: the number of visible options plus the current input value.
+     */
+    optionsChange: {
+        optionsLength: number;
+        inputValue?: string;
+    } | undefined;
+    /**
+     * Fired immediately when the aggregate loading state changes (skeleton count transitions
+     * between 0 and >0). Used for empty suppression in ComboboxState and for aria-busy on the listbox.
+     */
+    loadingChange: boolean;
+    /**
+     * Fired after a 500ms debounce when loading persists, or immediately when loading ends.
+     * Used to control the loading message text in the live region (ComboboxState).
+     */
+    loadingAnnouncement: boolean;
+}
+/** Callbacks provided by the consumer (React/Vue) to react to combobox state changes. */
+interface ComboboxCallbacks {
+    /** Called when an option is selected (click or keyboard). */
+    onSelect?(option: {
+        value: string;
+    }): void;
+}
+/**
+ * Behavioral options for input-mode combobox (autocomplete/filter pattern).
+ * Shared between the core JSX template props (`ComboboxInputProps`) and the
+ * runtime controller options (`SetupComboboxInputOptions`).
+ */
+interface ComboboxInputOptions {
+    /**
+     * Controls how the combobox filters options as the user types.
+     *
+     * - `'auto'` (default) — Options are automatically filtered client-side.
+     * - `'manual'` — Filtering is the consumer's responsibility.
+     * - `'off'` — Like `'manual'`, but the input is rendered as `readOnly`
+     *   and `openOnFocus` defaults to `true`.
+     */
+    filter?: 'auto' | 'manual' | 'off';
+    /**
+     * When true, the combobox opens automatically when the input receives focus.
+     * When false (default, unless `filter` is `'off'`), the combobox only opens
+     * on click, typing, or keyboard navigation.
+     *
+     * @default false (true when filter is 'off')
+     */
+    openOnFocus?: boolean;
+}
+
+/**
+ * Defines the props for the core ComboboxInput template.
+ */
+interface ComboboxInputProps$1 extends HasClassName, HasTheme, ComboboxCallbacks, ComboboxInputOptions {
+    /** 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;
+}
+/**
+ * Props from the core `ComboboxInputProps` that framework wrappers (React/Vue)
+ * are expected to provide internally or re-type with framework-specific equivalents
+ * (e.g. React refs, framework-specific button props). Wrappers should omit these
+ * keys when exposing the core props to consumers.
+ */
+type ComboboxInputPropsToOverride = 'listboxId' | 'isOpen' | 'inputRef' | 'textFieldRef' | 'toggleButtonProps' | 'handleToggle';
+
 interface InputLabelProps$1 extends HasClassName, HasTheme {
     /** Typography variant. */
     typography?: Typography;
@@ -1969,36 +2066,13 @@ declare const RawInputTextarea: Comp<Omit<RawInputTextareaProps, "type">, HTMLTe
  * Props for Combobox.Input component.
  * Note: role, aria-autocomplete, aria-controls, aria-expanded are set internally and cannot be overridden.
  */
-interface ComboboxInputProps extends TextFieldProps {
-    /** Reference to the input element. */
-    inputRef?: Ref<HTMLInputElement>;
+interface ComboboxInputProps extends TextFieldProps, ReactToJSX<ComboboxInputProps$1, ComboboxInputPropsToOverride> {
     /**
      * Props for the toggle button.
      * When provided, a chevron button will be rendered in the text field's afterElement
      * to toggle the listbox visibility.
      */
     toggleButtonProps?: Pick<IconButtonProps, 'label'> & Partial<Omit<IconButtonProps, 'label'>>;
-    /** Called when an option is selected. */
-    onSelect?: (option: {
-        value: string;
-    }) => void;
-    /**
-     * Controls how the combobox filters options as the user types.
-     *
-     * - `'auto'` (default) — Options are automatically filtered client-side.
-     * - `'manual'` — Filtering is the consumer's responsibility.
-     * - `'off'` — Like `'manual'`, but the input is rendered as `readOnly`
-     *   and `openOnFocus` defaults to `true`.
-     */
-    filter?: 'auto' | 'manual' | 'off';
-    /**
-     * When true, the combobox opens automatically when the input receives focus.
-     * When false (default, unless `filter` is `'off'`), the combobox only opens
-     * on click, typing, or keyboard navigation.
-     *
-     * @default false (true when filter is 'off')
-     */
-    openOnFocus?: boolean;
 }
 
 /**
@@ -2011,7 +2085,7 @@ type ComboboxButtonLabelDisplayMode = 'show-selection' | 'show-label' | 'show-to
 /**
  * Defines the props for the core ComboboxButton template.
  */
-interface ComboboxButtonProps$1 extends HasClassName {
+interface ComboboxButtonProps$1 extends HasClassName, ComboboxCallbacks {
     /** The label for the button (used for ARIA and tooltip). */
     label: string;
     /** The currently selected value to display. */
@@ -2049,32 +2123,6 @@ declare namespace ComboboxProvider {
     var displayName: string;
 }
 
-/** Map of combobox event names to their payload types. */
-interface ComboboxEventMap {
-    /** Fired when the combobox open state changes. Payload: whether the combobox is open. */
-    open: boolean;
-    /** Fired when the active descendant changes (visual focus). Payload: the option id or null. */
-    activeDescendantChange: string | null;
-    /**
-     * Fired when the visible option count changes.
-     * Payload: the number of visible options plus the current input value.
-     */
-    optionsChange: {
-        optionsLength: number;
-        inputValue?: string;
-    } | undefined;
-    /**
-     * Fired immediately when the aggregate loading state changes (skeleton count transitions
-     * between 0 and >0). Used for empty suppression in ComboboxState and for aria-busy on the listbox.
-     */
-    loadingChange: boolean;
-    /**
-     * Fired after a 500ms debounce when loading persists, or immediately when loading ends.
-     * Used to control the loading message text in the live region (ComboboxState).
-     */
-    loadingAnnouncement: boolean;
-}
-
 /**
  * Hook to subscribe to a combobox event via the handle's subscriber system.
  * Re-subscribes when the handle changes (e.g. trigger mount/unmount).
@@ -2087,12 +2135,7 @@ declare function useComboboxEvent<K extends keyof ComboboxEventMap>(event: K, in
  * Polymorphic component — use `as` to render the trigger as a different element or component
  * (e.g., `as="a"`, `as={RouterLink}`). Defaults to the LumX `Button` component.
  */
-type ComboboxButtonProps<E extends ElementType$1 = typeof Button> = Omit<HasPolymorphicAs$1<E>, 'children' | 'role' | 'aria-controls' | 'aria-haspopup' | 'aria-expanded' | 'aria-activedescendant'> & HasRequiredLinkHref$1<E> & ReactToJSX<ComboboxButtonProps$1> & {
-    /** Called when an option is selected. */
-    onSelect?: (option: {
-        value: string;
-    }) => void;
-};
+type ComboboxButtonProps<E extends ElementType$1 = typeof Button> = Omit<HasPolymorphicAs$1<E>, 'children' | 'role' | 'aria-controls' | 'aria-haspopup' | 'aria-expanded' | 'aria-activedescendant'> & HasRequiredLinkHref$1<E> & ReactToJSX<ComboboxButtonProps$1>;
 
 /**
  * Combobox.OptionAction props.
@@ -2116,11 +2159,7 @@ declare const Combobox: {
     /** Provides shared combobox context (handle, listbox ID, anchor ref) to all sub-components. */
     Provider: typeof ComboboxProvider;
     /** Button trigger for select-only combobox mode with keyboard navigation and typeahead. */
-    Button: (<E extends React$1.ElementType = Comp<ButtonProps, HTMLButtonElement | HTMLAnchorElement>>(props: Omit<HasPolymorphicAs$1<E>, "children" | "aria-expanded" | "aria-haspopup" | "role" | "aria-controls" | "aria-activedescendant"> & _lumx_core_js_types.HasRequiredLinkHref<E> & ReactToJSX<ComboboxButtonProps$1> & {
-        onSelect?: (option: {
-            value: string;
-        }) => void;
-    } & React$1.ComponentProps<E> & {
+    Button: (<E extends React$1.ElementType = Comp<ButtonProps, HTMLButtonElement | HTMLAnchorElement>>(props: Omit<HasPolymorphicAs$1<E>, "children" | "aria-expanded" | "aria-haspopup" | "role" | "aria-controls" | "aria-activedescendant"> & _lumx_core_js_types.HasRequiredLinkHref<E> & ReactToJSX<ComboboxButtonProps$1> & React$1.ComponentProps<E> & {
         ref?: ComponentRef<E> | undefined;
     }) => React.JSX.Element) & {
         displayName: string;

package/index.js

@@ -6770,9 +6770,9 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
       }
     },
     select(option) {
-      callbacks.onSelect({
+      callbacks.onSelect?.({
         value: option ? getOptionValue(option) : ''
-      }, handle);
+      });
     },
     registerOption(element, callback) {
       const filterLower = filterValue.toLowerCase();
@@ -7334,6 +7334,7 @@ const ComboboxButton = Object.assign(forwardRefPolymorphic((props, ref) => {
  * @returns A ComboboxHandle for interacting with the combobox.
  */
 function setupComboboxInput(input, options) {
+  let handle;
   const {
     filter = 'auto',
     onSelect: optionOnSelect
@@ -7355,21 +7356,21 @@ function setupComboboxInput(input, options) {
    * Wraps the consumer's onSelect to perform input-mode side effects after selection:
    * clears the active descendant, resets the filter, and re-opens the popup.
    */
-  const onSelect = (option, combobox) => {
-    optionOnSelect(option, combobox);
+  const onSelect = option => {
+    optionOnSelect?.(option);
 
     // Clear the active item. In multi-select, keep visual focus so the
     // user can continue navigating after selection.
-    if (!combobox.isMultiSelect) {
-      combobox.focusNav?.clear();
+    if (!handle.isMultiSelect) {
+      handle.focusNav?.clear();
     }
     userHasTyped = false;
-    combobox.setIsOpen(true);
+    handle.setIsOpen(true);
     if (autoFilter) {
-      combobox.setFilter('');
+      handle.setFilter('');
     }
   };
-  const handle = setupCombobox({
+  handle = setupCombobox({
     onSelect
   }, {
     wrapNavigation: true