@pine-ds/core 3.29.0 → 3.30.0

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

@@ -22,6 +22,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 +53,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 +70,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;
@@ -170,8 +192,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 +263,14 @@ export class PdsModal {
         return thisZIndex === maxZIndex;
     }
     render() {
-        return (h("dialog", { key: 'cf2710a889d8f0e80a3551088ab38a88dc44ad1e', class: {
+        return (h("dialog", { key: 'd345ea0a585213fd7879a2fe27071705fbdba79b', 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: '34c9a222d58ffd9736a36ab6848679186167e878', 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: '4eef9c3001b6a7c972fa8e49fa3f0b140c7fe7ce' }))));
     }
     static get is() { return "pds-modal"; }
     static get originalStyleUrls() {
@@ -365,6 +395,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);

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

@@ -1031,16 +1031,16 @@ export class PdsMultiselect {
                 'pds-multiselect__trigger--invalid': this.invalid || !!this.errorMessage,
                 'pds-multiselect__trigger--has-value': hasSelections,
                 'pds-multiselect__trigger--pill-inline': true,
-            }, onClick: this.handleTriggerClick }, this.renderInlinePills(), h("button", { ref: el => (this.triggerEl = el), type: "button", id: this.componentId, part: "pill-toggle", class: "pds-multiselect__pill-toggle", disabled: this.disabled, "aria-expanded": this.isOpen ? 'true' : 'false', "aria-haspopup": "listbox", "aria-labelledby": this.label ? `${this.componentId}-label` : undefined, "aria-required": this.required ? 'true' : undefined, "aria-describedby": assignDescription(this.componentId, this.invalid || !!this.errorMessage, this.errorMessage || this.helperMessage), "aria-invalid": this.invalid || !!this.errorMessage ? 'true' : undefined, onKeyDown: this.handleTriggerKeyDown }, h("pds-icon", { class: "pds-multiselect__icon", icon: enlarge })))) : (h("button", { ref: el => (this.triggerEl = el), type: "button", part: "trigger", class: {
+            }, onClick: this.handleTriggerClick }, this.renderInlinePills(), h("button", { ref: el => (this.triggerEl = el), type: "button", id: this.componentId, part: "pill-toggle", class: "pds-multiselect__pill-toggle", disabled: this.disabled, "aria-expanded": this.isOpen ? 'true' : 'false', "aria-haspopup": "listbox", "aria-labelledby": this.label ? `${this.componentId}-label` : undefined, "aria-required": this.required ? 'true' : undefined, "aria-describedby": assignDescription(this.componentId, this.invalid || !!this.errorMessage, this.helperMessage, this.errorMessage), "aria-invalid": this.invalid || !!this.errorMessage ? 'true' : undefined, onKeyDown: this.handleTriggerKeyDown }, h("pds-icon", { class: "pds-multiselect__icon", icon: enlarge })))) : (h("button", { ref: el => (this.triggerEl = el), type: "button", part: "trigger", class: {
                 'pds-multiselect__trigger': true,
                 'pds-multiselect__trigger--open': this.isOpen,
                 'pds-multiselect__trigger--disabled': this.disabled,
                 'pds-multiselect__trigger--invalid': this.invalid || !!this.errorMessage,
                 'pds-multiselect__trigger--has-value': hasSelections,
-            }, id: this.componentId, disabled: this.disabled, "aria-required": this.required ? 'true' : undefined, "aria-expanded": this.isOpen ? 'true' : 'false', "aria-haspopup": "listbox", "aria-describedby": assignDescription(this.componentId, this.invalid || !!this.errorMessage, this.errorMessage || this.helperMessage), "aria-invalid": this.invalid || !!this.errorMessage ? 'true' : undefined, onClick: this.handleTriggerClick, onKeyDown: this.handleTriggerKeyDown }, h("span", { class: {
+            }, id: this.componentId, disabled: this.disabled, "aria-required": this.required ? 'true' : undefined, "aria-expanded": this.isOpen ? 'true' : 'false', "aria-haspopup": "listbox", "aria-describedby": assignDescription(this.componentId, this.invalid || !!this.errorMessage, this.helperMessage, this.errorMessage), "aria-invalid": this.invalid || !!this.errorMessage ? 'true' : undefined, onClick: this.handleTriggerClick, onKeyDown: this.handleTriggerKeyDown }, h("span", { class: {
                 'pds-multiselect__trigger-text': true,
                 'pds-multiselect__trigger-text--placeholder': !hasSelections || (this.selectedDisplay === 'pill' && this.pillPosition === 'below'),
-            } }, this.getTriggerText()), h("pds-icon", { class: "pds-multiselect__icon", icon: enlarge }))), this.renderDropdown()), this.selectedDisplay === 'pill' && this.pillPosition === 'below' && this.renderBelowPills(), h("span", { key: '973443f9eb29dcf7fb1bde3f9101ac02967a8fd9', class: "visually-hidden", "aria-live": "polite", "aria-atomic": "true" }, this.removalAnnouncement), this.helperMessage && !(this.errorMessage && this.errorMessage.length > 0) && (h("p", { key: '568aab2b278abb7f4426d84ee926b4883375fb11', class: "pds-multiselect__helper", id: messageId(this.componentId, 'helper') }, this.helperMessage)), this.errorMessage && (h("p", { key: 'daddf192efd47df8c15267b9896913b926e02544', class: "pds-multiselect__error", id: messageId(this.componentId, 'error') }, h("pds-icon", { key: 'd0c72ab75a8e02e61c09e980ae817790804a776a', icon: danger, size: "small" }), this.errorMessage)), h("div", { key: '0453db2fca10b3573b1dd244875f90c856c8887b', style: { display: 'none' } }, h("slot", { key: 'a612741afc9545e5e50c47d27c3c27c1d7cade3c' })))));
+            } }, this.getTriggerText()), h("pds-icon", { class: "pds-multiselect__icon", icon: enlarge }))), this.renderDropdown()), this.selectedDisplay === 'pill' && this.pillPosition === 'below' && this.renderBelowPills(), h("span", { key: '199804f5352818d32542864e3a61f7a9364cc2e3', class: "visually-hidden", "aria-live": "polite", "aria-atomic": "true" }, this.removalAnnouncement), this.helperMessage && !(this.errorMessage && this.errorMessage.length > 0) && (h("p", { key: 'e6855ff0aaf18f59dced2df5d636cadb4d47427b', class: "pds-multiselect__helper", id: messageId(this.componentId, 'helper') }, this.helperMessage)), this.errorMessage && (h("p", { key: '29eae23d8db31b9b9c292d5cd1dc5f641613ed32', class: "pds-multiselect__error", id: messageId(this.componentId, 'error') }, h("pds-icon", { key: 'aad6fd945998957cd28ab6eb97c4d80f0a732ea5', icon: danger, size: "small" }), this.errorMessage)), h("div", { key: '7d0d56a1e097cfc0c7396c1957d16014cb071b1e', style: { display: 'none' } }, h("slot", { key: '6e7fc9dbdab3977248439aa5ea14f13e0f45bbc6' })))));
     }
     static get is() { return "pds-multiselect"; }
     static get encapsulation() { return "shadow"; }

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

@@ -59,6 +59,9 @@
   color: var(--pine-color-text-label-disabled);
   cursor: not-allowed;
 }
+:host(.has-border):has(input:disabled) label::after {
+  cursor: not-allowed;
+}
 :host(.has-border).is-invalid .pds-radio__message--error {
   color: var(--pine-color-text-message-danger);
 }
@@ -255,6 +258,9 @@ label:has(input:disabled) {
   color: var(--pine-color-text-label-disabled);
   cursor: not-allowed;
 }
+:host(.has-image).is-disabled label::after {
+  cursor: not-allowed;
+}
 :host(.has-image).is-disabled .pds-radio__message {
   color: var(--pine-color-text-label-disabled);
 }

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

@@ -80,11 +80,11 @@ export class PdsRadio {
     }
     render() {
         const renderLabelAndMessages = () => [
-            h("label", { htmlFor: this.componentId, key: `${this.componentId}-label` }, h("input", { key: '75aca490be2db050f66ddd9cb45ce122bea4db53', "aria-describedby": assignDescription(this.componentId, this.invalid, this.helperMessage), "aria-invalid": this.invalid ? "true" : undefined, type: "radio", id: this.componentId, name: this.name, value: this.value, checked: this.checked, required: this.required, disabled: this.disabled, onChange: this.handleRadioChange, class: this.hasImage() ? 'visually-hidden' : '' }), h("span", { key: '1bbc7398d3be35e301526b0f842274a3f1db4457', class: this.hideLabel ? 'visually-hidden' : '' }, this.label)),
+            h("label", { htmlFor: this.componentId, key: `${this.componentId}-label` }, h("input", { key: 'ca6cb85ace418259f13b6be404e125d4c1c3a778', "aria-describedby": assignDescription(this.componentId, this.invalid, this.helperMessage, this.errorMessage), "aria-invalid": this.invalid ? "true" : undefined, type: "radio", id: this.componentId, name: this.name, value: this.value, checked: this.checked, required: this.required, disabled: this.disabled, onChange: this.handleRadioChange, class: this.hasImage() ? 'visually-hidden' : '' }), h("span", { key: '968c3dcc6b3e18a177db0570a9104b4755827a3e', class: this.hideLabel ? 'visually-hidden' : '' }, this.label)),
             this.helperMessage && (h("div", { key: `${this.componentId}-helper`, class: 'pds-radio__message', id: messageId(this.componentId, 'helper') }, this.helperMessage)),
-            this.errorMessage && (h("div", { key: `${this.componentId}-error`, class: `pds-radio__message pds-radio__message--error`, id: messageId(this.componentId, 'error'), "aria-live": "assertive" }, h("pds-icon", { key: 'e1a1228fa52e68623098f09493d93aa03d2e65c4', icon: danger, size: "small" }), this.errorMessage))
+            this.errorMessage && (h("div", { key: `${this.componentId}-error`, class: `pds-radio__message pds-radio__message--error`, id: messageId(this.componentId, 'error'), "aria-live": "assertive" }, h("pds-icon", { key: '2dec1d43ade25a8ff70301fb661174eff5efadeb', icon: danger, size: "small" }), this.errorMessage))
         ];
-        return (h(Host, { key: '60fabeef5778fd30e46cfd23d05684e1743bc57f', class: this.classNames() }, this.hasImage() && (h("div", { key: '9ba3e60182a68cc8e996623cf46e17001ff451f6', class: "pds-radio__image-container", part: "image-container" }, h("slot", { key: 'bf8927129eb68ee7ed07a1f8f8727f013254e133', name: "image", onSlotchange: () => (this._hasImage = this.hasImageSlot()) }))), this.hasImage() ? (h("div", { class: "pds-radio__content-wrapper" }, renderLabelAndMessages())) : (renderLabelAndMessages())));
+        return (h(Host, { key: '75563601db01d7db2a4c4e74364c0bb2d57ac9ae', class: this.classNames() }, this.hasImage() && (h("div", { key: '120ca4dd9d3828cda49c0f7539f429e2aaa89329', class: "pds-radio__image-container", part: "image-container" }, h("slot", { key: 'a03496e1acc3799740aa20342408de97991cad68', name: "image", onSlotchange: () => (this._hasImage = this.hasImageSlot()) }))), this.hasImage() ? (h("div", { class: "pds-radio__content-wrapper" }, renderLabelAndMessages())) : (renderLabelAndMessages())));
     }
     static get is() { return "pds-radio"; }
     static get encapsulation() { return "scoped"; }

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

@@ -1,5 +1,5 @@
 import { Host, h } from "@stencil/core";
-import { isSpecTest, messageId, exposeTypeProperty } from "../../utils/form";
+import { assignDescription, isSpecTest, messageId, exposeTypeProperty } from "../../utils/form";
 import { danger, enlarge } from "@pine-ds/icons/icons";
 /**
  * @slot action - Content to be displayed in the label area, typically for help icons or links
@@ -140,6 +140,11 @@ export class PdsSelect {
             return null;
         return (h("div", { class: "pds-select__message" }, this.getHelperMessage(), this.getErrorMessage()));
     }
+    // The field also renders as invalid whenever an error message is present, via
+    // `select:has(~ .pds-select__message .pds-select__error-message)` in the styles.
+    isInvalid() {
+        return Boolean(this.invalid) || Boolean(this.errorMessage);
+    }
     classNames() {
         const classNames = [];
         if (this.invalid) {
@@ -223,7 +228,7 @@ export class PdsSelect {
     }
     render() {
         const hasAction = this.el.querySelector('[slot="action"]') !== null;
-        return (h(Host, { key: '71f6bfba3361eaac3459c1b30b23183503b57ae5', "aria-disabled": this.disabled ? 'true' : null, class: this.classNames(), "has-action": hasAction && !this.hideLabel ? 'true' : null }, h("div", { key: 'cbd0059fc405179a59c29f81510d2948e358531c', class: "pds-select" }, !this.hideLabel && (h("div", { key: '87d42d145ec0a46a474bb599e46226efc72d1acb', class: "pds-select__label-wrapper" }, h("label", { key: '23e4b10a8b99023d1779de0eb6c56ff31189dce1', htmlFor: this.componentId }, h("span", { key: 'b655a0850ce9ce173fbd814461df8529c9c150d9', class: this.hideLabel ? 'visually-hidden' : '' }, this.label)), hasAction && this.renderAction())), h("select", { key: 'a9f2cd048cdea6f0a44305a2760c418617d7c0eb', "aria-label": this.hideLabel ? this.label : undefined, autocomplete: this.autocomplete || undefined, class: "pds-select__field", disabled: this.disabled, id: this.componentId, multiple: this.multiple, name: this.name, onBlur: this.onBlur, onChange: this.onSelectUpdate, onFocus: this.onFocus, onKeyDown: this.onKeyDown, part: "select", required: this.required, ref: (el) => (this.selectEl = el) }), h("div", { key: 'cca5b1b634d1d77bc4164cb196fdd1c4ffcb888e', "aria-hidden": "true", class: "hidden", ref: (el) => (this.slotContainer = el) }, h("slot", { key: '018780883212786a89c5e6f776dc8c69853bf732', onSlotchange: this.handleSlotChange })), this.renderMessages(), !this.multiple && h("pds-icon", { key: '10e82ad220b4e9d8d9c0710a14335d5603bd6164', "aria-hidden": "true", class: "pds-select__select-icon", icon: enlarge }))));
+        return (h(Host, { key: 'c74f5e86a09bd3fe6e8048ca103ec9aa66a98fc6', "aria-disabled": this.disabled ? 'true' : null, class: this.classNames(), "has-action": hasAction && !this.hideLabel ? 'true' : null }, h("div", { key: '76de23d6b0d9e32fab48e09a8f6ee3211e196115', class: "pds-select" }, !this.hideLabel && (h("div", { key: '1db87074447cbc819e6b06dd89135d018656a471', class: "pds-select__label-wrapper" }, h("label", { key: 'bc28c3b3361a19ee14a1b79edda736340009d87d', htmlFor: this.componentId }, h("span", { key: 'f0828e0e83c7c0d7cf50e08df4b861dad4df9eb9', class: this.hideLabel ? 'visually-hidden' : '' }, this.label)), hasAction && this.renderAction())), h("select", { key: 'd7d254887c976a95ad1f1da2ea540d6d3f986630', "aria-describedby": assignDescription(this.componentId, this.isInvalid(), this.helperMessage, this.errorMessage), "aria-invalid": this.isInvalid() ? 'true' : undefined, "aria-label": this.hideLabel ? this.label : undefined, autocomplete: this.autocomplete || undefined, class: "pds-select__field", disabled: this.disabled, id: this.componentId, multiple: this.multiple, name: this.name, onBlur: this.onBlur, onChange: this.onSelectUpdate, onFocus: this.onFocus, onKeyDown: this.onKeyDown, part: "select", required: this.required, ref: (el) => (this.selectEl = el) }), h("div", { key: '793a84d41bd5e18d64757238704a053b1135a83c', "aria-hidden": "true", class: "hidden", ref: (el) => (this.slotContainer = el) }, h("slot", { key: '27ed9ff31bbf83fcbd2ed8dd2b23b97422b18d25', onSlotchange: this.handleSlotChange })), this.renderMessages(), !this.multiple && h("pds-icon", { key: '43d415eab0fc8a3c02e19848a5622ea43f04256e', "aria-hidden": "true", class: "pds-select__select-icon", icon: enlarge }))));
     }
     static get is() { return "pds-select"; }
     static get encapsulation() { return "shadow"; }

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

@@ -82,9 +82,9 @@ export class PdsSwitch {
         this.inheritedAttributes = Object.assign({}, inheritAriaAttributes(this.el));
     }
     render() {
-        return (h(Host, { key: '96ee8c40c04e95b461ba2942b740503897a56b27', class: this.switchClassNames(), "aria-disabled": this.disabled ? 'true' : null }, h("label", { key: '441d6854f2c0b02ecf3d874198b3e0636d68c83b', htmlFor: this.componentId }, h("input", Object.assign({ key: 'a26cd5fb407abc20da3e9dcfe0e52333690b783a', "aria-describedby": assignDescription(this.componentId, this.invalid, this.errorMessage || this.helperMessage), "aria-invalid": this.invalid ? "true" : undefined, checked: this.checked, class: "pds-switch__input", disabled: this.disabled, id: this.componentId, name: this.name ? this.name : this.componentId, onChange: this.onSwitchUpdate, required: this.required, type: "checkbox", value: this.value }, this.inheritedAttributes)), h("span", { key: '5762c48f481c5c5d7b62e8dab40579a4e7ff290b', class: this.hideLabel ? 'visually-hidden' : '' }, this.label)), this.helperMessage &&
-            h("div", { key: '64c14b8833b45b4e9efb2f76faa47f0d24127c91', class: `pds-switch__message`, id: messageId(this.componentId, 'helper') }, this.helperMessage), this.errorMessage &&
-            h("div", { key: 'cecd2e8da713e74b8e6b528b50733015f5d5069b', class: `pds-switch__message pds-switch__message--error`, id: messageId(this.componentId, 'error'), "aria-live": "assertive" }, h("pds-icon", { key: '3a1c8f87b3909cdad1bc680931f5521ecb77acd6', icon: danger, size: "small" }), this.errorMessage)));
+        return (h(Host, { key: '96ee8c40c04e95b461ba2942b740503897a56b27', class: this.switchClassNames(), "aria-disabled": this.disabled ? 'true' : null }, h("label", { key: '441d6854f2c0b02ecf3d874198b3e0636d68c83b', htmlFor: this.componentId }, h("input", Object.assign({ key: 'ed0c344ab46d83faf902571fcd282a605f5cfbec', "aria-describedby": assignDescription(this.componentId, this.invalid, this.helperMessage, this.errorMessage), "aria-invalid": this.invalid ? "true" : undefined, checked: this.checked, class: "pds-switch__input", disabled: this.disabled, id: this.componentId, name: this.name ? this.name : this.componentId, onChange: this.onSwitchUpdate, required: this.required, type: "checkbox", value: this.value }, this.inheritedAttributes)), h("span", { key: 'a2e89156f56d6c921be9b866823bb4b36710b40f', class: this.hideLabel ? 'visually-hidden' : '' }, this.label)), this.helperMessage &&
+            h("div", { key: '1465778f0a69d4c87108a80603d123bf0500911d', class: `pds-switch__message`, id: messageId(this.componentId, 'helper') }, this.helperMessage), this.errorMessage &&
+            h("div", { key: '2a652c3019f45a060283f98ea97ac83e17d7de33', class: `pds-switch__message pds-switch__message--error`, id: messageId(this.componentId, 'error'), "aria-live": "assertive" }, h("pds-icon", { key: '438895d9ad8799b540ab239ac90bedcb0231d2f0', icon: danger, size: "small" }), this.errorMessage)));
     }
     static get is() { return "pds-switch"; }
     static get encapsulation() { return "shadow"; }

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

@@ -302,9 +302,9 @@ export class PdsTextarea {
     render() {
         const value = this.getValue();
         return (h(Host, { key: 'd13869d989752c76c80a46ebb0291df2c0546cc2', "aria-disabled": this.disabled ? 'true' : null, "aria-readonly": this.readonly ? 'true' : null, "has-action": this.hasAction && !this.hideLabel ? 'true' : null }, h("div", { key: '19454f642896485dc22bc5dac8b6ed3b4ae5627a', class: "pds-textarea" }, this.label &&
-            h("div", { key: 'def9e117ba3667a542e8cec32c2eabfa701c3305', class: "pds-textarea__label-wrapper" }, h("label", { key: '893a1db325ece460c627e72b765289098823e49e', htmlFor: this.componentId }, h("span", { key: 'd047f17441aa81800057d7403af15f6e38c53f6c', class: this.hideLabel ? 'visually-hidden' : '' }, this.label)), !this.hideLabel && this.renderAction()), h("div", { key: '7d0f2fab56fee9b9d9e0facabc7e607cb6bee23b', class: "pds-textarea__field-wrapper" }, h("textarea", Object.assign({ key: 'a3ecb78c5b8f42f8350abe623bacb55be6c4a0c0', ref: (el) => this.nativeTextarea = el, "aria-describedby": assignDescription(this.componentId, this.invalid, this.helperMessage), "aria-invalid": this.invalid ? "true" : undefined, autocomplete: this.autocomplete, class: this.textareaClassNames(), disabled: this.disabled, id: this.componentId, maxlength: this.maxLength, name: this.name, placeholder: this.placeholder, readOnly: this.readonly, required: this.required, rows: this.rows, onBlur: this.onBlur, onChange: this.onTextareaChange, onFocus: this.onFocus, onInput: this.onInput, onKeyDown: this.onKeyDown }, this.inheritedAttributes), value), this.renderCharacterCounter()), this.helperMessage &&
-            h("p", { key: 'b5229a6ef0b2c4ee5dcb820ce2b9bbf6334adef8', class: "pds-textarea__helper-message", id: messageId(this.componentId, 'helper') }, this.helperMessage), this.invalid &&
-            h("p", { key: '8e6dfa97496d553b8e1e2a50c1221fad3ddb539a', "aria-live": "assertive", class: "pds-textarea__error-message", id: messageId(this.componentId, 'error') }, h("pds-icon", { key: 'f3ed2677239e6d135480cf55d1d908936d746322', icon: danger, size: "small" }), this.errorMessage))));
+            h("div", { key: 'def9e117ba3667a542e8cec32c2eabfa701c3305', class: "pds-textarea__label-wrapper" }, h("label", { key: '893a1db325ece460c627e72b765289098823e49e', htmlFor: this.componentId }, h("span", { key: 'd047f17441aa81800057d7403af15f6e38c53f6c', class: this.hideLabel ? 'visually-hidden' : '' }, this.label)), !this.hideLabel && this.renderAction()), h("div", { key: '7d0f2fab56fee9b9d9e0facabc7e607cb6bee23b', class: "pds-textarea__field-wrapper" }, h("textarea", Object.assign({ key: '261e6031c61832acde2d595248ccdc8bd5c84768', ref: (el) => this.nativeTextarea = el, "aria-describedby": assignDescription(this.componentId, this.invalid, this.helperMessage, this.errorMessage), "aria-invalid": this.invalid ? "true" : undefined, autocomplete: this.autocomplete, class: this.textareaClassNames(), disabled: this.disabled, id: this.componentId, maxlength: this.maxLength, name: this.name, placeholder: this.placeholder, readOnly: this.readonly, required: this.required, rows: this.rows, onBlur: this.onBlur, onChange: this.onTextareaChange, onFocus: this.onFocus, onInput: this.onInput, onKeyDown: this.onKeyDown }, this.inheritedAttributes), value), this.renderCharacterCounter()), this.helperMessage &&
+            h("p", { key: 'de40f9d13bda3d9a224349b7f4ca38194e7adbb5', class: "pds-textarea__helper-message", id: messageId(this.componentId, 'helper') }, this.helperMessage), this.invalid &&
+            h("p", { key: '1306917ce521c3ad0d303d255f9e7aefd0e65de7', "aria-live": "assertive", class: "pds-textarea__error-message", id: messageId(this.componentId, 'error') }, h("pds-icon", { key: '1c9e22b9b4bf84f671797bbfb9080bdbdb7619a7', icon: danger, size: "small" }), this.errorMessage))));
     }
     static get is() { return "pds-textarea"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/utils/form.js

@@ -6,14 +6,18 @@ export const messageId = (id, messageType) => {
 };
 /**
  * Assign aria-description id to relate messages with form element
+ *
+ * Returns the error message id when invalid, otherwise the helper message id.
+ * Pass only messages the component renders — a described id must exist in the DOM.
  */
-export const assignDescription = (id, invalid, helperMessage) => {
-    if (!helperMessage)
-        return;
-    let relatedId = messageId(id, 'helper');
-    if (invalid)
-        relatedId = messageId(id, 'error');
-    return relatedId;
+export const assignDescription = (id, invalid, helperMessage, errorMessage) => {
+    const hasErrorMessage = Boolean(errorMessage);
+    const hasHelperMessage = Boolean(helperMessage);
+    if (invalid && hasErrorMessage)
+        return messageId(id, 'error');
+    if (hasHelperMessage)
+        return messageId(id, 'helper');
+    return undefined;
 };
 /**
  * Updates the `invalid` prop of a form element based on it's values validity

package/dist/docs.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-08-13T20:44:44",
+  "timestamp": "2026-08-27T21:56:56",
   "compiler": {
     "name": "@stencil/core",
     "version": "4.43.5",
@@ -705,6 +705,10 @@
         {
           "name": "part",
           "text": "image - The main image element that represents the avatar component."
+        },
+        {
+          "name": "part",
+          "text": "initials - The text element that renders the avatar's initials, for restyling their color."
         }
       ],
       "usage": {},
@@ -1083,6 +1087,10 @@
           "name": "image",
           "docs": "The main image element that represents the avatar component."
         },
+        {
+          "name": "initials",
+          "docs": "The text element that renders the avatar's initials, for restyling their color."
+        },
         {
           "name": "status",
           "docs": ""
@@ -13703,6 +13711,29 @@
           "getter": false,
           "setter": false
         },
+        {
+          "name": "errorMessage",
+          "type": "string",
+          "complexType": {
+            "original": "string",
+            "resolved": "string",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "error-message",
+          "reflectToAttr": false,
+          "docs": "Error message to display.",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "string"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "fetchTimeout",
           "type": "number",
@@ -13761,6 +13792,29 @@
           "getter": false,
           "setter": false
         },
+        {
+          "name": "helperMessage",
+          "type": "string",
+          "complexType": {
+            "original": "string",
+            "resolved": "string",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "helper-message",
+          "reflectToAttr": false,
+          "docs": "Helper message to display below the combobox.",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "string"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "hideLabel",
           "type": "boolean",
@@ -13790,6 +13844,29 @@
           "getter": false,
           "setter": false
         },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "invalid",
+          "reflectToAttr": false,
+          "docs": "If true, the combobox is in an invalid state.",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "label",
           "type": "string",
@@ -17383,6 +17460,35 @@
           "getter": false,
           "setter": false
         },
+        {
+          "name": "disableTopLayer",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "disable-top-layer",
+          "reflectToAttr": false,
+          "docs": "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.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "open",
           "type": "boolean",

package/dist/esm/{form-C3xDZBme.js → form-BuRbS7Hp.js}

@@ -6,14 +6,18 @@ const messageId = (id, messageType) => {
 };
 /**
  * Assign aria-description id to relate messages with form element
+ *
+ * Returns the error message id when invalid, otherwise the helper message id.
+ * Pass only messages the component renders — a described id must exist in the DOM.
  */
-const assignDescription = (id, invalid, helperMessage) => {
-    if (!helperMessage)
-        return;
-    let relatedId = messageId(id, 'helper');
-    if (invalid)
-        relatedId = messageId(id, 'error');
-    return relatedId;
+const assignDescription = (id, invalid, helperMessage, errorMessage) => {
+    const hasErrorMessage = Boolean(errorMessage);
+    const hasHelperMessage = Boolean(helperMessage);
+    if (invalid && hasErrorMessage)
+        return messageId(id, 'error');
+    if (hasHelperMessage)
+        return messageId(id, 'helper');
+    return undefined;
 };
 /**
  * Updates the `invalid` prop of a form element based on it's values validity