@pixum/combobox 5.10.5 → 5.10.7

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,216 @@
-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.
+     *
+     * Newly added. Consumer types that already carry a `disabled` field of a
+     * different type (e.g. `disabled: 'true' | 'false'`) are no longer
+     * assignable - widen it to `boolean` on the consumer side.
+     */
+    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;
+}
+/**
+ * Public options contract, kept for backwards compatibility.
+ *
+ * In the previous version this interface was the base of `ComboBoxProps` and
+ * the prop type of
+ * the exported options component. It describes the options as the *consumer*
+ * hands them in - not the normalised list the internal panel renders. The
+ * internal shape now lives in `ComboBoxOptionsPanelProps`.
+ *
+ * @deprecated Use `ComboBoxProps` (or `Pick<ComboBoxProps, 'options'>`)
+ * directly. Kept so existing imports do not silently change meaning; will be
+ * removed in the next major.
  */
 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 */
+    /** Options to display, either flat or grouped. */
+    options: ComboBoxOptionsInput;
+    /**
+     * Currently selected option value.
+     *
+     * @deprecated Use `value`. When both are set, `value` wins.
+     */
     selectedOption?: string;
-    /** Callback fired when an option is clicked */
+    /**
+     * Callback fired when an option is clicked.
+     *
+     * @deprecated Use `onOptionItemClick`. On `ComboBoxProps` this prop is
+     * narrowed to the trigger click handler `() => void`.
+     */
     onClick?: (value: string) => void;
-    /** Type of leading element to display (icon, avatar, etc.) */
+    /** Type of leading element to display (icon, avatar, checkbox …). */
+    leadingType?: LeadingType;
+    /** Additional details rendered below the options. */
+    optionDetails?: React.ReactNode;
+}
+/**
+ * Props of the rendered options panel - the internal, normalised shape.
+ *
+ * This is what `ComboBoxOptions` consumes. It is exported so custom panels can
+ * be typed against it, but it is not part of the consumer-facing API and may
+ * change without a major bump.
+ */
+export interface ComboBoxOptionsPanelProps {
+    /** 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
+ * Props of the ComboBox component.
+ *
+ * Extends the deprecated `ComboBoxOptionsProps` so that consumers who built
+ * their own prop types on top of it keep compiling.
  */
 export interface ComboBoxProps extends ComboBoxOptionsProps {
-    /** Additional CSS class name for the component */
+    /** 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 */
+    /**
+     * ID attribute for the input field.
+     *
+     * @deprecated The trigger generates its own ids for the ARIA wiring; `id` is
+     * forwarded to the underlying input untouched and no longer used internally.
+     */
+    id?: string;
+    /** 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.
+     *
+     * The array member is new in this version. Code that *reads* this prop back
+     * out of
+     * a props object has to narrow it (`Array.isArray(value)`).
+     */
+    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 */
+    /**
+     * Icon element displayed at the leading side of the trigger input.
+     *
+     * Deliberately `ReactNode`, not `ReactElement`: fragments, strings and
+     * conditional `false` have always been accepted here.
+     */
     leadingIcon?: React.ReactNode;
-}
-/**
- * Props for individual ComboBox option items
- */
-export interface ComboBoxOptionItemProps extends MenuItemProps {
-    /** Unique key for the option item */
-    key?: string;
+    /**
+     * 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"}