@pixum/combobox 5.10.4 → 5.10.6

package/lib/hooks/useIsDesktopScreenWidth.js

@@ -1,36 +1,46 @@
-import { useState, useEffect } from 'react';
+'use client';
+import { useSyncExternalStore } from 'react';
+const DESKTOP_MEDIA_QUERY = '(min-width: 960px)';
 /**
- * Custom hook that detects whether the viewport width is desktop size (>= 960px).
- * Listens to window resize events to update the state dynamically.
+ * Subscribes to the MediaQueryList. Using `change` instead of `resize` means
+ * there is only one re-render when the breakpoint is actually crossed.
  *
- * @returns True if the viewport width is 960px or greater, false otherwise
+ * @param onStoreChange - Callback invoked when the breakpoint match changes
+ * @returns An unsubscribe function that removes the listener
  */
-function isBrowser() {
-    return typeof window !== 'undefined';
+function subscribe(onStoreChange) {
+    if (typeof window === 'undefined' || !window.matchMedia) {
+        return () => { };
+    }
+    const mediaQueryList = window.matchMedia(DESKTOP_MEDIA_QUERY);
+    mediaQueryList.addEventListener('change', onStoreChange);
+    return () => mediaQueryList.removeEventListener('change', onStoreChange);
 }
 /**
- * Checks if the current viewport width is desktop size (>= 960px).
+ * Client snapshot: the current match state of the desktop breakpoint.
  *
- * @returns True if the viewport is desktop size, false otherwise or in non-browser environments
+ * @returns True if the desktop breakpoint currently matches, false otherwise
  */
-function isInitialScreenDesktop() {
-    if (isBrowser()) {
-        return window.innerWidth >= 960;
-    }
+function getSnapshot() {
+    if (typeof window === 'undefined' || !window.matchMedia)
+        return false;
+    return window.matchMedia(DESKTOP_MEDIA_QUERY).matches;
+}
+/**
+ * Server snapshot: deliberately `false` (mobile first), so that the server
+ * render and the first client render match deterministically.
+ *
+ * @returns Always false
+ */
+function getServerSnapshot() {
     return false;
 }
+/**
+ * Custom hook that detects whether the viewport width is desktop size (>= 960px).
+ *
+ * @returns True if the viewport width is 960px or greater, false otherwise
+ */
 export function useIsDesktopScreenWidth() {
-    const [isDesktop, setIsDesktop] = useState(isInitialScreenDesktop);
-    useEffect(() => {
-        const checkScreenSize = () => {
-            setIsDesktop(window.innerWidth >= 960);
-        };
-        checkScreenSize();
-        window.addEventListener('resize', checkScreenSize);
-        return () => {
-            window.removeEventListener('resize', checkScreenSize);
-        };
-    }, []);
-    return isDesktop;
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
 //# sourceMappingURL=useIsDesktopScreenWidth.js.map

package/lib/hooks/useIsDesktopScreenWidth.js.map

@@ -1 +1 @@
-{"version":3,"file":"useIsDesktopScreenWidth.js","sourceRoot":"","sources":["../../src/hooks/useIsDesktopScreenWidth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAE3C;;;;;GAKG;AAEH,SAAS,SAAS;IAChB,OAAO,OAAO,MAAM,KAAK,WAAW,CAAA;AACtC,CAAC;AAED;;;;GAIG;AACH,SAAS,sBAAsB;IAC7B,IAAI,SAAS,EAAE,EAAE,CAAC;QAChB,OAAO,MAAM,CAAC,UAAU,IAAI,GAAG,CAAA;IACjC,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,UAAU,uBAAuB;IACrC,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAU,sBAAsB,CAAC,CAAA;IAE3E,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,eAAe,GAAG,GAAG,EAAE;YAC3B,YAAY,CAAC,MAAM,CAAC,UAAU,IAAI,GAAG,CAAC,CAAA;QACxC,CAAC,CAAA;QAED,eAAe,EAAE,CAAA;QACjB,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAA;QAElD,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAA;QACvD,CAAC,CAAA;IACH,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,OAAO,SAAS,CAAA;AAClB,CAAC"}
+{"version":3,"file":"useIsDesktopScreenWidth.js","sourceRoot":"","sources":["../../src/hooks/useIsDesktopScreenWidth.ts"],"names":[],"mappings":"AAAA,YAAY,CAAA;AAEZ,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAE5C,MAAM,mBAAmB,GAAG,oBAAoB,CAAA;AAEhD;;;;;;GAMG;AACH,SAAS,SAAS,CAAC,aAAyB;IAC1C,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACxD,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;IACjB,CAAC;IAED,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAA;IAC7D,cAAc,CAAC,gBAAgB,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAA;IAExD,OAAO,GAAG,EAAE,CAAC,cAAc,CAAC,mBAAmB,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAA;AAC1E,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW;IAClB,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,CAAC,MAAM,CAAC,UAAU;QAAE,OAAO,KAAK,CAAA;IAErE,OAAO,MAAM,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC,OAAO,CAAA;AACvD,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB;IACxB,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,oBAAoB,CAAC,SAAS,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAA;AACxE,CAAC"}

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import { ComboBox } from './ComboBox';
-export default ComboBox;
-export * from './types';
-export { ComboBoxOptionsSlot } from './partials';
+export { ComboBox, default } from './ComboBox';
+export { ComboBoxOptionsSlot, type ComboBoxOptionsSlotProps } from './partials';
+export { useComboBox, useIsDesktopScreenWidth } from './hooks';
+export type { ComboBoxAriaProps, ComboBoxOption, ComboBoxOptionGroup, ComboBoxOptionItemProps, ComboBoxOptionsInput, ComboBoxOptionsProps, ComboBoxOptionsPanelProps, ComboBoxProps, ListboxAriaProps, } from './types';

package/lib/index.js

@@ -1,5 +1,4 @@
-import { ComboBox } from './ComboBox';
-export default ComboBox;
-export * from './types';
+export { ComboBox, default } from './ComboBox';
 export { ComboBoxOptionsSlot } from './partials';
+export { useComboBox, useIsDesktopScreenWidth } from './hooks';
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AACrC,eAAe,QAAQ,CAAA;AACvB,cAAc,SAAS,CAAA;AACvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,mBAAmB,EAAiC,MAAM,YAAY,CAAA;AAC/E,OAAO,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA"}

package/lib/partials/ComboBoxGroupedOptions.d.ts

@@ -0,0 +1,13 @@
+import { LeadingType } from '@pixum/menu-item';
+import React from 'react';
+import { ComboBoxOptionProps } from '../types';
+interface ComboBoxGroupedOptionsProps {
+    group: string;
+    items: ComboBoxOptionProps[];
+    selectedOption?: string;
+    onClick?: (value: string) => void;
+    onKeyDown: (e: React.KeyboardEvent, value: string) => void;
+    leadingType?: LeadingType;
+}
+export declare function ComboBoxGroupedOptions(props: ComboBoxGroupedOptionsProps): React.JSX.Element;
+export {};

package/lib/partials/ComboBoxGroupedOptions.js

@@ -0,0 +1,10 @@
+import Text, { TextVariant } from '@pixum/text';
+import React from 'react';
+import { ComboBoxOptions } from './ComboBoxOptions';
+export function ComboBoxGroupedOptions(props) {
+    const { group, items, selectedOption, onClick, onKeyDown, leadingType } = props;
+    return (React.createElement("div", { className: "combobox__options-group", key: `combobox__options-group-${group}` },
+        React.createElement(Text, { variant: TextVariant.HEADLINE, className: "combobox__sticky-header" }, group),
+        React.createElement(ComboBoxOptions, { items: items, selectedOption: selectedOption, onClick: onClick, onKeyDown: onKeyDown, leadingType: leadingType })));
+}
+//# sourceMappingURL=ComboBoxGroupedOptions.js.map

package/lib/partials/ComboBoxGroupedOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComboBoxGroupedOptions.js","sourceRoot":"","sources":["../../src/partials/ComboBoxGroupedOptions.tsx"],"names":[],"mappings":"AACA,OAAO,IAAI,EAAE,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,KAAK,MAAM,OAAO,CAAA;AACzB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAYnD,MAAM,UAAU,sBAAsB,CAAC,KAAkC;IACvE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,GACrE,KAAK,CAAA;IACP,OAAO,CACL,6BACE,SAAS,EAAC,yBAAyB,EACnC,GAAG,EAAE,2BAA2B,KAAK,EAAE;QAEvC,oBAAC,IAAI,IAAC,OAAO,EAAE,WAAW,CAAC,QAAQ,EAAE,SAAS,EAAC,yBAAyB,IACrE,KAAK,CACD;QACP,oBAAC,eAAe,IACd,KAAK,EAAE,KAAK,EACZ,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,WAAW,GACxB,CACE,CACP,CAAA;AACH,CAAC"}

package/lib/partials/ComboBoxMenu.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import { ComboBoxOptionsProps } from '../types';
+export declare function ComboBoxMenu(props: ComboBoxOptionsProps): React.JSX.Element;

package/lib/partials/ComboBoxMenu.js

@@ -0,0 +1,22 @@
+import React, { useEffect } from 'react';
+import Menu from '@pixum/menu';
+import { scrollOptionToViewport } from '../helper';
+import { ComboBoxOptions } from './ComboBoxOptions';
+import { ComboBoxGroupedOptions } from './ComboBoxGroupedOptions';
+import { useIsDesktopScreenWidth } from '../hooks';
+export function ComboBoxMenu(props) {
+    const { options, onClick, selectedOption, leadingType, optionDetails } = props;
+    const isDesktop = useIsDesktopScreenWidth();
+    const handleOnKeyDown = (e, value) => {
+        if (e.key === 'Enter') {
+            onClick === null || onClick === void 0 ? void 0 : onClick(value);
+        }
+    };
+    useEffect(() => {
+        scrollOptionToViewport(isDesktop);
+    }, [isDesktop]);
+    return (React.createElement(Menu, { className: "combobox__options" },
+        Array.isArray(options) ? (React.createElement(ComboBoxOptions, { items: options, selectedOption: selectedOption, onClick: onClick, onKeyDown: handleOnKeyDown, leadingType: leadingType })) : (React.createElement(React.Fragment, null, Object.entries(options).map(([group, items]) => (React.createElement(ComboBoxGroupedOptions, { group: group, items: items, selectedOption: selectedOption, onClick: onClick, onKeyDown: handleOnKeyDown, leadingType: leadingType }))))),
+        optionDetails && (React.createElement("div", { className: "combobox__option-details text--caption" }, optionDetails))));
+}
+//# sourceMappingURL=ComboBoxMenu.js.map

package/lib/partials/ComboBoxMenu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComboBoxMenu.js","sourceRoot":"","sources":["../../src/partials/ComboBoxMenu.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACxC,OAAO,IAAI,MAAM,aAAa,CAAA;AAC9B,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAElD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA;AAElD,MAAM,UAAU,YAAY,CAAC,KAA2B;IACtD,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,GAAG,KAAK,CAAA;IAC9E,MAAM,SAAS,GAAG,uBAAuB,EAAE,CAAA;IAE3C,MAAM,eAAe,GAAG,CAAC,CAAsB,EAAE,KAAa,EAAE,EAAE;QAChE,IAAI,CAAC,CAAC,GAAG,KAAK,OAAO,EAAE,CAAC;YACtB,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAG,KAAK,CAAC,CAAA;QAClB,CAAC;IACH,CAAC,CAAA;IAED,SAAS,CAAC,GAAG,EAAE;QACb,sBAAsB,CAAC,SAAS,CAAC,CAAA;IACnC,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAA;IAEf,OAAO,CACL,oBAAC,IAAI,IAAC,SAAS,EAAC,mBAAmB;QAChC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CACxB,oBAAC,eAAe,IACd,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,eAAe,EAC1B,WAAW,EAAE,WAAW,GACxB,CACH,CAAC,CAAC,CAAC,CACF,0CACG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAC/C,oBAAC,sBAAsB,IACrB,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,KAAK,EACZ,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,eAAe,EAC1B,WAAW,EAAE,WAAW,GACxB,CACH,CAAC,CACD,CACJ;QACA,aAAa,IAAI,CAChB,6BAAK,SAAS,EAAC,wCAAwC,IACpD,aAAa,CACV,CACP,CACI,CACR,CAAA;AACH,CAAC"}

package/lib/partials/ComboBoxNoResults.d.ts

@@ -0,0 +1,14 @@
+export interface ComboBoxNoResultsProps {
+    /** Message shown when no option matches the search. */
+    text?: string;
+}
+/**
+ * Empty state of the options list.
+ *
+ * `role="status"` makes screen readers announce the message when the list is
+ * filtered down to nothing.
+ *
+ * @param props - The props for the ComboBoxNoResults component
+ * @returns The no-results message
+ */
+export declare function ComboBoxNoResults({ text }: ComboBoxNoResultsProps): import("react/jsx-runtime").JSX.Element | null;

package/lib/partials/ComboBoxNoResults.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import Text, { TEXT_VARIANT } from '@pixum/text';
+import styles from '../ComboBox.module.css';
+/**
+ * Empty state of the options list.
+ *
+ * `role="status"` makes screen readers announce the message when the list is
+ * filtered down to nothing.
+ *
+ * @param props - The props for the ComboBoxNoResults component
+ * @returns The no-results message
+ */
+export function ComboBoxNoResults({ text }) {
+    if (!text)
+        return null;
+    return (_jsx(Text, { variant: TEXT_VARIANT.SUBHEADLINE, className: styles.noResults, children: text }));
+}
+//# sourceMappingURL=ComboBoxNoResults.js.map

package/lib/partials/ComboBoxNoResults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComboBoxNoResults.js","sourceRoot":"","sources":["../../src/partials/ComboBoxNoResults.tsx"],"names":[],"mappings":";AAAA,OAAO,IAAI,EAAE,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,MAAM,MAAM,wBAAwB,CAAA;AAO3C;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAE,IAAI,EAA0B;IAChE,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IAEtB,OAAO,CACL,KAAC,IAAI,IAAC,OAAO,EAAE,YAAY,CAAC,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,YACjE,IAAI,GACA,CACR,CAAA;AACH,CAAC"}

package/lib/partials/ComboBoxOptions.d.ts

@@ -1,10 +1,21 @@
-import type { ComboBoxOptionsProps } from '../types';
+import type { ComboBoxOptionsPanelProps } from '../types';
 /**
- * ComboBoxOptions component that renders a list of options in a menu.
- * Handles both grouped and ungrouped options and automatically scrolls to the selected option.
+ * Renders the options panel of the ComboBox.
+ *
+ * The panel is split in two: the `Menu` provides the visible box, the element
+ * inside it carries the `listbox` role and is the only part that scrolls. That
+ * keeps `optionDetails` a real footer - it stays visible without
+ * `position: sticky` and can no longer cover the active option - and it keeps
+ * the listbox free of anything that is not an option or a group, as ARIA
+ * requires.
+ *
+ * Flat and grouped options share one render path: the options arrive already
+ * normalised, `groupOptions` only splits them into their visual groups again.
+ * The listbox is not focusable - the focus stays in the input field, the active
+ * option is announced through `aria-activedescendant`.
  *
  * @param props - The props for the ComboBoxOptions component
- * @returns A menu containing the combobox options
+ * @returns The options panel
  */
-export declare function ComboBoxOptions({ options, onClick, selectedOption, leadingType, optionDetails, }: ComboBoxOptionsProps): import("react/jsx-runtime").JSX.Element;
+export declare function ComboBoxOptions({ options, listboxAriaProps, selectedValues, activeOptionId, leadingType, optionDetails, onOptionClick, }: ComboBoxOptionsPanelProps): import("react/jsx-runtime").JSX.Element;
 export default ComboBoxOptions;

package/lib/partials/ComboBoxOptions.js

@@ -1,29 +1,33 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect } from 'react';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import Menu from '@pixum/menu';
-import { useIsDesktopScreenWidth } from '../hooks';
-import { scrollOptionToViewport } from '../utils';
-import { ComboxBoxOptionsWithGrouping } from './ComboBoxOptionsWithGrouping';
-import { ComboBoxOptionsItems } from './ComboBoxOptionsItems';
+import Text, { TEXT_VARIANT } from '@pixum/text';
+import clsx from 'clsx';
+import { groupOptions } from '../utils';
+import { ComboBoxOptionsGroup } from './ComboBoxOptionsGroup';
+import styles from '../ComboBox.module.css';
 /**
- * ComboBoxOptions component that renders a list of options in a menu.
- * Handles both grouped and ungrouped options and automatically scrolls to the selected option.
+ * Renders the options panel of the ComboBox.
+ *
+ * The panel is split in two: the `Menu` provides the visible box, the element
+ * inside it carries the `listbox` role and is the only part that scrolls. That
+ * keeps `optionDetails` a real footer - it stays visible without
+ * `position: sticky` and can no longer cover the active option - and it keeps
+ * the listbox free of anything that is not an option or a group, as ARIA
+ * requires.
+ *
+ * Flat and grouped options share one render path: the options arrive already
+ * normalised, `groupOptions` only splits them into their visual groups again.
+ * The listbox is not focusable - the focus stays in the input field, the active
+ * option is announced through `aria-activedescendant`.
  *
  * @param props - The props for the ComboBoxOptions component
- * @returns A menu containing the combobox options
+ * @returns The options panel
  */
-export function ComboBoxOptions({ options, onClick, selectedOption, leadingType, optionDetails, }) {
-    const isDesktop = useIsDesktopScreenWidth();
-    const optionsWithoutGroup = Array.isArray(options);
-    const optionsWithGroup = Object.entries(options);
-    useEffect(() => {
-        // Wait for next browser frame to ensure DOM is fully rendered
-        const frameId = requestAnimationFrame(() => {
-            scrollOptionToViewport(isDesktop);
-        });
-        return () => cancelAnimationFrame(frameId);
-    }, [isDesktop, selectedOption]);
-    return (_jsxs(Menu, { className: "combobox__options scrollable", "data-tappable": "true", children: [optionsWithoutGroup ? (_jsx(ComboBoxOptionsItems, { items: options, selectedOption: selectedOption, onClick: onClick, leadingType: leadingType })) : (_jsx(_Fragment, { children: optionsWithGroup.map(([group, items]) => (_jsx(ComboxBoxOptionsWithGrouping, { group: group, items: items, selectedOption: selectedOption, onClick: onClick, leadingType: leadingType }, `combobox__options-group-${group}`))) })), optionDetails && (_jsx("div", { className: "combobox__option-details text--caption", children: optionDetails }))] }));
+export function ComboBoxOptions({ options, listboxAriaProps, selectedValues, activeOptionId, leadingType, optionDetails, onOptionClick, }) {
+    return (_jsxs(Menu, { className: styles.panel, "data-tappable": "true", children: [_jsx("div", Object.assign({ className: clsx(styles.options, 'scrollable'), tabIndex: -1 }, listboxAriaProps, { children: groupOptions(options).map(group => {
+                    var _a;
+                    return (_jsx(ComboBoxOptionsGroup, { group: group.group, options: group.options, selectedValues: selectedValues, activeOptionId: activeOptionId, leadingType: leadingType, onOptionClick: onOptionClick }, `combobox__options-group-${(_a = group.group) !== null && _a !== void 0 ? _a : 'default'}`));
+                }) })), optionDetails && (_jsx(Text, { variant: TEXT_VARIANT.CAPTION, className: styles.optionDetails, children: optionDetails }))] }));
 }
 export default ComboBoxOptions;
 //# sourceMappingURL=ComboBoxOptions.js.map

package/lib/partials/ComboBoxOptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"ComboBoxOptions.js","sourceRoot":"","sources":["../../src/partials/ComboBoxOptions.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACjC,OAAO,IAAI,MAAM,aAAa,CAAA;AAC9B,OAAO,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAEjD,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAA;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAE7D;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,OAAO,EACP,OAAO,EACP,cAAc,EACd,WAAW,EACX,aAAa,GACQ;IACrB,MAAM,SAAS,GAAG,uBAAuB,EAAE,CAAA;IAC3C,MAAM,mBAAmB,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAClD,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAEhD,SAAS,CAAC,GAAG,EAAE;QACb,8DAA8D;QAC9D,MAAM,OAAO,GAAG,qBAAqB,CAAC,GAAG,EAAE;YACzC,sBAAsB,CAAC,SAAS,CAAC,CAAA;QACnC,CAAC,CAAC,CAAA;QAEF,OAAO,GAAG,EAAE,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAA;IAC5C,CAAC,EAAE,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC,CAAA;IAE/B,OAAO,CACL,MAAC,IAAI,IAAC,SAAS,EAAC,8BAA8B,mBAAe,MAAM,aAChE,mBAAmB,CAAC,CAAC,CAAC,CACrB,KAAC,oBAAoB,IACnB,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,WAAW,GACxB,CACH,CAAC,CAAC,CAAC,CACF,4BACG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CACxC,KAAC,4BAA4B,IAE3B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,KAAK,EACZ,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,WAAW,IALnB,2BAA2B,KAAK,EAAE,CAMvC,CACH,CAAC,GACD,CACJ,EACA,aAAa,IAAI,CAChB,cAAK,SAAS,EAAC,wCAAwC,YACpD,aAAa,GACV,CACP,IACI,CACR,CAAA;AACH,CAAC;AAED,eAAe,eAAe,CAAA"}
+{"version":3,"file":"ComboBoxOptions.js","sourceRoot":"","sources":["../../src/partials/ComboBoxOptions.tsx"],"names":[],"mappings":";AAAA,OAAO,IAAI,MAAM,aAAa,CAAA;AAC9B,OAAO,IAAI,EAAE,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,IAAI,MAAM,MAAM,CAAA;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,MAAM,MAAM,wBAAwB,CAAA;AAG3C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,OAAO,EACP,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,aAAa,GACa;IAC1B,OAAO,CACL,MAAC,IAAI,IAAC,SAAS,EAAE,MAAM,CAAC,KAAK,mBAAgB,MAAM,aACjD,4BACE,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,EAC7C,QAAQ,EAAE,CAAC,CAAC,IACR,gBAAgB,cAEnB,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE;;oBAAC,OAAA,CAClC,KAAC,oBAAoB,IAEnB,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,OAAO,EAAE,KAAK,CAAC,OAAO,EACtB,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,cAAc,EAC9B,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,aAAa,IANvB,2BAA2B,MAAA,KAAK,CAAC,KAAK,mCAAI,SAAS,EAAE,CAO1D,CACH,CAAA;iBAAA,CAAC,IACE,EAEL,aAAa,IAAI,CAChB,KAAC,IAAI,IAAC,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,aAAa,YACjE,aAAa,GACT,CACR,IACI,CACR,CAAA;AACH,CAAC;AAED,eAAe,eAAe,CAAA"}

package/lib/partials/ComboBoxOptionsGroup.d.ts

@@ -0,0 +1,15 @@
+import type { ComboBoxOptionsItemsProps } from './ComboBoxOptionsItems';
+export interface ComboBoxOptionsGroupProps extends ComboBoxOptionsItemsProps {
+    /** Group headline. Without it the options are rendered without a header. */
+    group?: string;
+}
+/**
+ * Renders one group of options with an optional sticky headline.
+ *
+ * Flat lists use the same component with `group` left undefined, so there is
+ * only one place that renders options.
+ *
+ * @param props - The props for the ComboBoxOptionsGroup component
+ * @returns A group container with an optional header and its options
+ */
+export declare function ComboBoxOptionsGroup({ group, ...itemProps }: ComboBoxOptionsGroupProps): import("react/jsx-runtime").JSX.Element;

package/lib/partials/ComboBoxOptionsGroup.js

@@ -0,0 +1,31 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import Text, { TEXT_VARIANT } from '@pixum/text';
+import { ComboBoxOptionsItems } from './ComboBoxOptionsItems';
+import styles from '../ComboBox.module.css';
+/**
+ * Renders one group of options with an optional sticky headline.
+ *
+ * Flat lists use the same component with `group` left undefined, so there is
+ * only one place that renders options.
+ *
+ * @param props - The props for the ComboBoxOptionsGroup component
+ * @returns A group container with an optional header and its options
+ */
+export function ComboBoxOptionsGroup(_a) {
+    var { group } = _a, itemProps = __rest(_a, ["group"]);
+    if (!group)
+        return _jsx(ComboBoxOptionsItems, Object.assign({}, itemProps));
+    return (_jsxs("div", { role: "group", "aria-label": group, children: [_jsx(Text, { variant: TEXT_VARIANT.HEADLINE, className: styles.stickyHeader, children: group }), _jsx(ComboBoxOptionsItems, Object.assign({}, itemProps))] }));
+}
+//# sourceMappingURL=ComboBoxOptionsGroup.js.map

package/lib/partials/ComboBoxOptionsGroup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComboBoxOptionsGroup.js","sourceRoot":"","sources":["../../src/partials/ComboBoxOptionsGroup.tsx"],"names":[],"mappings":";;;;;;;;;;;;AAAA,OAAO,IAAI,EAAE,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,MAAM,MAAM,wBAAwB,CAAA;AAQ3C;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,EAGT;QAHS,EACnC,KAAK,OAEqB,EADvB,SAAS,cAFuB,SAGpC,CADa;IAEZ,IAAI,CAAC,KAAK;QAAE,OAAO,KAAC,oBAAoB,oBAAK,SAAS,EAAI,CAAA;IAE1D,OAAO,CACL,eAAK,IAAI,EAAC,OAAO,gBAAa,KAAK,aACjC,KAAC,IAAI,IAAC,OAAO,EAAE,YAAY,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,YAAY,YACjE,KAAK,GACD,EACP,KAAC,oBAAoB,oBAAK,SAAS,EAAI,IACnC,CACP,CAAA;AACH,CAAC"}

package/lib/partials/ComboBoxOptionsItems.d.ts

@@ -1,24 +1,39 @@
 import { LeadingType } from '@pixum/menu-item';
-import type { ComboBoxOptionItemProps } from '../types';
-/**
- * Props for the ComboBoxOptionsItems component
- */
-interface ComboBoxOptionsItemsProps {
-    /** Array of option items to display */
-    items: ComboBoxOptionItemProps[];
-    /** Currently selected option value */
-    selectedOption?: string;
-    /** Callback fired when an option is clicked */
-    onClick?: (value: string) => void;
-    /** Type of leading element to display (icon, avatar, etc.) */
+import type { ComboBoxOption } from '../types';
+export interface ComboBoxOptionsItemsProps {
+    /** Normalised options to render. */
+    options: ComboBoxOption[];
+    /** Values that are currently selected. */
+    selectedValues: string[];
+    /** DOM id of the active option (`aria-activedescendant`). */
+    activeOptionId?: string;
+    /** Type of the leading element, e.g. a checkbox for multi select. */
     leadingType?: LeadingType;
+    /** Called with the value of the clicked option. */
+    onOptionClick: (value: string) => void;
 }
 /**
- * ComboBoxOptionsItems component that renders individual menu items.
- * Handles click events and displays selected state for each option.
+ * Renders the individual options.
+ *
+ * The options are deliberately not focusable: the focus stays in the input
+ * field and the highlight is driven by `aria-activedescendant`. Checkbox
+ * options are ordinary options with `aria-selected` - inside a listbox that is
+ * the state screen readers announce, and it keeps mouse and keyboard selection
+ * on exactly the same code path.
+ *
+ * An option is a `MenuItemProps` object, so everything except the ComboBox
+ * specific `key` and `disabled` is spread onto the `MenuItem` unchanged.
+ * Consumers that pass further MenuItem props keep working without the ComboBox
+ * having to know about them; only `selected`, `tabIndex` and the keyboard
+ * handling are owned by the ComboBox and therefore not overridable.
+ *
+ * Styling hooks: every option carries its state as a data attribute
+ * (`data-selected`, `data-active`, `data-disabled`), so consumers can style
+ * options without knowing the hashed module class names. The selection state is
+ * left to `MenuItem` itself - the component does not add a `selected` class of
+ * its own, which would be impossible to override from the outside.
  *
  * @param props - The props for the ComboBoxOptionsItems component
- * @returns A list of clickable menu items
+ * @returns A list of selectable options
  */
-export declare function ComboBoxOptionsItems({ items, selectedOption, onClick, leadingType, }: ComboBoxOptionsItemsProps): import("react/jsx-runtime").JSX.Element;
-export {};
+export declare function ComboBoxOptionsItems({ options, selectedValues, activeOptionId, leadingType, onOptionClick, }: ComboBoxOptionsItemsProps): import("react/jsx-runtime").JSX.Element;

package/lib/partials/ComboBoxOptionsItems.js

@@ -1,24 +1,56 @@
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
-import MenuItem from '@pixum/menu-item';
+import MenuItem, { LeadingType } from '@pixum/menu-item';
 import clsx from 'clsx';
+import { toMenuItemProps } from '../utils';
+import styles from '../ComboBox.module.css';
 /**
- * ComboBoxOptionsItems component that renders individual menu items.
- * Handles click events and displays selected state for each option.
+ * Renders the individual options.
+ *
+ * The options are deliberately not focusable: the focus stays in the input
+ * field and the highlight is driven by `aria-activedescendant`. Checkbox
+ * options are ordinary options with `aria-selected` - inside a listbox that is
+ * the state screen readers announce, and it keeps mouse and keyboard selection
+ * on exactly the same code path.
+ *
+ * An option is a `MenuItemProps` object, so everything except the ComboBox
+ * specific `key` and `disabled` is spread onto the `MenuItem` unchanged.
+ * Consumers that pass further MenuItem props keep working without the ComboBox
+ * having to know about them; only `selected`, `tabIndex` and the keyboard
+ * handling are owned by the ComboBox and therefore not overridable.
+ *
+ * Styling hooks: every option carries its state as a data attribute
+ * (`data-selected`, `data-active`, `data-disabled`), so consumers can style
+ * options without knowing the hashed module class names. The selection state is
+ * left to `MenuItem` itself - the component does not add a `selected` class of
+ * its own, which would be impossible to override from the outside.
  *
  * @param props - The props for the ComboBoxOptionsItems component
- * @returns A list of clickable menu items
+ * @returns A list of selectable options
  */
-export function ComboBoxOptionsItems({ items, selectedOption, onClick, leadingType, }) {
-    return (_jsx(_Fragment, { children: items.map((item) => {
+export function ComboBoxOptionsItems({ options, selectedValues, activeOptionId, leadingType, onOptionClick, }) {
+    const isCheckbox = leadingType === LeadingType.CheckBox;
+    return (_jsx(_Fragment, { children: options.map(({ item, id, value, disabled }) => {
             var _a;
-            const itemText = item.text;
-            const isSelected = selectedOption === itemText;
-            return (_jsx("div", { className: "combobox__option-wrapper", role: "button", tabIndex: 0, onPointerDown: e => e.stopPropagation(), onTouchStart: e => e.stopPropagation(), onMouseDown: e => e.stopPropagation(), onClickCapture: e => {
-                    e.stopPropagation();
-                    onClick === null || onClick === void 0 ? void 0 : onClick(itemText);
-                }, children: _jsx(MenuItem, { tabIndex: -1, className: clsx(isSelected && 'selected'), onMouseEnter: item.onMouseEnter, leadingProps: leadingType ? { name: itemText, type: leadingType } : undefined, selected: selectedOption === itemText, text: itemText, subtext: item.subtext, subItemProps: {
-                        text: (_a = item.subItemProps) === null || _a === void 0 ? void 0 : _a.text,
-                    } }) }, `combobox-item-wrapper-${itemText}`));
+            const isSelected = selectedValues.includes(value);
+            const isActive = id === activeOptionId;
+            const menuItemProps = toMenuItemProps(item);
+            return (_jsx("div", { id: id, className: clsx(styles.option, isCheckbox && styles.optionCheckbox, isActive && styles.optionActive), role: "option", "aria-selected": isSelected, "aria-disabled": disabled || undefined, "data-selected": isSelected, "data-active": isActive, "data-disabled": disabled || undefined, onMouseDown: event => {
+                    // Keeps the focus in the input field ...
+                    event.preventDefault();
+                    // ... and keeps the bottom sheet's drag handler out of it.
+                    event.stopPropagation();
+                }, onPointerDown: event => event.stopPropagation(), 
+                // No preventDefault on touchstart, scrolling in the sheet must work.
+                onTouchStart: event => event.stopPropagation(), onClickCapture: event => {
+                    event.stopPropagation();
+                    if (disabled)
+                        return;
+                    onOptionClick(value);
+                }, children: _jsx(MenuItem, Object.assign({}, menuItemProps, { tabIndex: -1, disableKeyboardNav: true, 
+                    // A leading type set on the ComboBox wins over the option's own
+                    // one: it is what makes multi select look like a checkbox list.
+                    leadingProps: leadingType
+                        ? Object.assign(Object.assign({}, menuItemProps.leadingProps), { name: value, type: leadingType }) : menuItemProps.leadingProps, selected: isSelected })) }, (_a = item.key) !== null && _a !== void 0 ? _a : `combobox-item-wrapper-${id}`));
         }) }));
 }
 //# sourceMappingURL=ComboBoxOptionsItems.js.map

package/lib/partials/ComboBoxOptionsItems.js.map

@@ -1 +1 @@
-{"version":3,"file":"ComboBoxOptionsItems.js","sourceRoot":"","sources":["../../src/partials/ComboBoxOptionsItems.tsx"],"names":[],"mappings":";AAAA,OAAO,QAAyB,MAAM,kBAAkB,CAAA;AACxD,OAAO,IAAI,MAAM,MAAM,CAAA;AAiBvB;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,EACnC,KAAK,EACL,cAAc,EACd,OAAO,EACP,WAAW,GACe;IAC1B,OAAO,CACL,4BACG,KAAK,CAAC,GAAG,CAAC,CAAC,IAA6B,EAAE,EAAE;;YAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAA;YAC1B,MAAM,UAAU,GAAG,cAAc,KAAK,QAAQ,CAAA;YAE9C,OAAO,CACL,cAEE,SAAS,EAAC,0BAA0B,EACpC,IAAI,EAAC,QAAQ,EACb,QAAQ,EAAE,CAAC,EACX,aAAa,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,eAAe,EAAE,EACvC,YAAY,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,eAAe,EAAE,EACtC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,eAAe,EAAE,EACrC,cAAc,EAAE,CAAC,CAAC,EAAE;oBAClB,CAAC,CAAC,eAAe,EAAE,CAAA;oBACnB,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAG,QAAQ,CAAC,CAAA;gBACrB,CAAC,YAED,KAAC,QAAQ,IACP,QAAQ,EAAE,CAAC,CAAC,EACZ,SAAS,EAAE,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,EACzC,YAAY,EAAE,IAAI,CAAC,YAAY,EAC/B,YAAY,EACV,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,EAEjE,QAAQ,EAAE,cAAc,KAAK,QAAQ,EACrC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,IAAI,CAAC,OAAO,EACrB,YAAY,EAAE;wBACZ,IAAI,EAAE,MAAA,IAAI,CAAC,YAAY,0CAAE,IAAI;qBAC9B,GACD,IAzBG,yBAAyB,QAAQ,EAAE,CA0BpC,CACP,CAAA;QACH,CAAC,CAAC,GACD,CACJ,CAAA;AACH,CAAC"}
+{"version":3,"file":"ComboBoxOptionsItems.js","sourceRoot":"","sources":["../../src/partials/ComboBoxOptionsItems.tsx"],"names":[],"mappings":";AAAA,OAAO,QAAQ,EAAE,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,IAAI,MAAM,MAAM,CAAA;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,MAAM,MAAM,wBAAwB,CAAA;AAgB3C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,oBAAoB,CAAC,EACnC,OAAO,EACP,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,GACa;IAC1B,MAAM,UAAU,GAAG,WAAW,KAAK,WAAW,CAAC,QAAQ,CAAA;IAEvD,OAAO,CACL,4BACG,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE;;YAC7C,MAAM,UAAU,GAAG,cAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;YACjD,MAAM,QAAQ,GAAG,EAAE,KAAK,cAAc,CAAA;YACtC,MAAM,aAAa,GAAG,eAAe,CAAC,IAAI,CAAC,CAAA;YAE3C,OAAO,CACL,cAEE,EAAE,EAAE,EAAE,EACN,SAAS,EAAE,IAAI,CACb,MAAM,CAAC,MAAM,EACb,UAAU,IAAI,MAAM,CAAC,cAAc,EACnC,QAAQ,IAAI,MAAM,CAAC,YAAY,CAChC,EACD,IAAI,EAAC,QAAQ,mBACE,UAAU,mBACV,QAAQ,IAAI,SAAS,mBACrB,UAAU,iBACZ,QAAQ,mBACN,QAAQ,IAAI,SAAS,EACpC,WAAW,EAAE,KAAK,CAAC,EAAE;oBACnB,yCAAyC;oBACzC,KAAK,CAAC,cAAc,EAAE,CAAA;oBACtB,2DAA2D;oBAC3D,KAAK,CAAC,eAAe,EAAE,CAAA;gBACzB,CAAC,EACD,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,eAAe,EAAE;gBAC/C,qEAAqE;gBACrE,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,eAAe,EAAE,EAC9C,cAAc,EAAE,KAAK,CAAC,EAAE;oBACtB,KAAK,CAAC,eAAe,EAAE,CAAA;oBAEvB,IAAI,QAAQ;wBAAE,OAAM;oBAEpB,aAAa,CAAC,KAAK,CAAC,CAAA;gBACtB,CAAC,YAED,KAAC,QAAQ,oBACH,aAAa,IACjB,QAAQ,EAAE,CAAC,CAAC,EACZ,kBAAkB;oBAClB,gEAAgE;oBAChE,gEAAgE;oBAChE,YAAY,EACV,WAAW;wBACT,CAAC,iCACM,aAAa,CAAC,YAAY,KAC7B,IAAI,EAAE,KAAK,EACX,IAAI,EAAE,WAAW,IAErB,CAAC,CAAC,aAAa,CAAC,YAAY,EAEhC,QAAQ,EAAE,UAAU,IACpB,IA9CG,MAAA,IAAI,CAAC,GAAG,mCAAI,yBAAyB,EAAE,EAAE,CA+C1C,CACP,CAAA;QACH,CAAC,CAAC,GACD,CACJ,CAAA;AACH,CAAC"}

package/lib/partials/ComboBoxOptionsSlot.d.ts

@@ -1,34 +1,35 @@
-import type { ReactNode } from 'react';
-import '../styles.css';
-export interface ComboBoxOptionsSlotProps {
-    /** The content to render inside the options slot */
+import type { ElementType, HTMLAttributes, ReactNode } from 'react';
+export interface ComboBoxOptionsSlotProps extends HTMLAttributes<HTMLElement> {
+    /** The content to render inside the options slot. */
     children: ReactNode;
-    className?: string;
-    role?: string;
-    tag?: 'div' | 'ul' | 'ol' | 'dl';
+    /** Element the slot renders as. */
+    tag?: Extract<ElementType, 'div' | 'ul' | 'ol' | 'dl'>;
 }
 /**
- * Styled container for optionsSlot content.
+ * Styled container for `optionsSlot` content.
  *
- * Applies the standard ComboBox dropdown appearance — white background,
- * border, border-radius, box-shadow and top margin — so consumers don't
- * have to replicate it in every optionsSlot implementation.
+ * Applies the standard ComboBox dropdown appearance - background, border,
+ * border radius, box shadow and top margin - so consumers do not have to
+ * replicate it in every `optionsSlot` implementation. Every other prop
+ * (`role`, `aria-*`, ...) is forwarded, because the slot content owns its own
+ * accessibility semantics.
  *
- * Use it as the outermost wrapper of your optionsSlot:
+ * A slot replaces the built-in options list and therefore also its keyboard
+ * navigation: content rendered here has to bring its own key handling.
  *
  * ```tsx
  * import ComboBox, { ComboBoxOptionsSlot } from '@pixum/combobox'
  *
  * <ComboBox
  *   optionsSlot={
- *     <ComboBoxOptionsSlot>
+ *     <ComboBoxOptionsSlot role="listbox" aria-label="Pickup points">
  *       <MyCustomOptionsList />
  *     </ComboBoxOptionsSlot>
  *   }
  * />
  * ```
  *
- * @param children - The slot content to render inside the container
- * @returns A styled wrapper div matching the ComboBox dropdown look
+ * @param props - The props for the ComboBoxOptionsSlot component
+ * @returns A styled wrapper matching the ComboBox dropdown look
  */
-export declare function ComboBoxOptionsSlot({ children, className, role, tag, }: ComboBoxOptionsSlotProps): import("react/jsx-runtime").JSX.Element;
+export declare function ComboBoxOptionsSlot({ children, className, tag, ...rest }: ComboBoxOptionsSlotProps): import("react/jsx-runtime").JSX.Element;