@pine-ds/core 4.2.0 → 4.4.0

package/dist/collection/components/pds-combobox/pds-combobox.js

@@ -1,8 +1,9 @@
 import { h, Host } from "@stencil/core";
 import { assignDescription, isSpecTest, messageId } from "../../utils/form";
 import { autoUpdate, computePosition, flip, offset, shift } from "@floating-ui/dom";
-import { debounceEvent } from "../../utils/utils";
+import { cancelDebouncedEvent, debounceEvent, flushDebouncedEvent } from "../../utils/utils";
 import DOMPurify from "dompurify";
+import { FlyoutController, buildPanelEntries, findGroup, groupIconOf, groupLabelOf, isGroupDisabled, isOptionDisabled, panelColumn, parentOptgroupOf, } from "./grouped-options-panel";
 /**
  * @slot option - Option elements for the combobox dropdown
  * @slot trigger-content - Custom content for the button trigger when customTriggerContent is true
@@ -50,6 +51,35 @@ export class PdsCombobox {
          * @default 'host'
          */
         this.dropdownMount = 'host';
+        /**
+         * Accessible prefix for the row that returns to the group list when `group-display` is
+         * `drill-in`, read before the open group's label. Pass a translated string to localize it; defaults to English.
+         * @defaultValue 'Back'
+         */
+        this.drillInBackLabel = 'Back';
+        /**
+         * Maximum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value.
+         * @default '380px'
+         */
+        this.flyoutMaxWidth = '380px';
+        /**
+         * Minimum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value.
+         * The flyout is as wide as its options, between this and `flyout-max-width`.
+         * @default '280px'
+         */
+        this.flyoutMinWidth = '280px';
+        /**
+         * How option groups (`<optgroup>`, or the `group` field of `options`) are shown in the dropdown.
+         * `inline` lists each group's label above its options. `flyout` lists the groups, and opens a
+         * group's options in a panel beside it on hover or click; while searching, the matching options
+         * are listed under their group labels, and search also matches group labels. `flyout` groups
+         * by `<optgroup>` (or `group`) only: options under a `<pds-text>` heading are listed ungrouped.
+         * `drill-in` lists the groups too, but a click replaces the list with that group's options and a
+         * row back to the groups; use it where nothing can open beside the dropdown, such as a side
+         * panel. `flyout` falls back to `drill-in` when there is no room for a flyout on either side.
+         * @default 'inline'
+         */
+        this.groupDisplay = 'inline';
         /**
          * Visually hides the label text for instances where only the combobox should be displayed.
          * The visible `<label>` is omitted (same pattern as `pds-select`) so label spacing does not reserve layout;
@@ -63,6 +93,23 @@ export class PdsCombobox {
          * @default 'filter'
          */
         this.mode = 'filter';
+        /**
+         * Shows a search field at the top of the dropdown for the `button` and `chip` triggers, which
+         * can't be typed into. Search filters the options the same way typing in the `input` trigger
+         * does; in a grouped display it also matches group labels.
+         * @default false
+         */
+        this.panelSearch = false;
+        /**
+         * Accessible label for the search input inside the dropdown panel (`panel-search`). Pass a translated string to localize it; defaults to English.
+         * @defaultValue 'Search options'
+         */
+        this.searchOptionsLabel = 'Search options';
+        /**
+         * Placeholder text for the search input inside the dropdown panel (`panel-search`). Pass a translated string to localize it; defaults to English.
+         * @defaultValue 'Find...'
+         */
+        this.searchPlaceholder = 'Find...';
         /**
          * Determines the combobox trigger: 'input' (editable input), 'button' (button-like, non-editable), or 'chip' (chip-like, non-editable).
          * @default 'input'
@@ -135,6 +182,30 @@ export class PdsCombobox {
          * Internal state for dropdown open/close
          */
         this.isOpen = false;
+        /**
+         * The optgroup whose flyout is open, when `groupDisplay` is `flyout`.
+         */
+        this.openGroup = null;
+        /**
+         * Which way drill-in just moved, so the list slides that way: `in` to a group, `out` back to the
+         * groups. Cleared once the slide ends, so later renders don't animate.
+         */
+        this.drillDirection = null;
+        /**
+         * The group row highlighted in the grouped panel. It counts only while no option is
+         * highlighted (`highlightedIndex` is -1); see `highlightedGroupRow`.
+         */
+        this.highlightedGroup = null;
+        /** The keys, not the pointer, moved the highlight last; the focus ring shows only then. */
+        this.keyboardNavigating = false;
+        /**
+         * What's typed in the dropdown's own search field (`panelSearch`).
+         */
+        this.panelQuery = '';
+        /**
+         * `groupDisplay` is `flyout` but there's no room beside the dropdown, so groups drill in instead.
+         */
+        this.flyoutFallback = false;
         /**
          * Internal state for the currently selected option
          */
@@ -164,12 +235,39 @@ export class PdsCombobox {
         this.portalEl = null;
         this.bodyPortalAutoUpdateActive = false;
         this.isUpdatingFromSelection = false;
+        this.flyout = new FlyoutController(() => this.openGroup, group => {
+            this.openGroup = group;
+        });
+        /** The groups in the flyout panel's last render, so a row's index finds its optgroup. */
+        this.renderedGroups = [];
+        /** Room for a flyout was checked for this open. */
+        this.flyoutRoomChecked = false;
+        /** The highlighted option sits in a flyout that hasn't rendered yet; focus it after the next render. */
+        this.pendingOptionFocus = false;
+        /** Group rows' DOM ids, stable across renders so `aria-activedescendant` can point at a row. */
+        this.groupIds = new WeakMap();
+        this.groupIdCount = 0;
         /**
          * In filter mode, after choosing an option the input still shows the label and would
          * otherwise filter the list to matching substrings only. While this flag is true,
          * the list shows every option until the user types (then normal filtering applies).
          */
         this.expandFilterListWhileOpen = false;
+        this.onDrillAnimationEnd = (event) => {
+            var _a;
+            // Only the slide's own end: slotted consumer content can animate inside the list too.
+            if ((_a = event.animationName) === null || _a === void 0 ? void 0 : _a.startsWith('pds-combobox-drill'))
+                this.drillDirection = null;
+        };
+        /** `<label for>` only works on the input trigger; for a div trigger a click on the label focuses it. */
+        this.onLabelClick = () => {
+            var _a;
+            if (this.trigger !== 'input' && !this.disabled) {
+                (_a = this.triggerEl) === null || _a === void 0 ? void 0 : _a.focus();
+            }
+        };
+        /** The query behind the options loaded from `async-url`. */
+        this.lastFetchedQuery = '';
         this.handleInput = (e) => {
             const target = e.target;
             this.clearExpandFilterList();
@@ -206,6 +304,7 @@ export class PdsCombobox {
         this.handleKeyDown = (e) => {
             if (!this.isOpen && (e.key === 'ArrowDown' || e.key === 'ArrowUp' || (e.altKey && e.key === 'ArrowDown'))) {
                 e.preventDefault();
+                this.keyboardNavigating = true;
                 this.isOpen = true;
                 this.prepareExpandFilterListOnOpen();
                 this.filterOptions();
@@ -227,75 +326,53 @@ export class PdsCombobox {
             if (!this.isOpen) {
                 return;
             }
+            if (this.handleGroupedPanelKey(e))
+                return;
+            // The input trigger's text keeps Space, Home and End while the grouped panel shows.
+            if (this.showsGroupedPanel && this.trigger === 'input' && (e.key === ' ' || e.key === 'Home' || e.key === 'End'))
+                return;
             // Get only the option elements (skip group labels) for navigation
             const selectableOptions = this.filteredItems.filter(item => item.tagName === 'OPTION');
             switch (e.key) {
                 case 'ArrowDown':
                     e.preventDefault();
-                    // If no option is highlighted and we have options, start at 0
-                    if (this.highlightedIndex < 0 && selectableOptions.length > 0) {
-                        this.highlightedIndex = 0;
-                    }
-                    else {
-                        this.highlightedIndex = Math.min(this.highlightedIndex + 1, selectableOptions.length - 1);
-                    }
-                    this.updateOptionFocus();
+                    // If no option is highlighted, start at the first
+                    this.highlightOptionAt(selectableOptions, this.highlightedIndex < 0 ? 0 : this.highlightedIndex + 1);
                     break;
                 case 'ArrowUp':
                     e.preventDefault();
-                    // If no option is highlighted and we have options, start at last option
-                    if (this.highlightedIndex < 0 && selectableOptions.length > 0) {
-                        this.highlightedIndex = selectableOptions.length - 1;
-                    }
-                    else {
-                        this.highlightedIndex = Math.max(this.highlightedIndex - 1, 0);
-                    }
-                    this.updateOptionFocus();
+                    // If no option is highlighted, start at the last
+                    this.highlightOptionAt(selectableOptions, this.highlightedIndex < 0 ? selectableOptions.length - 1 : this.highlightedIndex - 1);
                     break;
                 case 'Home':
                     e.preventDefault();
-                    if (selectableOptions.length > 0) {
-                        this.highlightedIndex = 0;
-                        this.updateOptionFocus();
-                    }
+                    this.highlightOptionAt(selectableOptions, 0);
                     break;
                 case 'End':
                     e.preventDefault();
-                    if (selectableOptions.length > 0) {
-                        this.highlightedIndex = selectableOptions.length - 1;
-                        this.updateOptionFocus();
-                    }
+                    this.highlightOptionAt(selectableOptions, selectableOptions.length - 1);
                     break;
                 case 'PageDown':
                     e.preventDefault();
-                    if (selectableOptions.length > 0) {
-                        const nextIndex = Math.min(this.highlightedIndex + 10, selectableOptions.length - 1);
-                        this.highlightedIndex = nextIndex;
-                        this.updateOptionFocus();
-                    }
+                    this.highlightOptionAt(selectableOptions, this.highlightedIndex + 10);
                     break;
                 case 'PageUp':
                     e.preventDefault();
-                    if (selectableOptions.length > 0) {
-                        const prevIndex = Math.max(this.highlightedIndex - 10, 0);
-                        this.highlightedIndex = prevIndex;
-                        this.updateOptionFocus();
-                    }
+                    this.highlightOptionAt(selectableOptions, this.highlightedIndex - 10);
                     break;
                 case 'Enter':
+                case ' ': {
                     e.preventDefault();
-                    if (this.highlightedIndex >= 0 && this.highlightedIndex < selectableOptions.length) {
-                        this.handleOptionClick(selectableOptions[this.highlightedIndex]);
-                        this.restoreFocusToTrigger();
-                    }
-                    break;
-                case ' ':
-                    e.preventDefault();
-                    if (this.highlightedIndex >= 0 && this.highlightedIndex < selectableOptions.length) {
-                        this.handleOptionClick(selectableOptions[this.highlightedIndex]);
+                    // An option in a flyout the pointer has since closed isn't on screen; don't choose it.
+                    if (this.showsGroupedPanel && this.activeDescendantId === undefined)
+                        break;
+                    const option = selectableOptions[this.highlightedIndex];
+                    if (option !== undefined && !isOptionDisabled(option)) {
+                        this.handleOptionClick(option);
                         this.restoreFocusToTrigger();
                     }
                     break;
+                }
                 case 'Escape':
                     e.preventDefault();
                     this.isOpen = false;
@@ -320,12 +397,53 @@ export class PdsCombobox {
             const idx = Number(event.currentTarget.getAttribute('data-option-index'));
             const selectableOptions = this.filteredItems.filter(item => item.tagName === 'OPTION');
             const option = selectableOptions[idx];
+            if (isOptionDisabled(option))
+                return;
             this.handleOptionClick(option);
+            // The search field closes with the panel; send focus back to the trigger instead of losing it.
+            // (Enter and Space already restore focus in the key handler.)
+            if (this.usesPanelSearch)
+                this.restoreFocusToTrigger();
         };
         // Event handler for mouse enter on option
         this.onOptionMouseEnter = (event) => {
             const idx = Number(event.currentTarget.getAttribute('data-option-index'));
             this.highlightedIndex = idx;
+            this.keyboardNavigating = false;
+        };
+        this.onGroupRowMouseEnter = (event) => {
+            const group = this.groupFromEvent(event);
+            if (group !== null)
+                this.flyout.enter(group);
+        };
+        this.onGroupRowMouseLeave = (event) => {
+            const group = this.groupFromEvent(event);
+            if (group !== null)
+                this.flyout.leave(group);
+        };
+        // The pointer highlights a group's row as it does an option, so the keys carry on from there.
+        this.onGroupRowTriggerMouseEnter = (event) => {
+            const group = this.groupFromEvent(event);
+            if (group !== null)
+                this.highlightGroupRowByPointer(group);
+        };
+        this.onGroupBackMouseEnter = () => {
+            if (this.openGroup !== null)
+                this.highlightGroupRowByPointer(this.openGroup);
+        };
+        this.onGroupRowClick = (event) => {
+            var _a;
+            const group = this.groupFromEvent(event);
+            if (group === null)
+                return;
+            this.flyout.open(group);
+            // Highlight the group's first option, so the arrow keys carry on from the group just opened
+            // rather than from wherever the highlight was before.
+            const first = (_a = this.renderedGroups.find(entry => entry.optgroup === group)) === null || _a === void 0 ? void 0 : _a.options[0];
+            if (first !== undefined) {
+                this.highlightedIndex = first.index;
+                this.updateAriaActiveDescendant();
+            }
         };
         // Prevent blur on mousedown
         this.onOptionMouseDown = (event) => {
@@ -342,10 +460,7 @@ export class PdsCombobox {
             if (this.isOpen) {
                 this.prepareExpandFilterListOnOpen();
                 this.filterOptions();
-                // Trigger initial fetch if async and no options loaded yet
-                if (this.asyncUrl && this.internalOptions.length === 0) {
-                    this.debouncedFetchAsyncOptions(this.displayText, 1);
-                }
+                this.fetchAsyncOptionsOnOpen();
                 // Set highlighted index and prepare for keyboard navigation
                 this.setInitialHighlightedIndex();
                 // For button trigger, prepare for arrow-key navigation mode
@@ -360,12 +475,17 @@ export class PdsCombobox {
         };
         // Handler for button trigger keyboard events
         this.onButtonTriggerKeyDown = (e) => {
+            // Escape closes an open group before the dropdown. Other keys reach the tree through handleKeyDown.
+            if (this.isOpen && e.key === 'Escape' && this.handleGroupedPanelKey(e))
+                return;
             if ((e.key === 'Enter' || e.key === ' ' || e.key === 'ArrowDown' || e.key === 'ArrowUp') && !this.isOpen) {
                 e.preventDefault();
                 e.stopPropagation(); // Prevent the event from bubbling and triggering click
+                this.keyboardNavigating = true;
                 this.isOpen = true;
                 this.prepareExpandFilterListOnOpen();
                 this.filterOptions();
+                this.fetchAsyncOptionsOnOpen();
                 // Set highlighted index immediately
                 this.setInitialHighlightedIndex();
                 setTimeout(() => {
@@ -398,11 +518,13 @@ export class PdsCombobox {
         };
         // Close dropdown when focus leaves the combobox
         this.onComboboxFocusOut = (event) => {
-            var _a, _b;
+            var _a, _b, _c;
             const relatedTarget = event.relatedTarget;
             const isRelatedTargetInListbox = relatedTarget &&
                 (((_a = this.listboxEl) === null || _a === void 0 ? void 0 : _a.contains(relatedTarget)) || ((_b = this.portalEl) === null || _b === void 0 ? void 0 : _b.contains(relatedTarget)));
-            const isRelatedTargetInCombobox = this.el.contains(relatedTarget);
+            // `contains` doesn't cross into the shadow root, where the trigger lives; with panel search,
+            // focus leaves the search field for the trigger whenever it's clicked to close.
+            const isRelatedTargetInCombobox = relatedTarget !== null && (this.el.contains(relatedTarget) || !!((_c = this.el.shadowRoot) === null || _c === void 0 ? void 0 : _c.contains(relatedTarget)));
             // Don't close if focus is moving to an option in the listbox or staying within the combobox
             if (!isRelatedTargetInCombobox && !isRelatedTargetInListbox) {
                 this.isOpen = false;
@@ -425,11 +547,58 @@ export class PdsCombobox {
             // Load more when near bottom (within 50px)
             if (scrollBottom < 50) {
                 this.pdsComboboxLoadOptions.emit({
-                    query: this.displayText,
+                    query: this.activeQuery,
                     page: this.currentPage + 1,
                 });
-                this.debouncedFetchAsyncOptions(this.displayText, this.currentPage + 1);
+                this.debouncedFetchAsyncOptions(this.activeQuery, this.currentPage + 1);
+            }
+        };
+        // A press on the panel's padding, captions or status rows keeps focus in the search field;
+        // otherwise it would blur the field, closing a portaled panel or stranding the keys.
+        this.onPanelMouseDown = (event) => {
+            if (event.target !== this.panelSearchEl)
+                event.preventDefault();
+        };
+        this.onPanelSearchInput = (event) => {
+            this.setPanelQuery(event.target.value);
+        };
+        // Space, Home and End edit the search text rather than moving through the options.
+        this.onPanelSearchKeyDown = (event) => {
+            if (event.key === ' ' || event.key === 'Home' || event.key === 'End')
+                return;
+            if (this.handlePanelTab(event))
+                return;
+            this.handleKeyDown(event);
+        };
+        /**
+         * Keys in the list while a drilled-in group hides the search field. Backspace, like ArrowLeft,
+         * steps back to the groups; a character starts a search of the whole list. Characters typed
+         * before the search field renders and takes focus still land on the list, so they add to the
+         * query rather than starting it again.
+         */
+        this.onPanelTreeKeyDown = (event) => {
+            if (this.handlePanelTab(event))
+                return;
+            if (event.key === 'Backspace') {
+                event.preventDefault();
+                if (!this.leaveDrilledInGroup() && this.panelQuery !== '')
+                    this.setPanelQuery(this.panelQuery.slice(0, -1));
+                return;
+            }
+            // AltGr (Ctrl+Alt on Windows) and Option on macOS type characters too; Meta and Ctrl alone are
+            // shortcuts.
+            if (event.key.length === 1 && event.key !== ' ' && !event.metaKey && (!event.ctrlKey || event.altKey)) {
+                event.preventDefault();
+                this.flyout.reset();
+                // The query first, so leaving the group reads as search results, not a slide back.
+                this.setPanelQuery(this.panelQuery + event.key);
+                this.openGroup = null;
+                return;
             }
+            this.handleKeyDown(event);
+        };
+        this.onGroupBackClick = () => {
+            this.leaveDrilledInGroup();
         };
     }
     connectedCallback() {
@@ -466,15 +635,106 @@ export class PdsCombobox {
             this.deferredPortalTeardownId = undefined;
         }
         (_a = this.observer) === null || _a === void 0 ? void 0 : _a.disconnect();
+        cancelDebouncedEvent(this.pdsComboboxSearch);
         this.clearAsyncFetchState();
         this.removeBodyPortal();
+        this.flyout.reset();
     }
     componentDidRender() {
+        var _a;
         if (this.usesBodyPortal && this.isOpen) {
             this.syncBodyPortal();
         }
+        const row = (_a = this.listboxEl) === null || _a === void 0 ? void 0 : _a.querySelector('.pds-combobox__group-row--open');
+        const flyoutEl = row === null || row === void 0 ? void 0 : row.querySelector('.pds-combobox__flyout');
+        if (this.isOpen && this.listboxEl && row && flyoutEl) {
+            this.flyout.position(row, this.listboxEl, flyoutEl);
+        }
+        else {
+            this.flyout.stopPositioning();
+        }
+        // The row back is sticky over the group's options; scrolling an option into view stops below
+        // it. Set before any scroll below, and when it first applies, scroll the highlighted option
+        // again: the list keeps its offset on drilling in, and an earlier scroll had no padding.
+        if (this.panelTreeEl) {
+            const header = this.hidesPanelSearch ? this.panelTreeEl.querySelector('.pds-combobox__group-back-trigger') : null;
+            const padding = header ? `${header.offsetHeight}px` : '';
+            if (this.panelTreeEl.style.scrollPaddingBlockStart !== padding) {
+                this.panelTreeEl.style.scrollPaddingBlockStart = padding;
+                if (padding !== '' && this.highlightedIndex >= 0)
+                    this.pendingOptionFocus = true;
+            }
+        }
+        if (this.pendingOptionFocus) {
+            this.pendingOptionFocus = false;
+            this.updateOptionFocus();
+        }
+        // Panel search keeps focus in the search field, or in the list while a group hides the field.
+        const panelFocusEl = this.hidesPanelSearch ? this.panelTreeEl : this.panelSearchEl;
+        if (this.isOpen && this.usesPanelSearch && panelFocusEl && panelFocusEl !== this.panelFocusEl) {
+            this.focusPanel(panelFocusEl);
+        }
+    }
+    focusPanel(el) {
+        var _a, _b;
+        this.panelFocusEl = el;
+        // Before the dropdown is positioned it sits in the page's flow; don't scroll to it.
+        el.focus({ preventScroll: true });
+        // A search started by typing in the list carries its first character; type on after it.
+        if (el === this.panelSearchEl && this.panelQuery !== '') {
+            (_b = (_a = this.panelSearchEl).setSelectionRange) === null || _b === void 0 ? void 0 : _b.call(_a, this.panelQuery.length, this.panelQuery.length);
+        }
+        this.updateAriaActiveDescendant();
+    }
+    /** Switching display mode leaves no flyout or hover timer from the last one. */
+    groupDisplayChanged() {
+        this.flyout.reset();
+        this.openGroup = null;
+        // The reset isn't a drill-out, so it doesn't slide either.
+        this.drillDirection = null;
+    }
+    openGroupChanged(next, previous) {
+        this.handPanelFocusToList();
+        // Only moves between the drill-in panel's views slide; search results don't.
+        if (!this.isOpen || this.effectiveGroupDisplay !== 'drill-in' || !this.showsGroupedPanel)
+            return;
+        if (next !== null && previous === null)
+            this.drillDirection = 'in';
+        else if (next === null && previous !== null)
+            this.drillDirection = 'out';
+    }
+    /** A flyout with no room beside the dropdown drills in, which can hide the focused search field too. */
+    flyoutFallbackChanged() {
+        this.handPanelFocusToList();
+    }
+    /**
+     * Drilling into a group hides the search field, so focus moves to the list before the field
+     * unmounts: focus lost with it would leave the combobox and close the dropdown.
+     */
+    handPanelFocusToList() {
+        if (this.isOpen && this.hidesPanelSearch && this.panelTreeEl)
+            this.focusPanel(this.panelTreeEl);
     }
     isOpenChanged(isOpen) {
+        if (!isOpen) {
+            this.drillDirection = null;
+            this.openGroup = null;
+            this.highlightedGroup = null;
+            this.keyboardNavigating = false;
+            this.flyout.reset();
+            if (this.panelQuery !== '') {
+                // The field reopens empty, so tell consumers who filter `options` from this event.
+                this.panelQuery = '';
+                this.pdsComboboxSearch.emit({ query: '' });
+            }
+            // And with `async-url`, start loading the unsearched list now, so it's ready by the reopen.
+            if (this.usesPanelSearch && this.asyncUrl && this.lastFetchedQuery !== '') {
+                this.debouncedFetchAsyncOptions('', 1);
+            }
+            this.panelFocusEl = undefined;
+            this.flyoutRoomChecked = false;
+            this.flyoutFallback = false;
+        }
         if (isOpen && this.deferredPortalTeardownId !== undefined) {
             clearTimeout(this.deferredPortalTeardownId);
             this.deferredPortalTeardownId = undefined;
@@ -507,17 +767,52 @@ export class PdsCombobox {
     get usesBodyPortal() {
         return this.dropdownMount === 'body';
     }
+    get labelId() {
+        return `${this.componentId}-label`;
+    }
+    /** One check for "the `<label>` is rendered", so the label and the reference to it can't disagree. */
+    get hasVisibleLabel() {
+        return Boolean(this.label) && !this.hideLabel;
+    }
+    /**
+     * The button and chip triggers are `div`s, which `<label for>` can't name, so they point at the
+     * visible label instead. With `hide-label` there is no visible label and `aria-label` names them.
+     * With panel search the trigger is a button, which has no value, so its own text (the selection
+     * or placeholder) joins the label in its name.
+     */
+    get triggerLabelledBy() {
+        if (!this.hasVisibleLabel)
+            return undefined;
+        return this.usesPanelSearch ? `${this.labelId} ${this.componentId}` : this.labelId;
+    }
+    /** The div triggers' `aria-label` when the label is hidden; with panel search it names the selection too. */
+    get triggerAriaLabel() {
+        if (!this.hideLabel)
+            return undefined;
+        const shown = this.selectedLabel || this.placeholder;
+        return this.usesPanelSearch && shown ? `${this.label}, ${shown}` : this.label;
+    }
     get listboxId() {
         return `${this.componentId}-listbox`;
     }
     optionDomId(optionIndex) {
         return `${this.componentId}-option-${optionIndex}`;
     }
+    groupDomId(optgroup) {
+        let id = this.groupIds.get(optgroup);
+        if (id === undefined) {
+            id = `${this.componentId}-group-${this.groupIdCount++}`;
+            this.groupIds.set(optgroup, id);
+        }
+        return id;
+    }
     setupDebounce() {
         const { pdsComboboxSearch, debounce, originalSearchEmitter } = this;
         this.pdsComboboxSearch = debounce === undefined
             ? originalSearchEmitter !== null && originalSearchEmitter !== void 0 ? originalSearchEmitter : pdsComboboxSearch
             : debounceEvent(pdsComboboxSearch, debounce);
+        // After the swap, so an emit made while flushing goes to the new emitter, not the old one.
+        flushDebouncedEvent(pdsComboboxSearch);
     }
     optionsChanged() {
         if (this.options) {
@@ -664,6 +959,8 @@ export class PdsCombobox {
             });
             if (page === 1) {
                 this.internalOptions = formattedResults;
+                // Only once its results have loaded: a failed or aborted fetch leaves the last query's.
+                this.lastFetchedQuery = query;
             }
             else {
                 this.internalOptions = [...this.internalOptions, ...formattedResults];
@@ -688,26 +985,76 @@ export class PdsCombobox {
         }
     }
     updateOptionsFromAsync() {
+        var _a;
         if (!this.asyncUrl && !this.options)
             return;
         // Clear existing slot-based options when using async
         this.optionEls = [];
         this.allItems = [];
-        // Create option elements from async data
+        // Create option elements from async data. Grouped options are nested in an optgroup, as
+        // slotted markup would be, so grouping, filtering and labels work the same either way. Each
+        // group is listed where it first appears with all of its options, even when the data
+        // interleaves groups, so an option never renders under another group's label. Ungrouped
+        // options come first, so none reads as part of the group above it.
         const asyncOptions = this.options || this.internalOptions;
+        const groups = new Map();
+        const ungrouped = [];
+        const groupEntries = [];
         asyncOptions.forEach(opt => {
             const optionEl = document.createElement('option');
             optionEl.value = String(opt.id);
             optionEl.textContent = opt.text;
-            this.optionEls.push(optionEl);
-            this.allItems.push(optionEl);
+            if (opt.disabled === true)
+                optionEl.setAttribute('disabled', '');
+            // Only strings group an option or name an icon; anything else from JS is ignored, not coerced.
+            if (typeof opt.group !== 'string' || opt.group === '') {
+                ungrouped.push(optionEl);
+                return;
+            }
+            let optgroup = groups.get(opt.group);
+            if (!optgroup) {
+                optgroup = document.createElement('optgroup');
+                optgroup.label = opt.group;
+                groups.set(opt.group, optgroup);
+                groupEntries.push(optgroup);
+            }
+            if (!optgroup.hasAttribute('data-icon') && typeof opt.groupIcon === 'string' && opt.groupIcon !== '') {
+                optgroup.setAttribute('data-icon', opt.groupIcon);
+            }
+            optgroup.appendChild(optionEl);
         });
-        // Re-apply preselection if a value is set but no option has been selected yet.
-        // This handles the case where `value` is set before async options have loaded.
-        if (this.value && !this.selectedOption) {
+        [...ungrouped, ...groupEntries].forEach(entry => {
+            if (entry.tagName === 'OPTGROUP') {
+                this.allItems.push(entry);
+                Array.from(entry.children).forEach(child => {
+                    this.optionEls.push(child);
+                    this.allItems.push(child);
+                });
+            }
+            else {
+                this.optionEls.push(entry);
+                this.allItems.push(entry);
+            }
+        });
+        // A rebuild replaces every optgroup. Follow the open group to its new element by label, so the
+        // flyout stays open across reloads and pagination, or close it if the group is gone. The hover
+        // timers still hold the old element, so they're cleared either way. filterOptions, below,
+        // resets the highlight.
+        if (this.openGroup !== null && !groupEntries.includes(this.openGroup)) {
+            this.flyout.reset();
+            this.openGroup = (_a = groups.get(this.openGroup.label)) !== null && _a !== void 0 ? _a : null;
+        }
+        // Re-apply the selection to the rebuilt options: when `value` is set before async options have
+        // loaded, and after any rebuild, which detaches the previously selected option element.
+        if (this.value && (!this.selectedOption || !this.optionEls.includes(this.selectedOption))) {
             const matchingOption = this.optionEls.find(opt => opt.value === this.value);
             if (matchingOption) {
+                // Relinking a selection keeps the same value, so it keeps any text being typed too, which
+                // the selectedOption watcher would otherwise reset to the label.
+                const typed = this.selectedOption ? this.displayText : undefined;
                 this.setSelectedOption(matchingOption);
+                if (typed !== undefined)
+                    this.displayText = typed;
             }
         }
         this.filterOptions();
@@ -758,11 +1105,12 @@ export class PdsCombobox {
                 }
             }
             // For chip triggers, ensure we always have a selected option
-            if (!initialSelected && this.trigger === 'chip' && this.optionEls.length > 0) {
-                initialSelected = this.optionEls[0]; // Select first option as default
+            const firstEnabled = this.optionEls.find(opt => !isOptionDisabled(opt));
+            if (initialSelected === null && this.trigger === 'chip' && firstEnabled !== undefined) {
+                initialSelected = firstEnabled;
                 this.value = initialSelected.value;
                 this.displayText = this.getOptionLabel(initialSelected);
-                console.warn('PDS Combobox: Chip triggers should always have a selected option. Automatically selected the first option.');
+                console.warn('PDS Combobox: Chip triggers should always have a selected option. Automatically selected the first enabled option.');
             }
             // Update selection if we found a different selected option or if we don't have one
             if (initialSelected && initialSelected !== this.selectedOption) {
@@ -850,16 +1198,26 @@ export class PdsCombobox {
         }
     }
     filterOptions() {
+        // A new list replaces the rows a slide was animating, so its end event may never come.
+        this.drillDirection = null;
         // Ensure allItems includes optionEls if not already populated (for edge cases)
         if (this.allItems.length === 0 && this.optionEls.length > 0) {
             this.allItems = [...this.optionEls];
         }
-        if (this.mode === 'select-only' || this.expandFilterListWhileOpen) {
+        const searchesPanel = this.usesPanelSearch;
+        if ((this.mode === 'select-only' && !searchesPanel) || this.expandFilterListWhileOpen || (searchesPanel && this.panelQuery === '')) {
             this.filteredItems = [...this.allItems];
         }
         else {
-            const val = this.displayText.toLowerCase();
+            const val = (searchesPanel ? this.panelQuery : this.displayText).toLowerCase();
             const filteredOptions = this.optionEls.filter(option => {
+                // Outside inline mode a group's label is part of what search matches, so "tag" finds
+                // every option in the Tag group.
+                if (this.groupDisplay !== 'inline') {
+                    const groupLabel = groupLabelOf(option);
+                    if (groupLabel !== null && groupLabel.toLowerCase().includes(val))
+                        return true;
+                }
                 // For layout options, search both text content and data-search-text attribute
                 if (this.isOptionLayout(option)) {
                     const searchText = option.getAttribute('data-search-text') || option.textContent || '';
@@ -894,6 +1252,7 @@ export class PdsCombobox {
             });
         }
         this.highlightedIndex = -1;
+        this.highlightedGroup = null;
     }
     clearExpandFilterList() {
         this.expandFilterListWhileOpen = false;
@@ -923,7 +1282,8 @@ export class PdsCombobox {
         this.listboxEl.style.width = this.dropdownWidth;
         if (this.maxHeight) {
             this.listboxEl.style.maxHeight = this.maxHeight;
-            this.listboxEl.style.overflowY = 'auto';
+            // With panel search, the options list scrolls under a fixed search field.
+            this.listboxEl.style.overflowY = this.usesPanelSearch ? 'hidden' : 'auto';
         }
         this.listboxEl.offsetHeight;
         return computePosition(this.triggerEl, this.listboxEl, {
@@ -940,8 +1300,30 @@ export class PdsCombobox {
                 position: strategy,
                 zIndex,
             });
+            this.checkFlyoutRoom();
         });
     }
+    /**
+     * Once per open, after the dropdown is placed: with no room for a flyout on either side of it,
+     * `flyout` drills in instead. `flyout-min-width` is resolved through CSS, so any length works.
+     */
+    checkFlyoutRoom() {
+        if (!this.isOpen || this.groupDisplay !== 'flyout' || this.flyoutRoomChecked || !this.listboxEl)
+            return;
+        this.flyoutRoomChecked = true;
+        const probe = document.createElement('div');
+        // Fixed, like the flyout, so a percentage resolves against the viewport as the flyout's does.
+        probe.style.cssText = 'position:fixed;visibility:hidden;width:0;';
+        probe.style.minWidth = this.flyoutMinWidth;
+        this.listboxEl.appendChild(probe);
+        const needed = parseFloat(getComputedStyle(probe).minWidth);
+        probe.remove();
+        const rect = this.listboxEl.getBoundingClientRect();
+        const room = Math.max(window.innerWidth - rect.right, rect.left);
+        const fallback = Number.isFinite(needed) && needed > 0 && rect.width > 0 && room < needed;
+        if (fallback !== this.flyoutFallback)
+            this.flyoutFallback = fallback;
+    }
     openDropdownPositioning() {
         if (!this.triggerEl || !this.listboxEl) {
             return;
@@ -1044,6 +1426,130 @@ export class PdsCombobox {
             this.listboxEl = undefined;
         }
     }
+    /**
+     * The tree keys in the grouped panel. Up, Down, Home, End, PageUp and PageDown move within one
+     * level; Right, Enter or Space opens a group at its first option; Left, or Escape, closes the
+     * open group back to its row. Returns false for keys the listbox handling covers, such as
+     * Enter on an option.
+     */
+    handleGroupedPanelKey(e) {
+        if (!this.showsGroupedPanel)
+            return false;
+        this.keyboardNavigating = true;
+        // In the input trigger, Left and Right still move the caret through typed text, and Space,
+        // Home and End edit it, as they do in the panel's search field.
+        if (this.trigger === 'input') {
+            if ((e.key === 'ArrowLeft' || e.key === 'ArrowRight') && this.displayText !== '')
+                return false;
+            if (e.key === ' ' || e.key === 'Home' || e.key === 'End')
+                return false;
+        }
+        const entries = buildPanelEntries(this.filteredItems);
+        const drilledIn = this.effectiveGroupDisplay === 'drill-in' && this.openGroup !== null;
+        const current = this.currentPanelItem();
+        const column = panelColumn(entries, this.openGroup, current, drilledIn);
+        if (column.length === 0)
+            return false;
+        const position = current === null ? -1 : column.indexOf(current);
+        const moveTo = (to) => {
+            e.preventDefault();
+            this.highlightPanelItem(column[Math.max(0, Math.min(column.length - 1, to))]);
+            return true;
+        };
+        switch (e.key) {
+            case 'ArrowDown':
+                return moveTo(position < 0 ? 0 : position + 1);
+            case 'ArrowUp':
+                return moveTo(position < 0 ? column.length - 1 : position - 1);
+            case 'Home':
+                return moveTo(0);
+            case 'End':
+                return moveTo(column.length - 1);
+            case 'PageDown':
+                return moveTo(position < 0 ? 0 : position + 10);
+            case 'PageUp':
+                return moveTo(position < 0 ? column.length - 1 : position - 10);
+            case 'ArrowRight':
+            case 'Enter':
+            case ' ': {
+                if (current === null || typeof current === 'number')
+                    return false;
+                e.preventDefault();
+                if (!drilledIn || current !== this.openGroup) {
+                    this.expandGroup(entries, current);
+                }
+                else if (e.key === 'ArrowRight') {
+                    // On the row back of a drilled-in group: down into its options.
+                    if (column.length > 1)
+                        this.highlightPanelItem(column[1]);
+                }
+                else {
+                    this.leaveDrilledInGroup();
+                }
+                return true;
+            }
+            case 'ArrowLeft':
+            case 'Escape': {
+                // Escape with no group open closes the panel, through the listbox handling.
+                if (this.openGroup === null)
+                    return false;
+                e.preventDefault();
+                this.collapseToGroup(this.openGroup);
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Where the keyboard is in the grouped panel. An option highlighted in a group that has since
+     * closed (the pointer left its flyout) counts as its group's row, so the keys carry on from
+     * what's showing rather than from an option that isn't.
+     */
+    currentPanelItem() {
+        if (this.highlightedIndex < 0)
+            return this.highlightedGroup;
+        const selectable = this.filteredItems.filter(item => item.tagName === 'OPTION');
+        const group = parentOptgroupOf(selectable[this.highlightedIndex]);
+        return group !== null && group !== this.openGroup ? group : this.highlightedIndex;
+    }
+    /**
+     * Highlights the option at `index`, kept within the list. Disabled options can be highlighted,
+     * so assistive tech announces them as unavailable, but not chosen.
+     */
+    highlightOptionAt(options, index) {
+        if (options.length === 0)
+            return;
+        this.highlightedIndex = Math.max(0, Math.min(options.length - 1, index));
+        this.updateOptionFocus();
+    }
+    /** Highlights a group row or an option, opening or closing flyouts to match. */
+    highlightPanelItem(item) {
+        if (typeof item === 'number') {
+            this.highlightedIndex = item;
+        }
+        else {
+            this.highlightedIndex = -1;
+            this.highlightedGroup = item;
+        }
+        this.updateOptionFocus();
+    }
+    expandGroup(entries, optgroup) {
+        var _a;
+        this.flyout.open(optgroup);
+        const first = (_a = findGroup(entries, optgroup)) === null || _a === void 0 ? void 0 : _a.options[0];
+        if (first !== undefined)
+            this.highlightPanelItem(first.index);
+        // Its options render after this change; scroll to the first one then.
+        this.pendingOptionFocus = true;
+    }
+    /** Closes the open group and highlights its row, as a tree's Left does from a child. */
+    collapseToGroup(optgroup) {
+        this.flyout.reset();
+        this.openGroup = null;
+        this.highlightPanelItem(optgroup);
+        // The row renders after this change (in drill-in it replaces the row back); scroll to it then.
+        this.pendingOptionFocus = true;
+    }
     /**
      * Sets focus on the native input element.
      */
@@ -1057,8 +1563,9 @@ export class PdsCombobox {
         }
     }
     /**
-     * Sets the initial highlighted index when dropdown opens.
-     * If there's a selected option, highlight it. Otherwise, highlight the first option.
+     * Sets the initial highlighted index when dropdown opens. Highlights the selected option unless
+     * it's disabled. Otherwise highlights the first enabled option, or, in the grouped panel, the
+     * first row with something to choose, or nothing when every option is disabled.
      */
     setInitialHighlightedIndex() {
         const selectableOptions = this.filteredItems.filter(item => item.tagName === 'OPTION');
@@ -1066,16 +1573,33 @@ export class PdsCombobox {
             this.highlightedIndex = -1;
             return;
         }
-        // If there's a selected option, find its index in the filtered options
-        if (this.selectedOption) {
+        // If there's a selected option, find its index in the filtered options. A disabled one can be
+        // the value, as in a native select, but it isn't highlighted.
+        if (this.selectedOption && !isOptionDisabled(this.selectedOption)) {
             const selectedIndex = selectableOptions.findIndex(option => option === this.selectedOption);
             if (selectedIndex >= 0) {
                 this.highlightedIndex = selectedIndex;
+                // In the grouped panel, open on the selection's group, however the dropdown was opened, and
+                // scroll the selection into view once its group has rendered.
+                if (this.showsGroupedPanel) {
+                    this.openGroup = parentOptgroupOf(this.selectedOption);
+                    // Opening on the selection isn't drilling in, so it doesn't slide.
+                    this.drillDirection = null;
+                    this.pendingOptionFocus = true;
+                }
                 return;
             }
         }
-        // No selected option or selected option not in filtered results, highlight first option
-        this.highlightedIndex = 0;
+        // In the grouped panel, the first row with something to choose: a group stays closed until
+        // it's opened.
+        if (this.showsGroupedPanel) {
+            const first = buildPanelEntries(this.filteredItems).find(entry => entry.kind === 'group' ? !isGroupDisabled(entry.group) : !isOptionDisabled(entry.option));
+            this.highlightedIndex = (first === null || first === void 0 ? void 0 : first.kind) === 'option' ? first.index : -1;
+            this.highlightedGroup = (first === null || first === void 0 ? void 0 : first.kind) === 'group' ? first.group.optgroup : null;
+            return;
+        }
+        // No selected option or selected option not in filtered results, highlight the first enabled option
+        this.highlightedIndex = selectableOptions.findIndex(option => !isOptionDisabled(option));
     }
     /**
      * Focus management helper - moves focus to the first option when dropdown opens
@@ -1111,19 +1635,9 @@ export class PdsCombobox {
         const selectableOptions = this.filteredItems.filter(item => item.tagName === 'OPTION');
         if (selectableOptions.length > 0) {
             this.setInitialHighlightedIndex();
-            if (this.listboxEl) {
-                const optionElements = this.listboxEl.querySelectorAll('[role="option"]');
-                const highlightedOption = optionElements[this.highlightedIndex];
-                if (highlightedOption) {
-                    optionElements.forEach(option => {
-                        option.setAttribute('tabindex', '-1');
-                    });
-                    highlightedOption.setAttribute('tabindex', '0');
-                    highlightedOption.focus();
-                    highlightedOption.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
-                }
-            }
-            this.updateAriaActiveDescendant();
+            // By index, through the same path as arrowing: it opens the option's flyout group first
+            // when it isn't rendered, and highlights it once it is.
+            this.updateOptionFocus();
         }
     }
     /**
@@ -1131,14 +1645,58 @@ export class PdsCombobox {
      * Note: We don't actually focus the option to prevent focusout events that close the dropdown
      */
     updateOptionFocus() {
-        if (!this.listboxEl || this.highlightedIndex < 0)
+        var _a;
+        if (this.listboxEl === undefined || this.listboxEl === null)
             return;
+        // A row highlighted outright; an option highlighted in a closed group opens it below instead.
+        const groupRow = this.showsGroupedPanel && this.highlightedIndex < 0 ? this.highlightedGroup : null;
+        if (groupRow !== null) {
+            // Arrowing onto another row closes a flyout that hover left open.
+            if (this.effectiveGroupDisplay === 'flyout' && this.openGroup !== null && this.openGroup !== groupRow) {
+                this.flyout.reset();
+                this.openGroup = null;
+            }
+            // Matched by id, not a selector: componentId is consumer text and may not be selector-safe.
+            const id = this.groupDomId(groupRow);
+            (_a = Array.from(this.listboxEl.querySelectorAll('[role="treeitem"]'))
+                .find(row => row.id === id)) === null || _a === void 0 ? void 0 : _a.scrollIntoView({ block: 'nearest' });
+            this.updateAriaActiveDescendant();
+            return;
+        }
+        if (this.highlightedIndex < 0)
+            return;
+        // In the flyout panel only the open group's options are rendered: open the highlighted
+        // option's group, and finish once it has rendered. Through the controller, so a hover timer
+        // left running by the pointer can't close or switch the group the keys just moved into.
+        if (this.showsGroupedPanel) {
+            const selectable = this.filteredItems.filter(item => item.tagName === 'OPTION');
+            const group = parentOptgroupOf(selectable[this.highlightedIndex]);
+            const changed = group !== this.openGroup;
+            if (group !== null) {
+                this.flyout.open(group);
+            }
+            else {
+                this.flyout.reset();
+                this.openGroup = null;
+            }
+            if (changed) {
+                this.pendingOptionFocus = true;
+                return;
+            }
+        }
         const optionElements = this.listboxEl.querySelectorAll('[role="option"]');
-        const currentOption = optionElements[this.highlightedIndex];
+        // By index, not position: the flyout panel renders only some options.
+        const currentOption = this.listboxEl.querySelector(`[data-option-index="${this.highlightedIndex}"]`);
         if (currentOption) {
             // Check if any option currently has focus OR if we're in arrow-key navigation mode
             const hasOptionFocus = Array.from(optionElements).some(el => el === document.activeElement);
-            const shouldFocusOption = !this.usesBodyPortal && (hasOptionFocus || this.isArrowKeyNavigationMode);
+            // The panel's search field keeps focus and points at the option with aria-activedescendant,
+            // and so does the trigger over the grouped panel, whose group rows can't take focus and
+            // whose options are hidden while a flyout is placed.
+            const shouldFocusOption = !this.usesBodyPortal &&
+                !this.usesPanelSearch &&
+                !this.showsGroupedPanel &&
+                (hasOptionFocus || this.isArrowKeyNavigationMode);
             if (shouldFocusOption) {
                 optionElements.forEach(option => {
                     option.setAttribute('tabindex', '-1');
@@ -1146,21 +1704,64 @@ export class PdsCombobox {
                 currentOption.setAttribute('tabindex', '0');
                 currentOption.focus();
             }
-            // Always scroll the option into view
-            currentOption.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+            // Always scroll the option into view; in a flyout, by scrolling the flyout alone.
+            const flyout = currentOption.closest('.pds-combobox__flyout');
+            if (flyout) {
+                this.flyout.reveal(flyout, currentOption);
+            }
+            else {
+                currentOption.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+            }
         }
         // Always update aria-activedescendant on the trigger element
         this.updateAriaActiveDescendant();
     }
+    /** The highlighted group row in the grouped panel, or null while an option is highlighted. */
+    get highlightedGroupRow() {
+        if (!this.showsGroupedPanel)
+            return null;
+        if (this.highlightedIndex < 0)
+            return this.highlightedGroup;
+        // An option left highlighted in a flyout that has since closed shows as its group's row.
+        const current = this.currentPanelItem();
+        return typeof current === 'number' ? null : current;
+    }
     /**
-     * Updates aria-activedescendant on the trigger element
+     * The id of the highlighted option or group row, only while it's rendered. In the flyout panel
+     * an option in a closed group isn't in the DOM, and drilled into a group the other groups' rows
+     * aren't; `aria-activedescendant` must not point at a missing element.
      */
+    get activeDescendantId() {
+        if (!this.isOpen)
+            return undefined;
+        const groupRow = this.highlightedGroupRow;
+        if (groupRow !== null) {
+            const drilledIntoAnother = this.effectiveGroupDisplay === 'drill-in' && this.openGroup !== null && this.openGroup !== groupRow;
+            return drilledIntoAnother ? undefined : this.groupDomId(groupRow);
+        }
+        if (this.highlightedIndex < 0)
+            return undefined;
+        if (this.showsGroupedPanel) {
+            const selectable = this.filteredItems.filter(item => item.tagName === 'OPTION');
+            const group = parentOptgroupOf(selectable[this.highlightedIndex]);
+            if (group !== null && group !== this.openGroup)
+                return undefined;
+        }
+        return this.optionDomId(this.highlightedIndex);
+    }
+    /** Points the focused element's aria-activedescendant at the highlighted option, or clears it. */
     updateAriaActiveDescendant() {
-        if (this.triggerEl && this.highlightedIndex >= 0) {
-            this.triggerEl.setAttribute('aria-activedescendant', this.optionDomId(this.highlightedIndex));
+        // With panel search, the element with focus owns it, not the trigger: the search field, or
+        // the list while a drilled-in group hides the field.
+        const target = this.usesPanelSearch ? (this.hidesPanelSearch ? this.panelTreeEl : this.panelSearchEl) : this.triggerEl;
+        if (!target)
+            return;
+        const id = this.activeDescendantId;
+        if (id !== undefined) {
+            target.setAttribute('aria-activedescendant', id);
         }
-        else if (this.triggerEl) {
-            this.triggerEl.removeAttribute('aria-activedescendant');
+        else {
+            target.removeAttribute('aria-activedescendant');
         }
     }
     /**
@@ -1196,6 +1797,17 @@ export class PdsCombobox {
             this.pdsComboboxChange.emit({ value: '' });
         }
     }
+    // Group rows in the flyout panel carry their group's index, as options carry theirs.
+    groupFromEvent(event) {
+        var _a, _b;
+        const index = Number(event.currentTarget.getAttribute('data-group-index'));
+        return (_b = (_a = this.renderedGroups[index]) === null || _a === void 0 ? void 0 : _a.optgroup) !== null && _b !== void 0 ? _b : null;
+    }
+    highlightGroupRowByPointer(group) {
+        this.highlightedIndex = -1;
+        this.highlightedGroup = group;
+        this.keyboardNavigating = false;
+    }
     // Get the label of the selected option
     get selectedLabel() {
         return this.displayText || '';
@@ -1308,7 +1920,24 @@ export class PdsCombobox {
         // Fallback: Use component props
         return this.chipDot;
     }
+    /**
+     * With `async-url`, fetches when the button trigger opens: the first page if nothing has loaded.
+     * The panel's search field opens empty, so results left from the last search are refetched for
+     * an empty query.
+     */
+    fetchAsyncOptionsOnOpen() {
+        if (!this.asyncUrl)
+            return;
+        if (this.usesPanelSearch && (this.internalOptions.length === 0 || this.lastFetchedQuery !== '')) {
+            this.debouncedFetchAsyncOptions('', 1);
+        }
+        else if (this.internalOptions.length === 0) {
+            this.debouncedFetchAsyncOptions(this.displayText, 1);
+        }
+    }
     handleOptionClick(option) {
+        if (isOptionDisabled(option))
+            return;
         // Update reactive state - single source of truth
         // The @Watch('selectedOption') will handle displayText, value, and form internals
         this.setSelectedOption(option);
@@ -1322,33 +1951,242 @@ export class PdsCombobox {
         }
         const hasSlottedEmpty = !this.usesBodyPortal && !!this.el.querySelector('[slot="empty"]');
         const hasSlottedLoading = !this.usesBodyPortal && !!this.el.querySelector('[slot="loading"]');
-        let optionIndex = 0;
         const selectableOptions = this.filteredItems.filter(item => item.tagName === 'OPTION');
-        return (h("ul", { class: "pds-combobox__listbox", role: "listbox", id: this.listboxId, "aria-label": this.label || 'Options', "aria-multiselectable": "false", ref: el => (this.listboxEl = el), onScroll: this.handleScroll }, this.loading && (h("li", { class: "pds-combobox__loading", role: "presentation" }, hasSlottedLoading ? (h("slot", { name: "loading" })) : (h("pds-loader", { size: "small" })))), !this.loading && this.filteredItems.length === 0 && (h("li", { class: "pds-combobox__empty", role: "presentation" }, hasSlottedEmpty ? (h("slot", { name: "empty" })) : (h("span", null, "No options found")))), this.filteredItems.map((item, itemIdx) => {
+        const withSearch = this.usesPanelSearch;
+        // While a drilled-in group hides the search field, the list takes focus in its place.
+        const listTakesFocus = this.hidesPanelSearch;
+        const list = (h("ul", { key: "panel-list", class: {
+                'pds-combobox__listbox': !withSearch,
+                'pds-combobox__listbox-options': withSearch,
+                'pds-combobox__listbox-options--drilled-in': listTakesFocus,
+                'pds-combobox__listbox--grouped': this.groupDisplay !== 'inline',
+                'pds-combobox__listbox--drill-in': this.drillDirection === 'in',
+                'pds-combobox__listbox--drill-out': this.drillDirection === 'out',
+            }, onAnimationEnd: this.onDrillAnimationEnd, role: this.showsGroupedPanel ? 'tree' : 'listbox', id: this.listboxId, "aria-label": this.label || 'Options', "aria-multiselectable": "false",
+            // Focusable but out of the tab order with panel search, so it can take focus when a
+            // drilled-in group hides the field. Dropping it while focused would blur the list and close.
+            tabIndex: withSearch ? -1 : undefined, "aria-activedescendant": listTakesFocus ? this.activeDescendantId : undefined, onKeyDown: withSearch ? this.onPanelTreeKeyDown : undefined, ref: el => {
+                if (withSearch)
+                    this.panelTreeEl = el;
+                else
+                    this.listboxEl = el;
+            }, onScroll: this.handleScroll }, this.loading && (h("li", { class: "pds-combobox__loading", role: "presentation" }, hasSlottedLoading ? (h("slot", { name: "loading" })) : (h("pds-loader", { size: "small" })))), !this.loading && this.filteredItems.length === 0 && (h("li", { class: "pds-combobox__empty", role: "presentation" }, hasSlottedEmpty ? (h("slot", { name: "empty" })) : (h("span", null, "No options found")))), this.showsGroupedPanel ? this.renderGroupedPanel() : this.renderListboxItems(selectableOptions.length), this.hasMore && !this.loading && (h("li", { class: "pds-combobox__load-more", role: "presentation" }, h("pds-loader", { size: "small" })))));
+        if (!withSearch)
+            return list;
+        // The search field sits above the list; the wrapper is what's positioned and portaled.
+        return (h("div", { class: "pds-combobox__listbox pds-combobox__listbox--with-search", ref: el => (this.listboxEl = el), onMouseDown: this.onPanelMouseDown,
+            // Portaled, the panel sits outside .pds-combobox, so its focusout wouldn't reach that handler.
+            onFocusout: this.usesBodyPortal ? this.onComboboxFocusOut : undefined }, !listTakesFocus && this.renderPanelSearch(), list));
+    }
+    /**
+     * The listbox's items. Each optgroup's options sit in a `group` named for it, as in
+     * `pds-multiselect`, so assistive tech announces the group on entering it; a `pds-text` label
+     * stays a caption above the options that follow it.
+     */
+    renderListboxItems(setSize) {
+        const rendered = [];
+        let optionIndex = 0;
+        let group = null;
+        const closeGroup = () => {
+            if (group === null)
+                return;
+            const { optgroup, key, options, members } = group;
+            const groupIcon = groupIconOf(optgroup);
+            // As in the grouped displays: disabled when there's nothing left in it to choose.
+            const disabled = members.length > 0 && members.every(member => isOptionDisabled(member));
+            rendered.push(h("li", { key: key, class: { 'pds-combobox__group': true, 'pds-combobox__group--disabled': disabled }, role: "group", "aria-label": optgroup.label, "aria-disabled": disabled ? 'true' : undefined }, h("div", { class: { 'pds-combobox__group-label': true, 'pds-combobox__group-label--with-icon': groupIcon !== null }, "aria-hidden": "true" }, groupIcon !== null && (
+            // `name`, not `icon`: `icon` also loads URLs and data: SVGs, unsanitized.
+            h("pds-icon", { name: groupIcon, size: "small", "aria-hidden": "true", class: "pds-combobox__group-icon" })), optgroup.label), h("ul", { class: "pds-combobox__group-list", role: "presentation" }, options)));
+            group = null;
+        };
+        this.filteredItems.forEach((item, itemIdx) => {
             if (item.tagName === 'OPTGROUP') {
-                const optgroup = item;
-                return (h("li", { key: `optgroup-${itemIdx}`, class: "pds-combobox__group-label", role: "presentation", "aria-label": optgroup.label }, optgroup.label));
+                closeGroup();
+                group = { optgroup: item, key: `optgroup-${itemIdx}`, options: [], members: [] };
             }
             else if (item.tagName === 'PDS-TEXT') {
-                const pdsText = item;
-                return (h("li", { key: `pds-text-${itemIdx}`, class: "pds-combobox__group-label", role: "presentation" }, pdsText.textContent));
+                closeGroup();
+                rendered.push(h("li", { key: `pds-text-${itemIdx}`, class: "pds-combobox__group-label", role: "presentation" }, item.textContent));
             }
             else if (item.tagName === 'OPTION') {
                 const option = item;
-                const isSelected = this.isOptionSelected(option);
-                const isHighlighted = this.highlightedIndex === optionIndex;
-                const isLayout = this.isOptionLayout(option);
-                const isChip = this.isOptionChip(option);
-                const currentOptionIndex = optionIndex++;
-                return (h("li", { key: option.value, id: this.optionDomId(currentOptionIndex), role: "option", "aria-selected": isSelected ? 'true' : 'false', "aria-setsize": selectableOptions.length, "aria-posinset": currentOptionIndex + 1, "aria-label": isLayout || isChip ? option.getAttribute('aria-label') || this.getOptionLabel(option) : undefined, tabindex: this.usesBodyPortal ? '-1' : isHighlighted ? '0' : '-1', class: {
-                        'pds-combobox__option': true,
-                        'pds-combobox__option--highlighted': isHighlighted,
-                        'pds-combobox__option--layout': isLayout,
-                        'pds-combobox__option--chip': isChip,
-                    }, "data-option-index": currentOptionIndex, onMouseDown: this.onOptionMouseDown, onClick: this.onOptionClick, onMouseEnter: this.onOptionMouseEnter, onKeyDown: this.onOptionKeyDown }, isLayout ? (h("pds-box", { class: "pds-combobox__option-layout-wrapper", innerHTML: this.getOptionLayoutContent(option) })) : isChip ? (this.renderOptionChip(option)) : (this.getOptionLabel(option)), isSelected && h("pds-icon", { icon: "check", size: "regular", class: "pds-combobox__option-check" })));
+                if (group !== null && parentOptgroupOf(option) !== group.optgroup)
+                    closeGroup();
+                const rendering = this.renderOption(option, optionIndex, { posinset: optionIndex + 1, setsize: setSize });
+                optionIndex++;
+                if (group !== null) {
+                    group.options.push(rendering);
+                    group.members.push(option);
+                }
+                else {
+                    rendered.push(rendering);
+                }
             }
-            return null;
-        }), this.hasMore && !this.loading && (h("li", { class: "pds-combobox__load-more", role: "presentation" }, h("pds-loader", { size: "small" })))));
+        });
+        closeGroup();
+        return rendered;
+    }
+    /** `panelSearch` applies to the triggers that can't be typed into. */
+    get usesPanelSearch() {
+        return this.panelSearch && this.trigger !== 'input';
+    }
+    /** `groupDisplay`, with `flyout` drilling in when there's no room beside the dropdown. */
+    get effectiveGroupDisplay() {
+        return this.groupDisplay === 'flyout' && this.flyoutFallback ? 'drill-in' : this.groupDisplay;
+    }
+    /**
+     * The popup's role, for the triggers' `aria-haspopup`: a `tree` while the grouped panel shows
+     * groups, and a `listbox` of options otherwise, search results included.
+     */
+    get popupRole() {
+        return this.showsGroupedPanel ? 'tree' : 'listbox';
+    }
+    /**
+     * The input trigger's `aria-haspopup`. While closed it names what opening shows: the full list,
+     * so the grouped panel in a grouped display, even though the input still holds the selection's
+     * label.
+     */
+    get inputPopupRole() {
+        if (this.isOpen)
+            return this.popupRole;
+        return this.effectiveGroupDisplay === 'inline' ? 'listbox' : 'tree';
+    }
+    /**
+     * The button and chip triggers' `aria-haspopup`. With panel search the trigger opens the panel,
+     * which starts as a tree in a grouped display, so typing in the panel doesn't change it.
+     */
+    get triggerPopupRole() {
+        if (!this.usesPanelSearch)
+            return this.popupRole;
+        return this.groupDisplay === 'inline' ? 'listbox' : 'tree';
+    }
+    /**
+     * Drilled into a group with panel search: the group's row back takes the search field's place,
+     * since one group's options don't need searching. Typing searches the whole list again.
+     */
+    get hidesPanelSearch() {
+        return this.usesPanelSearch && this.showsGroupedPanel && this.effectiveGroupDisplay === 'drill-in' && this.openGroup !== null;
+    }
+    /** The grouped panel is showing groups rather than search results. */
+    get showsGroupedPanel() {
+        if (this.effectiveGroupDisplay === 'inline')
+            return false;
+        const searching = this.usesPanelSearch
+            ? this.panelQuery !== ''
+            : this.mode === 'filter' && !this.expandFilterListWhileOpen && this.displayText !== '';
+        return !searching;
+    }
+    setPanelQuery(query) {
+        this.panelQuery = query;
+        this.clearExpandFilterList();
+        this.filterOptions();
+        this.pdsComboboxSearch.emit({ query: this.panelQuery });
+        if (this.asyncUrl !== undefined && this.asyncUrl !== '') {
+            this.debouncedFetchAsyncOptions(this.panelQuery, 1);
+        }
+        // The list changes size, so place the dropdown again, as typing in the input trigger does.
+        setTimeout(() => this.openDropdownPositioning(), 0);
+    }
+    /** What's being searched: the panel's field, or the input trigger's text. */
+    get activeQuery() {
+        return this.usesPanelSearch ? this.panelQuery : this.displayText;
+    }
+    // Tab closes the dropdown and lands on the trigger, as Escape does: the focused field or list is
+    // about to unmount, so the browser can't tab on from it. The next Tab continues from the trigger.
+    handlePanelTab(event) {
+        if (event.key !== 'Tab')
+            return false;
+        event.preventDefault();
+        this.handleKeyDown(event);
+        this.restoreFocusToTrigger();
+        return true;
+    }
+    /** Returns from a drilled-in group to the group list; false when not drilled in. */
+    leaveDrilledInGroup() {
+        if (!this.showsGroupedPanel || this.effectiveGroupDisplay !== 'drill-in' || this.openGroup === null)
+            return false;
+        this.collapseToGroup(this.openGroup);
+        return true;
+    }
+    renderPanelSearch() {
+        return (h("div", { key: "panel-search", class: "pds-combobox__panel-search" }, h("pds-icon", { name: "search", size: "small", "aria-hidden": "true" }), h("input", { ref: el => (this.panelSearchEl = el), type: "text", class: "pds-combobox__panel-search-input", placeholder: this.searchPlaceholder, value: this.panelQuery, role: "combobox", "aria-label": this.searchOptionsLabel, "aria-haspopup": this.popupRole, "aria-controls": this.listboxId, "aria-autocomplete": "list", "aria-expanded": "true", "aria-activedescendant": this.activeDescendantId, autocomplete: "off", onInput: this.onPanelSearchInput, onKeyDown: this.onPanelSearchKeyDown })));
+    }
+    /**
+     * An option, as a listbox `option` or, given a tree `level`, a `treeitem`. `posinset` and
+     * `setsize` place it among its siblings.
+     */
+    renderOption(option, index, { posinset, setsize, level }) {
+        const isSelected = this.isOptionSelected(option);
+        const isHighlighted = this.highlightedIndex === index;
+        const isLayout = this.isOptionLayout(option);
+        const isChip = this.isOptionChip(option);
+        const isDisabled = isOptionDisabled(option);
+        const tree = level !== undefined;
+        return (h("li", { key: option.value, id: this.optionDomId(index), role: tree ? 'treeitem' : 'option', "aria-selected": isSelected ? 'true' : tree ? undefined : 'false', "aria-disabled": isDisabled ? 'true' : undefined, "aria-level": level, "aria-setsize": setsize, "aria-posinset": posinset, "aria-label": isLayout || isChip ? option.getAttribute('aria-label') || this.getOptionLabel(option) : undefined, tabindex: this.usesBodyPortal || this.usesPanelSearch || tree ? '-1' : isHighlighted ? '0' : '-1', class: {
+                'pds-combobox__option': true,
+                'pds-combobox__option--highlighted': isHighlighted,
+                'pds-combobox__option--layout': isLayout,
+                'pds-combobox__option--chip': isChip,
+                'pds-combobox__option--disabled': isDisabled,
+            }, "data-option-index": index, onMouseDown: this.onOptionMouseDown, onClick: this.onOptionClick, onMouseEnter: this.onOptionMouseEnter, onKeyDown: this.onOptionKeyDown }, isLayout ? (h("pds-box", { class: "pds-combobox__option-layout-wrapper", innerHTML: this.getOptionLayoutContent(option) })) : isChip ? (this.renderOptionChip(option)) : (this.getOptionLabel(option)), isSelected && h("pds-icon", { icon: "check", size: "regular", class: "pds-combobox__option-check" })));
+    }
+    /**
+     * `flyout`: one row per group, its options in a flyout beside it. `drill-in`: the same rows, and
+     * an opened group replaces them with its row, drawn as a row back, above its options. Either way
+     * it's a tree: the rows and ungrouped options are level 1, a group's options level 2.
+     */
+    renderGroupedPanel() {
+        const entries = buildPanelEntries(this.filteredItems);
+        const setsize = entries.length;
+        if (this.effectiveGroupDisplay === 'drill-in' && this.openGroup !== null) {
+            const position = entries.findIndex(entry => entry.kind === 'group' && entry.group.optgroup === this.openGroup);
+            const open = entries[position];
+            if ((open === null || open === void 0 ? void 0 : open.kind) === 'group')
+                return this.renderGroupBackRow(open.group, { posinset: position + 1, setsize });
+        }
+        this.renderedGroups = [];
+        return entries.map((entry, position) => {
+            const placement = { posinset: position + 1, setsize };
+            if (entry.kind === 'option')
+                return this.renderOption(entry.option, entry.index, Object.assign(Object.assign({}, placement), { level: 1 }));
+            this.renderedGroups.push(entry.group);
+            return this.renderGroupRow(entry.group, this.renderedGroups.length - 1, placement);
+        });
+    }
+    /** A group's options, as its children in the tree. */
+    renderGroupOptions(group) {
+        return group.options.map(({ option, index }, position) => this.renderOption(option, index, { posinset: position + 1, setsize: group.options.length, level: 2 }));
+    }
+    /**
+     * Drilled into a group: its treeitem, expanded. Its row reads as a way back ("Back: Tag") and
+     * leads its options.
+     */
+    renderGroupBackRow(group, { posinset, setsize }) {
+        const id = this.groupDomId(group.optgroup);
+        const disabled = isGroupDisabled(group);
+        return (h("li", { key: "group-back", id: id, class: {
+                'pds-combobox__group-back': true,
+                'pds-combobox__group-back--disabled': disabled,
+                'pds-combobox__group-back--highlighted': this.highlightedGroupRow === group.optgroup,
+                'pds-combobox__group-back--keyboard': this.keyboardNavigating && this.highlightedGroupRow === group.optgroup,
+            }, role: "treeitem", "aria-expanded": "true", "aria-disabled": disabled ? 'true' : undefined, "aria-level": 1, "aria-posinset": posinset, "aria-setsize": setsize, "aria-labelledby": `${id}-label` }, h("div", { class: "pds-combobox__group-row-trigger pds-combobox__group-back-trigger", onMouseDown: this.onOptionMouseDown, onMouseEnter: this.onGroupBackMouseEnter, onClick: this.onGroupBackClick }, h("span", { class: "pds-combobox__group-row-label", id: `${id}-label` }, h("pds-icon", { name: "caret-left", size: "regular", "aria-hidden": "true", class: "pds-combobox__group-row-caret" }), h("span", { class: "visually-hidden" }, this.drillInBackLabel, ": "), group.label)), h("ul", { class: "pds-combobox__drill-in-options", role: "group", "aria-label": group.label }, this.renderGroupOptions(group))));
+    }
+    renderGroupRow(group, groupIndex, { posinset, setsize }) {
+        const flyout = this.effectiveGroupDisplay === 'flyout';
+        const isOpen = flyout && this.openGroup === group.optgroup;
+        const hasSelection = group.options.some(({ option }) => this.isOptionSelected(option));
+        const disabled = isGroupDisabled(group);
+        const id = this.groupDomId(group.optgroup);
+        return (h("li", { key: `group-${groupIndex}`, id: id, class: {
+                'pds-combobox__group-row': true,
+                'pds-combobox__group-row--open': isOpen,
+                'pds-combobox__group-row--has-selection': hasSelection,
+                'pds-combobox__group-row--highlighted': this.highlightedGroupRow === group.optgroup,
+                'pds-combobox__group-row--keyboard': this.keyboardNavigating && this.highlightedGroupRow === group.optgroup,
+                'pds-combobox__group-row--disabled': disabled,
+            }, role: "treeitem", "aria-expanded": isOpen ? 'true' : 'false', "aria-disabled": disabled ? 'true' : undefined, "aria-level": 1, "aria-posinset": posinset, "aria-setsize": setsize, "aria-labelledby": `${id}-label`, "data-group-index": groupIndex, onMouseEnter: flyout ? this.onGroupRowMouseEnter : undefined, onMouseLeave: flyout ? this.onGroupRowMouseLeave : undefined }, h("div", { class: "pds-combobox__group-row-trigger", "data-group-index": groupIndex, onMouseDown: this.onOptionMouseDown, onMouseEnter: this.onGroupRowTriggerMouseEnter, onClick: this.onGroupRowClick }, h("span", { class: "pds-combobox__group-row-label", id: `${id}-label` }, group.icon !== null && (
+        // `name`, not `icon`: `icon` also loads URLs and data: SVGs, unsanitized.
+        h("pds-icon", { name: group.icon, size: "regular", "aria-hidden": "true", class: "pds-combobox__group-icon" })), group.label), h("pds-icon", { name: "caret-right", size: "regular", "aria-hidden": "true", class: "pds-combobox__group-row-caret" })), isOpen && (h("ul", { class: "pds-combobox__flyout", role: "group", "aria-label": group.label, style: { minWidth: this.flyoutMinWidth, maxWidth: this.flyoutMaxWidth } }, this.renderGroupOptions(group)))));
     }
     // Helper method to render the caret icon
     renderCaretIcon() {
@@ -1485,13 +2323,13 @@ export class PdsCombobox {
         ]
             .filter(Boolean)
             .join(' ');
-        return (h(Host, { key: 'a39df3c86a29028344943bd3a2828d5e99106d77', "aria-disabled": this.disabled ? 'true' : null }, h("div", { key: '32cdb8ce31f9d7c9eac8f995cd233fe6f4d9dfc3', class: "pds-combobox", tabIndex: -1, onFocusout: this.onComboboxFocusOut, part: "combobox" }, this.label && !this.hideLabel && (h("label", { key: '64ed7fe37082e2f895daae0090ae3dfac472e3c3', htmlFor: this.componentId, class: "pds-combobox__label" }, this.label)), this.trigger === 'input' ? (h("div", { class: "pds-combobox__input-wrapper", style: { width: this.triggerWidth } }, h("input", { ref: el => {
+        return (h(Host, { key: 'd709320411c4d1706133376ea716756c3e1c1471', "aria-disabled": this.disabled ? 'true' : null }, h("div", { key: '455a02fa764524c95fe0bbfd024eba7134b3ac34', class: "pds-combobox", tabIndex: -1, onFocusout: this.onComboboxFocusOut, part: "combobox" }, this.hasVisibleLabel && (h("label", { key: '0d243157491934d823156841e97bfd369e12c2d5', htmlFor: this.trigger === 'input' ? this.componentId : undefined, id: this.labelId, class: "pds-combobox__label", onClick: this.onLabelClick }, this.label)), this.trigger === 'input' ? (h("div", { class: "pds-combobox__input-wrapper", style: { width: this.triggerWidth } }, h("input", { ref: el => {
                 this.inputEl = el;
                 this.triggerEl = el;
             }, class: {
                 'pds-combobox__input': true,
                 'pds-combobox__input--invalid': this.isInvalid(),
-            }, type: "text", role: "combobox", "aria-autocomplete": "list", "aria-controls": this.listboxId, "aria-describedby": assignDescription(this.componentId, this.isInvalid(), this.helperMessage, this.errorMessage), "aria-invalid": this.isInvalid() ? 'true' : undefined, "aria-activedescendant": this.isOpen && this.highlightedIndex >= 0 ? this.optionDomId(this.highlightedIndex) : undefined, "aria-expanded": this.isOpen ? 'true' : 'false', "aria-disabled": this.disabled ? 'true' : 'false', "aria-label": this.hideLabel ? this.label : undefined, id: this.componentId, value: this.displayText, placeholder: this.placeholder, disabled: this.disabled, onInput: this.handleInput, onClick: this.handleInputClick, onKeyDown: this.handleKeyDown, autocomplete: "off", part: "input" }), h("pds-icon", { icon: "enlarge", "aria-hidden": "true", class: "pds-combobox__input-icon" }))) : this.trigger === 'chip' ? (h("div", { class: this.getChipTriggerClass(), style: { width: this.triggerWidth }, role: "combobox", "aria-haspopup": "listbox", "aria-controls": this.listboxId, "aria-describedby": assignDescription(this.componentId, this.isInvalid(), this.helperMessage, this.errorMessage), "aria-invalid": this.isInvalid() ? 'true' : undefined, "aria-activedescendant": this.isOpen && this.highlightedIndex >= 0 ? this.optionDomId(this.highlightedIndex) : undefined, "aria-expanded": this.isOpen ? 'true' : 'false', "aria-disabled": this.disabled ? 'true' : 'false', "aria-label": this.hideLabel ? this.label : undefined, id: this.componentId, tabIndex: this.disabled ? -1 : 0, onClick: this.onButtonTriggerClick, "data-layout": this.customTriggerContent, onKeyDown: this.onButtonTriggerKeyDown, onKeyUp: this.onButtonTriggerKeyUp, ref: el => (this.triggerEl = el), part: "chip-trigger" }, this.renderChipTriggerContent())) : (h("div", { class: triggerClass, style: { width: this.triggerWidth }, role: "combobox", "aria-haspopup": "listbox", "aria-controls": this.listboxId, "aria-describedby": assignDescription(this.componentId, this.isInvalid(), this.helperMessage, this.errorMessage), "aria-invalid": this.isInvalid() ? 'true' : undefined, "aria-activedescendant": this.isOpen && this.highlightedIndex >= 0 ? this.optionDomId(this.highlightedIndex) : undefined, "aria-expanded": this.isOpen ? 'true' : 'false', "aria-disabled": this.disabled ? 'true' : 'false', "aria-label": this.hideLabel ? this.label : undefined, id: this.componentId, tabIndex: this.disabled ? -1 : 0, onClick: this.onButtonTriggerClick, "data-layout": this.customTriggerContent, onKeyDown: this.onButtonTriggerKeyDown, onKeyUp: this.onButtonTriggerKeyUp, ref: el => (this.triggerEl = el), part: "button-trigger" }, this.renderButtonTriggerContent())), this.renderMessages(), h("div", { key: '48041c41a39987f2f4093bd048d6c495ea69514b', style: { display: 'none' } }, h("slot", { key: '5f4d95fefbd3dbdb33ecb25af593c9429df0e10b', onSlotchange: () => this.updateOptions() })), this.renderDropdown())));
+            }, type: "text", role: "combobox", "aria-autocomplete": "list", "aria-haspopup": this.inputPopupRole === 'tree' ? 'tree' : undefined, "aria-controls": this.listboxId, "aria-describedby": assignDescription(this.componentId, this.isInvalid(), this.helperMessage, this.errorMessage), "aria-invalid": this.isInvalid() ? 'true' : undefined, "aria-activedescendant": this.usesPanelSearch ? undefined : this.activeDescendantId, "aria-expanded": this.isOpen ? 'true' : 'false', "aria-disabled": this.disabled ? 'true' : 'false', "aria-label": this.hideLabel ? this.label : undefined, id: this.componentId, value: this.displayText, placeholder: this.placeholder, disabled: this.disabled, onInput: this.handleInput, onClick: this.handleInputClick, onKeyDown: this.handleKeyDown, autocomplete: "off", part: "input" }), h("pds-icon", { icon: "enlarge", "aria-hidden": "true", class: "pds-combobox__input-icon" }))) : this.trigger === 'chip' ? (h("div", { class: this.getChipTriggerClass(), style: { width: this.triggerWidth }, role: this.usesPanelSearch ? 'button' : 'combobox', "aria-haspopup": this.triggerPopupRole, "aria-controls": this.listboxId, "aria-describedby": assignDescription(this.componentId, this.isInvalid(), this.helperMessage, this.errorMessage), "aria-invalid": this.isInvalid() ? 'true' : undefined, "aria-activedescendant": this.usesPanelSearch ? undefined : this.activeDescendantId, "aria-expanded": this.isOpen ? 'true' : 'false', "aria-disabled": this.disabled ? 'true' : 'false', "aria-label": this.triggerAriaLabel, "aria-labelledby": this.triggerLabelledBy, id: this.componentId, tabIndex: this.disabled ? -1 : 0, onClick: this.onButtonTriggerClick, "data-layout": this.customTriggerContent, onKeyDown: this.onButtonTriggerKeyDown, onKeyUp: this.onButtonTriggerKeyUp, ref: el => (this.triggerEl = el), part: "chip-trigger" }, this.renderChipTriggerContent())) : (h("div", { class: triggerClass, style: { width: this.triggerWidth }, role: this.usesPanelSearch ? 'button' : 'combobox', "aria-haspopup": this.triggerPopupRole, "aria-controls": this.listboxId, "aria-describedby": assignDescription(this.componentId, this.isInvalid(), this.helperMessage, this.errorMessage), "aria-invalid": this.isInvalid() ? 'true' : undefined, "aria-activedescendant": this.usesPanelSearch ? undefined : this.activeDescendantId, "aria-expanded": this.isOpen ? 'true' : 'false', "aria-disabled": this.disabled ? 'true' : 'false', "aria-label": this.triggerAriaLabel, "aria-labelledby": this.triggerLabelledBy, id: this.componentId, tabIndex: this.disabled ? -1 : 0, onClick: this.onButtonTriggerClick, "data-layout": this.customTriggerContent, onKeyDown: this.onButtonTriggerKeyDown, onKeyUp: this.onButtonTriggerKeyUp, ref: el => (this.triggerEl = el), part: "button-trigger" }, this.renderButtonTriggerContent())), this.renderMessages(), h("div", { key: 'fd1eb34561f56df05e2f44c7acecde0e56b5e714', style: { display: 'none' } }, h("slot", { key: '68e11626a00175d0926c54086ae815be157e6bf0', onSlotchange: () => this.updateOptions() })), this.renderDropdown(), this.groupDisplay !== 'inline' && (h("span", { key: '6f3c60c3400d411abbed08ddc6e596db097bb097', class: "visually-hidden", role: "status", "aria-live": "polite" }, this.isOpen && this.effectiveGroupDisplay === 'drill-in' && this.openGroup !== null ? this.openGroup.label : '')))));
     }
     static get is() { return "pds-combobox"; }
     static get encapsulation() { return "shadow"; }
@@ -1700,6 +2538,98 @@ export class PdsCombobox {
                 "attribute": "dropdown-mount",
                 "defaultValue": "'host'"
             },
+            "drillInBackLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "'Back'"
+                        }],
+                    "text": "Accessible prefix for the row that returns to the group list when `group-display` is\n`drill-in`, read before the open group's label. Pass a translated string to localize it; defaults to English."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "drill-in-back-label",
+                "defaultValue": "'Back'"
+            },
+            "flyoutMaxWidth": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "'380px'"
+                        }],
+                    "text": "Maximum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "flyout-max-width",
+                "defaultValue": "'380px'"
+            },
+            "flyoutMinWidth": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "'280px'"
+                        }],
+                    "text": "Minimum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value.\nThe flyout is as wide as its options, between this and `flyout-max-width`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "flyout-min-width",
+                "defaultValue": "'280px'"
+            },
+            "groupDisplay": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'inline' | 'flyout' | 'drill-in'",
+                    "resolved": "\"drill-in\" | \"flyout\" | \"inline\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "'inline'"
+                        }],
+                    "text": "How option groups (`<optgroup>`, or the `group` field of `options`) are shown in the dropdown.\n`inline` lists each group's label above its options. `flyout` lists the groups, and opens a\ngroup's options in a panel beside it on hover or click; while searching, the matching options\nare listed under their group labels, and search also matches group labels. `flyout` groups\nby `<optgroup>` (or `group`) only: options under a `<pds-text>` heading are listed ungrouped.\n`drill-in` lists the groups too, but a click replaces the list with that group's options and a\nrow back to the groups; use it where nothing can open beside the dropdown, such as a side\npanel. `flyout` falls back to `drill-in` when there is no room for a flyout on either side."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "group-display",
+                "defaultValue": "'inline'"
+            },
             "helperMessage": {
                 "type": "string",
                 "mutable": false,
@@ -1819,6 +2749,29 @@ export class PdsCombobox {
                 "attribute": "mode",
                 "defaultValue": "'filter'"
             },
+            "panelSearch": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Shows a search field at the top of the dropdown for the `button` and `chip` triggers, which\ncan't be typed into. Search filters the options the same way typing in the `input` trigger\ndoes; in a grouped display it also matches group labels."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "panel-search",
+                "defaultValue": "false"
+            },
             "placeholder": {
                 "type": "string",
                 "mutable": false,
@@ -1838,6 +2791,52 @@ export class PdsCombobox {
                 "reflect": false,
                 "attribute": "placeholder"
             },
+            "searchOptionsLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "'Search options'"
+                        }],
+                    "text": "Accessible label for the search input inside the dropdown panel (`panel-search`). Pass a translated string to localize it; defaults to English."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "search-options-label",
+                "defaultValue": "'Search options'"
+            },
+            "searchPlaceholder": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "'Find...'"
+                        }],
+                    "text": "Placeholder text for the search input inside the dropdown panel (`panel-search`). Pass a translated string to localize it; defaults to English."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "search-placeholder",
+                "defaultValue": "'Find...'"
+            },
             "trigger": {
                 "type": "string",
                 "mutable": false,
@@ -1935,7 +2934,7 @@ export class PdsCombobox {
                 "mutable": false,
                 "complexType": {
                     "original": "ChipSentimentType",
-                    "resolved": "\"accent\" | \"brand\" | \"danger\" | \"info\" | \"neutral\" | \"success\" | \"warning\"",
+                    "resolved": "\"accent\" | \"brand\" | \"danger\" | \"info\" | \"neutral\" | \"solid\" | \"subtle\" | \"success\" | \"warning\"",
                     "references": {
                         "ChipSentimentType": {
                             "location": "import",
@@ -2200,6 +3199,12 @@ export class PdsCombobox {
             "filteredItems": {},
             "highlightedIndex": {},
             "isOpen": {},
+            "openGroup": {},
+            "drillDirection": {},
+            "highlightedGroup": {},
+            "keyboardNavigating": {},
+            "panelQuery": {},
+            "flyoutFallback": {},
             "selectedOption": {},
             "selectedOptionLayoutContent": {},
             "selectedOptionChipProps": {},
@@ -2328,6 +3333,15 @@ export class PdsCombobox {
     static get elementRef() { return "el"; }
     static get watchers() {
         return [{
+                "propName": "groupDisplay",
+                "methodName": "groupDisplayChanged"
+            }, {
+                "propName": "openGroup",
+                "methodName": "openGroupChanged"
+            }, {
+                "propName": "flyoutFallback",
+                "methodName": "flyoutFallbackChanged"
+            }, {
                 "propName": "isOpen",
                 "methodName": "isOpenChanged"
             }, {