@lumx/react 4.17.1-alpha.2 → 4.17.1-alpha.3

package/_internal/components/combobox/ComboboxInput.js

@@ -0,0 +1,79 @@
+import { forwardRef } from "../../utils/react/forwardRef.js";
+import { useMergeRefs } from "../../utils/react/mergeRefs.js";
+import { IconButton } from "../button/IconButton.js";
+import { useComboboxContext } from "./context/ComboboxContext.js";
+import { useComboboxOpen } from "./context/useComboboxOpen.js";
+import { setupComboboxInput } from "../../packages/lumx-core/src/js/components/Combobox/setupComboboxInput.js";
+import { CLASSNAME, COMPONENT_NAME, ComboboxInput as ComboboxInput$1 } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxInput.js";
+import { TextField } from "../text-field/TextField.js";
+import { useCallback, useEffect, useRef } from "react";
+//#region src/components/combobox/ComboboxInput.tsx
+/**
+* Combobox.Input component - wraps TextField with combobox ARIA attributes
+* and optionally includes a toggle button.
+*
+* @param props Component props.
+* @param ref   Component ref (will be forwarded to the anchor ref for popover positioning).
+* @return React element.
+*/
+var ComboboxInput = forwardRef((props, ref) => {
+	const { listboxId, anchorRef, setHandle } = useComboboxContext();
+	const [isOpen, setIsOpen] = useComboboxOpen();
+	const { inputRef: externalInputRef, toggleButtonProps, onSelect, filter, openOnFocus, ...otherProps } = props;
+	const internalInputRef = useRef(null);
+	const mergedInputRef = useMergeRefs(externalInputRef, internalInputRef);
+	const onSelectRef = useRef(onSelect);
+	onSelectRef.current = onSelect;
+	const onChangeRef = useRef(otherProps.onChange);
+	onChangeRef.current = otherProps.onChange;
+	useEffect(() => {
+		const input = internalInputRef.current;
+		if (!input) return void 0;
+		const handle = setupComboboxInput(input, {
+			onSelect(option) {
+				onChangeRef.current?.(option.value);
+				onSelectRef.current?.(option);
+			},
+			onInput(value) {
+				onChangeRef.current?.(value);
+			},
+			filter,
+			openOnFocus
+		});
+		setHandle(handle);
+		return () => {
+			handle.destroy();
+			setHandle(null);
+		};
+	}, [
+		filter,
+		openOnFocus,
+		setHandle
+	]);
+	const handleToggle = useCallback(() => {
+		setIsOpen(!isOpen);
+		internalInputRef.current?.focus();
+	}, [
+		internalInputRef,
+		isOpen,
+		setIsOpen
+	]);
+	return ComboboxInput$1({
+		...otherProps,
+		ref,
+		listboxId,
+		isOpen,
+		filter,
+		inputRef: mergedInputRef,
+		textFieldRef: anchorRef,
+		toggleButtonProps,
+		handleToggle
+	}, {
+		TextField,
+		IconButton
+	});
+});
+ComboboxInput.displayName = COMPONENT_NAME;
+ComboboxInput.className = CLASSNAME;
+//#endregion
+export { ComboboxInput };

package/_internal/components/combobox/ComboboxList.d.ts

@@ -0,0 +1,8 @@
+import { ReactToJSX } from "../../utils/type/ReactToJSX.js";
+import { ComboboxListProps as ComboboxListProps$1 } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxList.js";
+
+//#region src/components/combobox/ComboboxList.d.ts
+/** Props for Combobox.List component. */
+interface ComboboxListProps extends ReactToJSX<ComboboxListProps$1, 'aria-busy'> {}
+//#endregion
+export { ComboboxListProps };

package/_internal/components/combobox/ComboboxList.js

@@ -0,0 +1,64 @@
+import { forwardRef } from "../../utils/react/forwardRef.js";
+import { useMergeRefs } from "../../utils/react/mergeRefs.js";
+import { useComboboxContext } from "./context/ComboboxContext.js";
+import { useComboboxEvent } from "./context/useComboboxEvent.js";
+import { useComboboxOpen } from "./context/useComboboxOpen.js";
+import { CLASSNAME, COMPONENT_NAME, ComboboxList as ComboboxList$1 } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxList.js";
+import { ComboboxListContext } from "./context/ComboboxListContext.js";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/components/combobox/ComboboxList.tsx
+/**
+* Combobox.List component - wraps List with listbox ARIA attributes.
+* Registers itself as the combobox listbox on mount.
+*
+* To render the list inside a popover, wrap it with Combobox.Popover.
+*
+* @param props Component props.
+* @param ref   Component ref.
+* @return React element.
+*/
+var ComboboxList = forwardRef((props, ref) => {
+	const { listboxId, handle } = useComboboxContext();
+	const { "aria-label": ariaLabel, type = "listbox", className, children, ...forwardedProps } = props;
+	const internalRef = useRef(null);
+	const mergedRef = useMergeRefs(ref, internalRef);
+	const listContextValue = useMemo(() => ({ type }), [type]);
+	const [isOpen] = useComboboxOpen();
+	const visibleCount = useComboboxEvent("optionsChange", void 0)?.optionsLength ?? 0;
+	useEffect(() => {
+		const list = internalRef.current;
+		if (!list) return void 0;
+		return handle?.registerListbox(list);
+	}, [handle]);
+	const [isLoading, setIsLoading] = useState(false);
+	useEffect(() => {
+		if (!handle) return void 0;
+		setIsLoading(handle.isLoading);
+		return handle.subscribe("loadingChange", setIsLoading);
+	}, [handle]);
+	useEffect(() => {
+		if (isOpen) handle?.flushPendingNavigation();
+	}, [
+		isOpen,
+		visibleCount,
+		handle
+	]);
+	return /* @__PURE__ */ jsx(ComboboxListContext.Provider, {
+		value: listContextValue,
+		children: ComboboxList$1({
+			...forwardedProps,
+			"aria-label": ariaLabel,
+			"aria-busy": isLoading || void 0,
+			className,
+			ref: mergedRef,
+			id: listboxId,
+			type,
+			children: isOpen ? children : null
+		})
+	});
+});
+ComboboxList.displayName = COMPONENT_NAME;
+ComboboxList.className = CLASSNAME;
+//#endregion
+export { ComboboxList };

package/_internal/components/combobox/ComboboxOption.d.ts

@@ -0,0 +1,36 @@
+import { HasPolymorphicAs } from "../../utils/type/HasPolymorphicAs.js";
+import { index_d_exports } from "../../utils/type/index.js";
+import { ReactToJSX } from "../../utils/type/ReactToJSX.js";
+import { ComboboxOptionProps as ComboboxOptionProps$1, ComboboxOptionPropsToOverride } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxOption.js";
+import { TooltipProps } from "../tooltip/Tooltip.js";
+import { GenericProps } from "@lumx/core/js/types";
+import { ElementType, ReactNode } from "react";
+
+//#region src/components/combobox/ComboboxOption.d.ts
+/**
+ * Props forwarded to the inner action element (button or link).
+ */
+type ComboboxOptionActionProps<E extends ElementType = 'button'> = HasPolymorphicAs<E> & index_d_exports.HasRequiredLinkHref<E>;
+/**
+ * Props for Combobox.Option component.
+ */
+interface ComboboxOptionProps extends GenericProps, ReactToJSX<ComboboxOptionProps$1, ComboboxOptionPropsToOverride> {
+  /** Display label for the option. */
+  children?: ReactNode;
+  /** On option clicked (or activated with keyboard) */
+  onClick?(): void;
+  /** Content rendered before the option label (e.g. an icon or avatar). */
+  before?: ReactNode;
+  /**
+   * Content rendered after the option label.
+   * In grid mode (`type="grid"` on the parent Combobox.List), use `Combobox.OptionAction` elements here
+   * to add secondary action buttons. Each action becomes an independent `role="gridcell"`.
+   */
+  after?: ReactNode;
+  /** Props forwarded to a Tooltip wrapping the role="option" / role="gridcell" trigger element. */
+  tooltipProps?: Partial<TooltipProps>;
+  /** Props forwarded to the inner action element (e.g. `{ as: 'a', href: '/foo' }`). */
+  actionProps?: ComboboxOptionActionProps<any>;
+}
+//#endregion
+export { ComboboxOptionProps };

package/_internal/components/combobox/ComboboxOption.js

@@ -0,0 +1,76 @@
+import { useId } from "../../hooks/useId.js";
+import { forwardRef } from "../../utils/react/forwardRef.js";
+import { useMergeRefs } from "../../utils/react/mergeRefs.js";
+import { Tooltip } from "../tooltip/Tooltip.js";
+import { useComboboxContext } from "./context/ComboboxContext.js";
+import { useComboboxListContext } from "./context/ComboboxListContext.js";
+import { CLASSNAME, COMPONENT_NAME, ComboboxOption as ComboboxOption$1 } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxOption.js";
+import { ComboboxOptionContext } from "./context/ComboboxOptionContext.js";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/components/combobox/ComboboxOption.tsx
+/**
+* Combobox.Option component - wraps ListItem with option role and data-value.
+*
+* When filter="auto" is enabled on the parent Combobox.Input, each option registers itself
+* with the combobox handle (via an internal ref to its root <li>). When the filter changes,
+* the handle calls back with the new match state. When filtered out, the core template renders
+* a bare `<li hidden>` — no ARIA roles, no CSS classes — keeping the element in the DOM so
+* its textContent remains readable for future filter evaluations.
+*
+* In grid mode (`type="grid"` on the parent Combobox.List), the ListItem renders with `role="row"`
+* and the option content uses `role="gridcell"` instead of `role="option"`.
+* Use `after` to pass `Combobox.OptionAction` elements as secondary action gridcells.
+*
+* @param props Component props.
+* @param ref   Component ref.
+* @return React element.
+*/
+var ComboboxOption = forwardRef((props, ref) => {
+	const { value, description, children, isSelected, isDisabled, before, after, tooltipProps, actionProps, onClick, ...forwardedProps } = props;
+	const { type } = useComboboxListContext();
+	const { handle } = useComboboxContext();
+	const isGrid = type === "grid";
+	const optionId = useId();
+	const descriptionId = useId();
+	const internalRef = useRef(null);
+	const mergedRef = useMergeRefs(ref, internalRef);
+	const [isFiltered, setIsFiltered] = useState(false);
+	useEffect(() => {
+		const element = internalRef.current;
+		if (!element || !handle) return void 0;
+		return handle.registerOption(element, setIsFiltered);
+	}, [handle]);
+	useEffect(() => {
+		const element = internalRef.current;
+		if (!element || !handle) return;
+		handle.refilterOption(element);
+	}, [handle, value]);
+	const optionContextValue = useMemo(() => ({ optionId }), [optionId]);
+	const wrappedAfter = after ? /* @__PURE__ */ jsx(ComboboxOptionContext.Provider, {
+		value: optionContextValue,
+		children: after
+	}) : void 0;
+	return ComboboxOption$1({
+		...forwardedProps,
+		ref: mergedRef,
+		actionProps,
+		hidden: isFiltered,
+		value,
+		description,
+		children,
+		isSelected,
+		isDisabled,
+		isGrid,
+		before,
+		after: wrappedAfter,
+		handleClick: onClick,
+		id: optionId,
+		descriptionId,
+		tooltipProps
+	}, { Tooltip });
+});
+ComboboxOption.displayName = COMPONENT_NAME;
+ComboboxOption.className = CLASSNAME;
+//#endregion
+export { ComboboxOption };

package/_internal/components/combobox/ComboboxOptionAction.d.ts

@@ -0,0 +1,18 @@
+import { HasPolymorphicAs } from "../../utils/type/HasPolymorphicAs.js";
+import { index_d_exports } from "../../utils/type/index.js";
+import { ElementType, ReactNode, SyntheticEvent } from "react";
+
+//#region src/components/combobox/ComboboxOptionAction.d.ts
+/**
+ * Combobox.OptionAction props.
+ *
+ * Polymorphic component — use `as` to render as a different element or component
+ * (e.g., `as={IconButton}`, `as={Button}`). Defaults to `'button'`.
+ */
+type ComboboxOptionActionProps<E extends ElementType = 'button'> = HasPolymorphicAs<E> & index_d_exports.HasClassName & index_d_exports.HasRequiredLinkHref<E> & {
+  /** Content of the action (icon, label, etc.). Optional when using a polymorphic `as` that provides its own content (e.g., IconButton). */children?: ReactNode; /** Whether the action is disabled. */
+  isDisabled?: boolean; /** On click callback. */
+  onClick?(evt: SyntheticEvent): void;
+};
+//#endregion
+export { ComboboxOptionActionProps };

package/_internal/components/combobox/ComboboxOptionAction.js

@@ -0,0 +1,38 @@
+import { useId } from "../../hooks/useId.js";
+import { useDisableStateProps } from "../../utils/disabled/useDisableStateProps.js";
+import { forwardRefPolymorphic } from "../../utils/react/forwardRefPolymorphic.js";
+import { CLASSNAME, COMPONENT_NAME, ComboboxOptionAction as ComboboxOptionAction$1 } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxOptionAction.js";
+//#region src/components/combobox/ComboboxOptionAction.tsx
+/**
+* Combobox.OptionAction sub-component.
+*
+* 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).
+*
+* Uses the same polymorphic pattern as ListItem.Action (forwardRefPolymorphic + RawClickable).
+*
+* @param  props Component props.
+* @param  ref   Component ref.
+* @return React element.
+*/
+var ComboboxOptionAction = Object.assign(forwardRefPolymorphic((props, ref) => {
+	const { disabledStateProps, otherProps } = useDisableStateProps(props);
+	const { children, className, as: Element = "button", onClick, ...forwardedProps } = otherProps;
+	const actionId = useId();
+	return ComboboxOptionAction$1({
+		as: Element,
+		...forwardedProps,
+		...disabledStateProps,
+		id: actionId,
+		className,
+		handleClick: onClick,
+		ref,
+		children
+	});
+}), {
+	displayName: COMPONENT_NAME,
+	className: CLASSNAME
+});
+//#endregion
+export { ComboboxOptionAction };

package/_internal/components/combobox/ComboboxOptionMoreInfo.d.ts

@@ -0,0 +1,19 @@
+import { ReactToJSX } from "../../utils/type/ReactToJSX.js";
+import { IconButtonProps } from "../button/IconButton.js";
+import { ComboboxOptionMoreInfoProps as ComboboxOptionMoreInfoProps$1, ComboboxOptionMoreInfoPropsToOverride } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxOptionMoreInfo.js";
+import { ReactNode } from "react";
+
+//#region src/components/combobox/ComboboxOptionMoreInfo.d.ts
+/**
+ * Props for Combobox.OptionMoreInfo component.
+ */
+interface ComboboxOptionMoreInfoProps extends ReactToJSX<ComboboxOptionMoreInfoProps$1, ComboboxOptionMoreInfoPropsToOverride> {
+  /** Content of the popover (additional details about the option). */
+  children?: ReactNode;
+  /** Callback when the popover opens or closes. */
+  onToggle?(isOpen: boolean): void;
+  /** Props forwarded to the IconButton. */
+  buttonProps?: Partial<IconButtonProps>;
+}
+//#endregion
+export { ComboboxOptionMoreInfoProps };

package/_internal/components/combobox/ComboboxOptionMoreInfo.js

@@ -0,0 +1,49 @@
+import { IconButton } from "../button/IconButton.js";
+import { useComboboxEvent } from "./context/useComboboxEvent.js";
+import { useComboboxOptionContext } from "./context/ComboboxOptionContext.js";
+import { CLASSNAME, COMPONENT_NAME, ComboboxOptionMoreInfo as ComboboxOptionMoreInfo$1 } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxOptionMoreInfo.js";
+import { Popover } from "../popover/Popover.js";
+import { useEffect, useRef, useState } from "react";
+//#region src/components/combobox/ComboboxOptionMoreInfo.tsx
+/**
+* Combobox.OptionMoreInfo component.
+*
+* Displays an info icon button on a combobox option that shows a popover with additional details.
+* The popover opens on mouse hover over the icon or when the parent option is keyboard-highlighted.
+*
+* Must be placed in the `after` slot of a `Combobox.Option`.
+*
+* Please consider using a simpler option `description` prop instead for better UX and a11y.
+*
+* @param props Component props.
+* @return React element.
+*/
+var ComboboxOptionMoreInfo = (props) => {
+	const { children, onToggle, buttonProps, ...forwardedProps } = props;
+	const ref = useRef(null);
+	const [isHovered, setIsHovered] = useState(false);
+	const { optionId } = useComboboxOptionContext();
+	const isKeyboardHighlighted = useComboboxEvent("activeDescendantChange", null) === optionId;
+	const isOpen = isHovered || isKeyboardHighlighted;
+	useEffect(() => {
+		onToggle?.(isOpen);
+	}, [isOpen, onToggle]);
+	const popoverId = `${optionId}-more-info`;
+	return ComboboxOptionMoreInfo$1({
+		...forwardedProps,
+		ref,
+		isOpen,
+		popoverId,
+		children,
+		buttonProps,
+		onMouseEnter: () => setIsHovered(true),
+		onMouseLeave: () => setIsHovered(false)
+	}, {
+		IconButton,
+		Popover
+	});
+};
+ComboboxOptionMoreInfo.displayName = COMPONENT_NAME;
+ComboboxOptionMoreInfo.className = CLASSNAME;
+//#endregion
+export { ComboboxOptionMoreInfo };

package/_internal/components/combobox/ComboboxOptionSkeleton.d.ts

@@ -0,0 +1,19 @@
+import { ReactToJSX } from "../../utils/type/ReactToJSX.js";
+import { ComboboxOptionSkeletonProps as ComboboxOptionSkeletonProps$1, ComboboxOptionSkeletonPropsToOverride } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxOptionSkeleton.js";
+import { GenericProps } from "@lumx/core/js/types";
+import { ReactNode } from "react";
+
+//#region src/components/combobox/ComboboxOptionSkeleton.d.ts
+/**
+ * Props for Combobox.OptionSkeleton component.
+ */
+interface ComboboxOptionSkeletonProps extends GenericProps, ReactToJSX<ComboboxOptionSkeletonProps$1, ComboboxOptionSkeletonPropsToOverride> {
+  /** Content rendered before the skeleton text (e.g. SkeletonCircle for avatar placeholders). */
+  before?: ReactNode;
+  /** Content rendered after the skeleton text. */
+  after?: ReactNode;
+  /** Override the default SkeletonTypography content entirely. */
+  children?: ReactNode;
+}
+//#endregion
+export { ComboboxOptionSkeletonProps };

package/_internal/components/combobox/ComboboxOptionSkeleton.js

@@ -0,0 +1,38 @@
+import { useComboboxContext } from "./context/ComboboxContext.js";
+import { CLASSNAME, COMPONENT_NAME, ComboboxOptionSkeleton as ComboboxOptionSkeleton$1 } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxOptionSkeleton.js";
+import { useEffect } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/components/combobox/ComboboxOptionSkeleton.tsx
+/**
+* Combobox.OptionSkeleton component — renders skeleton placeholder(s) inside a combobox list.
+*
+* Registers once with the combobox handle on mount (regardless of `count`). The handle
+* fires `loadingChange` / `loadingAnnouncement` events, so consumers don't need an
+* explicit `isLoading` prop on `Combobox.List`.
+*
+* Width variation across skeletons is handled by SCSS `:nth-child` rules automatically.
+*
+* @example
+* ```tsx
+* // Basic — 3 plain skeletons
+* <Combobox.List aria-label="Users">
+*     {users.map(u => <Combobox.Option key={u.id} value={u.id}>{u.name}</Combobox.Option>)}
+*     {isLoading && <Combobox.OptionSkeleton count={3} />}
+* </Combobox.List>
+*
+* // With avatar placeholder
+* {isLoading && <Combobox.OptionSkeleton count={3} before={<SkeletonCircle size="s" />} />}
+* ```
+*
+* @param props Component props.
+* @return React element(s).
+*/
+var ComboboxOptionSkeleton = (props) => {
+	const { handle } = useComboboxContext();
+	useEffect(() => handle?.registerSkeleton(), [handle]);
+	return /* @__PURE__ */ jsx(ComboboxOptionSkeleton$1, { ...props });
+};
+ComboboxOptionSkeleton.displayName = COMPONENT_NAME;
+ComboboxOptionSkeleton.className = CLASSNAME;
+//#endregion
+export { ComboboxOptionSkeleton };

package/_internal/components/combobox/ComboboxPopover.d.ts

@@ -0,0 +1,18 @@
+import { PopoverProps } from "../popover/Popover.js";
+import { ReactNode } from "react";
+
+//#region src/components/combobox/ComboboxPopover.d.ts
+/**
+ * Props for Popover that can be passed to Combobox.Popover.
+ * Excludes isOpen, anchorRef, children, and onClose which are managed internally.
+ */
+type ComboboxPopoverProps = Partial<Omit<PopoverProps, 'isOpen' | 'anchorRef' | 'children' | 'onClose'>>;
+/**
+ * Props for the Combobox.Popover component.
+ */
+interface ComboboxPopoverComponentProps extends ComboboxPopoverProps {
+  /** Content (should contain a Combobox.List). */
+  children: ReactNode;
+}
+//#endregion
+export { ComboboxPopoverComponentProps, ComboboxPopoverProps };

package/_internal/components/combobox/ComboboxPopover.js

@@ -0,0 +1,32 @@
+import { useComboboxContext } from "./context/ComboboxContext.js";
+import { useComboboxOpen } from "./context/useComboboxOpen.js";
+import { Popover } from "../popover/Popover.js";
+import { CLASSNAME, COMPONENT_NAME, ComboboxPopover as ComboboxPopover$1 } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxPopover.js";
+import { FlexBox } from "../flex-box/FlexBox.js";
+//#region src/components/combobox/ComboboxPopover.tsx
+/**
+* Combobox.Popover component - renders a Popover connected to the combobox context.
+* Automatically binds to the combobox anchor element and open/close state.
+*
+* @param props Component props.
+* @return React element.
+*/
+var ComboboxPopover = (props) => {
+	const { anchorRef } = useComboboxContext();
+	const [isOpen, setIsOpen] = useComboboxOpen();
+	const { children, ...popoverProps } = props;
+	return ComboboxPopover$1({
+		...popoverProps,
+		children,
+		isOpen,
+		anchorRef,
+		handleClose: () => setIsOpen(false)
+	}, {
+		Popover,
+		FlexBox
+	});
+};
+ComboboxPopover.displayName = COMPONENT_NAME;
+ComboboxPopover.className = CLASSNAME;
+//#endregion
+export { ComboboxPopover };

package/_internal/components/combobox/ComboboxProvider.d.ts

@@ -0,0 +1,27 @@
+import { ReactNode } from "react";
+
+//#region src/components/combobox/ComboboxProvider.d.ts
+/**
+ * Defines the props of the component.
+ */
+interface ComboboxProviderProps {
+  /** Combobox content. */
+  children?: ReactNode;
+  /** Callback fired when the combobox open state changes. */
+  onOpen?: (isOpen: boolean) => void;
+}
+/**
+ * Combobox.Provider component.
+ *
+ * Provides shared context to sub-components. The vanilla JS combobox handle is
+ * created by the trigger sub-component (Combobox.Input or Combobox.Button) on mount.
+ *
+ * @param props Component props.
+ * @return React element.
+ */
+declare function ComboboxProvider(props: ComboboxProviderProps): import("react/jsx-runtime").JSX.Element;
+declare namespace ComboboxProvider {
+  var displayName: string;
+}
+//#endregion
+export { ComboboxProvider, ComboboxProviderProps };

package/_internal/components/combobox/ComboboxProvider.js

@@ -0,0 +1,41 @@
+import { useId } from "../../hooks/useId.js";
+import { ComboboxContext } from "./context/ComboboxContext.js";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/components/combobox/ComboboxProvider.tsx
+/**
+* Combobox.Provider component.
+*
+* Provides shared context to sub-components. The vanilla JS combobox handle is
+* created by the trigger sub-component (Combobox.Input or Combobox.Button) on mount.
+*
+* @param props Component props.
+* @return React element.
+*/
+function ComboboxProvider(props) {
+	const { children, onOpen } = props;
+	const listboxId = useId();
+	const anchorRef = useRef(null);
+	const [handle, setHandle] = useState(null);
+	const contextValue = useMemo(() => ({
+		handle,
+		setHandle,
+		listboxId,
+		anchorRef
+	}), [handle, listboxId]);
+	const onOpenRef = useRef(onOpen);
+	onOpenRef.current = onOpen;
+	useEffect(() => {
+		if (!handle) return void 0;
+		return handle.subscribe("open", (isOpen) => {
+			onOpenRef.current?.(isOpen);
+		});
+	}, [handle]);
+	return /* @__PURE__ */ jsx(ComboboxContext.Provider, {
+		value: contextValue,
+		children
+	});
+}
+ComboboxProvider.displayName = "Combobox.Provider";
+//#endregion
+export { ComboboxProvider };

package/_internal/components/combobox/ComboboxSection.d.ts

@@ -0,0 +1,15 @@
+import { ReactToJSX } from "../../utils/type/ReactToJSX.js";
+import { ComboboxSectionProps as ComboboxSectionProps$1, ComboboxSectionPropsToOverride } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxSection.js";
+import { GenericProps } from "@lumx/core/js/types";
+import { ReactNode } from "react";
+
+//#region src/components/combobox/ComboboxSection.d.ts
+/**
+ * Props for Combobox.Section component.
+ */
+interface ComboboxSectionProps extends GenericProps, ReactToJSX<ComboboxSectionProps$1, ComboboxSectionPropsToOverride> {
+  /** Section content (should be Combobox.Option elements). */
+  children: ReactNode;
+}
+//#endregion
+export { ComboboxSectionProps };

package/_internal/components/combobox/ComboboxSection.js

@@ -0,0 +1,47 @@
+import { forwardRef } from "../../utils/react/forwardRef.js";
+import { useMergeRefs } from "../../utils/react/mergeRefs.js";
+import { useComboboxContext } from "./context/ComboboxContext.js";
+import { CLASSNAME, COMPONENT_NAME, ComboboxSection as ComboboxSection$1 } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxSection.js";
+import { ListSection } from "../list/ListSection.js";
+import { Children, useEffect, useRef, useState } from "react";
+//#region src/components/combobox/ComboboxSection.tsx
+/**
+* Combobox.Section component - groups Combobox.Option items under a labelled section.
+* Delegates rendering to the core ComboboxSection template, injecting the React ListSection.
+*
+* Returns null when children is empty so the section header is not rendered as an orphan.
+*
+* When filter="auto" is active, the section registers itself with the combobox handle.
+* The handle monitors registered options within this section and notifies when all
+* are filtered out. When hidden, the core template renders a bare `<li hidden>` wrapper
+* so children (options) stay mounted and registered.
+*
+* @param props Component props.
+* @param ref   Component ref.
+* @return React element.
+*/
+var ComboboxSection = forwardRef((props, ref) => {
+	const { handle } = useComboboxContext();
+	const internalRef = useRef(null);
+	const mergedRef = useMergeRefs(ref, internalRef);
+	const [sectionState, setSectionState] = useState({
+		hidden: false,
+		"aria-hidden": false
+	});
+	useEffect(() => {
+		const element = internalRef.current;
+		if (!element || !handle) return void 0;
+		return handle.registerSection(element, setSectionState);
+	}, [handle]);
+	if (Children.count(props.children) === 0) return null;
+	return ComboboxSection$1({
+		...props,
+		ref: mergedRef,
+		hidden: sectionState.hidden,
+		"aria-hidden": sectionState["aria-hidden"] || void 0
+	}, { ListSection });
+});
+ComboboxSection.displayName = COMPONENT_NAME;
+ComboboxSection.className = CLASSNAME;
+//#endregion
+export { ComboboxSection };

package/_internal/components/combobox/ComboboxState.d.ts

@@ -0,0 +1,14 @@
+import { ReactToJSX } from "../../utils/type/ReactToJSX.js";
+import { ComboboxStateProps as ComboboxStateProps$1 } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxState.js";
+import { ReactNode } from "react";
+
+//#region src/components/combobox/ComboboxState.d.ts
+/**
+ * Props for Combobox.State component.
+ */
+interface ComboboxStateProps extends ReactToJSX<ComboboxStateProps$1, 'state'> {
+  /** Additional content rendered after the state message. */
+  children?: ReactNode;
+}
+//#endregion
+export { ComboboxStateProps };