@lumx/react 4.9.0-alpha.1 → 4.9.0-alpha.3

package/index.js

@@ -1,4 +1,4 @@
-import { Kind as Kind$1, Size as Size$1, ColorPalette as ColorPalette$1, Emphasis as Emphasis$1, ColorVariant, VISUALLY_HIDDEN, Theme as Theme$1, AspectRatio as AspectRatio$1, DOCUMENT, IS_BROWSER as IS_BROWSER$1, WINDOW, DIALOG_TRANSITION_DURATION, Orientation as Orientation$1, Alignment, NOTIFICATION_TRANSITION_DURATION } from '@lumx/core/js/constants';
+import { Kind as Kind$1, Size as Size$1, ColorPalette as ColorPalette$1, Emphasis as Emphasis$1, ColorVariant, VISUALLY_HIDDEN, Theme as Theme$1, AspectRatio as AspectRatio$1, DOCUMENT, IS_BROWSER as IS_BROWSER$1, WINDOW, DIALOG_TRANSITION_DURATION, Orientation as Orientation$1, Alignment as Alignment$1, NOTIFICATION_TRANSITION_DURATION } from '@lumx/core/js/constants';
 export * from '@lumx/core/js/constants';
 export * from '@lumx/core/js/types';
 import * as React from 'react';
@@ -9,7 +9,7 @@ import ReactDOM__default from 'react-dom';
 import { classNames, onEscapePressed, onEnterPressed as onEnterPressed$1, detectHorizontalSwipe } from '@lumx/core/js/utils';
 import last from 'lodash/last.js';
 import pull from 'lodash/pull.js';
-import { u as useDisabledStateContext, P as Portal, C as ClickAwayProvider } from './_internal/C9YCH96e.js';
+import { u as useDisabledStateContext, P as Portal, C as ClickAwayProvider } from './_internal/Dpulze-1.js';
 import isEmpty from 'lodash/isEmpty.js';
 import get from 'lodash/get.js';
 import { getDisabledState } from '@lumx/core/js/utils/disabledState';
@@ -892,6 +892,8 @@ const TOOLTIP_LONG_PRESS_DELAY = {
 /**
  * Alignments.
  */
+const Alignment = {
+  left: 'left'};
 const Theme = {
   light: 'light',
   dark: 'dark'
@@ -946,7 +948,10 @@ const AspectRatio = {
   /** Ratio 3:2 */
   horizontal: 'horizontal',
   /** Ratio 1:1 */
-  square: 'square'};
+  square: 'square',
+  /** Ratio constrained by the parent. */
+  free: 'free'
+};
 /**
  * Semantic info about the purpose of the component
  */
@@ -1637,6 +1642,7 @@ const IconButton = forwardRef((props, ref) => {
     tooltipProps,
     hideTooltip,
     label,
+    theme = defaultTheme,
     ...forwardedProps
   } = props;
   const {
@@ -1654,7 +1660,7 @@ const IconButton = forwardRef((props, ref) => {
     ...tooltipProps,
     children: IconButton$1({
       ref,
-      theme: defaultTheme,
+      theme,
       ...disabledStateProps,
       ...restOfOtherProps,
       handleClick: onClick,
@@ -3207,7 +3213,7 @@ function setupListbox(handle, signal, notify) {
  *
  * @see https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
  *
- * @param callbacks Callbacks for select and open/close events.
+ * @param callbacks Callbacks invoked on combobox events (e.g. option selection).
  * @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
@@ -3238,6 +3244,9 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
   /** Last notified isEmpty state, to avoid redundant `emptyChange` notifications. */
   let lastIsEmpty = true;
 
+  /** Last notified input value, to re-fire `emptyChange` when the user keeps typing while empty. */
+  let lastInputValue = '';
+
   /** Event subscribers managed by the handle. */
   const subscribers = {
     open: new Set(),
@@ -3253,7 +3262,9 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
   }
 
   /**
-   * Notify all registered sections and fire `emptyChange` if the visible option count changed.
+   * Notify all registered sections and fire `emptyChange` if the visible option count changed
+   * or if the input value changed while the list is empty (so `emptyMessage` callbacks get
+   * the updated query string).
    * Called whenever the set of visible options may have changed (option register/unregister, filter change).
    */
   function notifyVisibilityChange() {
@@ -3265,9 +3276,10 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
       if (!reg.lastFiltered) visibleCount += 1;
     }
     const isEmpty = visibleCount === 0;
-    if (isEmpty !== lastIsEmpty) {
+    const inputValue = trigger?.value ?? '';
+    if (isEmpty !== lastIsEmpty || isEmpty && inputValue !== lastInputValue) {
       lastIsEmpty = isEmpty;
-      const inputValue = trigger?.value ?? '';
+      lastInputValue = inputValue;
       notify('emptyChange', {
         isEmpty,
         inputValue
@@ -3286,6 +3298,22 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
   /** Timer for debounced loading announcement. */
   let loadingTimer;
 
+  /** Whether a loading announcement has been sent since the last open. */
+  let announcementSent = false;
+
+  /** Start or restart the debounced loading announcement timer if conditions are met. */
+  function startLoadingAnnouncementTimer() {
+    clearTimeout(loadingTimer);
+    if (skeletonCount > 0 && isOpenState) {
+      loadingTimer = setTimeout(() => {
+        if (skeletonCount > 0 && isOpenState) {
+          announcementSent = true;
+          notify('loadingAnnouncement', true);
+        }
+      }, LOADING_ANNOUNCEMENT_DELAY);
+    }
+  }
+
   /**
    * Called when the skeleton count transitions between 0 and >0 (or vice versa).
    * Fires `loadingChange` immediately and manages the debounced `loadingAnnouncement`.
@@ -3293,15 +3321,14 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
   function onSkeletonCountChange() {
     const isLoading = skeletonCount > 0;
     notify('loadingChange', isLoading);
-    clearTimeout(loadingTimer);
     if (isLoading) {
-      loadingTimer = setTimeout(() => {
-        if (skeletonCount > 0) {
-          notify('loadingAnnouncement', true);
-        }
-      }, LOADING_ANNOUNCEMENT_DELAY);
+      startLoadingAnnouncementTimer();
     } else {
-      notify('loadingAnnouncement', false);
+      clearTimeout(loadingTimer);
+      if (announcementSent) {
+        announcementSent = false;
+        notify('loadingAnnouncement', false);
+      }
     }
   }
 
@@ -3343,17 +3370,19 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
         case 'Enter':
           if (handle.isOpen && nav?.hasActiveItem && nav.activeItem) {
             if (!isOptionDisabled(nav.activeItem)) {
-              if (nav.type === 'grid' && isActionCell(nav.activeItem)) {
-                // Action cell: programmatically click it.
-                nav.activeItem.click();
-              } else {
-                // Option cell: select the option.
-                handle.select(nav.activeItem);
-              }
+              // Click the active item. For option cells, the delegated click handler
+              // on the listbox will call handle.select() and handle closing.
+              // For action cells and link options, the native click fires too.
+              nav.activeItem.click();
             }
-          }
-          // In multi-select mode, keep open after selection; otherwise toggle.
-          if (!handle.isMultiSelect) {
+            // Close for single-select. For option cells the delegated handler
+            // already closed, but setIsOpen(false) is idempotent. For action cells
+            // and disabled options, the delegated handler did NOT close, so this is needed.
+            if (!handle.isMultiSelect) {
+              handle.setIsOpen(false);
+            }
+          } else if (!handle.isMultiSelect) {
+            // No active item — toggle open/close.
             handle.setIsOpen(!handle.isOpen);
           }
           flag = true;
@@ -3406,10 +3435,12 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
           flag = true;
           break;
         case 'Tab':
-          // Select the active option (if any) and close. Let Tab propagate.
+          // Click the active option (if any) and close. Let Tab propagate.
           if (nav?.hasActiveItem && nav.activeItem && !isOptionDisabled(nav.activeItem)) {
-            handle.select(nav.activeItem);
+            nav.activeItem.click();
           }
+          // The delegated click handler closes for single-select, but for multi-select
+          // or when no item is active, we still need to explicitly close.
           handle.setIsOpen(false);
           break;
         case 'PageUp':
@@ -3484,16 +3515,38 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
       isOpenState = isOpen;
       if (!isOpen) {
         focusNav?.clear();
+        // Reset announcement state so it retriggers on next open
+        clearTimeout(loadingTimer);
+        if (announcementSent) {
+          announcementSent = false;
+          notify('loadingAnnouncement', false);
+        }
+      } else if (skeletonCount > 0) {
+        // Opening while already loading — start the announcement timer
+        startLoadingAnnouncementTimer();
       }
 
       // Update aria-expanded on trigger
       trigger?.setAttribute('aria-expanded', String(isOpen));
       notify('open', isOpen);
+
+      // When opening, always notify the current empty state so that
+      // subscribers (ComboboxState) get the correct initial value.
+      // Without this, a list that starts empty never fires `emptyChange`
+      // because `lastIsEmpty` is initialized to `true` and `notifyVisibilityChange`
+      // only fires on *changes*.
+      if (isOpen) {
+        const inputValue = trigger?.value ?? '';
+        notify('emptyChange', {
+          isEmpty: lastIsEmpty,
+          inputValue
+        });
+      }
     },
     select(option) {
       callbacks.onSelect({
         value: option ? getOptionValue(option) : ''
-      });
+      }, handle);
     },
     registerOption(element, callback) {
       const filterLower = filterValue.toLowerCase();
@@ -3605,10 +3658,12 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
       listbox = null;
       filterValue = '';
       lastIsEmpty = true;
+      lastInputValue = '';
       optionRegistrations.clear();
       sectionRegistrations.clear();
       skeletonCount = 0;
       clearTimeout(loadingTimer);
+      announcementSent = false;
       // Clear all subscribers
       for (const set of Object.values(subscribers)) {
         set.clear();
@@ -3775,13 +3830,8 @@ function setupComboboxButton(button, callbacks) {
         case ' ':
           // Space acts like Enter in button mode.
           if (combobox.isOpen && nav?.hasActiveItem && nav.activeItem) {
-            if (nav.type === 'grid' && isActionCell(nav.activeItem)) {
-              // Action cell: programmatically click it.
-              nav.activeItem.click();
-            } else {
-              combobox.select(nav.activeItem);
-              combobox.setIsOpen(false);
-            }
+            // Click the active item — delegated handler handles select + close.
+            nav.activeItem.click();
           } else {
             combobox.setIsOpen(true);
           }
@@ -6563,44 +6613,58 @@ const ComboboxButton = Object.assign(forwardRefPolymorphic((props, ref) => {
  * Handles: Home/End (text cursor), ArrowLeft/Right (clear active descendant),
  * filtering (on input and on open), and focus behavior.
  *
- * @param input     The input element to use as the combobox trigger.
- * @param callbacks Callbacks for select and open/close events.
- * @param options   Options for configuring the input-mode controller.
+ * @param input   The input element to use as the combobox trigger.
+ * @param options Options and callbacks for configuring the input-mode controller.
  * @returns A ComboboxHandle for interacting with the combobox.
  */
-function setupComboboxInput(input, callbacks, options = {}) {
+function setupComboboxInput(input, options) {
   const {
-    autoFilter = true
+    autoFilter = true,
+    onSelect: optionOnSelect
   } = options;
-  const handle = setupCombobox(callbacks, {
+
+  /**
+   * True when the current input value came from user typing (real InputEvent).
+   * False when the value was set programmatically (select, clear, etc.).
+   * Used to decide whether to re-apply the filter when the combobox opens.
+   */
+  let userHasTyped = false;
+
+  /**
+   * 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);
+
+    // Clear the active item. In multi-select, keep visual focus so the
+    // user can continue navigating after selection.
+    if (!combobox.isMultiSelect) {
+      combobox.focusNav?.clear();
+    }
+    userHasTyped = false;
+    combobox.setIsOpen(true);
+    if (autoFilter) {
+      combobox.setFilter('');
+    }
+  };
+  const handle = setupCombobox({
+    onSelect
+  }, {
     wrapNavigation: true
   }, (combobox, signal) => {
-    /**
-     * True when the current input value came from user typing (real InputEvent).
-     * False when the value was set programmatically (select, clear, etc.).
-     * Used to decide whether to re-apply the filter when the combobox opens.
-     */
-    let userHasTyped = false;
     signal.addEventListener('abort', () => {
       userHasTyped = false;
     });
 
-    // Filter on user typing; reset filter on programmatic input changes.
-    // Real user input fires an `InputEvent` (with `inputType`), while
-    // programmatic changes (selection bridge, clear, etc.) dispatch a
-    // plain `Event('input')` — we use this to distinguish the two.
+    // Filter on real user typing (InputEvent with `inputType`).
     input.addEventListener('input', event => {
-      const isUserTyping = event instanceof InputEvent;
-
-      // Clear the active item. In multi-select with a programmatic change, keep
-      // visual focus so the user can continue navigating after selection.
-      if (isUserTyping || !combobox.isMultiSelect) {
-        combobox.focusNav?.clear();
-      }
-      userHasTyped = isUserTyping;
+      if (!(event instanceof InputEvent)) return;
+      combobox.focusNav?.clear();
+      userHasTyped = true;
       combobox.setIsOpen(true);
       if (autoFilter) {
-        combobox.setFilter(isUserTyping ? input.value : '');
+        combobox.setFilter(input.value);
       }
     }, {
       signal
@@ -6694,6 +6758,7 @@ const ComboboxInput$1 = (props, {
     textFieldRef,
     toggleButtonProps,
     handleToggle,
+    theme,
     ...forwardedProps
   } = props;
   return /*#__PURE__*/jsx(TextField, {
@@ -6706,8 +6771,10 @@ const ComboboxInput$1 = (props, {
     inputRef: inputRef,
     textFieldRef: textFieldRef,
     autoComplete: "off",
+    theme: theme,
     afterElement: toggleButtonProps ? /*#__PURE__*/jsx(IconButton, {
       ...toggleButtonProps,
+      theme: theme,
       emphasis: "low",
       size: "s",
       icon: isOpen ? mdiChevronUp : mdiChevronDown,
@@ -7229,32 +7296,6 @@ TextField.displayName = COMPONENT_NAME$1d;
 TextField.className = CLASSNAME$1c;
 TextField.defaultProps = DEFAULT_PROPS$Z;
 
-/**
- * Set an input's value using the native HTMLInputElement.prototype.value setter,
- * bypassing React's controlled input value tracker, then dispatch an `input` event
- * so React's onChange fires.
- *
- * React wraps the `value` property setter on controlled inputs to track the "last
- * known value." If you set `input.value` through React's wrapper with the same value
- * React last rendered, the subsequent `input` event is suppressed. Using the native
- * setter bypasses this tracker, ensuring React detects a value change and fires onChange.
- */
-function setNativeInputValue(input, value) {
-  const nativeSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set;
-  if (nativeSetter) {
-    nativeSetter.call(input, value);
-  } else {
-    // Fallback: set directly (may not trigger React onChange on controlled inputs)
-    // eslint-disable-next-line no-param-reassign
-    input.value = value;
-  }
-
-  // Dispatch input event so React's onChange fires
-  input.dispatchEvent(new Event('input', {
-    bubbles: true
-  }));
-}
-
 /**
  * Props for Combobox.Input component.
  * Note: role, aria-autocomplete, aria-controls, aria-expanded are set internally and cannot be overridden.
@@ -7285,9 +7326,11 @@ const ComboboxInput = forwardRef((props, ref) => {
   const internalInputRef = useRef(null);
   const mergedInputRef = useMergeRefs(externalInputRef, internalInputRef);
 
-  // Keep onSelect in a ref to avoid re-creating the handle on every render
+  // Keep callbacks in refs to avoid re-creating the handle on every render
   const onSelectRef = useRef(onSelect);
   onSelectRef.current = onSelect;
+  const onChangeRef = useRef(otherProps.onChange);
+  onChangeRef.current = otherProps.onChange;
 
   // Create the combobox handle with input-mode controller on mount
   useEffect(() => {
@@ -7295,11 +7338,10 @@ const ComboboxInput = forwardRef((props, ref) => {
     if (!input) return undefined;
     const handle = setupComboboxInput(input, {
       onSelect(option) {
-        // Bridge to React's controlled input flow.
-        setNativeInputValue(input, option.value);
+        // Update controlled value through React's normal onChange flow.
+        onChangeRef.current?.(option.value);
         onSelectRef.current?.(option);
-      }
-    }, {
+      },
       autoFilter
     });
     setHandle(handle);
@@ -7737,6 +7779,7 @@ const ComboboxOption$1 = (props, {
     isGrid,
     isSelected,
     handleClick,
+    actionProps,
     ref,
     tooltipProps,
     value,
@@ -7749,7 +7792,8 @@ const ComboboxOption$1 = (props, {
     itemRole = isGrid ? 'row' : 'none';
   }
   const actionElement = ListItemAction$1({
-    as: 'p',
+    as: 'button',
+    ...actionProps,
     id,
     className: element$H('trigger'),
     handleClick,
@@ -7832,6 +7876,7 @@ const ComboboxOption = forwardRef((props, ref) => {
     before,
     after,
     tooltipProps,
+    actionProps,
     onClick,
     ...forwardedProps
   } = props;
@@ -7865,6 +7910,7 @@ const ComboboxOption = forwardRef((props, ref) => {
   return ComboboxOption$1({
     ...forwardedProps,
     ref: mergedRef,
+    actionProps,
     hidden: isFiltered,
     value,
     description,
@@ -8011,14 +8057,16 @@ const ComboboxOptionMoreInfo$1 = (props, {
     popoverId,
     ref,
     onMouseEnter,
-    onMouseLeave
+    onMouseLeave,
+    buttonProps
   } = props;
   return /*#__PURE__*/jsxs(Fragment, {
     children: [/*#__PURE__*/jsx(IconButton, {
       ref: ref,
-      className: block$R([className]),
       icon: mdiInformationOutline,
       size: "s",
+      ...buttonProps,
+      className: block$R([className, buttonProps?.className]),
       emphasis: "low",
       onMouseEnter: onMouseEnter,
       onMouseLeave: onMouseLeave
@@ -8036,6 +8084,7 @@ const ComboboxOptionMoreInfo$1 = (props, {
       closeOnEscape: true,
       closeOnClickAway: true,
       placement: "bottom-end",
+      hasArrow: true,
       children: children
     })]
   });
@@ -8720,6 +8769,7 @@ const ComboboxOptionMoreInfo = props => {
   const {
     children,
     onToggle,
+    buttonProps,
     ...forwardedProps
   } = props;
   const ref = useRef(null);
@@ -8750,6 +8800,7 @@ const ComboboxOptionMoreInfo = props => {
     isOpen,
     popoverId,
     children,
+    buttonProps,
     onMouseEnter: () => setIsHovered(true),
     onMouseLeave: () => setIsHovered(false)
   }, {
@@ -8835,9 +8886,10 @@ const ComboboxOptionSkeleton$1 = props => {
     children,
     className,
     ref,
+    count = 1,
     ...forwardedProps
   } = props;
-  return ListItem$1({
+  const itemProps = {
     ref,
     size: 'tiny',
     role: 'none',
@@ -8852,6 +8904,13 @@ const ComboboxOptionSkeleton$1 = props => {
         theme: "light"
       })]
     })
+  };
+  return /*#__PURE__*/jsx(Fragment, {
+    children: Array.from({
+      length: count
+    }, (_, i) => /*#__PURE__*/jsx(ListItem$1, {
+      ...itemProps
+    }, i))
   });
 };
 
@@ -8880,19 +8939,13 @@ const ComboboxOptionSkeleton$1 = props => {
  * @return React element(s).
  */
 const ComboboxOptionSkeleton = props => {
-  const {
-    count = 1,
-    ...itemProps
-  } = props;
   const {
     handle
   } = useComboboxContext();
   useEffect(() => handle?.registerSkeleton(), [handle]);
-  return Array.from({
-    length: count
-  }, (_, i) => /*#__PURE__*/jsx(ComboboxOptionSkeleton$1, {
-    ...itemProps
-  }, i));
+  return /*#__PURE__*/jsx(ComboboxOptionSkeleton$1, {
+    ...props
+  });
 };
 ComboboxOptionSkeleton.displayName = COMPONENT_NAME$12;
 ComboboxOptionSkeleton.className = CLASSNAME$11;
@@ -9443,11 +9496,12 @@ const ListSection$1 = props => {
     ...forwardedProps
   } = props;
   const labelId = `${id}-label`;
+  const hasHeader = !!label;
   return /*#__PURE__*/jsxs("li", {
     ref: ref,
     ...forwardedProps,
     className: classnames(className, block$O()),
-    children: [label && /*#__PURE__*/jsxs(Text, {
+    children: [hasHeader && /*#__PURE__*/jsxs(Text, {
       as: "p",
       typography: "overline",
       className: element$D('title'),
@@ -9458,7 +9512,7 @@ const ListSection$1 = props => {
     }), /*#__PURE__*/jsx("ul", {
       ...itemsWrapperProps,
       className: element$D('items'),
-      "aria-labelledby": label ? labelId : undefined,
+      "aria-labelledby": hasHeader ? labelId : undefined,
       children: children
     })]
   });
@@ -9619,6 +9673,7 @@ const ComboboxState$1 = (props, {
     loadingMessage,
     state
   } = props;
+  const isOpen = state?.isOpen ?? true;
   const showError = !!errorMessage;
   const resolvedEmptyMessage = typeof emptyMessage === 'function' ? emptyMessage(state?.inputValue || '') : emptyMessage;
   // Suppress empty while loading (immediate flag prevents false "no results" before data arrives)
@@ -9632,6 +9687,12 @@ const ComboboxState$1 = (props, {
     hAlign: 'center',
     vAlign: 'center'
   };
+
+  // Gate message content behind isOpen so that content is *inserted* into the
+  // aria-live region when the popover opens, triggering screen reader announcements.
+  // Without this gate, content is already present (just hidden via display:none from
+  // the popover's closeMode="hide") and revealing it doesn't trigger announcements.
+  const renderContent = isOpen;
   return /*#__PURE__*/jsxs(GenericBlock, {
     className: classnames(!show && visuallyHidden(), block$N(), padding('regular')),
     orientation: "vertical",
@@ -9639,17 +9700,17 @@ const ComboboxState$1 = (props, {
     role: "status",
     "aria-live": "polite",
     "aria-atomic": true,
-    children: [showEmpty && /*#__PURE__*/jsx(Text, {
+    children: [renderContent && showEmpty && /*#__PURE__*/jsx(Text, {
       as: "p",
       typography: "body1",
       color: "dark-L2",
       children: resolvedEmptyMessage
-    }), showLoading && /*#__PURE__*/jsx(Text, {
+    }), renderContent && showLoading && /*#__PURE__*/jsx(Text, {
       as: "p",
       typography: "body1",
       color: "dark-L2",
       children: loadingMessage
-    }), !!errorMessage && /*#__PURE__*/jsxs(Fragment, {
+    }), renderContent && !!errorMessage && /*#__PURE__*/jsxs(Fragment, {
       children: [/*#__PURE__*/jsx(Text, {
         as: "p",
         typography: "subtitle2",
@@ -9664,6 +9725,62 @@ const ComboboxState$1 = (props, {
   });
 };
 
+/**
+ * Delay before inserting content into the aria-live region after the popover opens (ms).
+ *
+ * The popover uses `closeMode="hide"` (`display:none` when closed), so the live region
+ * container is not in the accessibility tree until the popover becomes visible.
+ * Screen readers only detect content *changes* in live regions that are already visible.
+ * This delay ensures the popover's `display:none` is removed and the accessibility tree
+ * is updated before content is inserted, so screen readers reliably announce it.
+ */
+const OPEN_ANNOUNCEMENT_DELAY = 100;
+
+/** Setters invoked by `subscribeComboboxState` when handle events fire. */
+
+/**
+ * Subscribe to the combobox handle events needed by `ComboboxState`.
+ *
+ * Manages three subscriptions:
+ * - `loadingChange` → `setIsLoading` (+ synchronous initial read of `handle.isLoading`)
+ * - `loadingAnnouncement` → `setShouldAnnounce`
+ * - `open` → `setIsOpen` (deferred by {@link OPEN_ANNOUNCEMENT_DELAY}ms on open, immediate on close)
+ *
+ * @param handle  The combobox handle to subscribe to.
+ * @param setters Framework-specific state setters.
+ * @returns A cleanup function that unsubscribes all events and clears timers.
+ */
+function subscribeComboboxState(handle, setters) {
+  const {
+    setIsLoading,
+    setShouldAnnounce,
+    setIsOpen
+  } = setters;
+
+  // Read current loading state synchronously
+  setIsLoading(handle.isLoading);
+  const unsubLoadingChange = handle.subscribe('loadingChange', setIsLoading);
+  const unsubLoadingAnnouncement = handle.subscribe('loadingAnnouncement', setShouldAnnounce);
+  let openTimer;
+  const unsubOpen = handle.subscribe('open', open => {
+    clearTimeout(openTimer);
+    if (open) {
+      // Delay content insertion so the popover is visible in the
+      // accessibility tree before the live region content changes.
+      openTimer = setTimeout(() => setIsOpen(true), OPEN_ANNOUNCEMENT_DELAY);
+    } else {
+      // Reset immediately on close
+      setIsOpen(false);
+    }
+  });
+  return () => {
+    unsubLoadingChange();
+    unsubLoadingAnnouncement();
+    unsubOpen();
+    clearTimeout(openTimer);
+  };
+}
+
 /**
  * Similar to lodash `partition` function but working with multiple predicates.
  *
@@ -9967,25 +10084,21 @@ const ComboboxState = props => {
     handle
   } = useComboboxContext();
   const emptyState = useComboboxEvent('emptyChange', undefined);
-
-  // Track loading state with both initial read and event subscription
-  // (same pattern as ComboboxList for aria-busy)
   const [isLoading, setIsLoading] = useState(false);
   const [shouldAnnounce, setShouldAnnounce] = useState(false);
+  const [isOpen, setIsOpen] = useState(false);
   useEffect(() => {
     if (!handle) return undefined;
-    // Read current state synchronously
-    setIsLoading(handle.isLoading);
-    const unsub1 = handle.subscribe('loadingChange', setIsLoading);
-    const unsub2 = handle.subscribe('loadingAnnouncement', setShouldAnnounce);
-    return () => {
-      unsub1();
-      unsub2();
-    };
+    return subscribeComboboxState(handle, {
+      setIsLoading,
+      setShouldAnnounce,
+      setIsOpen
+    });
   }, [handle]);
   const state = {
     ...emptyState,
-    isLoading
+    isLoading,
+    isOpen
   };
 
   // Only pass loadingMessage to core after the 500ms debounce threshold
@@ -10006,19 +10119,32 @@ ComboboxState.className = CLASSNAME$X;
  * Combobox compound component namespace.
  */
 const Combobox = {
+  /** Provides shared combobox context (handle, listbox ID, anchor ref) to all sub-components. */
   Provider: ComboboxProvider,
+  /** Button trigger for select-only combobox mode with keyboard navigation and typeahead. */
   Button: ComboboxButton,
+  /** Text input trigger for autocomplete combobox mode with optional toggle button and filtering. */
   Input: ComboboxInput,
+  /** Listbox container that registers with the combobox handle and tracks loading state. */
   List: ComboboxList,
+  /** Selectable option item with filtering and keyboard navigation support. */
   Option: ComboboxOption,
+  /** Secondary action button within a grid-mode option row, rendered as an independent gridcell. */
   OptionAction: ComboboxOptionAction,
+  /** Info button on an option that shows a popover on hover or keyboard highlight. */
   OptionMoreInfo: ComboboxOptionMoreInfo,
+  /** Loading placeholder skeleton(s) that auto-register loading state with the combobox handle. */
   OptionSkeleton: ComboboxOptionSkeleton,
+  /** Floating popover container that auto-binds to the combobox anchor and open/close state. */
   Popover: ComboboxPopover,
+  /** Labelled group of options that auto-hides when all its child options are filtered out. */
   Section: ComboboxSection,
+  /** Displays empty, error, and loading state messages for the combobox list. */
   State: ComboboxState,
   /** Visual separator between option groups (alias for ListDivider). Purely decorative — invisible to screen readers. */
-  Divider: ListDivider
+  Divider: ListDivider,
+  /** Hook to subscribe to combobox events. Must be used within a Combobox.Provider. */
+  useComboboxEvent
 };
 
 /**
@@ -11523,7 +11649,7 @@ const CLASSNAME$P = 'lumx-expansion-panel';
 const {
   block: block$G,
   element: element$x
-} = classNames.bem(CLASSNAME$P);
+} = bem(CLASSNAME$P);
 
 /**
  * Component default props.
@@ -11531,9 +11657,6 @@ const {
 const DEFAULT_PROPS$L = {
   closeMode: 'unmount'
 };
-const isDragHandle = isComponent(DragHandle);
-const isHeader = isComponent('header');
-const isFooter = isComponent('footer');
 
 /**
  * ExpansionPanel component.
@@ -11542,48 +11665,45 @@ const isFooter = isComponent('footer');
  * @param  ref   Component ref.
  * @return React element.
  */
-const ExpansionPanel = forwardRef((props, ref) => {
-  const defaultTheme = useTheme() || Theme$1.light;
+const ExpansionPanel$1 = props => {
   const {
     className,
-    closeMode = DEFAULT_PROPS$L.closeMode,
     children: anyChildren,
     hasBackground,
+    ref,
     hasHeaderDivider,
     isOpen,
     label,
-    onClose,
-    onOpen,
-    onToggleOpen,
-    theme = defaultTheme,
+    handleClose,
+    handleOpen,
+    handleToggleOpen,
+    theme,
     toggleButtonProps,
+    headerProps,
+    headerContent,
+    dragHandle,
+    wrapperRef,
+    content,
+    isChildrenVisible,
+    IconButton,
+    footer,
+    closeMode,
     ...forwardedProps
   } = props;
-  const children = Children.toArray(anyChildren);
-
-  // Partition children by types.
-  const [[dragHandle], [header], [footer], content] = partitionMulti(children, [isDragHandle, isHeader, isFooter]);
-
-  // Either take the header in children or create one with the label.
-  const headerProps = /*#__PURE__*/React__default.isValidElement(header) ? header.props : {};
-  const headerContent = !isEmpty(headerProps.children) ? headerProps.children : /*#__PURE__*/jsx("span", {
-    className: element$x('label'),
-    children: label
-  });
   const toggleOpen = event => {
     const shouldOpen = !isOpen;
-    if (onOpen && shouldOpen) {
-      onOpen(event);
+    if (handleOpen && shouldOpen) {
+      handleOpen(event);
     }
-    if (onClose && !shouldOpen) {
-      onClose(event);
+    if (handleClose && !shouldOpen) {
+      handleClose(event);
     }
-    if (onToggleOpen) {
-      onToggleOpen(shouldOpen, event);
+    if (handleToggleOpen) {
+      handleToggleOpen(shouldOpen, event);
     }
   };
-  const color = theme === Theme$1.dark ? ColorPalette$1.light : ColorPalette$1.dark;
-  const rootClassName = classNames.join(className, block$G({
+  const color = theme === Theme.dark ? ColorPalette.light : ColorPalette.dark;
+  const rootClassName = classnames(className, block$G({
     'has-background': hasBackground,
     'has-header': Boolean(!isEmpty(headerProps.children)),
     'has-header-divider': hasHeaderDivider,
@@ -11592,35 +11712,6 @@ const ExpansionPanel = forwardRef((props, ref) => {
     'is-open': isOpen,
     [`theme-${theme}`]: Boolean(theme)
   }));
-  const wrapperRef = useRef(null);
-
-  // Children stay visible while the open/close transition is running
-  const [isChildrenVisible, setChildrenVisible] = React__default.useState(isOpen);
-  const isOpenRef = React__default.useRef(isOpen);
-  React__default.useEffect(() => {
-    if (isOpen || closeMode === 'hide') {
-      setChildrenVisible(true);
-    } else if (!IS_BROWSER$1) {
-      // Outside a browser we can't wait for the transition
-      setChildrenVisible(false);
-    }
-    isOpenRef.current = isOpen;
-  }, [closeMode, isOpen]);
-
-  // Change children's visibility on the transition end
-  React__default.useEffect(() => {
-    const {
-      current: wrapper
-    } = wrapperRef;
-    if (!IS_BROWSER$1 || !wrapper) {
-      return undefined;
-    }
-    const onTransitionEnd = () => {
-      setChildrenVisible(isOpenRef.current || closeMode === 'hide');
-    };
-    wrapper.addEventListener('transitionend', onTransitionEnd);
-    return () => wrapper.removeEventListener('transitionend', onTransitionEnd);
-  }, [closeMode]);
   return /*#__PURE__*/jsxs("section", {
     ref: ref,
     ...forwardedProps,
@@ -11640,7 +11731,7 @@ const ExpansionPanel = forwardRef((props, ref) => {
         children: /*#__PURE__*/jsx(IconButton, {
           ...toggleButtonProps,
           color: color,
-          emphasis: Emphasis$1.low,
+          emphasis: Emphasis.low,
           icon: isOpen ? mdiChevronUp : mdiChevronDown,
           "aria-expanded": isOpen || 'false'
         })
@@ -11660,6 +11751,92 @@ const ExpansionPanel = forwardRef((props, ref) => {
       })
     })]
   });
+};
+
+const isDragHandle = isComponent(DragHandle);
+const isHeader = isComponent('header');
+const isFooter = isComponent('footer');
+
+/**
+ * ExpansionPanel component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+const ExpansionPanel = forwardRef((props, ref) => {
+  const defaultTheme = useTheme() || Theme$1.light;
+  const {
+    closeMode = DEFAULT_PROPS$L.closeMode,
+    children: anyChildren,
+    isOpen,
+    label,
+    onClose,
+    onOpen,
+    onToggleOpen,
+    theme = defaultTheme,
+    ...forwardedProps
+  } = props;
+  const children = Children.toArray(anyChildren);
+
+  // Partition children by types.
+  const [[dragHandle], [header], [footer], content] = partitionMulti(children, [isDragHandle, isHeader, isFooter]);
+
+  // Either take the header in children or create one with the label.
+  const headerProps = /*#__PURE__*/React__default.isValidElement(header) ? header.props : {};
+  const headerContent = !isEmpty(headerProps.children) ? headerProps.children : /*#__PURE__*/jsx("span", {
+    className: element$x('label'),
+    children: label
+  });
+  const wrapperRef = useRef(null);
+
+  // Children stay visible while the open/close transition is running
+  const [isChildrenVisible, setChildrenVisible] = React__default.useState(isOpen);
+  const isOpenRef = React__default.useRef(isOpen);
+  React__default.useEffect(() => {
+    if (isOpen || closeMode === 'hide') {
+      setChildrenVisible(true);
+    } else if (!IS_BROWSER$1) {
+      // Outside a browser we can't wait for the transition
+      setChildrenVisible(false);
+    }
+    isOpenRef.current = isOpen;
+  }, [closeMode, isOpen]);
+
+  // Change children's visibility on the transition end
+  React__default.useEffect(() => {
+    const {
+      current: wrapper
+    } = wrapperRef;
+    if (!IS_BROWSER$1 || !wrapper) {
+      return undefined;
+    }
+    const onTransitionEnd = () => {
+      setChildrenVisible(isOpenRef.current || closeMode === 'hide');
+    };
+    wrapper.addEventListener('transitionend', onTransitionEnd);
+    return () => wrapper.removeEventListener('transitionend', onTransitionEnd);
+  }, [closeMode]);
+  return ExpansionPanel$1({
+    content,
+    dragHandle,
+    footer,
+    headerContent,
+    ref,
+    headerProps,
+    wrapperRef,
+    IconButton,
+    isOpen,
+    handleClose: onClose,
+    handleToggleOpen: onToggleOpen,
+    handleOpen: onOpen,
+    theme,
+    isChildrenVisible,
+    children,
+    closeMode,
+    label,
+    ...forwardedProps
+  });
 });
 ExpansionPanel.displayName = COMPONENT_NAME$O;
 ExpansionPanel.className = CLASSNAME$P;
@@ -12237,7 +12414,7 @@ const {
  */
 const DEFAULT_PROPS$F = {
   captionPosition: ImageBlockCaptionPosition.below,
-  align: Alignment.left
+  align: Alignment$1.left
 };
 
 /**
@@ -13651,7 +13828,7 @@ const CLASSNAME$B = 'lumx-mosaic';
 const {
   block: block$v,
   element: element$n
-} = classNames.bem(CLASSNAME$B);
+} = bem(CLASSNAME$B);
 
 /**
  * Component default props.
@@ -13665,26 +13842,27 @@ const DEFAULT_PROPS$C = {};
  * @param  ref   Component ref.
  * @return React element.
  */
-const Mosaic = forwardRef((props, ref) => {
-  const defaultTheme = useTheme() || Theme$1.light;
+const Mosaic$1 = props => {
   const {
     className,
-    theme = defaultTheme,
+    theme,
     thumbnails,
-    onImageClick,
+    handleClick,
+    Thumbnail,
+    ref,
     ...forwardedProps
   } = props;
-  const handleImageClick = useMemo(() => {
-    if (!onImageClick) return undefined;
+  const onImageClick = () => {
+    if (!handleClick) return undefined;
     return (index, onClick) => event => {
       onClick?.(event);
-      onImageClick?.(index);
+      handleClick?.(index);
     };
-  }, [onImageClick]);
+  };
   return /*#__PURE__*/jsx("div", {
     ref: ref,
     ...forwardedProps,
-    className: classNames.join(className, block$v({
+    className: classnames(className, block$v({
       [`theme-${theme}`]: Boolean(theme),
       'has-1-thumbnail': thumbnails?.length === 1,
       'has-2-thumbnails': thumbnails?.length === 2,
@@ -13707,9 +13885,9 @@ const Mosaic = forwardRef((props, ref) => {
             align: align || Alignment.left,
             image: image,
             theme: theme,
-            aspectRatio: AspectRatio$1.free,
+            aspectRatio: AspectRatio.free,
             fillHeight: true,
-            onClick: handleImageClick?.(index, onClick) || onClick
+            onClick: onImageClick()?.(index, onClick) || onClick
           }), thumbnails.length > 4 && index === 3 && /*#__PURE__*/jsx("div", {
             className: element$n('overlay'),
             children: /*#__PURE__*/jsxs("span", {
@@ -13720,6 +13898,33 @@ const Mosaic = forwardRef((props, ref) => {
       })
     })
   });
+};
+
+/**
+ * Defines the props of the component.
+ */
+
+/**
+ * Mosaic component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+const Mosaic = forwardRef((props, ref) => {
+  const defaultTheme = useTheme() || Theme$1.light;
+  const {
+    theme = defaultTheme,
+    onImageClick,
+    ...forwardedProps
+  } = props;
+  return Mosaic$1({
+    ref,
+    theme,
+    Thumbnail,
+    handleClick: onImageClick,
+    ...forwardedProps
+  });
 });
 Mosaic.displayName = COMPONENT_NAME$A;
 Mosaic.className = CLASSNAME$B;
@@ -14519,7 +14724,6 @@ const reducer = (state, action) => {
         if (state.activeTabIndex === action.payload) {
           return state;
         }
-        // Change active tab index.
         return {
           ...state,
           activeTabIndex: action.payload
@@ -14531,7 +14735,6 @@ const reducer = (state, action) => {
           type,
           id
         } = action.payload;
-        // Append tab/tabPanel id in state.
         return {
           ...state,
           ids: {
@@ -14548,7 +14751,6 @@ const reducer = (state, action) => {
         } = action.payload;
         const index = state.ids[type].indexOf(id);
         if (index === -1) return state;
-        // Remove tab & tab panel at index.
         const tabIds = [...state.ids.tab];
         tabIds.splice(index, 1);
         const tabPanelIds = [...state.ids.tabPanel];
@@ -14565,7 +14767,9 @@ const reducer = (state, action) => {
       return state;
   }
 };
+
 const TabProviderContext = /*#__PURE__*/createContext(null);
+
 /* eslint-disable react-hooks/rules-of-hooks */
 const useTabProviderContext = (type, originalId) => {
   const context = useContext(TabProviderContext);
@@ -17378,7 +17582,7 @@ const Switch$1 = props => {
  * Component default props.
  */
 const DEFAULT_PROPS$c = {
-  position: Alignment.left
+  position: Alignment$1.left
 };
 
 /**
@@ -17937,7 +18141,7 @@ const TABS_CLASSNAME = `lumx-tabs`;
 const {
   block: block$6,
   element: element$4
-} = classNames.bem(TABS_CLASSNAME);
+} = bem(TABS_CLASSNAME);
 let TabListLayout = /*#__PURE__*/function (TabListLayout) {
   TabListLayout["clustered"] = "clustered";
   TabListLayout["fixed"] = "fixed";
@@ -17970,26 +18174,21 @@ const DEFAULT_PROPS$6 = {
  * @param  ref   Component ref.
  * @return React element.
  */
-const TabList = forwardRef((props, ref) => {
-  const defaultTheme = useTheme() || Theme$1.light;
+const TabList$1 = props => {
   const {
     'aria-label': ariaLabel,
     children,
     className,
     layout = DEFAULT_PROPS$6.layout,
     position = DEFAULT_PROPS$6.position,
-    theme = defaultTheme,
+    theme,
+    ref,
     ...forwardedProps
   } = props;
-  const tabListRef = React__default.useRef(null);
-  useRovingTabIndexContainer({
-    containerRef: tabListRef,
-    itemSelector: '[role="tab"]'
-  });
   return /*#__PURE__*/jsx("div", {
-    ref: mergeRefs(ref, tabListRef),
+    ref: ref,
     ...forwardedProps,
-    className: classNames.join(className, block$6({
+    className: classnames(className, block$6({
       [`layout-${layout}`]: Boolean(layout),
       [`position-${position}`]: Boolean(position),
       [`theme-${theme}`]: Boolean(theme)
@@ -18001,6 +18200,33 @@ const TabList = forwardRef((props, ref) => {
       children: children
     })
   });
+};
+
+/**
+ * TabList component.
+ *
+ * Implements WAI-ARIA `tablist` role {@see https://www.w3.org/TR/wai-aria-practices-1.1/examples/tabs/tabs-1/tabs.html#rps_label}
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+const TabList = forwardRef((props, ref) => {
+  const defaultTheme = useTheme() || Theme$1.light;
+  const {
+    theme = defaultTheme,
+    ...forwardedProps
+  } = props;
+  const tabListRef = React__default.useRef(null);
+  useRovingTabIndexContainer({
+    containerRef: tabListRef,
+    itemSelector: '[role="tab"]'
+  });
+  return TabList$1({
+    theme,
+    ref: mergeRefs(ref, tabListRef),
+    ...forwardedProps
+  });
 });
 TabList.displayName = COMPONENT_NAME$5;
 TabList.className = TABS_CLASSNAME;
@@ -18039,12 +18265,15 @@ const Tab$1 = props => {
     icon,
     iconProps = {},
     isAnyDisabled,
+    isDisabled,
     id,
     isActive,
     label,
     handleFocus,
     handleKeyPress,
     tabIndex = -1,
+    tabIndexProp = 'tabIndex',
+    keyPressProp = 'onKeyPress',
     changeToTab,
     tabPanelId,
     shouldActivateOnFocus,
@@ -18083,10 +18312,10 @@ const Tab$1 = props => {
       'is-disabled': isAnyDisabled
     })),
     onClick: changeToCurrentTab,
-    onKeyPress: onKeyPress,
+    [keyPressProp]: onKeyPress,
     onFocus: onFocus,
     role: "tab",
-    tabIndex: isActive ? 0 : tabIndex,
+    [tabIndexProp]: isActive ? 0 : tabIndex,
     "aria-disabled": isAnyDisabled,
     "aria-selected": isActive,
     "aria-controls": tabPanelId,
@@ -18157,7 +18386,7 @@ const COMPONENT_NAME$3 = 'TabPanel';
 const CLASSNAME$4 = `lumx-tab-panel`;
 const {
   block: block$4
-} = classNames.bem(CLASSNAME$4);
+} = bem(CLASSNAME$4);
 
 /**
  * Component default props.
@@ -18173,27 +18402,60 @@ const DEFAULT_PROPS$4 = {};
  * @param  ref   Component ref.
  * @return React element.
  */
-const TabPanel = forwardRef((props, ref) => {
+const TabPanel$1 = props => {
   const {
     children,
-    id,
     className,
-    isActive: propIsActive,
+    isActive,
+    id,
+    tabId,
+    isLazy,
+    tabIndexProp = 'tabIndex',
+    ref,
     ...forwardedProps
   } = props;
-  const state = useTabProviderContext('tabPanel', id);
-  const isActive = propIsActive || state?.isActive;
   return /*#__PURE__*/jsx("div", {
     ref: ref,
     ...forwardedProps,
-    id: state?.tabPanelId,
-    className: classNames.join(className, block$4({
+    id: id,
+    className: classnames(className, block$4({
       'is-active': isActive
     })),
     role: "tabpanel",
-    tabIndex: isActive ? 0 : -1,
-    "aria-labelledby": state?.tabId,
-    children: (!state?.isLazy || isActive) && children
+    [tabIndexProp]: isActive ? 0 : -1,
+    "aria-labelledby": tabId,
+    children: (!isLazy || isActive) && children
+  });
+};
+
+/**
+ * Defines the props of the component.
+ */
+
+/**
+ * TabPanel component.
+ *
+ * Implements WAI-ARIA `tabpanel` role {@see https://www.w3.org/TR/wai-aria-practices-1.1/examples/tabs/tabs-1/tabs.html#rps_label}
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+const TabPanel = forwardRef((props, ref) => {
+  const {
+    id,
+    isActive: propIsActive,
+    ...forwardedProps
+  } = props;
+  const state = useTabProviderContext('tabPanel', id);
+  const isActive = propIsActive || state?.isActive;
+  return TabPanel$1({
+    ref,
+    isActive,
+    id: state?.tabPanelId,
+    isLazy: state?.isLazy,
+    tabId: state?.tabId,
+    ...forwardedProps
   });
 });
 TabPanel.displayName = COMPONENT_NAME$3;