@pixum/combobox 5.10.3 → 5.10.4-alpha.18

package/lib/ComboBox.module.css

@@ -0,0 +1 @@
+.root{position:relative;width:100%}.root .headline[class*=text--]+*{margin-top:var(--spacing)}:is(.root,.sheet) :is(.panel,.optionsSlot,.header){position:relative;width:100%}:is(.root,.sheet) .panel{display:flex;flex-direction:column;max-height:inherit;overflow:hidden}:is(.root,.sheet) :is(.options,.optionsSlot){display:flex;flex:1 1 auto;flex-direction:column;min-height:0;overflow:auto;scroll-padding-block-start:var(--combobox-sticky-offset,2.75rem)}.sheet .header{align-items:flex-start;height:auto;margin:var(--spacing-5) auto var(--spacing-2);padding:0 var(--spacing-2)}:is(.root,.sheet) ul.optionsSlot{list-style:none;padding:0}.root .optionsSlot{margin-top:var(--spacing)}:is(.root,.sheet) .option{cursor:pointer;touch-action:manipulation;-webkit-tap-highlight-color:transparent;-webkit-user-select:none;user-select:none}:is(.root,.sheet) .optionCheckbox[data-selected=true] :global(.menu-item){background-color:initial}:is(.root,.sheet) .option.optionActive :global(.menu-item),:is(.root,.sheet) .optionCheckbox.optionActive :global(.menu-item){background-color:var(--color-canvas--hover)}:is(.root,.sheet) .option[data-selected=true]:not(.optionCheckbox) :global(.menu-item){background-color:var(--color-accent);color:var(--color-surface)}:is(.root,.sheet) .option[aria-disabled=true]{cursor:not-allowed;opacity:.5}@media (forced-colors:active){:is(.root,.sheet) .option.optionActive :global(.menu-item){outline:2px solid Highlight;outline-offset:-2px}}:is(.root,.sheet) .stickyHeader{background-color:var(--color-surface);border-bottom:1px solid var(--color-dim);padding:var(--spacing-1_25) var(--spacing-2);position:-webkit-sticky;position:sticky;top:0}:is(.root,.sheet) .options :global(.text--caption){color:var(--color-on-secondary)}:is(.root,.sheet) .option[data-selected=true]:not(.optionCheckbox) :global(.menu-item .text--caption){color:var(--color-surface)}:is(.root,.sheet) .options :global(.item-header){display:flex;justify-content:space-between}:is(.root,.sheet) .optionDetails{background-color:var(--color-surface);border-top:1px solid var(--color-dim);flex:0 0 auto;padding:var(--spacing-1_25) var(--spacing)}:is(.root,.sheet) .noResults{padding:var(--spacing-2) var(--spacing);text-align:center}@media screen and (min-width:960px){.root :is(.panel,.optionsSlot){border-radius:12px;margin-top:var(--spacing);max-height:330px;position:absolute}}

package/lib/hooks/useComboBox.d.ts

@@ -0,0 +1,60 @@
+import type { ComboBoxAriaProps, ComboBoxOption, ListboxAriaProps } from '../types';
+export interface UseComboBoxOptions {
+    /** Normalised options in render order. */
+    options: ComboBoxOption[];
+    /** Whether the list is currently open. */
+    isOpen: boolean;
+    /** Opens the list. */
+    open: () => void;
+    /**
+     * Closes the list. `restoreFocus` is `false` when the focus must stay where
+     * the user put it (Tab).
+     */
+    close: (restoreFocus?: boolean) => void;
+    /** Values that are currently selected. */
+    selectedValues: string[];
+    /** Called with the value of the option that was activated by the keyboard. */
+    onSelect: (value: string) => void;
+    /** Id of the listbox element. */
+    listboxId: string;
+    /** Whether the open list offers a freely typeable search field. */
+    searchable?: boolean;
+    /** Multi select keeps the list open after a selection. */
+    multiple?: boolean;
+    /** Enter opens the closed list (APG select-only). */
+    openOnEnter?: boolean;
+}
+export interface UseComboBoxResult {
+    /** ARIA props for the element that owns the `combobox` role. */
+    comboboxAriaProps: ComboBoxAriaProps;
+    /** ARIA props for the element that owns the `listbox` role. */
+    listboxAriaProps: ListboxAriaProps;
+    /** Keyboard handler for the combobox element. */
+    onKeyDown: React.KeyboardEventHandler<HTMLInputElement>;
+    /** DOM id of the active option, `undefined` while closed. */
+    activeOptionId: string | undefined;
+    /** Index of the active option, `null` while closed or empty. */
+    activeIndex: number | null;
+}
+/**
+ * Headless controller for the WAI-ARIA combobox pattern.
+ *
+ * The focus never moves into the list: the active option is communicated
+ * exclusively via `aria-activedescendant`, which keeps the search field
+ * typeable while the user navigates.
+ *
+ * Keyboard (APG combobox with listbox popup):
+ * - closed: ArrowUp/ArrowDown/Alt+ArrowDown, Enter, Space open the list
+ * - open: ArrowUp/ArrowDown navigate (skipping disabled options),
+ *   Home/End jump to the first/last option, Enter selects,
+ *   Escape and Alt+ArrowUp close, Tab closes and lets the focus move on
+ * - Space selects while the field is not typeable; as soon as a search field
+ *   is open it types a space character instead, as APG requires
+ *
+ * On open the starting point is always the selected option, so ArrowDown moves
+ * to the option right after it.
+ *
+ * @param options - Configuration of the combobox
+ * @returns ARIA props, the keyboard handler and the active option
+ */
+export declare function useComboBox({ options, isOpen, open, close, selectedValues, onSelect, listboxId, searchable, multiple, openOnEnter, }: UseComboBoxOptions): UseComboBoxResult;

package/lib/hooks/useComboBox.js

@@ -0,0 +1,225 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { findEnabledIndex } from '../utils';
+/**
+ * Headless controller for the WAI-ARIA combobox pattern.
+ *
+ * The focus never moves into the list: the active option is communicated
+ * exclusively via `aria-activedescendant`, which keeps the search field
+ * typeable while the user navigates.
+ *
+ * Keyboard (APG combobox with listbox popup):
+ * - closed: ArrowUp/ArrowDown/Alt+ArrowDown, Enter, Space open the list
+ * - open: ArrowUp/ArrowDown navigate (skipping disabled options),
+ *   Home/End jump to the first/last option, Enter selects,
+ *   Escape and Alt+ArrowUp close, Tab closes and lets the focus move on
+ * - Space selects while the field is not typeable; as soon as a search field
+ *   is open it types a space character instead, as APG requires
+ *
+ * On open the starting point is always the selected option, so ArrowDown moves
+ * to the option right after it.
+ *
+ * @param options - Configuration of the combobox
+ * @returns ARIA props, the keyboard handler and the active option
+ */
+export function useComboBox({ options, isOpen, open, close, selectedValues, onSelect, listboxId, searchable = true, multiple = false, openOnEnter = true, }) {
+    var _a;
+    const [activeIndex, setActiveIndex] = useState(null);
+    /**
+     * Read inside effects only. Keeping the selection in a ref avoids re-running
+     * the "open" effect when a consumer passes a new array instance per render.
+     */
+    const selectedValuesRef = useRef(selectedValues);
+    selectedValuesRef.current = selectedValues;
+    /** Tracks the closed -> open edge so navigation is not reset while open. */
+    const wasOpen = useRef(false);
+    /**
+     * Active option requested while the list was still closed (Home/End). The
+     * open effect consumes it instead of falling back to the selected option.
+     */
+    const pendingActiveIndex = useRef(null);
+    /** Typing is only possible while an open search field is rendered. */
+    const canType = isOpen && searchable;
+    /**
+     * Sets the starting point when the list opens: the selected option, or the
+     * first enabled one as a fallback.
+     */
+    useEffect(() => {
+        if (!isOpen) {
+            wasOpen.current = false;
+            setActiveIndex(null);
+            return;
+        }
+        if (wasOpen.current)
+            return;
+        wasOpen.current = true;
+        const pending = pendingActiveIndex.current;
+        pendingActiveIndex.current = null;
+        if (pending !== null) {
+            setActiveIndex(pending);
+            return;
+        }
+        const selectedIndex = options.findIndex(option => !option.disabled && selectedValuesRef.current.includes(option.value));
+        setActiveIndex(selectedIndex !== -1 ? selectedIndex : findEnabledIndex(options, -1, 1));
+    }, [isOpen, options]);
+    /**
+     * Keeps the active index valid while the list is filtered down.
+     */
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        setActiveIndex(previous => {
+            const isStillValid = previous !== null &&
+                previous < options.length &&
+                !options[previous].disabled;
+            if (isStillValid)
+                return previous;
+            return findEnabledIndex(options, -1, 1);
+        });
+    }, [isOpen, options]);
+    /**
+     * Moves the active option by `delta` positions, wrapping around and skipping
+     * disabled options.
+     *
+     * @param delta - Number of positions to move; negative moves backwards
+     */
+    const move = useCallback((delta) => setActiveIndex(previous => findEnabledIndex(options, previous !== null && previous !== void 0 ? previous : (delta > 0 ? -1 : 0), delta)), [options]);
+    /**
+     * Selects the active option. In single select the list closes afterwards,
+     * in multi select it stays open so further options can be toggled.
+     */
+    const selectActiveOption = useCallback(() => {
+        if (activeIndex === null)
+            return;
+        const option = options[activeIndex];
+        if (!option || option.disabled)
+            return;
+        onSelect(option.value);
+    }, [activeIndex, options, onSelect]);
+    const onKeyDown = useCallback(event => {
+        switch (event.key) {
+            case 'ArrowDown':
+            case 'ArrowUp': {
+                event.preventDefault();
+                if (!isOpen) {
+                    open();
+                    break;
+                }
+                // Alt+ArrowUp closes and keeps the current selection.
+                if (event.key === 'ArrowUp' && event.altKey) {
+                    close();
+                    break;
+                }
+                // Alt+ArrowDown only opens, it never moves the active option.
+                if (event.altKey)
+                    break;
+                move(event.key === 'ArrowDown' ? 1 : -1);
+                break;
+            }
+            case 'Enter': {
+                if (!isOpen) {
+                    if (!openOnEnter)
+                        break;
+                    // preventDefault stops an implicit form submit.
+                    event.preventDefault();
+                    open();
+                    break;
+                }
+                if (activeIndex === null)
+                    break;
+                event.preventDefault();
+                selectActiveOption();
+                break;
+            }
+            case ' ': {
+                // An open search field must receive a real space character.
+                if (canType)
+                    break;
+                event.preventDefault();
+                if (isOpen && activeIndex !== null) {
+                    selectActiveOption();
+                    break;
+                }
+                open();
+                break;
+            }
+            case 'Escape': {
+                if (!isOpen)
+                    break;
+                event.preventDefault();
+                close();
+                break;
+            }
+            case 'Tab': {
+                // No preventDefault: the focus moves on, the popup just closes.
+                if (isOpen)
+                    close(false);
+                break;
+            }
+            case 'Home':
+            case 'End': {
+                if (options.length === 0)
+                    break;
+                event.preventDefault();
+                const targetIndex = event.key === 'Home'
+                    ? findEnabledIndex(options, -1, 1)
+                    : findEnabledIndex(options, options.length, -1);
+                // Closed: open first, the effect picks the index up from the ref.
+                if (!isOpen) {
+                    pendingActiveIndex.current = targetIndex;
+                    open();
+                    break;
+                }
+                setActiveIndex(targetIndex);
+                break;
+            }
+            default:
+                break;
+        }
+    }, [
+        isOpen,
+        open,
+        close,
+        move,
+        activeIndex,
+        selectActiveOption,
+        canType,
+        openOnEnter,
+        options,
+    ]);
+    const activeOptionId = isOpen && activeIndex !== null ? (_a = options[activeIndex]) === null || _a === void 0 ? void 0 : _a.id : undefined;
+    /**
+     * Scrolls the active option into view. Purely DOM based, so it works for the
+     * desktop popover and the bottom sheet alike.
+     */
+    useEffect(() => {
+        if (!activeOptionId)
+            return;
+        const frameId = requestAnimationFrame(() => {
+            var _a;
+            (_a = document
+                .getElementById(activeOptionId)) === null || _a === void 0 ? void 0 : _a.scrollIntoView({ block: 'nearest' });
+        });
+        return () => cancelAnimationFrame(frameId);
+    }, [activeOptionId]);
+    const comboboxAriaProps = useMemo(() => ({
+        role: 'combobox',
+        'aria-expanded': isOpen,
+        'aria-haspopup': 'listbox',
+        'aria-controls': isOpen ? listboxId : undefined,
+        'aria-activedescendant': activeOptionId,
+        'aria-autocomplete': searchable ? 'list' : 'none',
+    }), [isOpen, listboxId, activeOptionId, searchable]);
+    const listboxAriaProps = useMemo(() => ({
+        role: 'listbox',
+        id: listboxId,
+        'aria-multiselectable': multiple || undefined,
+    }), [listboxId, multiple]);
+    return {
+        comboboxAriaProps,
+        listboxAriaProps,
+        onKeyDown,
+        activeOptionId,
+        activeIndex,
+    };
+}
+//# sourceMappingURL=useComboBox.js.map

package/lib/hooks/useComboBox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useComboBox.js","sourceRoot":"","sources":["../../src/hooks/useComboBox.ts"],"names":[],"mappings":"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"}

package/lib/hooks/useComboBoxFocus.d.ts

@@ -0,0 +1,35 @@
+export interface UseComboBoxFocusResult {
+    /**
+     * Ref for the trigger field (SelectInput).
+     *
+     * `| null` is part of the type parameter: since React 19 `useRef<T>(null)`
+     * returns `RefObject<T | null>` instead of the old `RefObject<T>`.
+     */
+    triggerRef: React.RefObject<HTMLInputElement | null>;
+    /**
+     * Callback ref for the search field. Focuses it the moment it is mounted -
+     * in the desktop popover as well as in the bottom sheet.
+     */
+    searchInputRef: (input: HTMLInputElement | null) => void;
+    /** Moves the focus back to the trigger without re-opening the list. */
+    returnFocusToTrigger: () => void;
+    /**
+     * Whether the current focus event on the trigger was caused by
+     * `returnFocusToTrigger` and must therefore not open the list.
+     */
+    isReturningFocus: () => boolean;
+}
+/**
+ * Bundles the focus choreography of the ComboBox:
+ *
+ * - opening moves the focus into the search field as soon as it mounts,
+ * - closing moves it back to the trigger,
+ * - the focus handler of the trigger can tell a returning focus from a real
+ *   user focus and therefore does not re-open the list it just closed.
+ *
+ * The search field is wired up with a callback ref, so both the popover and the
+ * bottom sheet share one implementation and no polling is needed.
+ *
+ * @returns Refs and helpers for the focus handling
+ */
+export declare function useComboBoxFocus(): UseComboBoxFocusResult;

package/lib/hooks/useComboBoxFocus.js

@@ -0,0 +1,48 @@
+import { useCallback, useEffect, useRef } from 'react';
+/**
+ * Bundles the focus choreography of the ComboBox:
+ *
+ * - opening moves the focus into the search field as soon as it mounts,
+ * - closing moves it back to the trigger,
+ * - the focus handler of the trigger can tell a returning focus from a real
+ *   user focus and therefore does not re-open the list it just closed.
+ *
+ * The search field is wired up with a callback ref, so both the popover and the
+ * bottom sheet share one implementation and no polling is needed.
+ *
+ * @returns Refs and helpers for the focus handling
+ */
+export function useComboBoxFocus() {
+    const triggerRef = useRef(null);
+    const returningFocus = useRef(false);
+    const frameRef = useRef(null);
+    useEffect(() => () => {
+        if (frameRef.current !== null)
+            cancelAnimationFrame(frameRef.current);
+    }, []);
+    const searchInputRef = useCallback((input) => {
+        if (!input)
+            return;
+        input.focus();
+        // One frame later, so Safari does not drop the selection again when
+        // `readOnly` changes within the same render.
+        requestAnimationFrame(() => {
+            var _a;
+            (_a = input.setSelectionRange) === null || _a === void 0 ? void 0 : _a.call(input, 0, input.value.length);
+        });
+    }, []);
+    const returnFocusToTrigger = useCallback(() => {
+        returningFocus.current = true;
+        // Wait for the commit that unmounts the popover / bottom sheet, otherwise
+        // the focus would end up on `<body>`.
+        frameRef.current = requestAnimationFrame(() => {
+            var _a;
+            (_a = triggerRef.current) === null || _a === void 0 ? void 0 : _a.focus();
+            // `focus()` dispatches synchronously, so the flag has served its purpose.
+            returningFocus.current = false;
+        });
+    }, []);
+    const isReturningFocus = useCallback(() => returningFocus.current, []);
+    return { triggerRef, searchInputRef, returnFocusToTrigger, isReturningFocus };
+}
+//# sourceMappingURL=useComboBoxFocus.js.map

package/lib/hooks/useComboBoxFocus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useComboBoxFocus.js","sourceRoot":"","sources":["../../src/hooks/useComboBoxFocus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAA;AAwBtD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,UAAU,GAAG,MAAM,CAAmB,IAAI,CAAC,CAAA;IACjD,MAAM,cAAc,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IACpC,MAAM,QAAQ,GAAG,MAAM,CAAgB,IAAI,CAAC,CAAA;IAE5C,SAAS,CACP,GAAG,EAAE,CAAC,GAAG,EAAE;QACT,IAAI,QAAQ,CAAC,OAAO,KAAK,IAAI;YAAE,oBAAoB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;IACvE,CAAC,EACD,EAAE,CACH,CAAA;IAED,MAAM,cAAc,GAAG,WAAW,CAAC,CAAC,KAA8B,EAAE,EAAE;QACpE,IAAI,CAAC,KAAK;YAAE,OAAM;QAElB,KAAK,CAAC,KAAK,EAAE,CAAA;QAEb,oEAAoE;QACpE,6CAA6C;QAC7C,qBAAqB,CAAC,GAAG,EAAE;;YACzB,MAAA,KAAK,CAAC,iBAAiB,sDAAG,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QAClD,CAAC,CAAC,CAAA;IACJ,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,MAAM,oBAAoB,GAAG,WAAW,CAAC,GAAG,EAAE;QAC5C,cAAc,CAAC,OAAO,GAAG,IAAI,CAAA;QAE7B,0EAA0E;QAC1E,sCAAsC;QACtC,QAAQ,CAAC,OAAO,GAAG,qBAAqB,CAAC,GAAG,EAAE;;YAC5C,MAAA,UAAU,CAAC,OAAO,0CAAE,KAAK,EAAE,CAAA;YAC3B,0EAA0E;YAC1E,cAAc,CAAC,OAAO,GAAG,KAAK,CAAA;QAChC,CAAC,CAAC,CAAA;IACJ,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,MAAM,gBAAgB,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;IAEtE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,CAAA;AAC/E,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/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/utils/options.d.ts

@@ -0,0 +1,40 @@
+import type { ComboBoxOption, ComboBoxOptionGroup, ComboBoxOptionsInput } from '../types';
+/**
+ * Normalises flat and grouped options into one list in render order.
+ *
+ * The index of an entry is identical for both input shapes and is therefore
+ * used as the option DOM id that `aria-activedescendant` points at. Doing this
+ * once removes the offset arithmetic that grouped rendering used to need.
+ *
+ * @param options - Flat or grouped options as passed in by the consumer
+ * @param listboxId - Id of the listbox, used as prefix for the option ids
+ * @returns The normalised options in render order
+ */
+export declare function normaliseOptions(options: ComboBoxOptionsInput, listboxId: string): ComboBoxOption[];
+/**
+ * Splits normalised options back into their render groups while keeping the
+ * global indices intact, so that the list can be rendered with a single code
+ * path for flat and grouped options.
+ *
+ * @param options - Normalised options in render order
+ * @returns One entry per consecutive group
+ */
+export declare function groupOptions(options: ComboBoxOption[]): ComboBoxOptionGroup[];
+/**
+ * Normalises the `value` prop to an array, so that single and multi select
+ * share the same selection logic.
+ *
+ * @param value - Selected value(s) or `undefined`
+ * @returns The selected values as an array
+ */
+export declare function toValueArray(value: string | string[] | undefined): string[];
+/**
+ * Finds the first option that can be activated, starting at `start` and moving
+ * by `delta` with wrap-around. Disabled options are skipped.
+ *
+ * @param options - Normalised options
+ * @param start - Index to start from; use `-1` to start before the first option
+ * @param delta - Step width, negative values move backwards
+ * @returns The index of the next enabled option, or `null` when there is none
+ */
+export declare function findEnabledIndex(options: ComboBoxOption[], start: number, delta: number): number | null;

package/lib/utils/options.js

@@ -0,0 +1,85 @@
+/**
+ * Normalises flat and grouped options into one list in render order.
+ *
+ * The index of an entry is identical for both input shapes and is therefore
+ * used as the option DOM id that `aria-activedescendant` points at. Doing this
+ * once removes the offset arithmetic that grouped rendering used to need.
+ *
+ * @param options - Flat or grouped options as passed in by the consumer
+ * @param listboxId - Id of the listbox, used as prefix for the option ids
+ * @returns The normalised options in render order
+ */
+export function normaliseOptions(options, listboxId) {
+    const groups = Array.isArray(options)
+        ? [['', options]]
+        : Object.entries(options);
+    const normalised = [];
+    groups.forEach(([group, items]) => {
+        items.forEach(item => {
+            var _a;
+            const index = normalised.length;
+            normalised.push({
+                item,
+                group: group || undefined,
+                value: (_a = item.value) !== null && _a !== void 0 ? _a : item.text,
+                index,
+                id: `${listboxId}-option-${index}`,
+                disabled: item.disabled === true,
+            });
+        });
+    });
+    return normalised;
+}
+/**
+ * Splits normalised options back into their render groups while keeping the
+ * global indices intact, so that the list can be rendered with a single code
+ * path for flat and grouped options.
+ *
+ * @param options - Normalised options in render order
+ * @returns One entry per consecutive group
+ */
+export function groupOptions(options) {
+    return options.reduce((groups, option) => {
+        const current = groups[groups.length - 1];
+        if (current && current.group === option.group) {
+            current.options.push(option);
+            return groups;
+        }
+        groups.push({ group: option.group, options: [option] });
+        return groups;
+    }, []);
+}
+/**
+ * Normalises the `value` prop to an array, so that single and multi select
+ * share the same selection logic.
+ *
+ * @param value - Selected value(s) or `undefined`
+ * @returns The selected values as an array
+ */
+export function toValueArray(value) {
+    if (Array.isArray(value))
+        return value;
+    return value ? [value] : [];
+}
+/**
+ * Finds the first option that can be activated, starting at `start` and moving
+ * by `delta` with wrap-around. Disabled options are skipped.
+ *
+ * @param options - Normalised options
+ * @param start - Index to start from; use `-1` to start before the first option
+ * @param delta - Step width, negative values move backwards
+ * @returns The index of the next enabled option, or `null` when there is none
+ */
+export function findEnabledIndex(options, start, delta) {
+    const { length } = options;
+    if (length === 0)
+        return null;
+    let index = start;
+    for (let step = 0; step < length; step += 1) {
+        index = (index + delta + length) % length;
+        if (!options[index].disabled)
+            return index;
+    }
+    return null;
+}
+//# sourceMappingURL=options.js.map

package/lib/utils/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/utils/options.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAA6B,EAC7B,SAAiB;IAEjB,MAAM,MAAM,GAA0C,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAC1E,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACjB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAE3B,MAAM,UAAU,GAAqB,EAAE,CAAA;IAEvC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE;QAChC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE;;YACnB,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAA;YAE/B,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI;gBACJ,KAAK,EAAE,KAAK,IAAI,SAAS;gBACzB,KAAK,EAAE,MAAA,IAAI,CAAC,KAAK,mCAAI,IAAI,CAAC,IAAI;gBAC9B,KAAK;gBACL,EAAE,EAAE,GAAG,SAAS,WAAW,KAAK,EAAE;gBAClC,QAAQ,EAAE,IAAI,CAAC,QAAQ,KAAK,IAAI;aACjC,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,OAAO,UAAU,CAAA;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,OAAyB;IACpD,OAAO,OAAO,CAAC,MAAM,CAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE;QAC9D,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QAEzC,IAAI,OAAO,IAAI,OAAO,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;YAC9C,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YAE5B,OAAO,MAAM,CAAA;QACf,CAAC;QAED,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QAEvD,OAAO,MAAM,CAAA;IACf,CAAC,EAAE,EAAE,CAAC,CAAA;AACR,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,KAAoC;IAC/D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAEtC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AAC7B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAyB,EACzB,KAAa,EACb,KAAa;IAEb,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IAC1B,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAE7B,IAAI,KAAK,GAAG,KAAK,CAAA;IAEjB,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QAC5C,KAAK,GAAG,CAAC,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC,GAAG,MAAM,CAAA;QAEzC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAA;IAC5C,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixum/combobox",
-  "version": "5.10.3",
+  "version": "5.10.4-alpha.18+d1e52db7f",
   "main": "lib/index.js",
   "module": "lib/index.js",
   "license": "UNLICENSED",
@@ -8,7 +8,7 @@
     "@pixum/bottom-sheet": "3.0.18",
     "@pixum/menu": "3.0.14",
     "@pixum/menu-item": "2.0.14",
-    "@pixum/text": "2.0.20",
+    "@pixum/text": ">=3.7.0",
     "@pixum/theme-provider": "4.2.20",
     "@pixum/web-input": "2.1.0"
   },
@@ -18,5 +18,5 @@
   "sideEffects": [
     "*.css"
   ],
-  "gitHead": "848db84bc61d3cf9135572f504aafc6326f9bdf2"
+  "gitHead": "d1e52db7fc60033d1e40fedde10ee6e52216e657"
 }