@pine-ds/core 3.29.0 → 3.31.1

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

@@ -58,13 +58,45 @@
 .pds-combobox__input::placeholder {
   color: var(--pine-color-text-placeholder);
 }
+.pds-combobox__input.pds-combobox__input--invalid {
+  background: var(--pine-color-red-050);
+  border-color: var(--pine-color-border-danger);
+}
+:host-context([data-theme=dark]) .pds-combobox__input.pds-combobox__input--invalid {
+  background: var(--pine-color-red-950);
+}
+.pds-combobox__input.pds-combobox__input--invalid:hover:not(:disabled) {
+  border-color: var(--pine-color-border-danger);
+}
+.pds-combobox__input.pds-combobox__input--invalid:focus-visible {
+  outline-color: var(--pine-color-focus-ring-danger);
+}
 
 .pds-combobox__input-icon {
   color: var(--pine-color-text-secondary);
   inset-inline-end: var(--pine-dimension-150);
   pointer-events: none;
   position: absolute;
-  z-index: var(--pine-z-index-raised);
+  z-index: calc(var(--pine-z-index-raised) - 1);
+}
+
+.pds-combobox__helper {
+  color: var(--pine-color-text-message);
+  font: var(--pine-typography-body-sm-medium);
+  margin-block-start: var(--pine-dimension-2xs);
+}
+
+.pds-combobox__error {
+  align-items: flex-start;
+  color: var(--pine-color-text-message-danger);
+  display: flex;
+  font: var(--pine-typography-body-sm-medium);
+  gap: var(--pine-dimension-2xs);
+  margin-block-start: var(--pine-dimension-2xs);
+}
+.pds-combobox__error pds-icon {
+  flex-shrink: 0;
+  margin-block-start: var(--pine-dimension-025);
 }
 
 .pds-combobox__listbox {

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

@@ -1,5 +1,5 @@
 import { h, Host } from "@stencil/core";
-import { isSpecTest } from "../../utils/form";
+import { assignDescription, isSpecTest, messageId } from "../../utils/form";
 import { autoUpdate, computePosition, flip, offset, shift } from "@floating-ui/dom";
 import { debounceEvent } from "../../utils/utils";
 import DOMPurify from "dompurify";
@@ -1182,6 +1182,20 @@ export class PdsCombobox {
     async getSelectedValue() {
         return this.selectedOption ? this.selectedOption.value : null;
     }
+    /**
+     * Clears the selected value and resets the component.
+     */
+    async clear() {
+        const hadValue = this.value !== '' || this.displayText !== '';
+        this.displayText = '';
+        this.setSelectedOption(null);
+        this.value = '';
+        this.filterOptions();
+        this.updateFormValue('');
+        if (hadValue) {
+            this.pdsComboboxChange.emit({ value: '' });
+        }
+    }
     // Get the label of the selected option
     get selectedLabel() {
         return this.displayText || '';
@@ -1450,6 +1464,19 @@ export class PdsCombobox {
             ,
             large: chipProps.large, icon: chipProps.icon, dot: chipProps.dot, class: "pds-combobox__option-chip" }, this.getOptionLabel(option)));
     }
+    // Mirrors pds-multiselect and pds-select: an error message on its own puts the
+    // field in an invalid state, so assistive tech agrees with the visual treatment.
+    isInvalid() {
+        return Boolean(this.invalid) || Boolean(this.errorMessage);
+    }
+    renderMessages() {
+        const hasErrorMessage = Boolean(this.errorMessage);
+        const showHelperMessage = Boolean(this.helperMessage) && !hasErrorMessage;
+        return [
+            showHelperMessage && (h("p", { class: "pds-combobox__helper", id: messageId(this.componentId, 'helper') }, this.helperMessage)),
+            hasErrorMessage && (h("p", { class: "pds-combobox__error", id: messageId(this.componentId, 'error'), "aria-live": "assertive" }, h("pds-icon", { icon: "danger", size: "small", "aria-hidden": "true" }), this.errorMessage)),
+        ];
+    }
     render() {
         const triggerClass = [
             'pds-combobox__button-trigger',
@@ -1458,10 +1485,13 @@ export class PdsCombobox {
         ]
             .filter(Boolean)
             .join(' ');
-        return (h(Host, { key: '3de5711e53460545e3cb962d446880a99edcd44c', "aria-disabled": this.disabled ? 'true' : null }, h("div", { key: 'cce16999fc6be08b99a113ae58cb2be0fbe9c577', class: "pds-combobox", tabIndex: -1, onFocusout: this.onComboboxFocusOut, part: "combobox" }, this.label && !this.hideLabel && (h("label", { key: '355650eba712d6c91694752daed4cf18008a920d', 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: '25ce0fc749a909555762a44ff7ff089ab65465d4', "aria-disabled": this.disabled ? 'true' : null }, h("div", { key: '8f10f691452c1b793fd31b719f43de04b1ea064b', class: "pds-combobox", tabIndex: -1, onFocusout: this.onComboboxFocusOut, part: "combobox" }, this.label && !this.hideLabel && (h("label", { key: 'af6ee018cc15d1bc0b75b7d33530e2678fe6017b', 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 => {
                 this.inputEl = el;
                 this.triggerEl = el;
-            }, class: "pds-combobox__input", type: "text", role: "combobox", "aria-autocomplete": "list", "aria-controls": this.listboxId, "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-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-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())), h("div", { key: '87ffd9a2472b7459343daf4c0f7d46f260365180', style: { display: 'none' } }, h("slot", { key: 'fd0e21c876fbf21761ad63c9529a304912aecd1d', onSlotchange: () => this.updateOptions() })), this.renderDropdown())));
+            }, 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: '586e443fb97fbe74888d6c296db63a0ed7c95787', style: { display: 'none' } }, h("slot", { key: '9a287c316d09bc4cc7fd94ad7dbdbf5458753162', onSlotchange: () => this.updateOptions() })), this.renderDropdown())));
     }
     static get is() { return "pds-combobox"; }
     static get encapsulation() { return "shadow"; }
@@ -1582,6 +1612,25 @@ export class PdsCombobox {
                 "attribute": "disabled",
                 "defaultValue": "false"
             },
+            "errorMessage": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Error message to display."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "error-message"
+            },
             "dropdownPlacement": {
                 "type": "string",
                 "mutable": false,
@@ -1651,6 +1700,25 @@ export class PdsCombobox {
                 "attribute": "dropdown-mount",
                 "defaultValue": "'host'"
             },
+            "helperMessage": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Helper message to display below the combobox."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "helper-message"
+            },
             "hideLabel": {
                 "type": "boolean",
                 "mutable": false,
@@ -1671,6 +1739,25 @@ export class PdsCombobox {
                 "attribute": "hide-label",
                 "defaultValue": "false"
             },
+            "invalid": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "If true, the combobox is in an invalid state."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "invalid"
+            },
             "label": {
                 "type": "string",
                 "mutable": false,
@@ -2218,6 +2305,23 @@ export class PdsCombobox {
                     "text": "Gets the value of the currently selected option.",
                     "tags": []
                 }
+            },
+            "clear": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Clears the selected value and resets the component.",
+                    "tags": []
+                }
             }
         };
     }

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

@@ -10,7 +10,10 @@ export default {
     dropdownPlacement: 'bottom-start',
     dropdownMount: 'host',
     dropdownWidth: '236px',
+    errorMessage: null,
+    helperMessage: null,
     hideLabel: false,
+    invalid: false,
     maxHeight: null,
     mode: 'filter',
     trigger: 'input',
@@ -38,7 +41,10 @@ const BaseTemplate = (args) => html`
   dropdown-placement=${args.dropdownPlacement}
   dropdown-mount=${args.dropdownMount}
   dropdown-width=${args.dropdownWidth}
+  error-message=${args.errorMessage}
+  helper-message=${args.helperMessage}
   hide-label=${args.hideLabel}
+  invalid=${args.invalid}
   max-height=${args.maxHeight}
   label=${args.label}
   placeholder=${args.placeholder}
@@ -70,6 +76,25 @@ Default.args = {
   value: 'panda',
 };
 
+export const HelperMessage = BaseTemplate.bind();
+HelperMessage.args = {
+  componentId: 'combobox-helper-story',
+  name: 'favoriteAnimal',
+  label: 'Favorite Animal',
+  placeholder: 'placeholder_text',
+  helperMessage: 'Start typing to filter the list.',
+};
+
+export const ErrorMessage = BaseTemplate.bind();
+ErrorMessage.args = {
+  componentId: 'combobox-error-story',
+  name: 'favoriteAnimal',
+  label: 'Favorite Animal',
+  placeholder: 'placeholder_text',
+  errorMessage: 'Please choose an animal.',
+  invalid: true,
+};
+
 export const ButtonTrigger = BaseTemplate.bind();
 ButtonTrigger.args = {
   componentId: 'combobox-button-trigger-story',
@@ -83,6 +108,41 @@ ButtonTrigger.args = {
   value: 'dog',
 };
 
+export const ProgrammaticClear = (args) => html`
+<pds-box direction="column" gap="sm" align-items="start">
+  <pds-combobox
+    id="combobox-clear-story"
+    component-id=${args.componentId}
+    name=${args.name}
+    label=${args.label}
+    placeholder=${args.placeholder}
+    trigger=${args.trigger}
+    mode=${args.mode}
+    value=${args.value}
+  >
+    <option value="cat">Cat</option>
+    <option value="dog">Dog</option>
+    <option value="panda">Panda</option>
+    <option value="snake">Snake</option>
+  </pds-combobox>
+  <pds-button
+    variant="secondary"
+    size="sm"
+    @click=${() => document.querySelector('#combobox-clear-story').clear()}
+  >
+    Reset
+  </pds-button>
+</pds-box>`;
+ProgrammaticClear.args = {
+  componentId: 'combobox-clear-story',
+  name: 'favoriteAnimal',
+  label: 'Favorite Animal',
+  placeholder: 'Select an animal',
+  trigger: 'input',
+  mode: 'filter',
+  value: 'panda',
+};
+
 export const ChipTriggerAndLayout = (args) => html`
 <pds-box min-width="100%" direction="row" gap="sm" wrap>
   <pds-combobox

package/dist/collection/components/pds-input/pds-input.css

@@ -37,7 +37,7 @@
   top: 50%;
   transform: translateY(-50%);
   white-space: nowrap;
-  z-index: var(--pine-z-index-raised);
+  z-index: calc(var(--pine-z-index-raised) - 1);
 }
 :host::part(prefix) {
   border-end-start-radius: var(--pds-input-border-radius);

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

@@ -289,7 +289,7 @@ export class PdsInput {
         return (h(Host, { key: 'ecf4cc212e5c3ebc18082b790803e6b2ccb8ca77', "aria-disabled": this.disabled ? 'true' : null, "aria-readonly": this.readonly ? 'true' : null, "has-prefix": this.hasPrefix ? 'true' : null, "has-suffix": this.hasSuffix ? 'true' : null, "has-prepend": this.hasPrepend ? 'true' : null, "has-append": this.hasAppend ? 'true' : null, "has-action": this.hasAction && !this.hideLabel ? 'true' : null, "full-width": this.fullWidth ? 'true' : null }, h("div", { key: 'acdf92a30068fc04a17816ec6d85295b47e512ee', class: "pds-input" }, label && (h("div", { key: '4569f0b3761db89e85a090eff6af1c47cb562115', class: {
                 'pds-input__label-wrapper': true,
                 'visually-hidden': this.hideLabel,
-            } }, h("label", { key: '90b0a863d78115fa158429db11548fc2a9ee5ae6', htmlFor: componentId, class: "pds-input__label" }, h("span", { key: '3d440aaafc4daeffe45152cd23d27472d7ebf85a' }, label, this.required && h("span", { key: 'c7bf6ef6191e961a106b8885cab604aa89730eba', class: "pds-input__required-indicator" }, " *"))), !this.hideLabel && this.renderAction())), h("div", { key: '81f0b8a347bc9a06c753b9f31f5e30ac78e45adb', class: inputWrapperClasses }, this.renderPrepend(), this.renderPrefix(), h("input", Object.assign({ key: '3785b396bf9174766973e8b19028e4dcecde19d9', ref: (input) => (this.nativeInput = input), class: "pds-input__field", "aria-describedby": assignDescription(componentId, invalid, helperMessage), "aria-invalid": invalid ? "true" : undefined, autocomplete: this.autocomplete, disabled: disabled, id: componentId, max: this.max, maxlength: this.maxlength, min: this.min, minlength: this.minlength, name: this.name, pattern: this.pattern, placeholder: this.placeholder, readOnly: this.readonly, required: this.required, step: this.step, type: this.type, value: value, onInput: this.onInputEvent, onChange: this.onChangeEvent, onBlur: this.onBlurEvent, onFocus: this.onFocusEvent, onKeyDown: this.onKeyDownEvent, onCompositionstart: this.onCompositionStart, onCompositionend: this.onCompositionEnd }, this.inheritedAttributes)), this.renderSuffix(), this.renderAppend()), helperMessage && (h("p", { key: 'e9e4aa936346811e0a5ca0fa5107f548b52fcc99', class: "pds-input__helper-message", id: messageId(componentId, 'helper') }, helperMessage)), errorMessage && (h("p", { key: 'ef3694246fa3d8f818da438e7ec4411dd56b084c', class: "pds-input__error-message", id: messageId(componentId, 'error') }, h("pds-icon", { key: 'f1e488b33c8338f54cd83a59e219311a844e3c97', "aria-hidden": "true", icon: danger, size: "small" }), errorMessage)))));
+            } }, h("label", { key: '90b0a863d78115fa158429db11548fc2a9ee5ae6', htmlFor: componentId, class: "pds-input__label" }, h("span", { key: '3d440aaafc4daeffe45152cd23d27472d7ebf85a' }, label, this.required && h("span", { key: 'c7bf6ef6191e961a106b8885cab604aa89730eba', class: "pds-input__required-indicator" }, " *"))), !this.hideLabel && this.renderAction())), h("div", { key: '81f0b8a347bc9a06c753b9f31f5e30ac78e45adb', class: inputWrapperClasses }, this.renderPrepend(), this.renderPrefix(), h("input", Object.assign({ key: '41ed8dab6f7c71c6c382627ca4dc48bb95c1161d', ref: (input) => (this.nativeInput = input), class: "pds-input__field", "aria-describedby": assignDescription(componentId, invalid, helperMessage, errorMessage), "aria-invalid": invalid ? "true" : undefined, autocomplete: this.autocomplete, disabled: disabled, id: componentId, max: this.max, maxlength: this.maxlength, min: this.min, minlength: this.minlength, name: this.name, pattern: this.pattern, placeholder: this.placeholder, readOnly: this.readonly, required: this.required, step: this.step, type: this.type, value: value, onInput: this.onInputEvent, onChange: this.onChangeEvent, onBlur: this.onBlurEvent, onFocus: this.onFocusEvent, onKeyDown: this.onKeyDownEvent, onCompositionstart: this.onCompositionStart, onCompositionend: this.onCompositionEnd }, this.inheritedAttributes)), this.renderSuffix(), this.renderAppend()), helperMessage && (h("p", { key: '4791ddeb01b758a94a2fddfec6093b9b39eefafa', class: "pds-input__helper-message", id: messageId(componentId, 'helper') }, helperMessage)), errorMessage && (h("p", { key: 'd0a22ae4b0e400e1d5df55e35c0aaaa5c5ea3ab7', class: "pds-input__error-message", id: messageId(componentId, 'error') }, h("pds-icon", { key: '69975cdcc15e5ab6df9e2c354977e2c6dae18f6e', "aria-hidden": "true", icon: danger, size: "small" }), errorMessage)))));
     }
     static get is() { return "pds-input"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/components/pds-modal/pds-modal-content/pds-modal-content.js

@@ -1,4 +1,5 @@
 import { h, Host } from "@stencil/core";
+import { unwrapReconnectedContent } from "../../../utils/reconnected-content";
 export class PdsModalContent {
     constructor() {
         /**
@@ -12,6 +13,10 @@ export class PdsModalContent {
          */
         this.userSetBorder = false;
     }
+    // Unwraps a nested .pds-modal-content left by a page-cache (Turbo, bfcache) reconnect.
+    componentDidRender() {
+        unwrapReconnectedContent(this.el.querySelector('.pds-modal-content'), '.pds-modal-content');
+    }
     componentWillLoad() {
         // Check if border was explicitly set via attribute or property
         const borderAttr = this.el.getAttribute('border');
@@ -173,10 +178,10 @@ export class PdsModalContent {
     render() {
         // Only apply max-height style if it's not 'none'
         const styleObj = this.contentMaxHeight !== 'none' ? { maxHeight: this.contentMaxHeight } : {};
-        return (h(Host, { key: 'fae42c1fc151e4855cd2c731802c15851473be79' }, h("div", { key: 'feb61d6a7227d8113b931df6280358cd9b4fe583', class: {
+        return (h(Host, { key: 'f3e75b90be56bb27ba5f4fde473fac474846f346' }, h("div", { key: '5035d5fa319fe2aaa8adffb825f0d2babfd11a26', class: {
                 'pds-modal-content': true,
                 [`pds-modal-content--border-${this.border}`]: true
-            }, style: styleObj, tabindex: "-1" }, h("slot", { key: '1c9e55ecd1ad353699e5a4590ee04c9005719f6d' }))));
+            }, style: styleObj, tabindex: "-1" }, h("slot", { key: '73299f6f7045ea50a5bf134da04f1e30cd9f233c' }))));
     }
     static get is() { return "pds-modal-content"; }
     static get originalStyleUrls() {

package/dist/collection/components/pds-modal/pds-modal-footer/pds-modal-footer.js

@@ -1,7 +1,12 @@
 import { h } from "@stencil/core";
+import { unwrapReconnectedContent } from "../../../utils/reconnected-content";
 export class PdsModalFooter {
+    // Unwraps a nested .pds-modal__footer left by a page-cache (Turbo, bfcache) reconnect.
+    componentDidRender() {
+        unwrapReconnectedContent(this.el.querySelector('.pds-modal__footer'), '.pds-modal__footer');
+    }
     render() {
-        return (h("footer", { key: '0fa58ce225ce31a1f40d6ce1d3276e716b36de8d', class: "pds-modal__footer" }, h("slot", { key: 'df0bbdb56c711c7eb34db7181f940de11d4449ef' })));
+        return (h("footer", { key: '1220d6319585df0128924ebac52569af7645f525', class: "pds-modal__footer" }, h("slot", { key: '1bbbf4897f41c802fc5773154cee3930290c906a' })));
     }
     static get is() { return "pds-modal-footer"; }
     static get originalStyleUrls() {
@@ -14,4 +19,5 @@ export class PdsModalFooter {
             "$": ["pds-modal-footer.css"]
         };
     }
+    static get elementRef() { return "el"; }
 }

package/dist/collection/components/pds-modal/pds-modal-header/pds-modal-header.js

@@ -1,7 +1,12 @@
 import { h } from "@stencil/core";
+import { unwrapReconnectedContent } from "../../../utils/reconnected-content";
 export class PdsModalHeader {
+    // Unwraps a nested .pds-modal__header left by a page-cache (Turbo, bfcache) reconnect.
+    componentDidRender() {
+        unwrapReconnectedContent(this.el.querySelector('.pds-modal__header'), '.pds-modal__header');
+    }
     render() {
-        return (h("header", { key: '1a471bd6dfa2b654f5a6ebdf8fb5baef728324b3', class: "pds-modal__header" }, h("slot", { key: '946a365ab3c2ca627d618188890d385c054b4c16' })));
+        return (h("header", { key: '0fd8a216ae8dc149b59cd29c8706d5a45a21de15', class: "pds-modal__header" }, h("slot", { key: '4bf075dfd4870621e6e0b710fcdb42aac53810b3' })));
     }
     static get is() { return "pds-modal-header"; }
     static get originalStyleUrls() {
@@ -14,4 +19,5 @@ export class PdsModalHeader {
             "$": ["pds-modal-header.css"]
         };
     }
+    static get elementRef() { return "el"; }
 }

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

@@ -1,4 +1,5 @@
 import { h } from "@stencil/core";
+import { unwrapReconnectedContent } from "../../utils/reconnected-content";
 export class PdsModal {
     constructor() {
         this.focusableElements = [];
@@ -22,6 +23,16 @@ export class PdsModal {
          * @default true
          */
         this.scrollable = true;
+        /**
+         * Whether the modal opens outside the browser top layer as a non-modal dialog.
+         * When `true` it opens with `dialog.show()` instead of `dialog.showModal()`, so
+         * overlays rendered elsewhere in the DOM (file pickers, editor menus) can display
+         * above it via `z-index`. The page is not made inert and focus is not trapped in
+         * this mode. Read when the modal opens; changing it while the modal is open is
+         * not supported.
+         * @default false
+         */
+        this.disableTopLayer = false;
         /**
          * Stores the list of focusable elements in the modal
          */
@@ -43,6 +54,13 @@ export class PdsModal {
                 return;
             // Handle Escape key to close the modal
             if (e.key === 'Escape') {
+                // In non-top-layer mode, focus can move into an overlay stacked above the
+                // modal (the reason disableTopLayer exists). If that overlay owns focus,
+                // leave Escape to it rather than dismissing this modal out from under it.
+                const active = document.activeElement;
+                if (this.disableTopLayer && active && active !== document.body && !this.el.contains(active)) {
+                    return;
+                }
                 // Always prevent native dialog close behavior
                 e.preventDefault();
                 // Only close if backdropDismiss is enabled and this is the innermost modal
@@ -53,6 +71,11 @@ export class PdsModal {
             }
             // Handle Tab key for focus trapping
             if (e.key === 'Tab') {
+                // In non-top-layer mode the modal is deliberately not focus-isolated: focus
+                // must be able to leave it into overlays stacked above (the whole point of
+                // disableTopLayer), so do not trap Tab here.
+                if (this.disableTopLayer)
+                    return;
                 // If there are no focusable elements, do nothing
                 if (this.focusableElements.length === 0)
                     return;
@@ -84,6 +107,10 @@ export class PdsModal {
         // Add keyboard event listener
         document.addEventListener('keydown', this.handleKeyDown);
     }
+    // Unwraps a nested dialog.pds-modal__backdrop left by a page-cache (Turbo, bfcache) reconnect.
+    componentDidRender() {
+        unwrapReconnectedContent(this.el.querySelector('.pds-modal'), 'dialog.pds-modal__backdrop', '.pds-modal');
+    }
     disconnectedCallback() {
         // Clean up event listener
         document.removeEventListener('keydown', this.handleKeyDown);
@@ -170,8 +197,16 @@ export class PdsModal {
             try {
                 // Store the currently focused element to restore focus when modal closes
                 this.previousActiveElement = document.activeElement;
-                // Use native dialog showModal method which makes the rest of the page inert
-                this.modalRef.showModal();
+                // showModal() promotes the dialog to the browser top layer (and makes the
+                // rest of the page inert), which prevents any overlay outside the dialog
+                // from ever painting above it. show() opens a non-modal dialog that stays
+                // in the normal stacking context so those overlays can stack above it.
+                if (this.disableTopLayer) {
+                    this.modalRef.show();
+                }
+                else {
+                    this.modalRef.showModal();
+                }
                 this.open = true;
                 // Update focusable elements and set initial focus
                 // Using a longer timeout to ensure all components are fully rendered
@@ -233,14 +268,14 @@ export class PdsModal {
         return thisZIndex === maxZIndex;
     }
     render() {
-        return (h("dialog", { key: 'cf2710a889d8f0e80a3551088ab38a88dc44ad1e', class: {
+        return (h("dialog", { key: '134e913f0bf5d7bf77e67f00707a399fae986fcb', class: {
                 'pds-modal__backdrop': true,
                 'open': this.open
-            }, "aria-modal": "true", "aria-labelledby": `${this.componentId}-heading`, onClick: this.handleBackdropClick }, h("div", { key: 'a06d017153e67ad38bc1ced56ba22aeade977aaf', class: {
+            }, "aria-modal": this.disableTopLayer ? 'false' : 'true', "aria-labelledby": `${this.componentId}-heading`, onClick: this.handleBackdropClick }, h("div", { key: '6cb819a92c00b5c8676b4d1a84301896373305f3', class: {
                 'pds-modal': true,
                 [`pds-modal--${this.size}`]: true,
                 'pds-modal--scrollable': this.scrollable
-            }, part: "modal" }, h("slot", { key: 'd995c586809a4940c091912244a86cb4605a961c' }))));
+            }, part: "modal" }, h("slot", { key: 'aff0f88a7b9e1b4b681a6a14636153ce3a6907d5' }))));
     }
     static get is() { return "pds-modal"; }
     static get originalStyleUrls() {
@@ -365,6 +400,29 @@ export class PdsModal {
                 "reflect": false,
                 "attribute": "scrollable",
                 "defaultValue": "true"
+            },
+            "disableTopLayer": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Whether the modal opens outside the browser top layer as a non-modal dialog.\nWhen `true` it opens with `dialog.show()` instead of `dialog.showModal()`, so\noverlays rendered elsewhere in the DOM (file pickers, editor menus) can display\nabove it via `z-index`. The page is not made inert and focus is not trapped in\nthis mode. Read when the modal opens; changing it while the modal is open is\nnot supported."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disable-top-layer",
+                "defaultValue": "false"
             }
         };
     }

package/dist/collection/components/pds-modal/stories/pds-modal.stories.js

@@ -8,6 +8,7 @@ export default {
   args: {
     backdropDismiss: true,
     componentId: 'modal-demo',
+    disableTopLayer: false,
     open: false,
     scrollable: true,
     size: 'md',
@@ -26,6 +27,7 @@ const BaseTemplate = (args) => html`
       component-id="${args.componentId}"
       size="${args.size}"
       ?backdrop-dismiss=${args.backdropDismiss}
+      ?disable-top-layer=${args.disableTopLayer}
       scrollable="${args.scrollable}"
       ?open=${args.open}
       key="${args.scrollable ? 'scrollable' : 'non-scrollable'}"
@@ -652,3 +654,78 @@ export const CustomBorders = CustomBordersTemplate.bind({});
 CustomBorders.args = {
   componentId: 'custom-borders-modal',
 };
+
+// Demonstrates `disable-top-layer`: the modal opens as a non-modal dialog
+// (dialog.show()) so an overlay appended to document.body can display above it.
+// With the default top-layer behavior the same overlay would render behind the
+// modal and be unreachable.
+const DisableTopLayerTemplate = (args) => html`
+  <div style="padding: 1rem;">
+    <pds-button onClick="document.querySelector('#${args.componentId}').open = true">
+      Open Modal (disable-top-layer)
+    </pds-button>
+
+    <pds-modal
+      id="${args.componentId}"
+      component-id="${args.componentId}"
+      size="${args.size}"
+      ?backdrop-dismiss=${args.backdropDismiss}
+      ?disable-top-layer=${args.disableTopLayer}
+      ?open=${args.open}
+    >
+      <pds-modal-header>
+        <pds-box direction="column" fit padding="md">
+          <pds-box align-items="center" fit justify-content="space-between">
+            <pds-text tag="h2" size="h3">Modal Title</pds-text>
+            <pds-button
+              class="pds-modal__close"
+              variant="unstyled"
+              icon-only="true"
+              onclick="document.querySelector('#${args.componentId}').open = false"
+              aria-label="Close modal"
+              part="close-button"
+            >
+              <pds-icon slot="start" name="remove" aria-hidden="true"></pds-icon>
+            </pds-button>
+          </pds-box>
+        </pds-box>
+      </pds-modal-header>
+
+      <pds-modal-content>
+        <pds-box fit direction="column" padding-inline-start="md" padding-inline-end="md" gap="sm">
+          <p>
+            This modal uses <code>disable-top-layer</code>, so it renders in the normal stacking
+            context instead of the browser top layer.
+          </p>
+          <p>
+            An overlay appended to <code>document.body</code> with a higher <code>z-index</code> can
+            therefore display above it &mdash; useful for file pickers, rich-text editor menus, and
+            other body-mounted overlays that would otherwise be trapped behind a top-layer dialog.
+          </p>
+          <pds-button
+            variant="secondary"
+            onclick="(function(){var o=document.createElement('button');o.type='button';o.textContent='Overlay above the modal — focusable, keyboard-dismissable. Click or press Enter.';o.setAttribute('style','position:fixed;inset:auto 2rem 2rem auto;max-width:20rem;padding:1rem;border:0;text-align:start;border-radius:8px;background:#111;color:#fff;z-index:2147483647;cursor:pointer;box-shadow:0 8px 24px rgba(0,0,0,.4)');var modal=document.querySelector('#${args.componentId}');var remove=function(){o.remove()};o.onclick=remove;o.addEventListener('keydown',function(e){if(e.key==='Escape')remove()});if(modal)modal.addEventListener('pdsModalClose',remove,{once:true});document.body.appendChild(o);o.focus();})()"
+          >
+            Show overlay above modal
+          </pds-button>
+        </pds-box>
+      </pds-modal-content>
+
+      <pds-modal-footer>
+        <pds-box justify-content="end" fit padding="md" gap="sm">
+          <pds-button variant="secondary" onclick="document.querySelector('#${args.componentId}').open = false">
+            Close
+          </pds-button>
+        </pds-box>
+      </pds-modal-footer>
+    </pds-modal>
+  </div>
+`;
+
+export const DisableTopLayer = DisableTopLayerTemplate.bind({});
+DisableTopLayer.args = {
+  componentId: 'disable-top-layer-modal',
+  disableTopLayer: true,
+  size: 'md',
+  open: false,
+};

package/dist/collection/components/pds-multiselect/pds-multiselect.css

@@ -291,7 +291,7 @@
 
 .pds-multiselect__helper {
   color: var(--pine-color-text-message);
-  font: var(--pine-typography-body-sm);
+  font: var(--pine-typography-body-sm-medium);
   margin-block-start: var(--pine-dimension-2xs);
   margin-inline-start: var(--pine-dimension-none);
 }
@@ -300,7 +300,7 @@
   align-items: flex-start;
   color: var(--pine-color-text-message-danger);
   display: flex;
-  font: var(--pine-typography-body-sm);
+  font: var(--pine-typography-body-sm-medium);
   gap: var(--pine-dimension-2xs);
   margin-block-start: var(--pine-dimension-2xs);
   margin-inline-start: var(--pine-dimension-none);