@lumx/react 4.18.0-next.1 → 4.18.0-next.3

package/index.d.ts

@@ -815,7 +815,7 @@ interface ButtonProps extends GenericProps$1, ReactToJSX<ButtonProps$1> {
  * @param  ref   Component ref.
  * @return React element.
  */
-declare const Button: Comp<ButtonProps, HTMLButtonElement | HTMLAnchorElement>;
+declare const Button: Comp<ButtonProps, HTMLAnchorElement | HTMLButtonElement>;
 
 interface IconButtonProps$1 extends BaseButtonProps {
     /**
@@ -1890,6 +1890,19 @@ interface ComboboxInputOptions {
      * @default false (true when filter is 'off')
      */
     openOnFocus?: boolean;
+    /**
+     * Controls what happens to the input value when an option is selected.
+     *
+     * - `'fill'` (default) — The input is updated with the selected option value via `onChange`.
+     * - `'keep'` — The input value is left unchanged; `onChange` is not called.
+     *   Useful when the component manages the displayed value independently (e.g. showing
+     *   an option display name rather than the raw option ID). The filter still resets.
+     * - `'clear'` — The input is cleared (empty string) via `onChange` after selection.
+     *   Useful for multi-select patterns where typing starts fresh after each pick.
+     *
+     * @default 'fill'
+     */
+    selectionMode?: 'fill' | 'keep' | 'clear';
 }
 
 /**
@@ -2197,7 +2210,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> & React$1.ComponentProps<E> & {
+    Button: (<E extends React$1.ElementType = Comp<ButtonProps, HTMLAnchorElement | HTMLButtonElement>>(props: Omit<HasPolymorphicAs$1<E>, "children" | "role" | "aria-activedescendant" | "aria-controls" | "aria-expanded" | "aria-haspopup"> & _lumx_core_js_types.HasRequiredLinkHref<E> & ReactToJSX<ComboboxButtonProps$1> & React$1.ComponentProps<E> & {
         ref?: ComponentRef<E> | undefined;
     }) => React.JSX.Element) & {
         displayName: string;
@@ -2723,7 +2736,7 @@ declare const GenericBlockGapSize: Pick<{
     readonly medium: "medium";
     readonly big: "big";
     readonly huge: "huge";
-}, "big" | "medium" | "tiny" | "regular" | "huge">;
+}, "big" | "tiny" | "medium" | "regular" | "huge">;
 type GenericBlockGapSize = ValueOf<typeof GenericBlockGapSize>;
 
 interface GenericBlockProps$1 extends FlexBoxProps$1 {
@@ -2953,7 +2966,7 @@ interface GridColumnProps extends GenericProps$1, ReactToJSX<GridColumnProps$1>
  */
 declare const GridColumn: Comp<GridColumnProps, HTMLElement>;
 
-declare const ICON_SIZES: ("m" | "s" | "xxs" | "xs" | "l" | "xl" | "xxl")[];
+declare const ICON_SIZES: ("s" | "m" | "xxs" | "xs" | "l" | "xl" | "xxl")[];
 
 type IconSizes = (typeof ICON_SIZES)[number];
 /**
@@ -3454,7 +3467,7 @@ interface LinkProps extends GenericProps$1, ReactToJSX<LinkProps$1> {
  * @param  ref   Component ref.
  * @return React element.
  */
-declare const Link: Comp<LinkProps, HTMLButtonElement | HTMLAnchorElement>;
+declare const Link: Comp<LinkProps, HTMLAnchorElement | HTMLButtonElement>;
 
 /**
  * Defines the props of the component.

package/index.js

@@ -6460,6 +6460,12 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
   /** Last notified input value, to re-fire `optionsChange` when the user keeps typing while empty. */
   let lastInputValue = '';
 
+  /** Last notified loading state, used to replay current state to late subscribers. */
+  let lastLoadingState = false;
+
+  /** Number of currently mounted skeleton placeholders. */
+  let skeletonCount = 0;
+
   /** Event subscribers managed by the handle. */
   const subscribers = {
     open: new Set(),
@@ -6474,6 +6480,20 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
     subscribers[event].forEach(cb => cb(value));
   }
 
+  /** Count visible (non-filtered) options. */
+  function getVisibleOptionCount() {
+    let count = 0;
+    for (const reg of optionRegistrations.values()) {
+      if (!reg.lastFiltered) count += 1;
+    }
+    return count;
+  }
+
+  /** True when the popup has visible content (options or skeletons). */
+  function hasVisibleContent() {
+    return getVisibleOptionCount() > 0 || skeletonCount > 0;
+  }
+
   /**
    * Notify all registered sections and fire `optionsChange` if the visible option count changed
    * or if the input value changed while the list is empty (so `emptyMessage` callbacks get
@@ -6484,10 +6504,7 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
     for (const [sectionElement] of sectionRegistrations) {
       notifySection(sectionElement, sectionRegistrations, optionRegistrations);
     }
-    let visibleCount = 0;
-    for (const reg of optionRegistrations.values()) {
-      if (!reg.lastFiltered) visibleCount += 1;
-    }
+    const visibleCount = getVisibleOptionCount();
     const inputValue = trigger?.value ?? '';
     const isEmpty = visibleCount === 0;
     if (visibleCount !== lastOptionsLength || isEmpty && inputValue !== lastInputValue) {
@@ -6498,6 +6515,12 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
         inputValue
       });
     }
+
+    // Re-evaluate aria-expanded when the combobox is open — visible content may have
+    // changed due to filtering, option register/unregister, or skeleton transitions.
+    if (isOpenState) {
+      trigger?.setAttribute('aria-expanded', String(hasVisibleContent()));
+    }
   }
 
   // ── Skeleton loading tracking ──────────────────────────────
@@ -6505,9 +6528,6 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
   /** Delay before announcing loading in the live region (ms). */
   const LOADING_ANNOUNCEMENT_DELAY = 500;
 
-  /** Number of currently mounted skeleton placeholders. */
-  let skeletonCount = 0;
-
   /** Timer for debounced loading announcement. */
   let loadingTimer;
 
@@ -6533,6 +6553,7 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
    */
   function onSkeletonCountChange() {
     const isLoading = skeletonCount > 0;
+    lastLoadingState = isLoading;
     notify('loadingChange', isLoading);
     if (isLoading) {
       startLoadingAnnouncementTimer();
@@ -6735,8 +6756,8 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
         startLoadingAnnouncementTimer();
       }
 
-      // Update aria-expanded on trigger
-      trigger?.setAttribute('aria-expanded', String(isOpen));
+      // Update aria-expanded on trigger (false when no visible options or skeletons)
+      trigger?.setAttribute('aria-expanded', String(isOpen && hasVisibleContent()));
       notify('open', isOpen);
     },
     select(option) {
@@ -6871,6 +6892,17 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
     },
     subscribe(event, callback) {
       subscribers[event].add(callback);
+      // Replay current loading state to late subscribers so that framework wrappers
+      // that subscribe after initial mount (e.g. async Vue watchers) don't miss the
+      // initial events fired during mount.
+      if (event === 'open' && isOpenState) {
+        callback(true);
+      }
+      if (event === 'loadingChange' && lastLoadingState) {
+        callback(true);
+      }
+
+      // Cleanup function
       return () => {
         subscribers[event].delete(callback);
       };
@@ -6882,6 +6914,7 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
       filterValue = '';
       lastOptionsLength = 0;
       lastInputValue = '';
+      lastLoadingState = false;
       optionRegistrations.clear();
       sectionRegistrations.clear();
       skeletonCount = 0;
@@ -7278,6 +7311,10 @@ const ComboboxButton = Object.assign(forwardRefPolymorphic((props, ref) => {
     setHandle
   } = useComboboxContext();
   const [isOpen] = useComboboxOpen();
+  const state = useComboboxEvent('optionsChange', {
+    optionsLength: 0
+  });
+  const isLoading = useComboboxEvent('loadingChange', false);
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const {
     as,
@@ -7319,7 +7356,7 @@ const ComboboxButton = Object.assign(forwardRefPolymorphic((props, ref) => {
     value,
     labelDisplayMode,
     listboxId,
-    isOpen,
+    isOpen: isOpen && (!!state?.optionsLength || isLoading),
     ref: mergedRef
   }, {
     Button: ButtonComp,
@@ -7350,8 +7387,10 @@ function setupComboboxInput(input, options) {
   let handle;
   const {
     filter = 'auto',
+    selectionMode = 'fill',
     onSelect: optionOnSelect,
-    onInput: onInputCallback
+    onInput: onInputCallback,
+    onChange: onChangeCallback
   } = options;
   const openOnFocus = options.openOnFocus ?? filter === 'off';
   const autoFilter = filter === 'auto';
@@ -7367,15 +7406,20 @@ function setupComboboxInput(input, options) {
   let userHasTyped = false;
 
   /**
-   * Wraps the consumer's onSelect to perform input-mode side effects after selection:
-   * resets the filter and typing state.
+   * Wraps the consumer's onSelect to perform input-mode side effects after selection,
+   * and drive `onChange` according to `selectionMode`.
+   * Filter and typing state are always reset on selection.
    */
   const onSelect = option => {
     optionOnSelect?.(option);
     userHasTyped = false;
-    if (autoFilter) {
-      handle.setFilter('');
+    if (autoFilter) handle.setFilter('');
+    if (selectionMode === 'fill') {
+      onChangeCallback?.(option.value);
+    } else if (selectionMode === 'clear') {
+      onChangeCallback?.('');
     }
+    // 'keep': onChange is not called — input value stays as-is.
   };
   handle = setupCombobox({
     onSelect
@@ -8118,8 +8162,13 @@ const ComboboxInput = forwardRef((props, ref) => {
     onSelect,
     filter,
     openOnFocus,
+    selectionMode,
     ...otherProps
   } = props;
+  const state = useComboboxEvent('optionsChange', {
+    optionsLength: 0
+  });
+  const isLoading = useComboboxEvent('loadingChange', false);
   const internalInputRef = useRef(null);
   const mergedInputRef = useMergeRefs(externalInputRef, internalInputRef);
 
@@ -8135,14 +8184,15 @@ const ComboboxInput = forwardRef((props, ref) => {
     if (!input) return undefined;
     const handle = setupComboboxInput(input, {
       onSelect(option) {
-        // Update controlled value through React's normal onChange flow.
-        onChangeRef.current?.(option.value);
         onSelectRef.current?.(option);
       },
+      onChange(value) {
+        onChangeRef.current?.(value);
+      },
       onInput(value) {
-        // Keep controlled value in sync.
         onChangeRef.current?.(value);
       },
+      selectionMode,
       filter,
       openOnFocus
     });
@@ -8151,7 +8201,7 @@ const ComboboxInput = forwardRef((props, ref) => {
       handle.destroy();
       setHandle(null);
     };
-  }, [filter, openOnFocus, setHandle]);
+  }, [filter, openOnFocus, selectionMode, setHandle]);
   const handleToggle = useCallback(() => {
     setIsOpen(!isOpen);
     internalInputRef.current?.focus();
@@ -8160,7 +8210,7 @@ const ComboboxInput = forwardRef((props, ref) => {
     ...otherProps,
     ref,
     listboxId,
-    isOpen,
+    isOpen: isOpen && (!!state?.optionsLength || isLoading),
     filter,
     inputRef: mergedInputRef,
     textFieldRef: anchorRef,
@@ -18217,6 +18267,7 @@ const SelectTextField$2 = (props, {
     children: [/*#__PURE__*/jsx(Combobox.Input, {
       label: label,
       ...inputProps,
+      selectionMode: "keep",
       chips: chips
     }), /*#__PURE__*/jsxs(Combobox.Popover, {
       fitToAnchorWidth: "minWidth",