@pixum/combobox 5.10.4-alpha.22 → 5.10.4-alpha.24

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,GACQ;IACrB,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/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;

package/lib/partials/ComboBoxOptionsSlot.js

@@ -1,32 +1,47 @@
+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 } from "react/jsx-runtime";
-import '../styles.css';
 import Menu from '@pixum/menu';
 import clsx from 'clsx';
+import styles from '../ComboBox.module.css';
 /**
- * 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 function ComboBoxOptionsSlot({ children, className = '', role = '', tag = 'ul', }) {
-    return (_jsx(Menu, { tag: tag, className: clsx(className, 'combobox__options-slot'), role: role, children: children }));
+export function ComboBoxOptionsSlot(_a) {
+    var { children, className, tag = 'ul' } = _a, rest = __rest(_a, ["children", "className", "tag"]);
+    return (_jsx(Menu, Object.assign({ tag: tag, className: clsx(styles.optionsSlot, className) }, rest, { children: children })));
 }
 //# sourceMappingURL=ComboBoxOptionsSlot.js.map

package/lib/partials/ComboBoxOptionsSlot.js.map

@@ -1 +1 @@
-{"version":3,"file":"ComboBoxOptionsSlot.js","sourceRoot":"","sources":["../../src/partials/ComboBoxOptionsSlot.tsx"],"names":[],"mappings":";AACA,OAAO,eAAe,CAAA;AACtB,OAAO,IAAI,MAAM,aAAa,CAAA;AAC9B,OAAO,IAAI,MAAM,MAAM,CAAA;AASvB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAClC,QAAQ,EACR,SAAS,GAAG,EAAE,EACd,IAAI,GAAG,EAAE,EACT,GAAG,GAAG,IAAI,GACe;IACzB,OAAO,CACL,KAAC,IAAI,IACH,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,wBAAwB,CAAC,EACpD,IAAI,EAAE,IAAI,YAET,QAAQ,GACJ,CACR,CAAA;AACH,CAAC"}
+{"version":3,"file":"ComboBoxOptionsSlot.js","sourceRoot":"","sources":["../../src/partials/ComboBoxOptionsSlot.tsx"],"names":[],"mappings":";;;;;;;;;;;;AACA,OAAO,IAAI,MAAM,aAAa,CAAA;AAC9B,OAAO,IAAI,MAAM,MAAM,CAAA;AACvB,OAAO,MAAM,MAAM,wBAAwB,CAAA;AAU3C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAKT;QALS,EAClC,QAAQ,EACR,SAAS,EACT,GAAG,GAAG,IAAI,OAEe,EADtB,IAAI,cAJ2B,gCAKnC,CADQ;IAEP,OAAO,CACL,KAAC,IAAI,kBAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,SAAS,CAAC,IAAM,IAAI,cACrE,QAAQ,IACJ,CACR,CAAA;AACH,CAAC"}

package/lib/partials/index.d.ts

@@ -1,4 +1,5 @@
 export * from './ComboBoxOptions';
-export * from './ComboBoxOptionsWithGrouping';
+export * from './ComboBoxOptionsGroup';
 export * from './ComboBoxOptionsItems';
 export * from './ComboBoxOptionsSlot';
+export * from './ComboBoxNoResults';

package/lib/partials/index.js

@@ -1,5 +1,6 @@
 export * from './ComboBoxOptions';
-export * from './ComboBoxOptionsWithGrouping';
+export * from './ComboBoxOptionsGroup';
 export * from './ComboBoxOptionsItems';
 export * from './ComboBoxOptionsSlot';
+export * from './ComboBoxNoResults';
 //# sourceMappingURL=index.js.map

package/lib/partials/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/partials/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,wBAAwB,CAAA;AACtC,cAAc,uBAAuB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/partials/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AACtC,cAAc,uBAAuB,CAAA;AACrC,cAAc,qBAAqB,CAAA"}

package/lib/types.d.ts

@@ -1,78 +1,149 @@
-import { LeadingType, MenuItemProps } from '@pixum/menu-item';
-import { ThemeType } from '@pixum/theme-provider';
-import { InputModesType } from '@pixum/web-input';
+import type { LeadingType, MenuItemProps } from '@pixum/menu-item';
+import type { ThemeType } from '@pixum/theme-provider';
+import type { InputModesType } from '@pixum/web-input';
 /**
- * Props for the ComboBoxOptions component
+ * An option as handed in by the consumer.
+ *
+ * Everything a `MenuItem` understands is accepted and forwarded unchanged -
+ * the ComboBox only adds `key` and `disabled` on top. That keeps existing
+ * consumers working: they pass their MenuItem props as they always did, and
+ * props the ComboBox does not know about still reach the `MenuItem`.
  */
+export interface ComboBoxOptionItemProps extends MenuItemProps {
+    /** Unique key for the option item */
+    key?: string;
+    /** Disabled options are rendered, but skipped by mouse and keyboard. */
+    disabled?: boolean;
+}
+/** Options are accepted either as a flat list or grouped by a group headline. */
+export type ComboBoxOptionsInput = ComboBoxOptionItemProps[] | Record<string, ComboBoxOptionItemProps[]>;
+/**
+ * An option after normalisation. Flat and grouped options are reduced to this
+ * shape once, so keyboard navigation, rendering and ARIA ids all work on the
+ * very same list in the very same order.
+ */
+export interface ComboBoxOption {
+    /** The original option as handed in by the consumer. */
+    item: ComboBoxOptionItemProps;
+    /**
+     * Stable value of the option, reported by `onOptionItemClick` and compared
+     * against `value`. Resolved by `resolveOptionValue`: the option's `text` when
+     * it is a string, otherwise `key`, otherwise the render index.
+     */
+    value: string;
+    /** Position in render order. Drives the DOM id and the keyboard navigation. */
+    index: number;
+    /** DOM id, referenced by `aria-activedescendant`. */
+    id: string;
+    /** Group headline the option belongs to, `undefined` for flat lists. */
+    group?: string;
+    /** Whether the option can be activated. */
+    disabled: boolean;
+}
+/** Options of one render group, produced by `groupOptions`. */
+export interface ComboBoxOptionGroup {
+    /** Group headline, `undefined` for flat lists. */
+    group?: string;
+    /** Options of this group, still carrying their global render index. */
+    options: ComboBoxOption[];
+}
+/** ARIA props for the element that owns the `combobox` role. */
+export interface ComboBoxAriaProps {
+    role: 'combobox';
+    'aria-expanded': boolean;
+    'aria-haspopup': 'listbox';
+    'aria-controls': string | undefined;
+    'aria-activedescendant': string | undefined;
+    'aria-autocomplete': 'list' | 'none';
+}
+/** ARIA props for the element that owns the `listbox` role. */
+export interface ListboxAriaProps {
+    role: 'listbox';
+    id: string;
+    /** Only set for multi select; single select listboxes omit it. */
+    'aria-multiselectable'?: boolean;
+}
+/** Props of the rendered options list. */
 export interface ComboBoxOptionsProps {
-    /** Options to display in the combobox, can be grouped or a flat array */
-    options: Record<string, ComboBoxOptionItemProps[]> | 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.) */
+    /** Normalised options in render order. */
+    options: ComboBoxOption[];
+    /** ARIA props of the listbox element. */
+    listboxAriaProps: ListboxAriaProps;
+    /** 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;
-    /** Additional details to display below the options */
+    /** Additional details rendered as a sticky footer below the options. */
     optionDetails?: React.ReactNode;
+    /** Called with the value of the clicked option. */
+    onOptionClick: (value: string) => void;
 }
-/**
- * Props for the ComboBox component
- */
-export interface ComboBoxProps extends ComboBoxOptionsProps {
-    /** Additional CSS class name for the component */
+/** Props of the ComboBox component. */
+export interface ComboBoxProps {
+    /** Additional CSS class name for the trigger field. */
     className?: string;
-    /** Name attribute for the input field */
+    /** Name attribute for the input field. */
     name?: string;
-    /** Headline text displayed in mobile bottom sheet */
+    /** Headline text displayed in the mobile bottom sheet. */
     headline?: string;
-    /** Helper text displayed below the input */
+    /** Helper text displayed below the input field. */
     helperText?: string;
-    /** ID attribute for the input field */
-    id?: string;
-    /** Label text for the input field */
+    /** Label text for the input field. */
     label?: string;
-    /** Whether the dropdown/bottom sheet is currently open */
+    /** Options to display, either flat or grouped. */
+    options: ComboBoxOptionsInput;
+    /** Whether the popover / bottom sheet is currently open. */
     isOpen: boolean;
-    /** State setter function to control open/close state */
+    /** State setter that controls the open state. */
     setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
-    /** Callback fired when the search input value changes */
-    onChange?: (value: string) => void;
-    /** Callback fired when an option item is clicked */
+    /**
+     * Selected value: a string for single select, an array of strings when
+     * `multiple` is set.
+     */
+    value?: string | string[];
+    /** Allows selecting several options; combine with a checkbox `leadingType`. */
+    multiple?: boolean;
+    /** Called with the value of the selected (in multi select: toggled) option. */
     onOptionItemClick?: (value: string) => void;
-    /** Callback fired when user clicks outside the component */
+    /** Called when the search input value changes. */
+    onChange?: (value: string) => void;
+    /** Called when the user clicks outside of the component. */
     onOutsideClick?: () => void;
-    /** Callback fired when the input field is clicked */
+    /** Called when the trigger field is clicked. */
     onClick?: () => void;
-    /** Callback fired when the bottom sheet is closed */
+    /** Called when the bottom sheet has been closed. */
     onSheetClose?: () => void;
-    /** Placeholder text for the input field */
+    /** Placeholder text for the input field. */
     placeholder?: string;
-    /** Search pattern/regex for input validation */
+    /** Search pattern for input validation. */
     searchPattern?: string;
-    /** Current value of the combobox */
-    value?: string;
-    /** Text to display when no results are found */
+    /** Text to display when there is no option to show. */
     noResultsText?: string;
-    /** Input mode for mobile keyboards (text, numeric, etc.) */
+    /** Input mode for mobile keyboards. */
     inputMode?: InputModesType;
-    /** Whether to show the search input field */
+    /** Renders a search input inside the popover / bottom sheet. */
     withSearch?: boolean;
-    /** Whether the combobox is disabled */
+    /** Enter opens the closed list. Disable it inside forms with implicit submit. */
+    openOnEnter?: boolean;
+    /** Whether the combobox is disabled. */
     disabled?: boolean;
-    /** Show disabled style + horizontal shimmer animation while content is loading */
+    /** Disabled style plus shimmer animation while content is loading. */
     loading?: boolean;
-    /** Theme configuration for the component */
+    /** Type of the leading element of an option (icon, avatar, checkbox …). */
+    leadingType?: LeadingType;
+    /** Additional details rendered below the options. */
+    optionDetails?: React.ReactNode;
+    /** Theme configuration for the component. */
     theme?: ThemeType;
-    /** Custom slot that replaces the standard options/no-results block */
+    /** Custom slot that replaces the standard options / no-results block. */
     optionsSlot?: React.ReactNode;
-    /** Icon element displayed at the leading (left) side of the trigger input */
-    leadingIcon?: React.ReactNode;
-}
-/**
- * Props for individual ComboBox option items
- */
-export interface ComboBoxOptionItemProps extends MenuItemProps {
-    /** Unique key for the option item */
-    key?: string;
+    /** Icon element displayed at the leading side of the trigger input. */
+    leadingIcon?: React.ReactElement | null;
+    /**
+     * Formats the selected values for the trigger field.
+     * Defaults to the labels of the selected options joined by a comma.
+     */
+    renderValue?: (labels: string[]) => string;
 }

package/lib/utils/index.d.ts

@@ -1,2 +1 @@
-export * from './calculateListMaxHeight';
-export * from './scrollOptionToViewport';
+export * from './options';

package/lib/utils/index.js

@@ -1,3 +1,2 @@
-export * from './calculateListMaxHeight';
-export * from './scrollOptionToViewport';
+export * from './options';
 //# sourceMappingURL=index.js.map

package/lib/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA"}

package/lib/utils/options.d.ts

@@ -1,4 +1,41 @@
-import type { ComboBoxOption, ComboBoxOptionGroup, ComboBoxOptionsInput } from '../types';
+import type { MenuItemProps } from '@pixum/menu-item';
+import type { ComboBoxOption, ComboBoxOptionGroup, ComboBoxOptionItemProps, ComboBoxOptionsInput } from '../types';
+/**
+ * Resolves the stable value of an option.
+ *
+ * `MenuItemProps` does not guarantee a plain string `text`, so the value is
+ * resolved in three steps: the visible label first - that is the value existing
+ * consumers pass in as `value` and get back from `onOptionItemClick` -, then
+ * the explicit `key`, and finally the render index as a last resort so that
+ * options without a label still get a unique value.
+ *
+ * @param item - The option as handed in by the consumer
+ * @param index - Position of the option in render order
+ * @returns The stable value of the option
+ */
+export declare function resolveOptionValue(item: ComboBoxOptionItemProps, index: number): string;
+/**
+ * Returns the label of an option for the trigger field.
+ *
+ * Falls back to the resolved value when the option renders a custom node
+ * instead of a plain string.
+ *
+ * @param option - A normalised option
+ * @returns The label to display in the trigger field
+ */
+export declare function getOptionLabel(option: ComboBoxOption): string;
+/**
+ * Strips the ComboBox specific props from an option so the rest can be spread
+ * onto the `MenuItem`.
+ *
+ * `key` is a reserved React prop and `disabled` is handled by the option
+ * wrapper (`aria-disabled` plus the click guard); everything else belongs to
+ * `MenuItem` and is forwarded untouched.
+ *
+ * @param item - The option as handed in by the consumer
+ * @returns The props meant for the `MenuItem`
+ */
+export declare function toMenuItemProps({ key, disabled, ...menuItemProps }: ComboBoxOptionItemProps): MenuItemProps;
 /**
  * Normalises flat and grouped options into one list in render order.
  *