@pine-ds/core 4.5.0 → 4.7.0

package/dist/types/components/pds-dropdown-menu/pds-dropdown-menu.d.ts

@@ -1,6 +1,7 @@
 import type { BasePdsProps } from "../../utils/interfaces";
 import { PlacementType } from "../../utils/types";
 /**
+ * @slot header - Non-interactive content displayed above the menu items inside the dropdown panel. It renders outside the menu role, so assistive tech reads it as plain content rather than as a menu item.
  * @part menu-panel - Exposes the dropdown menu container for styling.
  */
 export declare class PdsDropdownMenu implements BasePdsProps {
@@ -13,6 +14,7 @@ export declare class PdsDropdownMenu implements BasePdsProps {
     private triggerObserver;
     host: HTMLPdsDropdownMenuElement;
     currentFocusIndex: number;
+    hasHeader: boolean;
     /**
      * A unique identifier used for the underlying component `id` attribute.
      */
@@ -21,12 +23,14 @@ export declare class PdsDropdownMenu implements BasePdsProps {
      * The placement of the dropdown panel relative to the trigger.
      */
     placement: PlacementType;
+    componentWillLoad(): void;
     componentDidRender(): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
     private handleTriggerSlotChange;
     private syncTriggerAria;
     private observeTrigger;
+    private handleHeaderSlotChange;
     private handleSlotChange;
     private toggleDropdown;
     private openDropdown;
@@ -38,6 +42,7 @@ export declare class PdsDropdownMenu implements BasePdsProps {
     private focusItemByIndex;
     private focusNextItem;
     private focusPreviousItem;
+    handleEscapeKeyDown(event: KeyboardEvent): void;
     handleKeyDown(event: KeyboardEvent): void;
     handleWindowClick(event: MouseEvent): void;
     render(): any;

package/dist/types/components/pds-modal/pds-modal.d.ts

@@ -9,7 +9,8 @@ export declare class PdsModal {
     private focusableElements;
     el: HTMLPdsModalElement;
     /**
-     * Whether the modal can be dismissed by clicking the backdrop
+     * Whether the modal can be dismissed by clicking the backdrop, pressing Escape, or the browser's
+     * own close request (such as a back gesture)
      * @default true
      */
     backdropDismiss: boolean;
@@ -73,6 +74,7 @@ export declare class PdsModal {
     sizeChanged(): void;
     componentDidLoad(): void;
     componentDidRender(): void;
+    connectedCallback(): void;
     disconnectedCallback(): void;
     handleOpenChange(newValue: boolean): void;
     /**
@@ -96,6 +98,7 @@ export declare class PdsModal {
      * Closes the modal
      */
     hideModal(): Promise<void>;
+    private handleCancel;
     private handleBackdropClick;
     /**
      * Gets the z-index of a modal's backdrop element
@@ -127,9 +130,13 @@ export declare class PdsModal {
      */
     private isStackedAboveOverlay;
     /**
-     * Checks if this modal is the innermost (highest z-index) modal
+     * The open modal that takes Escape or a backdrop click, among those with no other open modal
+     * inside them (a nested modal's backdrop can share its outer modal's z-index). A top-layer dialog
+     * (or a modal inside one) paints above anything outside it, and within the top layer the last
+     * opened is on top. Modals in the same layer (the page, or one top-layer dialog) then rank by
+     * the highest backdrop, then the one later in the page.
      */
-    private isInnermostModal;
+    private innermostOpenModal;
     /** Whether a modal dialog other than this one sits between the focused element and this modal. */
     private modalDialogAbove;
     /** The focused element's place in the list: its own stop, or the innermost stop it sits in. */

package/dist/types/components/pds-multiselect/pds-multiselect.d.ts

@@ -319,7 +319,8 @@ export declare class PdsMultiselect {
     refreshOptions(): Promise<void>;
     /**
      * Handle global keyboard events for accessibility.
-     * Closes dropdown on Escape key press regardless of focus location.
+     * Closes dropdown on Escape key press regardless of focus location. Taken in document's capture
+     * phase, before a modal around the multiselect hears it on document and closes too.
      */
     handleWindowKeyDown(event: KeyboardEvent): void;
     private get activeTriggerEl();

package/dist/types/components/pds-popover/pds-popover.d.ts

@@ -36,7 +36,7 @@ export declare class PdsPopover {
      */
     private triggerObserver;
     /**
-     * Portal element rendered in document.body
+     * Portal element: in document.body, or in the open dialog the popover is in
      */
     private portalEl;
     /**
@@ -136,6 +136,9 @@ export declare class PdsPopover {
      * Restores moved nodes back to their original positions
      */
     private restorePortalContent;
+    /** The focus style copied into a shadow root the panel opened in, which `document.head` can't reach. */
+    private shadowFocusStyle;
+    private copyFocusStylesInto;
     private removePortal;
     /**
      * Opens the popover programmatically
@@ -149,14 +152,41 @@ export declare class PdsPopover {
      * Toggles the popover open/closed state programmatically
      */
     toggle(): Promise<void>;
+    /**
+     * Puts the panel where it shows above everything around the popover. In an open dialog, it goes
+     * inside it: a modal dialog sits in the top layer above the body and makes the rest of the page
+     * inert, and a non-modal one sits above it by z-index. Right after the popover, it's next in the
+     * Tab order. In another component's slot, though, it would have no slot to render in, and in a
+     * form its buttons would submit it, so there it goes at the end of the dialog.
+     */
+    private placePortal;
+    private forgetOpen;
+    /**
+     * Whether an Escape is this popover's. One from a dialog the popover isn't in belongs to that
+     * dialog when it's above it: a top-layer dialog or a pds-modal. A plain non-modal dialog inside
+     * the popover's modal doesn't close on Escape, so the popover takes it.
+     */
+    private takesEscapeFrom;
     /**
      * Adds light dismiss listeners (click outside and escape key)
      */
     private addLightDismissListeners;
+    /** The dialog the panel was opened in, closed along with it. */
+    private watchedDialog;
+    private onDialogClose;
+    /** Closes the popover when the dialog it opened in closes, so it isn't left open inside. */
+    private watchDialogClose;
+    private unwatchDialogClose;
     /**
      * Removes light dismiss listeners
      */
     private removeLightDismissListeners;
+    /**
+     * Inside a dialog, the panel can sit in a form that wraps the dialog, which a body portal never
+     * did. A submit from the panel (a button in it, or Enter in a field in it) is stopped, so the
+     * panel behaves as it does in the body.
+     */
+    private handleSubmitFromPanel;
     /**
      * Adds scroll and resize listeners for repositioning
      */

package/dist/types/components/pds-tabs/pds-tab/pds-tab.d.ts

@@ -4,6 +4,9 @@ import { EventEmitter } from '../../../stencil-public-runtime';
  */
 export declare class PdsTab {
     el: HTMLPdsTabElement;
+    private hostKeeper;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     componentDidRender(): void;
     /**
      * Determines the tab's disabled state.

package/dist/types/components/pds-tabs/pds-tabpanel/pds-tabpanel.d.ts

@@ -3,6 +3,9 @@
  */
 export declare class PdsTabpanel {
     el: HTMLPdsTabpanelElement;
+    private hostKeeper;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     componentDidRender(): void;
     /**
      * Sets the related tab name, this name must match a `pds-tab`'s tab name property

package/dist/types/components/pds-tabs/pds-tabs.d.ts

@@ -8,8 +8,16 @@ export declare class PdsTabs {
     private tabPanels;
     el: HTMLPdsTabsElement;
     private hostKeeper;
+    private tabsSlot;
+    private tabPanelsSlot;
+    private slotChangeScheduled;
+    private activeTabNameBeforeSlotChange;
+    private lastFocusedTab;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    private handleFocusIn;
+    private handleFocusOut;
+    componentDidLoad(): void;
     /**
      * Sets the aria-label attached to the tablist element
      */
@@ -19,9 +27,10 @@ export declare class PdsTabs {
      */
     componentId: string;
     /**
-     * Sets tabs variant styles as outlined in Figma documentation
+     * Sets tabs variant styles as outlined in Figma documentation.
+     * Applies in both panel and nav mode; omitting it renders the primary style.
      */
-    variant: 'primary' | 'availability' | 'filter' | 'pill';
+    variant?: 'primary' | 'availability' | 'filter' | 'pill';
     /**
      * Adds a divider rule beneath the tab list.
      * @defaultValue false
@@ -58,6 +67,9 @@ export declare class PdsTabs {
     private warnOnNavConfig;
     private moveActiveTab;
     private findAllChildren;
+    private setupSlotChangeListeners;
+    private handleSlotChange;
+    private recollectAfterSlotChange;
     private propGeneration;
     private passPropsToChildren;
     private classNames;

package/dist/types/components.d.ts

@@ -1430,12 +1430,13 @@ export namespace Components {
         "vertical": boolean;
     }
     /**
-     * A non-modal side panel composed from `pds-modal`.
-     * Unlike `pds-modal`, the page stays interactive while a drawer is open: no
-     * dimming, no blur, no scroll lock, no click blocking. `pds-drawer` renders a
-     * `pds-modal` internally with `disableTopLayer` always on and its backdrop
-     * suppressed, and adds the edge, width and dismiss behavior a side panel
-     * needs on top. It does not reimplement focus, Escape or dialog semantics —
+     * A side panel composed from `pds-modal`, non-modal by default.
+     * By default, unlike `pds-modal`, the page stays interactive while a drawer
+     * is open: no dimming, no blur, no scroll lock, no click blocking.
+     * `pds-drawer` renders a `pds-modal` internally with `disableTopLayer` on and
+     * its backdrop suppressed, and adds the edge, width and dismiss behavior a
+     * side panel needs on top. With `modal`, it opens that `pds-modal` in the top
+     * layer instead and keeps its backdrop. It does not reimplement focus, Escape or dialog semantics —
      * those come from `pds-modal` unchanged.
      * @lightDom renders-markup
      */
@@ -1445,15 +1446,20 @@ export namespace Components {
          */
         "componentId": string;
         /**
-          * Whether to move focus into the drawer when it opens. `auto` is right for a drawer opened by a direct user action (a click, a deep link the user just navigated to). Set to `none` for a drawer that can open from a background event while the user is mid-task elsewhere on the page — moving focus there would interrupt them, and the page stays live under a non-modal drawer, so it is a genuine data-entry risk, not just an annoyance.
+          * Whether to move focus into the drawer when it opens. `auto` is right for a drawer opened by a direct user action (a click, a deep link the user just navigated to). Set to `none` for a drawer that can open from a background event while the user is mid-task elsewhere on the page — moving focus there would interrupt them, and the page stays live under a non-modal drawer, so it is a genuine data-entry risk, not just an annoyance. A `modal` drawer ignores `none`: the page behind it is inert, so focus starts in the drawer.
           * @default 'auto'
          */
         "initialFocus": 'auto' | 'none';
         /**
-          * Whether the drawer can be dismissed with a pointerdown outside it. Replaces `pds-modal`'s `backdropDismiss` — there is no backdrop to click. This also gates Escape, matching how `backdropDismiss` gates Escape on `pds-modal` today: setting this to `false` means the close button is the only way out.  A trigger outside the drawer should only ever set `open` to `true` and leave closing to the drawer itself. A toggle-style trigger (`open = !open`) fights light dismiss: clicking it while open closes the drawer on `pointerdown`, then the trigger's own click handler re-opens it.
+          * Whether the drawer can be dismissed with a pointerdown outside it (in a `modal` drawer, a click on its backdrop). Replaces `pds-modal`'s `backdropDismiss`. This also gates Escape, matching how `backdropDismiss` gates Escape on `pds-modal` today: setting this to `false` means the close button is the only way out.  A trigger outside the drawer should only ever set `open` to `true` and leave closing to the drawer itself. A toggle-style trigger (`open = !open`) fights light dismiss: clicking it while open closes the drawer on `pointerdown`, then the trigger's own click handler re-opens it.
           * @default true
          */
         "lightDismiss": boolean;
+        /**
+          * Whether the drawer is modal. A modal drawer dims the page behind it with a backdrop, makes the page inert, and keeps focus inside the drawer, like `pds-modal`. Use it for a task the page should wait on. Leave it off for a panel people work alongside the page. Read when the drawer opens; changing it while the drawer is open is not supported.
+          * @default false
+         */
+        "modal": boolean;
         /**
           * Whether the drawer is open
           * @default false
@@ -1838,7 +1844,7 @@ export namespace Components {
      */
     interface PdsModal {
         /**
-          * Whether the modal can be dismissed by clicking the backdrop
+          * Whether the modal can be dismissed by clicking the backdrop, pressing Escape, or the browser's own close request (such as a back gesture)
           * @default true
          */
         "backdropDismiss": boolean;
@@ -2718,9 +2724,9 @@ export namespace Components {
          */
         "tablistLabel": string;
         /**
-          * Sets tabs variant styles as outlined in Figma documentation
+          * Sets tabs variant styles as outlined in Figma documentation. Applies in both panel and nav mode; omitting it renders the primary style.
          */
-        "variant": 'primary' | 'availability' | 'filter' | 'pill';
+        "variant"?: 'primary' | 'availability' | 'filter' | 'pill';
     }
     interface PdsText {
         /**
@@ -3254,12 +3260,13 @@ declare global {
         "pdsDrawerClose": void;
     }
     /**
-     * A non-modal side panel composed from `pds-modal`.
-     * Unlike `pds-modal`, the page stays interactive while a drawer is open: no
-     * dimming, no blur, no scroll lock, no click blocking. `pds-drawer` renders a
-     * `pds-modal` internally with `disableTopLayer` always on and its backdrop
-     * suppressed, and adds the edge, width and dismiss behavior a side panel
-     * needs on top. It does not reimplement focus, Escape or dialog semantics —
+     * A side panel composed from `pds-modal`, non-modal by default.
+     * By default, unlike `pds-modal`, the page stays interactive while a drawer
+     * is open: no dimming, no blur, no scroll lock, no click blocking.
+     * `pds-drawer` renders a `pds-modal` internally with `disableTopLayer` on and
+     * its backdrop suppressed, and adds the edge, width and dismiss behavior a
+     * side panel needs on top. With `modal`, it opens that `pds-modal` in the top
+     * layer instead and keeps its backdrop. It does not reimplement focus, Escape or dialog semantics —
      * those come from `pds-modal` unchanged.
      * @lightDom renders-markup
      */
@@ -5284,12 +5291,13 @@ declare namespace LocalJSX {
         "vertical"?: boolean;
     }
     /**
-     * A non-modal side panel composed from `pds-modal`.
-     * Unlike `pds-modal`, the page stays interactive while a drawer is open: no
-     * dimming, no blur, no scroll lock, no click blocking. `pds-drawer` renders a
-     * `pds-modal` internally with `disableTopLayer` always on and its backdrop
-     * suppressed, and adds the edge, width and dismiss behavior a side panel
-     * needs on top. It does not reimplement focus, Escape or dialog semantics —
+     * A side panel composed from `pds-modal`, non-modal by default.
+     * By default, unlike `pds-modal`, the page stays interactive while a drawer
+     * is open: no dimming, no blur, no scroll lock, no click blocking.
+     * `pds-drawer` renders a `pds-modal` internally with `disableTopLayer` on and
+     * its backdrop suppressed, and adds the edge, width and dismiss behavior a
+     * side panel needs on top. With `modal`, it opens that `pds-modal` in the top
+     * layer instead and keeps its backdrop. It does not reimplement focus, Escape or dialog semantics —
      * those come from `pds-modal` unchanged.
      * @lightDom renders-markup
      */
@@ -5299,15 +5307,20 @@ declare namespace LocalJSX {
          */
         "componentId"?: string;
         /**
-          * Whether to move focus into the drawer when it opens. `auto` is right for a drawer opened by a direct user action (a click, a deep link the user just navigated to). Set to `none` for a drawer that can open from a background event while the user is mid-task elsewhere on the page — moving focus there would interrupt them, and the page stays live under a non-modal drawer, so it is a genuine data-entry risk, not just an annoyance.
+          * Whether to move focus into the drawer when it opens. `auto` is right for a drawer opened by a direct user action (a click, a deep link the user just navigated to). Set to `none` for a drawer that can open from a background event while the user is mid-task elsewhere on the page — moving focus there would interrupt them, and the page stays live under a non-modal drawer, so it is a genuine data-entry risk, not just an annoyance. A `modal` drawer ignores `none`: the page behind it is inert, so focus starts in the drawer.
           * @default 'auto'
          */
         "initialFocus"?: 'auto' | 'none';
         /**
-          * Whether the drawer can be dismissed with a pointerdown outside it. Replaces `pds-modal`'s `backdropDismiss` — there is no backdrop to click. This also gates Escape, matching how `backdropDismiss` gates Escape on `pds-modal` today: setting this to `false` means the close button is the only way out.  A trigger outside the drawer should only ever set `open` to `true` and leave closing to the drawer itself. A toggle-style trigger (`open = !open`) fights light dismiss: clicking it while open closes the drawer on `pointerdown`, then the trigger's own click handler re-opens it.
+          * Whether the drawer can be dismissed with a pointerdown outside it (in a `modal` drawer, a click on its backdrop). Replaces `pds-modal`'s `backdropDismiss`. This also gates Escape, matching how `backdropDismiss` gates Escape on `pds-modal` today: setting this to `false` means the close button is the only way out.  A trigger outside the drawer should only ever set `open` to `true` and leave closing to the drawer itself. A toggle-style trigger (`open = !open`) fights light dismiss: clicking it while open closes the drawer on `pointerdown`, then the trigger's own click handler re-opens it.
           * @default true
          */
         "lightDismiss"?: boolean;
+        /**
+          * Whether the drawer is modal. A modal drawer dims the page behind it with a backdrop, makes the page inert, and keeps focus inside the drawer, like `pds-modal`. Use it for a task the page should wait on. Leave it off for a panel people work alongside the page. Read when the drawer opens; changing it while the drawer is open is not supported.
+          * @default false
+         */
+        "modal"?: boolean;
         /**
           * Emitted when the drawer is closed
          */
@@ -5724,7 +5737,7 @@ declare namespace LocalJSX {
      */
     interface PdsModal {
         /**
-          * Whether the modal can be dismissed by clicking the backdrop
+          * Whether the modal can be dismissed by clicking the backdrop, pressing Escape, or the browser's own close request (such as a back gesture)
           * @default true
          */
         "backdropDismiss"?: boolean;
@@ -6644,9 +6657,9 @@ declare namespace LocalJSX {
          */
         "tablistLabel": string;
         /**
-          * Sets tabs variant styles as outlined in Figma documentation
+          * Sets tabs variant styles as outlined in Figma documentation. Applies in both panel and nav mode; omitting it renders the primary style.
          */
-        "variant": 'primary' | 'availability' | 'filter' | 'pill';
+        "variant"?: 'primary' | 'availability' | 'filter' | 'pill';
     }
     interface PdsText {
         /**
@@ -7200,6 +7213,7 @@ declare namespace LocalJSX {
         "side": 'start' | 'end';
         "size": 'sm' | 'md';
         "scrollable": boolean;
+        "modal": boolean;
         "lightDismiss": boolean;
         "initialFocus": 'auto' | 'none';
     }
@@ -7613,7 +7627,7 @@ declare namespace LocalJSX {
         "pds-table-head-cell": Omit<PdsTableHeadCell, keyof PdsTableHeadCellAttributes> & { [K in keyof PdsTableHeadCell & keyof PdsTableHeadCellAttributes]?: PdsTableHeadCell[K] } & { [K in keyof PdsTableHeadCell & keyof PdsTableHeadCellAttributes as `attr:${K}`]?: PdsTableHeadCellAttributes[K] } & { [K in keyof PdsTableHeadCell & keyof PdsTableHeadCellAttributes as `prop:${K}`]?: PdsTableHeadCell[K] };
         "pds-table-row": Omit<PdsTableRow, keyof PdsTableRowAttributes> & { [K in keyof PdsTableRow & keyof PdsTableRowAttributes]?: PdsTableRow[K] } & { [K in keyof PdsTableRow & keyof PdsTableRowAttributes as `attr:${K}`]?: PdsTableRowAttributes[K] } & { [K in keyof PdsTableRow & keyof PdsTableRowAttributes as `prop:${K}`]?: PdsTableRow[K] };
         "pds-tabpanel": Omit<PdsTabpanel, keyof PdsTabpanelAttributes> & { [K in keyof PdsTabpanel & keyof PdsTabpanelAttributes]?: PdsTabpanel[K] } & { [K in keyof PdsTabpanel & keyof PdsTabpanelAttributes as `attr:${K}`]?: PdsTabpanelAttributes[K] } & { [K in keyof PdsTabpanel & keyof PdsTabpanelAttributes as `prop:${K}`]?: PdsTabpanel[K] } & OneOf<"name", PdsTabpanel["name"], PdsTabpanelAttributes["name"]>;
-        "pds-tabs": Omit<PdsTabs, keyof PdsTabsAttributes> & { [K in keyof PdsTabs & keyof PdsTabsAttributes]?: PdsTabs[K] } & { [K in keyof PdsTabs & keyof PdsTabsAttributes as `attr:${K}`]?: PdsTabsAttributes[K] } & { [K in keyof PdsTabs & keyof PdsTabsAttributes as `prop:${K}`]?: PdsTabs[K] } & OneOf<"tablistLabel", PdsTabs["tablistLabel"], PdsTabsAttributes["tablistLabel"]> & OneOf<"componentId", PdsTabs["componentId"], PdsTabsAttributes["componentId"]> & OneOf<"variant", PdsTabs["variant"], PdsTabsAttributes["variant"]>;
+        "pds-tabs": Omit<PdsTabs, keyof PdsTabsAttributes> & { [K in keyof PdsTabs & keyof PdsTabsAttributes]?: PdsTabs[K] } & { [K in keyof PdsTabs & keyof PdsTabsAttributes as `attr:${K}`]?: PdsTabsAttributes[K] } & { [K in keyof PdsTabs & keyof PdsTabsAttributes as `prop:${K}`]?: PdsTabs[K] } & OneOf<"tablistLabel", PdsTabs["tablistLabel"], PdsTabsAttributes["tablistLabel"]> & OneOf<"componentId", PdsTabs["componentId"], PdsTabsAttributes["componentId"]>;
         "pds-text": Omit<PdsText, keyof PdsTextAttributes> & { [K in keyof PdsText & keyof PdsTextAttributes]?: PdsText[K] } & { [K in keyof PdsText & keyof PdsTextAttributes as `attr:${K}`]?: PdsTextAttributes[K] } & { [K in keyof PdsText & keyof PdsTextAttributes as `prop:${K}`]?: PdsText[K] };
         "pds-textarea": Omit<PdsTextarea, keyof PdsTextareaAttributes> & { [K in keyof PdsTextarea & keyof PdsTextareaAttributes]?: PdsTextarea[K] } & { [K in keyof PdsTextarea & keyof PdsTextareaAttributes as `attr:${K}`]?: PdsTextareaAttributes[K] } & { [K in keyof PdsTextarea & keyof PdsTextareaAttributes as `prop:${K}`]?: PdsTextarea[K] } & OneOf<"componentId", PdsTextarea["componentId"], PdsTextareaAttributes["componentId"]>;
         "pds-toast": Omit<PdsToast, keyof PdsToastAttributes> & { [K in keyof PdsToast & keyof PdsToastAttributes]?: PdsToast[K] } & { [K in keyof PdsToast & keyof PdsToastAttributes as `attr:${K}`]?: PdsToastAttributes[K] } & { [K in keyof PdsToast & keyof PdsToastAttributes as `prop:${K}`]?: PdsToast[K] } & OneOf<"componentId", PdsToast["componentId"], PdsToastAttributes["componentId"]>;
@@ -7650,12 +7664,13 @@ declare module "@stencil/core" {
             "pds-datepicker": LocalJSX.IntrinsicElements["pds-datepicker"] & JSXBase.HTMLAttributes<HTMLPdsDatepickerElement>;
             "pds-divider": LocalJSX.IntrinsicElements["pds-divider"] & JSXBase.HTMLAttributes<HTMLPdsDividerElement>;
             /**
-             * A non-modal side panel composed from `pds-modal`.
-             * Unlike `pds-modal`, the page stays interactive while a drawer is open: no
-             * dimming, no blur, no scroll lock, no click blocking. `pds-drawer` renders a
-             * `pds-modal` internally with `disableTopLayer` always on and its backdrop
-             * suppressed, and adds the edge, width and dismiss behavior a side panel
-             * needs on top. It does not reimplement focus, Escape or dialog semantics —
+             * A side panel composed from `pds-modal`, non-modal by default.
+             * By default, unlike `pds-modal`, the page stays interactive while a drawer
+             * is open: no dimming, no blur, no scroll lock, no click blocking.
+             * `pds-drawer` renders a `pds-modal` internally with `disableTopLayer` on and
+             * its backdrop suppressed, and adds the edge, width and dismiss behavior a
+             * side panel needs on top. With `modal`, it opens that `pds-modal` in the top
+             * layer instead and keeps its backdrop. It does not reimplement focus, Escape or dialog semantics —
              * those come from `pds-modal` unchanged.
              * @lightDom renders-markup
              */

package/dist/types/utils/attributes.d.ts

@@ -7,7 +7,7 @@ export type Attributes = {
  * @param el - Element to write to
  * @param attributes - Attribute names and the values they should have
  */
-export declare const setAttributesIfChanged: (el: Element, attributes: Record<string, string>) => void;
+export declare const setAttributesIfChanged: (el: Element, attributes: Record<string, string>) => boolean;
 /**
  * The classes, style properties and other attributes a component renders onto its own host.
  */
@@ -23,7 +23,7 @@ export type HostStyling = {
  * @param el - Host element
  * @param expected - Classes and style properties the component rendered
  */
-export declare const restoreHostStyling: (el: HTMLElement, { classes, styles }: HostStyling) => void;
+export declare const restoreHostStyling: (el: HTMLElement, { classes, styles }: HostStyling) => boolean;
 /**
  * Inherit attributes from the host element
  * @param el - Host element

package/dist/types/utils/css.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Escapes a string so it's safe to interpolate into a CSS identifier (an id selector like `#${id}`)
+ * or into CSS text (a stylesheet rule referencing that id). Equivalent to the native `CSS.escape`,
+ * reimplemented because Stencil's unit-test DOM (`newSpecPage`'s mock-doc) doesn't provide it.
+ * @param value - The string to escape, e.g. a consumer-supplied id
+ */
+export declare const cssEscape: (value: string) => string;

package/dist/types/utils/keep-hydrated.d.ts

@@ -11,6 +11,32 @@ export declare const isStencilClass: (el: Element, name: string) => boolean;
  * The class names in a rendered `class` value: a string, or Stencil's `{ name: boolean }` form.
  */
 export declare const classNamesOf: (classes: string | Record<string, boolean>) => string[];
+/**
+ * The restore kind for a host's own classes, styles and attributes, shared by a component's own
+ * host restore and `keepPineHydrated`: one fight on a host's classes stops both, and warns once.
+ */
+export declare const HOST_RESTORE = "host";
+/**
+ * Remembers the Stencil classes an element has had, and returns all of them. A restore can't read
+ * them from the latest mutation alone: after a script's last strip they're gone from its old value
+ * too, and the next change would restore nothing.
+ */
+export declare const stencilClassesOf: (seen: Set<string>, el: Element, oldValue: string | null) => string[];
+/**
+ * Wraps a restore callback, which returns whether it wrote anything, so that it writes at most
+ * `MAX_RESTORES_PER_TASK` times before the next task (until the message posted after its first write
+ * runs). Past that, another script is undoing every restore as soon as it lands, so it stops and
+ * lets that script win rather than hang the page. What that script left stays until something
+ * changes the element again: the count resets on the next task, so a later change is restored, but
+ * nothing is restored on its own. The first give-up warns, logging `el` so it can be found in
+ * devtools; later ones, and other restores of the same `kind` giving up on the same element, are
+ * silent.
+ * @param restore - Puts back what something removed; returns `true` if it wrote anything
+ * @param warning - What the console warning says was given up
+ * @param el - The element being restored, logged with the warning
+ * @param kind - What's being restored; one warning per element for each kind
+ */
+export declare const limitRestores: <A extends unknown[]>(restore: (...args: A) => boolean, warning: string, el?: Element, kind?: string) => ((...args: A) => void);
 /**
  * Puts Stencil's own classes back on any Pine component that loses them. Stencil hides a component
  * until it has `hydrated`, so a DOM morph that strips a host's `class` makes it vanish, and nothing
@@ -18,8 +44,9 @@ export declare const classNamesOf: (classes: string | Record<string, boolean>) =
  * host restore of their own. It only restores classes the element had, so it never runs ahead of
  * Stencil. It can't see inside shadow roots, which a morph doesn't reach either.
  *
- * A script that removes `hydrated` on purpose sees it come back, and one that removes it every time it
- * appears never settles: don't strip Pine's classes from a `MutationObserver`.
+ * A script that removes `hydrated` on purpose sees it come back. One that removes it every time it
+ * appears (from a `MutationObserver`, say) wins after a few rounds, and the component logs a console
+ * warning. The component then stays hidden, as that script left it, until its class changes again.
  *
  * Pine's global script calls this, so the CDN and `dist` builds get it on load. The custom-elements
  * build (`@pine-ds/core/components/*`, `@pine-ds/react`) has no global script: call it once yourself.

package/dist/vscode.html-data.json

@@ -8174,7 +8174,7 @@
       "name": "pds-drawer",
       "description": {
         "kind": "markdown",
-        "value": "A non-modal side panel. Unlike `pds-modal`, the page stays interactive while a drawer is open — no dimming, no blur, no scroll lock, no click blocking.\n\n**Events:**\n- `pdsDrawerClose` - Emitted when the drawer is closed\n- `pdsDrawerOpen` - Emitted when the drawer is opened"
+        "value": "A side panel. By default it's non-modal: unlike `pds-modal`, the page stays interactive while a drawer is open — no dimming, no blur, no scroll lock, no click blocking. Add `modal` for a drawer the page should wait on (see [Modal](#modal)).\n\n**Events:**\n- `pdsDrawerClose` - Emitted when the drawer is closed\n- `pdsDrawerOpen` - Emitted when the drawer is opened"
       },
       "attributes": [
         {
@@ -8188,7 +8188,7 @@
           "name": "initial-focus",
           "description": {
             "kind": "markdown",
-            "value": "Whether to move focus into the drawer when it opens. `auto` is right for\na drawer opened by a direct user action (a click, a deep link the user\njust navigated to). Set to `none` for a drawer that can open from a\nbackground event while the user is mid-task elsewhere on the page —\nmoving focus there would interrupt them, and the page stays live under\na non-modal drawer, so it is a genuine data-entry risk, not just an\nannoyance.\n\n**Type:** `\"auto\" | \"none\"`\n\n**Default:** `'auto'`"
+            "value": "Whether to move focus into the drawer when it opens. `auto` is right for\na drawer opened by a direct user action (a click, a deep link the user\njust navigated to). Set to `none` for a drawer that can open from a\nbackground event while the user is mid-task elsewhere on the page —\nmoving focus there would interrupt them, and the page stays live under\na non-modal drawer, so it is a genuine data-entry risk, not just an\nannoyance. A `modal` drawer ignores `none`: the page behind it is inert,\nso focus starts in the drawer.\n\n**Type:** `\"auto\" | \"none\"`\n\n**Default:** `'auto'`"
           },
           "values": [
             {
@@ -8203,7 +8203,14 @@
           "name": "light-dismiss",
           "description": {
             "kind": "markdown",
-            "value": "Whether the drawer can be dismissed with a pointerdown outside it.\nReplaces `pds-modal`'s `backdropDismiss` — there is no backdrop to click.\nThis also gates Escape, matching how `backdropDismiss` gates Escape on\n`pds-modal` today: setting this to `false` means the close button is the\nonly way out.\n\nA trigger outside the drawer should only ever set `open` to `true` and\nleave closing to the drawer itself. A toggle-style trigger (`open =\n!open`) fights light dismiss: clicking it while open closes the drawer\non `pointerdown`, then the trigger's own click handler re-opens it.\n\n**Default:** `true`"
+            "value": "Whether the drawer can be dismissed with a pointerdown outside it (in a\n`modal` drawer, a click on its backdrop).\nReplaces `pds-modal`'s `backdropDismiss`.\nThis also gates Escape, matching how `backdropDismiss` gates Escape on\n`pds-modal` today: setting this to `false` means the close button is the\nonly way out.\n\nA trigger outside the drawer should only ever set `open` to `true` and\nleave closing to the drawer itself. A toggle-style trigger (`open =\n!open`) fights light dismiss: clicking it while open closes the drawer\non `pointerdown`, then the trigger's own click handler re-opens it.\n\n**Default:** `true`"
+          }
+        },
+        {
+          "name": "modal",
+          "description": {
+            "kind": "markdown",
+            "value": "Whether the drawer is modal. A modal drawer dims the page behind it with a\nbackdrop, makes the page inert, and keeps focus inside the drawer, like\n`pds-modal`. Use it for a task the page should wait on. Leave it off for a\npanel people work alongside the page. Read when the drawer opens; changing\nit while the drawer is open is not supported.\n\n**Default:** `false`"
           }
         },
         {
@@ -8304,7 +8311,7 @@
       "name": "pds-dropdown-menu",
       "description": {
         "kind": "markdown",
-        "value": "Dropdown Menus reveal a list of actions from a button trigger, implementing the WAI-ARIA Menu Button pattern. Use them to conserve space when options do not need to be visible at all times.\n\n**Examples:**\n[Default](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#default), [With Separator](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#with-separator), [With Icons](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#with-icons), [With Links](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#with-links), [With External Links](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#with-external-links), [Mixing Menu Items with Raw Elements](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#mixing-menu-items-with-raw-elements), [With Disabled Items](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#with-disabled-items), [With Custom Placement](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#with-custom-placement), [Scrollable Menu](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#scrollable-menu)\n\n**CSS Parts:**\n- `menu-panel` - Exposes the dropdown menu container for styling."
+        "value": "Dropdown Menus reveal a list of actions from a button trigger, implementing the WAI-ARIA Menu Button pattern. Use them to conserve space when options do not need to be visible at all times.\n\n**Examples:**\n[Default](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#default), [With Separator](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#with-separator), [With Icons](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#with-icons), [With Header](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#with-header), [With Links](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#with-links), [With External Links](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#with-external-links), [Mixing Menu Items with Raw Elements](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#mixing-menu-items-with-raw-elements), [With Disabled Items](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#with-disabled-items), [With Custom Placement](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#with-custom-placement), [Scrollable Menu](https://pine-design-system.netlify.app/?path=/docs/components-dropdown-menu--docs#scrollable-menu)\n\n**Slots:**\n- `header` - Non-interactive content displayed above the menu items inside the dropdown panel. It renders outside the menu role, so assistive tech reads it as plain content rather than as a menu item.\n\n**CSS Parts:**\n- `menu-panel` - Exposes the dropdown menu container for styling."
       },
       "attributes": [
         {
@@ -9062,7 +9069,7 @@
           "name": "backdrop-dismiss",
           "description": {
             "kind": "markdown",
-            "value": "Whether the modal can be dismissed by clicking the backdrop\n\n**Default:** `true`"
+            "value": "Whether the modal can be dismissed by clicking the backdrop, pressing Escape, or the browser's\nown close request (such as a back gesture)\n\n**Default:** `true`"
           }
         },
         {
@@ -11016,7 +11023,7 @@
           "name": "variant",
           "description": {
             "kind": "markdown",
-            "value": "Sets tabs variant styles as outlined in Figma documentation\n\n**Type:** `\"availability\" | \"filter\" | \"pill\" | \"primary\"`"
+            "value": "Sets tabs variant styles as outlined in Figma documentation.\nApplies in both panel and nav mode; omitting it renders the primary style.\n\n**Type:** `\"availability\" | \"filter\" | \"pill\" | \"primary\"`"
           },
           "values": [
             {