@pine-ds/core 4.10.0 → 4.12.0

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

@@ -10,6 +10,10 @@ import { FlyoutController, buildPanelEntries, findGroup, groupBadgeOf, groupIcon
  * @slot trigger-content - Custom content for the button trigger when customTriggerContent is true
  * @slot empty - Custom empty state message when no options match
  * @slot loading - Custom loading indicator
+ * @part button-trigger - Exposes the button trigger for styling. Appears only when `trigger` is `button`.
+ * @part chip-trigger - Exposes the chip trigger for styling. Appears only when `trigger` is `chip`.
+ * @part combobox - Exposes the outer container around the label, trigger and messages for styling.
+ * @part input - Exposes the native `input` element for styling. Appears only when `trigger` is `input`, the default.
  */
 export class PdsCombobox {
     constructor() {
@@ -35,11 +39,6 @@ export class PdsCombobox {
          * @default 'bottom-start'
          */
         this.dropdownPlacement = 'bottom-start';
-        /**
-         * Width of the dropdown. Any valid CSS width value.
-         * @default '236px'
-         */
-        this.dropdownWidth = '236px';
         /**
          * Where to mount the dropdown listbox (`host` or `body`, sometimes called “append to body”).
          * Use `body` inside scrollable containers (for example modals) so the list is not clipped by
@@ -67,16 +66,18 @@ export class PdsCombobox {
          */
         this.noOptionsFoundLabel = 'No options found';
         /**
-         * Maximum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value.
-         * @default '380px'
+         * Maximum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width
+         * value, including its padding.
+         * @default '388px'
          */
-        this.flyoutMaxWidth = '380px';
+        this.flyoutMaxWidth = '388px';
         /**
-         * 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'
+         * Minimum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width
+         * value, including its padding. The flyout is as wide as its options, between this and
+         * `flyout-max-width`.
+         * @default '288px'
          */
-        this.flyoutMinWidth = '280px';
+        this.flyoutMinWidth = '288px';
         /**
          * 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
@@ -163,7 +164,7 @@ export class PdsCombobox {
          */
         this.chipDot = false;
         /**
-         * The value of the combobox input.
+         * The `value` of the selected option.
          */
         this.value = '';
         /**
@@ -287,15 +288,30 @@ export class PdsCombobox {
          * the list shows every option until the user types (then normal filtering applies).
          */
         this.expandFilterListWhileOpen = false;
+        this.onHeightGlideCancel = (event) => {
+            const panel = this.listboxEl;
+            if (event.animationName !== 'pds-combobox-height-glide' || event.target !== panel)
+                return;
+            // Turning around mid-glide cancels the old glide as the new one starts; only a glide with none
+            // left running cleans up.
+            const running = panel.getAnimations().some(a => a.animationName === 'pds-combobox-height-glide');
+            // A drill waiting to render glides from here next; it cleans up then.
+            if (!running && this.drillFromHeight === undefined)
+                this.endHeightGlide();
+        };
         this.onPanelPointer = (event) => {
             const canHover = event.pointerType !== 'touch';
             if (this.pointerCanHover !== canHover)
                 this.pointerCanHover = canHover;
         };
         this.onDrillAnimationEnd = (event) => {
-            // Only the slide's own end: slotted consumer content can animate inside the list too.
+            // Only the component's own ends (the slide by name, the glide by its target): slotted consumer
+            // content can animate inside the list too.
             if (event.animationName === 'pds-combobox-drill')
                 this.drillDirection = null;
+            if (event.animationName === 'pds-combobox-height-glide' && event.target === this.listboxEl && this.drillFromHeight === undefined) {
+                this.endHeightGlide();
+            }
         };
         /** `<label for>` only works on the input trigger; for a div trigger a click on the label focuses it. */
         this.onLabelClick = () => {
@@ -593,6 +609,8 @@ export class PdsCombobox {
                 }
             }
         };
+        /** A pick that fills the field from its placeholder fades in; a value it loads with doesn't. */
+        this.fadesValueIn = false;
         this.handleScroll = (e) => {
             if (!this.asyncUrl || !this.hasMore || this.loading)
                 return;
@@ -711,6 +729,14 @@ export class PdsCombobox {
         if (this.usesBodyPortal && this.isOpen) {
             this.syncBodyPortal();
         }
+        // Opening places the dropdown a tick later, which can run before the dropdown has rendered and
+        // then skips it, leaving it without its dropdown-width and max-height. Place a newly rendered
+        // dropdown here too.
+        if (this.isOpen && this.triggerEl && this.listboxEl && this.listboxEl !== this.placedListboxEl) {
+            this.placedListboxEl = this.listboxEl;
+            void this.positionDropdown();
+        }
+        this.glideDrillHeight();
         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) {
@@ -719,18 +745,6 @@ export class PdsCombobox {
         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();
@@ -758,8 +772,7 @@ export class PdsCombobox {
      * Scrolls just enough to show `el`, as `scrollIntoView({ block: 'nearest' })` does. In the drill-in
      * panel it scrolls the list alone, and never sideways: while a drill-in slide offsets a row past
      * the list's edge, `scrollIntoView` also scrolls the list horizontally to reach it, which eats most
-     * of the slide. There it keeps clear of the sticky row back, through the scroll padding set for it,
-     * but doesn't scroll the page or a scrolling ancestor.
+     * of the slide. It doesn't scroll the page or a scrolling ancestor.
      */
     scrollIntoViewNearest(el, smooth) {
         const behavior = smooth ? 'smooth' : 'auto';
@@ -767,18 +780,29 @@ export class PdsCombobox {
             el.scrollIntoView({ block: 'nearest', behavior });
             return;
         }
-        const list = this.usesPanelSearch ? this.panelTreeEl : this.listboxEl;
+        // The row back is the drilled-in header, above the scrolling options: always in view.
+        if (el.classList.contains('pds-combobox__group-back-trigger'))
+            return;
+        const list = this.scrollListEl;
         if (!list)
             return;
         const offset = el.getBoundingClientRect().top - list.getBoundingClientRect().top - list.clientTop;
-        // The padding keeps rows clear of the sticky row back; the row back itself doesn't need it.
-        const padding = el.classList.contains('pds-combobox__group-back-trigger') ? 0 : parseFloat(list.style.scrollPaddingBlockStart) || 0;
-        const top = list.scrollTop + offset - padding;
+        const top = list.scrollTop + offset;
         const bottom = list.scrollTop + offset + el.offsetHeight - list.clientHeight;
         const target = top < list.scrollTop ? top : bottom > list.scrollTop ? bottom : null;
         if (target !== null)
             list.scrollTo({ top: target, behavior });
     }
+    /**
+     * The element that scrolls the panel's rows. Every layer is a header (the search field, or a
+     * drilled-in group's row back) above the rows that scroll: drilled in, the group's options;
+     * otherwise the list under the search field, or the panel itself.
+     */
+    get scrollListEl() {
+        var _a;
+        const list = this.usesPanelSearch ? this.panelTreeEl : this.listboxEl;
+        return (_a = list === null || list === void 0 ? void 0 : list.querySelector('.pds-combobox__group-back > .pds-combobox__drill-in-options')) !== null && _a !== void 0 ? _a : list;
+    }
     focusPanel(el) {
         var _a, _b;
         this.panelFocusEl = el;
@@ -796,6 +820,7 @@ export class PdsCombobox {
         this.openGroup = null;
         // The reset isn't a drill-out, so it doesn't slide either.
         this.drillDirection = null;
+        this.endHeightGlide();
     }
     openGroupChanged(next, previous) {
         this.handPanelFocusToList();
@@ -807,6 +832,74 @@ export class PdsCombobox {
             this.drillDirection = 'in';
         else if (next === null && previous !== null)
             this.drillDirection = 'out';
+        else
+            return;
+        // The views differ in height; measured now, before the next one renders, so it can glide.
+        const panel = this.listboxEl;
+        if (!panel)
+            return;
+        const from = panel.getBoundingClientRect().height;
+        this.drillFromHeight = from;
+        // Pinned there until componentDidRender measures the new view, however late: a child component
+        // that renders late could otherwise let the browser paint the new view at its full height first.
+        panel.style.height = `${from}px`;
+        panel.classList.add('pds-combobox__listbox--height-hold');
+        this.syncPanelOverflow();
+    }
+    releaseHeightHold() {
+        const panel = this.listboxEl;
+        panel === null || panel === void 0 ? void 0 : panel.style.removeProperty('height');
+        panel === null || panel === void 0 ? void 0 : panel.classList.remove('pds-combobox__listbox--height-hold');
+    }
+    /**
+     * Hands the dropdown's height before and after a drill to the SCSS glide. Neither is known ahead,
+     * so they're measured: CSS can't animate to the height its content turns out to be.
+     */
+    glideDrillHeight() {
+        const from = this.drillFromHeight;
+        this.drillFromHeight = undefined;
+        const panel = this.listboxEl;
+        if (from === undefined || !panel)
+            return;
+        // A drill back mid-glide starts from where the last one is now, then measures the real height.
+        this.releaseHeightHold();
+        panel.classList.remove('pds-combobox__listbox--height-glide');
+        this.syncPanelOverflow();
+        const to = panel.getBoundingClientRect().height;
+        if (Math.abs(to - from) < 1) {
+            this.endHeightGlide();
+            return;
+        }
+        panel.style.setProperty('--pds-combobox-glide-from', `${from}px`);
+        panel.style.setProperty('--pds-combobox-glide-to', `${to}px`);
+        panel.classList.add('pds-combobox__listbox--height-glide');
+        this.syncPanelOverflow();
+        // A glide cut short without ending (the panel hidden mid-way) still cleans up. JSX has no
+        // `onAnimationCancel`; adding the same listener again is a no-op.
+        panel.addEventListener('animationcancel', this.onHeightGlideCancel);
+    }
+    /** Ends a glide, and a drill still waiting to glide, so nothing starts once it renders. */
+    endHeightGlide() {
+        this.drillFromHeight = undefined;
+        this.releaseHeightHold();
+        const panel = this.listboxEl;
+        panel === null || panel === void 0 ? void 0 : panel.classList.remove('pds-combobox__listbox--height-glide');
+        this.syncPanelOverflow();
+        panel === null || panel === void 0 ? void 0 : panel.style.removeProperty('--pds-combobox-glide-from');
+        panel === null || panel === void 0 ? void 0 : panel.style.removeProperty('--pds-combobox-glide-to');
+        panel === null || panel === void 0 ? void 0 : panel.removeEventListener('animationcancel', this.onHeightGlideCancel);
+    }
+    /**
+     * With `max-height`, the panel's own scroll, set inline so it outranks the stylesheet: hidden under a
+     * fixed search field, and while the height glides (so no scrollbar flashes), otherwise auto.
+     */
+    syncPanelOverflow() {
+        var _a;
+        if (((_a = this.maxHeight) !== null && _a !== void 0 ? _a : '') === '' || !this.listboxEl)
+            return;
+        const gliding = this.listboxEl.classList.contains('pds-combobox__listbox--height-glide') ||
+            this.listboxEl.classList.contains('pds-combobox__listbox--height-hold');
+        this.listboxEl.style.overflowY = this.usesPanelSearch || gliding ? 'hidden' : 'auto';
     }
     /** A flyout with no room beside the dropdown drills in, which can hide the focused search field too. */
     flyoutFallbackChanged() {
@@ -838,6 +931,7 @@ export class PdsCombobox {
     }
     isOpenChanged(isOpen) {
         if (!isOpen) {
+            this.endHeightGlide();
             this.revealedGroupLabel = null;
             this.drillDirection = null;
             this.openGroup = null;
@@ -1197,61 +1291,66 @@ export class PdsCombobox {
             this.updateOptionsFromAsync();
             return;
         }
-        // Get all elements from the slot
+        // Get all elements from the slot. Before the first render there's no slot yet, so read the
+        // host's own children that it will hold (through any slot passing options on): otherwise a
+        // combobox created with a `value`, such as a form re-rendered after a pick, paints its
+        // placeholder for a frame, until `slotchange` finds the selected option.
         const slot = (_a = this.el.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector('slot[name="option"], slot:not([name])');
-        if (slot) {
-            const allElements = slot.assignedElements({ flatten: true });
-            // Separate options from group labels and flatten optgroups
-            this.allItems = [];
-            this.optionEls = [];
-            allElements.forEach(el => {
-                if (el.tagName === 'OPTION') {
-                    this.optionEls.push(el);
-                    this.allItems.push(el);
-                }
-                else if (el.tagName === 'OPTGROUP') {
-                    const optgroup = el;
-                    this.allItems.push(optgroup);
-                    // Add optgroup children (options)
-                    Array.from(optgroup.children).forEach(child => {
-                        if (child.tagName === 'OPTION') {
-                            this.optionEls.push(child);
-                            this.allItems.push(child);
-                        }
-                    });
-                }
-                else if (el.tagName === 'PDS-TEXT') {
-                    this.allItems.push(el);
-                }
-            });
-            // Set initial selected option based on value property
-            let initialSelected = null;
-            // Check if value property matches any option
-            if (this.value) {
-                initialSelected = this.optionEls.find(opt => opt.value === this.value) || null;
-                if (initialSelected) {
-                    // Update the display text to show the option's text content
-                    this.displayText = this.getOptionLabel(initialSelected);
-                    // Keep this.value as the actual option value (already correct)
-                }
-            }
-            // For chip triggers, ensure we always have a selected option
-            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 enabled option.');
+        const allElements = slot
+            ? slot.assignedElements({ flatten: true })
+            : Array.from(this.el.children)
+                .filter(el => !el.getAttribute('slot'))
+                .flatMap(el => (el.tagName === 'SLOT' ? el.assignedElements({ flatten: true }) : [el]));
+        // Separate options from group labels and flatten optgroups
+        this.allItems = [];
+        this.optionEls = [];
+        allElements.forEach(el => {
+            if (el.tagName === 'OPTION') {
+                this.optionEls.push(el);
+                this.allItems.push(el);
+            }
+            else if (el.tagName === 'OPTGROUP') {
+                const optgroup = el;
+                this.allItems.push(optgroup);
+                // Add optgroup children (options)
+                Array.from(optgroup.children).forEach(child => {
+                    if (child.tagName === 'OPTION') {
+                        this.optionEls.push(child);
+                        this.allItems.push(child);
+                    }
+                });
             }
-            // Update selection if we found a different selected option or if we don't have one
-            if (initialSelected && initialSelected !== this.selectedOption) {
-                this.setSelectedOption(initialSelected);
+            else if (el.tagName === 'PDS-TEXT') {
+                this.allItems.push(el);
             }
-            else if (!this.selectedOption && initialSelected) {
-                this.setSelectedOption(initialSelected);
+        });
+        // Set initial selected option based on value property
+        let initialSelected = null;
+        // Check if value property matches any option
+        if (this.value) {
+            initialSelected = this.optionEls.find(opt => opt.value === this.value) || null;
+            if (initialSelected) {
+                // Update the display text to show the option's text content
+                this.displayText = this.getOptionLabel(initialSelected);
+                // Keep this.value as the actual option value (already correct)
             }
-            this.filterOptions();
         }
+        // For chip triggers, ensure we always have a selected option
+        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 enabled option.');
+        }
+        // Update selection if we found a different selected option or if we don't have one
+        if (initialSelected && initialSelected !== this.selectedOption) {
+            this.setSelectedOption(initialSelected);
+        }
+        else if (!this.selectedOption && initialSelected) {
+            this.setSelectedOption(initialSelected);
+        }
+        this.filterOptions();
     }
     // Helper method to get option label, falling back to text content if no label attribute
     getOptionLabel(option) {
@@ -1327,10 +1426,19 @@ export class PdsCombobox {
         else {
             this.selectedOptionChipProps = null;
         }
+        // Immediately update layout content too, the same way: the @Watch('selectedOption') below
+        // isn't active yet the first time this runs, during componentWillLoad's initial selection,
+        // so a preselected layout option would otherwise show its plain label until some later change
+        // triggers the watcher.
+        this.selectedOptionLayoutContent = option && this.isOptionLayout(option)
+            ? this.getOptionLayoutContent(option)
+            : '';
     }
     filterOptions() {
-        // A new list replaces the rows a slide was animating, so its end event may never come.
+        // A new list replaces the rows a slide or height glide was animating, so their end events may
+        // never come.
         this.drillDirection = null;
+        this.endHeightGlide();
         // Ensure allItems includes optionEls if not already populated (for edge cases)
         if (this.allItems.length === 0 && this.optionEls.length > 0) {
             this.allItems = [...this.optionEls];
@@ -1349,11 +1457,13 @@ export class PdsCombobox {
                     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 || '';
+                // `data-search-text`, when set, is what search matches, so an option can be found by more
+                // than its label without a custom layout. A layout option otherwise matches its text.
+                const searchText = option.getAttribute('data-search-text');
+                if (searchText)
                     return searchText.toLowerCase().includes(val);
-                }
+                if (this.isOptionLayout(option))
+                    return (option.textContent || '').toLowerCase().includes(val);
                 return this.getOptionLabel(option).toLowerCase().includes(val);
             });
             // Rebuild filtered items maintaining group structure - simplified approach
@@ -1403,6 +1513,7 @@ export class PdsCombobox {
         }
     }
     positionDropdown() {
+        var _a;
         if (!this.triggerEl || !this.listboxEl) {
             return;
         }
@@ -1410,21 +1521,24 @@ export class PdsCombobox {
         const zIndex = this.usesBodyPortal
             ? 'var(--pine-z-index-priority)'
             : 'var(--pine-z-index-raised)';
-        this.listboxEl.style.width = this.dropdownWidth;
+        // Unset, the panel's own width applies, which differs with its padding (see the dropdown panel styles).
+        this.listboxEl.style.width = (_a = this.dropdownWidth) !== null && _a !== void 0 ? _a : '';
         if (this.maxHeight) {
             this.listboxEl.style.maxHeight = this.maxHeight;
             // With panel search, the options list scrolls under a fixed search field.
-            this.listboxEl.style.overflowY = this.usesPanelSearch ? 'hidden' : 'auto';
+            this.syncPanelOverflow();
         }
         this.listboxEl.offsetHeight;
         return computePosition(this.triggerEl, this.listboxEl, {
             placement: this.dropdownPlacement,
             strategy,
-            middleware: [offset(12), flip(), shift({ padding: 5 })],
-        }).then(({ x, y }) => {
+            middleware: [offset(8), flip(), shift({ padding: 5 })],
+        }).then(({ x, y, placement }) => {
             if (!this.listboxEl) {
                 return;
             }
+            // Where it landed after flipping, so the opening motion moves away from the field.
+            this.listboxEl.dataset.placement = placement;
             Object.assign(this.listboxEl.style, {
                 left: `${x}px`,
                 top: `${y}px`,
@@ -1710,6 +1824,8 @@ export class PdsCombobox {
     highlightOptionAt(options, index) {
         if (options.length === 0)
             return;
+        // Only the keys move it, so it shows the keyboard's ring, as in the grouped panel.
+        this.keyboardNavigating = true;
         this.highlightedIndex = Math.max(0, Math.min(options.length - 1, index));
         this.updateOptionFocus();
     }
@@ -2137,6 +2253,8 @@ export class PdsCombobox {
     handleOptionClick(option) {
         if (isOptionDisabled(option))
             return;
+        if (this.selectedIcon === null)
+            this.fadesValueIn = true;
         // Update reactive state - single source of truth
         // The @Watch('selectedOption') will handle displayText, value, and form internals
         this.setSelectedOption(option);
@@ -2144,12 +2262,34 @@ export class PdsCombobox {
         this.clearExpandFilterList();
         this.pdsComboboxChange.emit({ value: option.value });
     }
+    /** The row shown while options load: at the top of the list, or of a drilled-in group's options. */
+    renderLoadingRow() {
+        if (!this.loading)
+            return null;
+        const hasSlottedLoading = !this.usesBodyPortal && !!this.el.querySelector('[slot="loading"]');
+        return (h("li", { class: "pds-combobox__loading", role: "presentation" }, hasSlottedLoading ? h("slot", { name: "loading" }) : h("pds-loader", { size: "small" })));
+    }
+    /** The row after the last option while more can load, inside whatever scrolls them. */
+    renderLoadMoreRow() {
+        if (!this.hasMore || this.loading)
+            return null;
+        return (h("li", { class: "pds-combobox__load-more", role: "presentation" }, h("pds-loader", { size: "small" })));
+    }
+    /** Drilled into a group: the group and its place among the panel's entries; otherwise null. */
+    drilledInEntry(entries) {
+        if (this.effectiveGroupDisplay !== 'drill-in' || this.openGroup === null)
+            return null;
+        const position = entries.findIndex(entry => entry.kind === 'group' && entry.group.optgroup === this.openGroup);
+        const open = entries[position];
+        return (open === null || open === void 0 ? void 0 : open.kind) === 'group' ? { group: open.group, position } : null;
+    }
     renderDropdown() {
         if (!this.isOpen) {
             return null;
         }
         const hasSlottedEmpty = !this.usesBodyPortal && !!this.el.querySelector('[slot="empty"]');
-        const hasSlottedLoading = !this.usesBodyPortal && !!this.el.querySelector('[slot="loading"]');
+        // Drilled in, the group's options scroll under the row back, so their loading rows go with them.
+        const drilledIn = this.showsGroupedPanel && this.drilledInEntry(this.panelEntries()) !== null;
         const selectableOptions = this.filteredItems.filter(item => item.tagName === 'OPTION');
         const withSearch = this.usesPanelSearch;
         // While a drilled-in group hides the search field, the list takes focus in its place.
@@ -2171,11 +2311,11 @@ export class PdsCombobox {
                     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, this.noOptionsFoundLabel)))), 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" })))));
+            }, onScroll: this.handleScroll }, !drilledIn && this.renderLoadingRow(), !this.loading && this.filteredItems.length === 0 && (h("li", { class: "pds-combobox__empty", role: "presentation" }, hasSlottedEmpty ? (h("slot", { name: "empty" })) : (h("span", null, this.noOptionsFoundLabel)))), this.showsGroupedPanel ? this.renderGroupedPanel() : this.renderListboxItems(selectableOptions.length), !drilledIn && this.renderLoadMoreRow()));
         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,
+        return (h("div", { class: "pds-combobox__listbox pds-combobox__listbox--with-search", ref: el => (this.listboxEl = el), onAnimationEnd: this.onDrillAnimationEnd, 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));
     }
@@ -2315,7 +2455,11 @@ export class PdsCombobox {
         return true;
     }
     renderPanelSearch() {
-        return (h("div", { key: "panel-search", class: "pds-combobox__panel-search" }, h("pds-icon", { name: "search", size: "regular", "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 })));
+        return (h("div", { key: "panel-search", class: {
+                'pds-combobox__panel-search': true,
+                // Coming back from a group, the search field slides in with the groups.
+                'pds-combobox__panel-search--drill-out': this.drillDirection === 'out',
+            } }, h("pds-icon", { name: "search", size: "regular", "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
@@ -2334,6 +2478,8 @@ export class PdsCombobox {
                 : badge && `${this.getOptionLabel(option)}, ${badge.label}`, tabindex: this.usesBodyPortal || this.usesPanelSearch || tree ? '-1' : isHighlighted ? '0' : '-1', class: {
                 'pds-combobox__option': true,
                 'pds-combobox__option--highlighted': isHighlighted,
+                // The keyboard's place, as on the group rows (`--keyboard`).
+                'pds-combobox__option--keyboard': isHighlighted && this.keyboardNavigating,
                 'pds-combobox__option--layout': isLayout,
                 'pds-combobox__option--chip': isChip,
                 'pds-combobox__option--disabled': isDisabled,
@@ -2395,12 +2541,9 @@ export class PdsCombobox {
     renderGroupedPanel() {
         const entries = this.panelEntries();
         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 });
-        }
+        const drilled = this.drilledInEntry(entries);
+        if (drilled)
+            return this.renderGroupBackRow(drilled.group, { posinset: drilled.position + 1, setsize });
         this.renderedGroups = [];
         return entries.map((entry, position) => {
             const placement = { posinset: position + 1, setsize };
@@ -2428,13 +2571,13 @@ export class PdsCombobox {
                 // As the group rows: shaded for the keys, and by `:hover` for the pointer.
                 'pds-combobox__group-back--highlighted': this.keyboardNavigating && 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))));
+            }, 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, onScroll: this.handleScroll }, this.renderLoadingRow(), this.renderGroupOptions(group), this.renderLoadMoreRow())));
     }
     renderGroupRow(group, groupIndex, { posinset, setsize }) {
         const flyout = this.effectiveGroupDisplay === 'flyout';
         const isOpen = flyout && this.openGroup === group.optgroup;
-        // Drill-in shades a group row only for the keys: not for the group holding the selection, or the
-        // row the pointer or a click-open left highlighted, which read as picked. `:hover` covers the pointer.
+        // `--has-selection` is a state hook only (tests read it), not styled. The fill follows
+        // `--highlighted` (always in flyout, in drill-in only for the keys) and a flyout's `--open` row.
         const hasSelection = flyout && group.options.some(({ option }) => this.isOptionSelected(option));
         const isCurrent = this.highlightedGroupRow === group.optgroup;
         const disabled = isGroupDisabled(group);
@@ -2465,6 +2608,7 @@ export class PdsCombobox {
                 'pds-combobox__button-trigger-label': true,
                 'pds-combobox__button-trigger-label--placeholder': !this.selectedLabel,
                 'pds-combobox__button-trigger-label--with-icon': icon !== null,
+                'pds-combobox__button-trigger-label--value-in': icon !== null && this.fadesValueIn,
             } }, icon !== null && (
         // `name`, not `icon`: `icon` also loads URLs and data: SVGs, unsanitized.
         h("pds-icon", { name: icon, size: "regular", "aria-hidden": "true", class: "pds-combobox__button-trigger-icon" })), this.truncate ? (
@@ -2605,13 +2749,13 @@ export class PdsCombobox {
         ]
             .filter(Boolean)
             .join(' ');
-        return (h(Host, { key: '104eb1c4cdca4494b10dea660e27a98b0c18bf64', "aria-disabled": this.disabled ? 'true' : null }, h("div", { key: '2548ff2b304bb6a5a249b5059a0b60b55cdf2152', class: "pds-combobox", tabIndex: -1, onFocusout: this.onComboboxFocusOut, part: "combobox" }, this.hasVisibleLabel && (h("label", { key: '7a261c72452ca7a278e1067e41c6eed52f29edc8', 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 => {
+        return (h(Host, { key: '3a7f09752d2dff0fbf653852cd9ea474a44c61d5', "aria-disabled": this.disabled ? 'true' : null }, h("div", { key: '56d3bf86655abfd945228ee0bc3a556a6ad766b3', class: "pds-combobox", tabIndex: -1, onFocusout: this.onComboboxFocusOut, part: "combobox" }, this.hasVisibleLabel && (h("label", { key: 'a07f37d62bca1b15df3aa258d94c0df4609b93b3', 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-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, onMouseEnter: this.truncate ? this.onButtonTriggerMouseEnter : undefined, ref: el => (this.triggerEl = el), part: "button-trigger" }, this.renderButtonTriggerContent())), this.renderMessages(), h("div", { key: 'ffd3bc72b34a7278f3fa706a236017a26b86ea3f', style: { display: 'none' } }, h("slot", { key: 'f47a81191ad7fd8c6bf63cf8ef39934cbf7fd28c', onSlotchange: () => this.updateOptions() })), this.renderDropdown(), this.groupDisplay !== 'inline' && [
+            }, 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, onMouseEnter: this.truncate ? this.onButtonTriggerMouseEnter : undefined, ref: el => (this.triggerEl = el), part: "button-trigger" }, this.renderButtonTriggerContent())), this.renderMessages(), h("div", { key: '0c0accd76b79aba9fa3072eb68800102d458d0a7', style: { display: 'none' } }, h("slot", { key: 'be9cc4c897788342bbc96321f033ed4fd97e80ff', onSlotchange: () => this.updateOptions() })), this.renderDropdown(), this.groupDisplay !== 'inline' && [
             h("span", { key: "drill-status", class: "visually-hidden", role: "status", "aria-live": "polite" }, this.isOpen && this.effectiveGroupDisplay === 'drill-in' && this.openGroup !== null ? this.openGroup.label : ''),
             // Its own region: sharing one, revealing a row then opening it would leave the text the
             // same, and opening the group would go unannounced.
@@ -2788,19 +2932,15 @@ export class PdsCombobox {
                     "references": {}
                 },
                 "required": false,
-                "optional": false,
+                "optional": true,
                 "docs": {
-                    "tags": [{
-                            "name": "default",
-                            "text": "'236px'"
-                        }],
-                    "text": "Width of the dropdown. Any valid CSS width value."
+                    "tags": [],
+                    "text": "Width of the dropdown, including its padding. Any valid CSS width value.\nWithout it, the dropdown is 252px wide, 244px with grouped options and 236px with a panel search."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": false,
-                "attribute": "dropdown-width",
-                "defaultValue": "'236px'"
+                "attribute": "dropdown-width"
             },
             "dropdownMount": {
                 "type": "string",
@@ -2884,15 +3024,15 @@ export class PdsCombobox {
                 "docs": {
                     "tags": [{
                             "name": "default",
-                            "text": "'380px'"
+                            "text": "'388px'"
                         }],
-                    "text": "Maximum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value."
+                    "text": "Maximum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width\nvalue, including its padding."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": false,
                 "attribute": "flyout-max-width",
-                "defaultValue": "'380px'"
+                "defaultValue": "'388px'"
             },
             "flyoutMinWidth": {
                 "type": "string",
@@ -2907,15 +3047,15 @@ export class PdsCombobox {
                 "docs": {
                     "tags": [{
                             "name": "default",
-                            "text": "'280px'"
+                            "text": "'288px'"
                         }],
-                    "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`."
+                    "text": "Minimum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width\nvalue, including its padding. The flyout is as wide as its options, between this and\n`flyout-max-width`."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": false,
                 "attribute": "flyout-min-width",
-                "defaultValue": "'280px'"
+                "defaultValue": "'288px'"
             },
             "groupDisplay": {
                 "type": "string",
@@ -3369,7 +3509,7 @@ export class PdsCombobox {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "The value of the combobox input."
+                    "text": "The `value` of the selected option."
                 },
                 "getter": false,
                 "setter": false,