@porsche-design-system/components-react 4.6.0-rc.2 → 4.6.0

package/CHANGELOG.md

@@ -14,6 +14,31 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0),
 
 ## [Unreleased]
 
+## [4.6.0] - 2026-08-20
+
+## [4.6.0-rc.3] - 2026-08-19
+
+### Added
+
+- **Testing**: the `testing` sub-package now provides a `Shadow` counterpart for every Testing Library query, so
+  elements rendered inside Shadow DOM can be queried directly. Eight query families (`AltText`, `DisplayValue`,
+  `LabelText`, `PlaceholderText`, `Role`, `TestId`, `Text`, `Title`) in six variants each, plus `screen`, `within`,
+  `deepQuerySelector` and `deepQuerySelectorAll`. The existing `getByRoleShadowed`, `getByLabelTextShadowed` and
+  `getByTextShadowed` helpers remain available.
+  ([#4492](https://github.com/porsche-design-system/porsche-design-system/pull/4492))
+
+### Changed
+
+- **Testing**: the `testing` sub-package requires a DOM. Importing it where no DOM is available now throws an explicit
+  error on import. ([#4492](https://github.com/porsche-design-system/porsche-design-system/pull/4492))
+- `Flyout`, `Modal`, `Sheet`, `Drilldown`: the `dismiss` event now carries a payload identifying how the component was
+  closed. The event detail changed from `void` to `{ reason: 'dismiss-button' | 'backdrop' | 'escape' }`, exported as
+  `FlyoutDismissEventDetail`, `ModalDismissEventDetail`, `SheetDismissEventDetail` and `DrilldownDismissEventDetail`.
+  ([#4675](https://github.com/porsche-design-system/porsche-design-system/pull/4675))
+- `Popover`: the `dismiss` event now carries a payload identifying how the component was closed. The event detail
+  changed from `void` to `{ reason: 'outside-click' | 'focus-out' | 'escape' }`, exported as
+  `PopoverDismissEventDetail`. ([#4675](https://github.com/porsche-design-system/porsche-design-system/pull/4675))
+
 ## [4.6.0-rc.2] - 2026-08-13
 
 ### Added

package/esm/lib/components/drilldown.wrapper.d.ts

@@ -1,5 +1,5 @@
 import type { BaseProps } from '../../BaseProps';
-import type { SelectedAriaAttributes, DrilldownAriaAttribute, DrilldownUpdateEventDetail } from '../types';
+import type { SelectedAriaAttributes, DrilldownAriaAttribute, DrilldownDismissEventDetail, DrilldownUpdateEventDetail } from '../types';
 export type PDrilldownProps = BaseProps & {
     /**
      * Sets which `p-drilldown-item` (by `identifier`) is currently expanded to show its sub-navigation level.
@@ -10,9 +10,9 @@ export type PDrilldownProps = BaseProps & {
      */
     aria?: SelectedAriaAttributes<DrilldownAriaAttribute>;
     /**
-     * Emitted when the user closes the drilldown via the close button or Escape key.
+     * Emitted when the user closes the drilldown via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<DrilldownDismissEventDetail>) => void;
     /**
      * Emitted when the active navigation level changes, with the new `activeIdentifier` in the event detail.
      */
@@ -33,9 +33,9 @@ export declare const PDrilldown: import("react").ForwardRefExoticComponent<Omit<
      */
     aria?: SelectedAriaAttributes<DrilldownAriaAttribute>;
     /**
-     * Emitted when the user closes the drilldown via the close button or Escape key.
+     * Emitted when the user closes the drilldown via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<DrilldownDismissEventDetail>) => void;
     /**
      * Emitted when the active navigation level changes, with the new `activeIdentifier` in the event detail.
      */

package/esm/lib/components/flyout.wrapper.d.ts

@@ -1,5 +1,5 @@
 import type { BaseProps } from '../../BaseProps';
-import type { SelectedAriaAttributes, FlyoutAriaAttribute, FlyoutBackdrop, FlyoutBackground, FlyoutFooterBehavior, BreakpointCustomizable, FlyoutMotionHiddenEndEventDetail, FlyoutMotionVisibleEndEventDetail, FlyoutPosition } from '../types';
+import type { SelectedAriaAttributes, FlyoutAriaAttribute, FlyoutBackdrop, FlyoutBackground, FlyoutFooterBehavior, BreakpointCustomizable, FlyoutDismissEventDetail, FlyoutMotionHiddenEndEventDetail, FlyoutMotionVisibleEndEventDetail, FlyoutPosition } from '../types';
 export type PFlyoutProps = BaseProps & {
     /**
      * Sets ARIA attributes on the flyout dialog element for improved screen reader accessibility.
@@ -31,9 +31,9 @@ export type PFlyoutProps = BaseProps & {
      */
     fullscreen?: BreakpointCustomizable<boolean>;
     /**
-     * Emitted when the user closes the flyout via the close button, backdrop click, or Escape key.
+     * Emitted when the user closes the flyout via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<FlyoutDismissEventDetail>) => void;
     /**
      * Emitted after the flyout's close transition completes and the panel is fully hidden.
      */
@@ -84,9 +84,9 @@ export declare const PFlyout: import("react").ForwardRefExoticComponent<Omit<imp
      */
     fullscreen?: BreakpointCustomizable<boolean>;
     /**
-     * Emitted when the user closes the flyout via the close button, backdrop click, or Escape key.
+     * Emitted when the user closes the flyout via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<FlyoutDismissEventDetail>) => void;
     /**
      * Emitted after the flyout's close transition completes and the panel is fully hidden.
      */

package/esm/lib/components/modal.wrapper.d.ts

@@ -1,5 +1,5 @@
 import type { BaseProps } from '../../BaseProps';
-import type { SelectedAriaAttributes, ModalAriaAttribute, ModalBackdrop, ModalBackground, BreakpointCustomizable, ModalMotionHiddenEndEventDetail, ModalMotionVisibleEndEventDetail } from '../types';
+import type { SelectedAriaAttributes, ModalAriaAttribute, ModalBackdrop, ModalBackground, BreakpointCustomizable, ModalDismissEventDetail, ModalMotionHiddenEndEventDetail, ModalMotionVisibleEndEventDetail } from '../types';
 export type PModalProps = BaseProps & {
     /**
      * Sets ARIA attributes on the dialog element for improved accessibility when no visible heading is present.
@@ -31,9 +31,9 @@ export type PModalProps = BaseProps & {
      */
     fullscreen?: BreakpointCustomizable<boolean>;
     /**
-     * Emitted when the user closes the modal via the dismiss button, backdrop click, or Escape key.
+     * Emitted when the user closes the modal via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<ModalDismissEventDetail>) => void;
     /**
      * Emitted after the modal's close transition completes and the dialog is fully hidden.
      */
@@ -79,9 +79,9 @@ export declare const PModal: import("react").ForwardRefExoticComponent<Omit<impo
      */
     fullscreen?: BreakpointCustomizable<boolean>;
     /**
-     * Emitted when the user closes the modal via the dismiss button, backdrop click, or Escape key.
+     * Emitted when the user closes the modal via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<ModalDismissEventDetail>) => void;
     /**
      * Emitted after the modal's close transition completes and the dialog is fully hidden.
      */

package/esm/lib/components/popover.wrapper.d.ts

@@ -1,5 +1,5 @@
 import type { BaseProps } from '../../BaseProps';
-import type { SelectedAriaAttributes, PopoverAriaAttribute, PopoverDirection } from '../types';
+import type { SelectedAriaAttributes, PopoverAriaAttribute, PopoverDirection, PopoverDismissEventDetail } from '../types';
 export type PPopoverProps = BaseProps & {
     /**
      * Sets ARIA attributes on the popover panel to improve accessibility for screen readers.
@@ -19,9 +19,9 @@ export type PPopoverProps = BaseProps & {
      */
     direction?: PopoverDirection;
     /**
-     * Emitted in controlled mode when the user requests to close the popover via the Escape key, an outside click, or when keyboard focus leaves the popover (Tab / Shift+Tab).
+     * Emitted in controlled mode when the user requests to close the popover via the Escape key, an outside click, or when keyboard focus leaves the popover (Tab / Shift+Tab). The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<PopoverDismissEventDetail>) => void;
     /**
      * Controls whether the popover is visible. When set (controlled mode), visibility follows this prop and the consumer owns the open state via a slotted `button`. When omitted (uncontrolled mode), the component manages visibility itself.
      */
@@ -46,9 +46,9 @@ export declare const PPopover: import("react").ForwardRefExoticComponent<Omit<im
      */
     direction?: PopoverDirection;
     /**
-     * Emitted in controlled mode when the user requests to close the popover via the Escape key, an outside click, or when keyboard focus leaves the popover (Tab / Shift+Tab).
+     * Emitted in controlled mode when the user requests to close the popover via the Escape key, an outside click, or when keyboard focus leaves the popover (Tab / Shift+Tab). The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<PopoverDismissEventDetail>) => void;
     /**
      * Controls whether the popover is visible. When set (controlled mode), visibility follows this prop and the consumer owns the open state via a slotted `button`. When omitted (uncontrolled mode), the component manages visibility itself.
      */

package/esm/lib/components/sheet.wrapper.d.ts

@@ -1,5 +1,5 @@
 import type { BaseProps } from '../../BaseProps';
-import type { SelectedAriaAttributes, SheetAriaAttribute, SheetBackground, SheetMotionHiddenEndEventDetail, SheetMotionVisibleEndEventDetail } from '../types';
+import type { SelectedAriaAttributes, SheetAriaAttribute, SheetBackground, SheetDismissEventDetail, SheetMotionHiddenEndEventDetail, SheetMotionVisibleEndEventDetail } from '../types';
 export type PSheetProps = BaseProps & {
     /**
      * Sets ARIA attributes on the sheet dialog element for improved accessibility when the default `aria-label` is insufficient.
@@ -21,9 +21,9 @@ export type PSheetProps = BaseProps & {
      */
     dismissButton?: boolean;
     /**
-     * Emitted when the user dismisses the sheet via the close button, backdrop click, or Escape key.
+     * Emitted when the user closes the sheet via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<SheetDismissEventDetail>) => void;
     /**
      * Emitted after the sheet's close transition has fully completed and the panel is hidden.
      */
@@ -59,9 +59,9 @@ export declare const PSheet: import("react").ForwardRefExoticComponent<Omit<impo
      */
     dismissButton?: boolean;
     /**
-     * Emitted when the user dismisses the sheet via the close button, backdrop click, or Escape key.
+     * Emitted when the user closes the sheet via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<SheetDismissEventDetail>) => void;
     /**
      * Emitted after the sheet's close transition has fully completed and the panel is hidden.
      */

package/esm/lib/types.d.ts

@@ -697,6 +697,10 @@ export type BreakpointValues<T> = {
     base: T;
 };
 export type BreakpointCustomizable<T> = T | BreakpointValues<T>;
+export type DialogDismissReason = "dismiss-button" | "backdrop" | "escape";
+export type DialogDismissEventDetail = {
+    reason: DialogDismissReason;
+};
 declare const LINK_TARGETS: readonly [
     "_self",
     "_blank",
@@ -1129,6 +1133,7 @@ export type DrilldownAriaAttribute = (typeof DRILLDOWN_ARIA_ATTRIBUTES)[number];
 export type DrilldownUpdateEventDetail = {
     activeIdentifier: string | undefined;
 };
+export type DrilldownDismissEventDetail = DialogDismissEventDetail;
 export type DrilldownLinkTarget = LinkTarget;
 export type DrilldownLinkAriaAttribute = LinkAriaAttribute;
 declare const FIELDSET_LABEL_SIZES: readonly [
@@ -1188,6 +1193,7 @@ declare const FLYOUT_ARIA_ATTRIBUTES: readonly [
 export type FlyoutAriaAttribute = (typeof FLYOUT_ARIA_ATTRIBUTES)[number];
 export type FlyoutMotionVisibleEndEventDetail = TransitionEvent;
 export type FlyoutMotionHiddenEndEventDetail = TransitionEvent;
+export type FlyoutDismissEventDetail = DialogDismissEventDetail;
 export type FlyoutBackdrop = Backdrop;
 declare const HEADING_TAGS: readonly [
     "h1",
@@ -1417,6 +1423,7 @@ export type ModalBackground = (typeof MODAL_BACKGROUNDS)[number];
 export type ModalBackdrop = Backdrop;
 export type ModalMotionVisibleEndEventDetail = TransitionEvent;
 export type ModalMotionHiddenEndEventDetail = TransitionEvent;
+export type ModalDismissEventDetail = DialogDismissEventDetail;
 declare const MODEL_SIGNATURES_MANIFEST: {
     "718": {
         src: string;
@@ -1539,6 +1546,9 @@ declare const POPOVER_ARIA_ATTRIBUTES: readonly [
     "aria-label"
 ];
 export type PopoverAriaAttribute = (typeof POPOVER_ARIA_ATTRIBUTES)[number];
+export type PopoverDismissEventDetail = {
+    reason: "outside-click" | "focus-out" | "escape";
+};
 declare const GROUP_DIRECTIONS: readonly [
     "row",
     "column"
@@ -1587,6 +1597,7 @@ declare const SHEET_BACKGROUNDS: readonly [
 export type SheetBackground = (typeof SHEET_BACKGROUNDS)[number];
 export type SheetMotionVisibleEndEventDetail = TransitionEvent;
 export type SheetMotionHiddenEndEventDetail = TransitionEvent;
+export type SheetDismissEventDetail = DialogDismissEventDetail;
 declare const SPINNER_COLORS: readonly [
     "primary",
     "inherit"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porsche-design-system/components-react",
-  "version": "4.6.0-rc.2",
+  "version": "4.6.0",
   "description": "Porsche Design System is a component library designed to help developers create the best experience for software or services distributed by Dr. Ing. h.c. F. Porsche AG.",
   "keywords": [
     "porsche",
@@ -21,7 +21,7 @@
     "url": "https://github.com/porsche-design-system/porsche-design-system"
   },
   "dependencies": {
-    "@porsche-design-system/components-js": "4.6.0-rc.2"
+    "@porsche-design-system/components-js": "4.6.0"
   },
   "peerDependencies": {
     "ag-grid-community": ">= 36.0.0 <37.0.0",

package/skills/pds-knowledge-react/SKILL.md

@@ -15,11 +15,11 @@ Prefer Porsche Design System components and tokens for new UI, even when the use
 
 This skill currently covers components, global stylesheets and theming, tokens, and styling integrations. It does not yet include complete getting-started, setup, and installation guidance; the v3-to-v4 migration guide; the changelog; partials; patterns and templates; the AG Grid theme; or the Storefront’s Must Know and Help sections.
 
-Before using documentation outside this skill or the installed package, match it to the installed PDS version. This skill was generated for `4.6.0-rc.2`; prefer the [exact-version Porsche Design System Storefront](https://designsystem.porsche.com/v4.6.0-rc.2/). Major-version URLs such as `/v4/` always serve the latest v4 release and may describe APIs or setup introduced after the installed version. Use them only as a fallback and verify relevant details against the installed package.
+Before using documentation outside this skill or the installed package, match it to the installed PDS version. This skill was generated for `4.6.0`; prefer the [exact-version Porsche Design System Storefront](https://designsystem.porsche.com/v4.6.0/). Major-version URLs such as `/v4/` always serve the latest v4 release and may describe APIs or setup introduced after the installed version. Use them only as a fallback and verify relevant details against the installed package.
 
 For runnable patterns and templates, consult the [Porsche Design System examples repository](https://github.com/porsche-design-system/examples), selecting a release tag or commit that matches the installed package instead of assuming its default branch is compatible. For release-specific changes, read `../../CHANGELOG.md`.
 
-For exact API facts, inspect the installed typings and metadata first. When readable implementation details are necessary, use the [exact-version component source](https://github.com/porsche-design-system/porsche-design-system/tree/v4.6.0-rc.2/packages/components/src/components) under the repository's `packages/components/src/components/<component>` directory. Do not use the default branch, which may represent a newer release.
+For exact API facts, inspect the installed typings and metadata first. When readable implementation details are necessary, use the [exact-version component source](https://github.com/porsche-design-system/porsche-design-system/tree/v4.6.0/packages/components/src/components) under the repository's `packages/components/src/components/<component>` directory. Do not use the default branch, which may represent a newer release.
 
 For deployed browser behavior, inspect component requests in the Network panel. Treat these minified, content-hashed CDN artifacts as a debugging fallback; use the exact-version repository source for readable implementation details.
 
@@ -110,7 +110,7 @@ import { PButton, PorscheDesignSystemProvider } from '@porsche-design-system/com
 
 On the server, the `/ssr` build emits component markup and styles as Declarative Shadow DOM so the browser can create the Shadow DOM before JavaScript runs. In the browser, it initializes like the standard React wrapper. The framework build must replace `process.browser` for its server and client targets and eliminate the unused branch.
 
-Framework setup differs. Follow the [Next.js integration guide](https://designsystem.porsche.com/v4.6.0-rc.2/developing/next-js/getting-started/) or the [React Router integration guide](https://designsystem.porsche.com/v4.6.0-rc.2/developing/react-router/getting-started/). Remix users should follow the React Router guidance because Remix v2 was upstreamed into React Router.
+Framework setup differs. Follow the [Next.js integration guide](https://designsystem.porsche.com/v4.6.0/developing/next-js/getting-started/) or the [React Router integration guide](https://designsystem.porsche.com/v4.6.0/developing/react-router/getting-started/). Remix users should follow the React Router guidance because Remix v2 was upstreamed into React Router.
 
 ## Stylesheets
 

package/skills/pds-knowledge-react/references/components/p-drilldown/p-drilldown.md

@@ -92,7 +92,7 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 
 | Event | Type | Description |
 | --- | --- | --- |
-| `dismiss` | `CustomEvent<void>` | Emitted when the user closes the drilldown via the close button or Escape key. |
+| `dismiss` | `CustomEvent<DrilldownDismissEventDetail>`<br>`{ reason: 'dismiss-button' | 'backdrop' | 'escape' }` | Emitted when the user closes the drilldown via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used. |
 | `update` | `CustomEvent<DrilldownUpdateEventDetail>`<br>`{ activeIdentifier: string | undefined }` | Emitted when the active navigation level changes, with the new `activeIdentifier` in the event detail. |
 
 ### Controlled properties

package/skills/pds-knowledge-react/references/components/p-flyout/p-flyout.md

@@ -95,7 +95,7 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 
 | Event | Type | Description |
 | --- | --- | --- |
-| `dismiss` | `CustomEvent<void>` | Emitted when the user closes the flyout via the close button, backdrop click, or Escape key. |
+| `dismiss` | `CustomEvent<FlyoutDismissEventDetail>`<br>`{ reason: 'dismiss-button' | 'backdrop' | 'escape' }` | Emitted when the user closes the flyout via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used. |
 | `motionHiddenEnd` | `CustomEvent<FlyoutMotionHiddenEndEventDetail>`<br>`TransitionEvent` | Emitted after the flyout's close transition completes and the panel is fully hidden. |
 | `motionVisibleEnd` | `CustomEvent<FlyoutMotionVisibleEndEventDetail>`<br>`TransitionEvent` | Emitted after the flyout's open transition completes and the panel is fully visible. |
 

package/skills/pds-knowledge-react/references/components/p-modal/p-modal.md

@@ -102,7 +102,7 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 
 | Event | Type | Description |
 | --- | --- | --- |
-| `dismiss` | `CustomEvent<void>` | Emitted when the user closes the modal via the dismiss button, backdrop click, or Escape key. |
+| `dismiss` | `CustomEvent<ModalDismissEventDetail>`<br>`{ reason: 'dismiss-button' | 'backdrop' | 'escape' }` | Emitted when the user closes the modal via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used. |
 | `motionHiddenEnd` | `CustomEvent<ModalMotionHiddenEndEventDetail>`<br>`TransitionEvent` | Emitted after the modal's close transition completes and the dialog is fully hidden. |
 | `motionVisibleEnd` | `CustomEvent<ModalMotionVisibleEndEventDetail>`<br>`TransitionEvent` | Emitted after the modal's open transition completes and the dialog is fully visible. |
 

package/skills/pds-knowledge-react/references/components/p-popover/p-popover.md

@@ -85,7 +85,7 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 
 | Event | Type | Description |
 | --- | --- | --- |
-| `dismiss` | `CustomEvent<void>` | Emitted in controlled mode when the user requests to close the popover via the Escape key, an outside click, or when keyboard focus leaves the popover (Tab / Shift+Tab). |
+| `dismiss` | `CustomEvent<PopoverDismissEventDetail>`<br>`{ reason: 'outside-click' | 'focus-out' | 'escape' }` | Emitted in controlled mode when the user requests to close the popover via the Escape key, an outside click, or when keyboard focus leaves the popover (Tab / Shift+Tab). The event detail identifies which of the three was used. |
 
 ### Controlled properties
 

package/skills/pds-knowledge-react/references/components/p-sheet/p-sheet.md

@@ -95,7 +95,7 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 
 | Event | Type | Description |
 | --- | --- | --- |
-| `dismiss` | `CustomEvent<void>` | Emitted when the user dismisses the sheet via the close button, backdrop click, or Escape key. |
+| `dismiss` | `CustomEvent<SheetDismissEventDetail>`<br>`{ reason: 'dismiss-button' | 'backdrop' | 'escape' }` | Emitted when the user closes the sheet via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used. |
 | `motionHiddenEnd` | `CustomEvent<SheetMotionHiddenEndEventDetail>`<br>`TransitionEvent` | Emitted after the sheet's close transition has fully completed and the panel is hidden. |
 | `motionVisibleEnd` | `CustomEvent<SheetMotionVisibleEndEventDetail>`<br>`TransitionEvent` | Emitted after the sheet's open transition has fully completed and the panel is visible. |
 

package/skills/pds-knowledge-react/references/components/p-table/p-table.md

@@ -86,7 +86,7 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 
 | Event | Type | Description |
 | --- | --- | --- |
-| `update` | `CustomEvent<TableUpdateEventDetail>`<br>`{ id: string; active?: boolean; direction?: Direction }` | Emitted when the user clicks a sortable column header, carrying the new sort configuration in the event detail. |
+| `update` | `CustomEvent<TableUpdateEventDetail>`<br>`{ id: string; active?: boolean; direction?: 'asc' | 'desc' }` | Emitted when the user clicks a sortable column header, carrying the new sort configuration in the event detail. |
 
 ### Slots
 

package/ssr/cjs/components/dist/styles/esm/styles-entry.cjs

@@ -3849,7 +3849,7 @@ const OPTION_LIST_SAFE_ZONE = 6;
 
 const getCDNBaseURL = () => global.PORSCHE_DESIGN_SYSTEM_CDN_URL + "/porsche-design-system";
 
-const prefix = `[Porsche Design System v${"4.6.0-rc.2"}]` // this part isn't covered by unit tests
+const prefix = `[Porsche Design System v${"4.6.0"}]` // this part isn't covered by unit tests
     ;
 const consoleError = (...messages) => {
     console.error(prefix, ...messages);

package/ssr/cjs/components/dist/utils/esm/utils-entry.cjs

@@ -3473,6 +3473,29 @@ const showDialog = (dialog, scrollArea) => {
     dialog.inert = false; // Re-enable focus on dialog element
     dialog.focus(); // set focus programmatically to dialog element to prevent transition bug in Safari
 };
+// Callers map this to the `escape` dismiss reason, which only holds because we never set `closedby`. With
+// `closedby="any"` the native `cancel` fires for outside clicks too, indistinguishably, so they would be reported as
+// `escape` and no test would catch it. Backdrop clicks are detected separately via `isDialogBackdropTarget`.
+const onCancelDialog = (e, cb, disable = false) => {
+    e.preventDefault(); // prevent closing the dialog uncontrolled by ESC
+    if (!disable) {
+        cb();
+    }
+};
+// A click/press lands on the backdrop when its target is the `<dialog>` element itself or the `.scroller` wrapper
+// (both cover the area around the panel). Any deeper target means the interaction happened inside the panel content.
+const isDialogBackdropTarget = (e) => {
+    const target = e.target;
+    return target.className === 'scroller' || target.tagName === 'DIALOG';
+};
+const onClickDialog = (e, cb, disable, isPointerDownInside = false) => {
+    // Skip dismissal when the pointer gesture *started* inside the panel (e.g. a text selection dragged out and released
+    // on the backdrop). A `click` only fires on the nearest common ancestor of `mousedown`/`mouseup`, so such a gesture
+    // retargets the resulting `click` to the backdrop and would otherwise wrongly dismiss. Mirrors `p-popover`.
+    if (!disable && !isPointerDownInside && isDialogBackdropTarget(e)) {
+        cb(); // dismiss dialog when clicked on backdrop
+    }
+};
 
 const getCDNBaseURL = () => global.PORSCHE_DESIGN_SYSTEM_CDN_URL + "/porsche-design-system";
 
@@ -3482,7 +3505,7 @@ const hasShowPickerSupport = () => (hasDocument &&
     'showPicker' in HTMLInputElement.prototype &&
     CSS.supports('selector(::-webkit-calendar-picker-indicator)'));
 
-const prefix = `[Porsche Design System v${"4.6.0-rc.2"}]` // this part isn't covered by unit tests
+const prefix = `[Porsche Design System v${"4.6.0"}]` // this part isn't covered by unit tests
     ;
 const consoleError$1 = (...messages) => {
     console.error(prefix, ...messages);
@@ -4441,6 +4464,7 @@ exports.hasWindow = hasWindow$1;
 exports.headerSlot = headerSlot;
 exports.internalDrilldown = internalDrilldown;
 exports.isCurrentInput = isCurrentInput;
+exports.isDialogBackdropTarget = isDialogBackdropTarget;
 exports.isDisabledOrLoading = isDisabledOrLoading;
 exports.isElementOfKind = isElementOfKind;
 exports.isInfinitePagination = isInfinitePagination;
@@ -4452,6 +4476,8 @@ exports.labelId = labelId;
 exports.mergeInputNativeAria = mergeInputNativeAria;
 exports.normalizeAiTagLocale = normalizeAiTagLocale;
 exports.observedNodesMap = observedNodesMap;
+exports.onCancelDialog = onCancelDialog;
+exports.onClickDialog = onClickDialog;
 exports.parseAndGetAriaAttributes = parseAndGetAriaAttributes;
 exports.parseJSONAttribute = parseJSONAttribute;
 exports.resolveAiTagTranslationLanguage = resolveAiTagTranslationLanguage;

package/ssr/cjs/components-react/projects/react-ssr-wrapper/src/lib/dsr-components/drilldown.cjs

@@ -39,6 +39,7 @@ class DSRDrilldown extends react.Component {
         const style = minifyCss.minifyCss(stylesEntry.getDrilldownCss(this.props.open, this.primary, this.isSecondaryDrawerVisible));
         return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsxs("template", { shadowroot: "open", shadowrootmode: "open", children: [jsxRuntime.jsx("style", { dangerouslySetInnerHTML: { __html: style } }), jsxRuntime.jsx("dialog", { inert: !this.props.open, ...utilsEntry.parseAndGetAriaAttributes(this.props.aria), children: jsxRuntime.jsxs("div", { className: "drawer", children: [jsxRuntime.jsx(buttonPure_wrapper.PButtonPure, { className: "back", type: "button", size: "small", alignLabel: "end", stretch: true, icon: "arrow-left", hideLabel: true, children: "Back" }), jsxRuntime.jsx(button_wrapper.PButton, { className: "dismiss-mobile", type: "button", icon: "close", compact: true, variant: "secondary", hideLabel: true, children: "Dismiss drilldown" }), jsxRuntime.jsx(button_wrapper.PButton, { className: "dismiss-desktop", type: "button", icon: "close", variant: "secondary", hideLabel: true, children: "Dismiss drilldown" }), jsxRuntime.jsx("div", { className: "scroller", children: jsxRuntime.jsx("slot", {}) })] }) })] }), this.props.children] }));
     }
+    onDismissButtonClick = () => this.props.dismissDialog('dismiss-button');
 }
 
 exports.DSRDrilldown = DSRDrilldown;

package/ssr/cjs/components-react/projects/react-ssr-wrapper/src/lib/dsr-components/flyout.cjs

@@ -56,6 +56,9 @@ class DSRFlyout extends react.Component {
                                 ...utilsEntry.parseAndGetAriaAttributes(this.props.aria),
                             }), children: jsxRuntime.jsx("slot", {}) })] }), this.props.children] }));
     }
+    onDialogCancel = (e) => utilsEntry.onCancelDialog(e, () => this.props.dismissDialog('escape'));
+    onDialogBackdropClick = (e) => utilsEntry.onClickDialog(e, () => this.props.dismissDialog('backdrop'), this.props.disableBackdropClick, this.props.isPointerDownInside);
+    onDismissButtonClick = () => this.props.dismissDialog('dismiss-button');
 }
 
 exports.DSRFlyout = DSRFlyout;

package/ssr/cjs/components-react/projects/react-ssr-wrapper/src/lib/dsr-components/modal.cjs

@@ -54,6 +54,9 @@ class DSRModal extends react.Component {
                                 ...utilsEntry.parseAndGetAriaAttributes(this.props.aria),
                             }), children: jsxRuntime.jsx("slot", {}) })] }), this.props.children] }));
     }
+    onDialogCancel = (e) => utilsEntry.onCancelDialog(e, () => this.props.dismissDialog('escape'), !this.props.dismissButton);
+    onDialogBackdropClick = (e) => utilsEntry.onClickDialog(e, () => this.props.dismissDialog('backdrop'), this.props.disableBackdropClick, this.props.isPointerDownInside);
+    onDismissButtonClick = () => this.props.dismissDialog('dismiss-button');
 }
 
 exports.DSRModal = DSRModal;

package/ssr/cjs/components-react/projects/react-ssr-wrapper/src/lib/dsr-components/sheet.cjs

@@ -51,6 +51,9 @@ class DSRSheet extends react.Component {
                                 ...utilsEntry.parseAndGetAriaAttributes(this.props.aria),
                             }), children: jsxRuntime.jsx("slot", {}) })] }), this.props.children] }));
     }
+    onDialogCancel = (e) => utilsEntry.onCancelDialog(e, () => this.props.dismissDialog('escape'), !this.props.dismissButton);
+    onDialogBackdropClick = (e) => utilsEntry.onClickDialog(e, () => this.props.dismissDialog('backdrop'), this.props.disableBackdropClick, this.props.isPointerDownInside);
+    onDismissButtonClick = () => this.props.dismissDialog('dismiss-button');
 }
 
 exports.DSRSheet = DSRSheet;

package/ssr/esm/components/dist/styles/esm/styles-entry.mjs

@@ -3847,7 +3847,7 @@ const OPTION_LIST_SAFE_ZONE = 6;
 
 const getCDNBaseURL = () => global.PORSCHE_DESIGN_SYSTEM_CDN_URL + "/porsche-design-system";
 
-const prefix = `[Porsche Design System v${"4.6.0-rc.2"}]` // this part isn't covered by unit tests
+const prefix = `[Porsche Design System v${"4.6.0"}]` // this part isn't covered by unit tests
     ;
 const consoleError = (...messages) => {
     console.error(prefix, ...messages);

package/ssr/esm/components/dist/utils/esm/utils-entry.mjs

@@ -3471,6 +3471,29 @@ const showDialog = (dialog, scrollArea) => {
     dialog.inert = false; // Re-enable focus on dialog element
     dialog.focus(); // set focus programmatically to dialog element to prevent transition bug in Safari
 };
+// Callers map this to the `escape` dismiss reason, which only holds because we never set `closedby`. With
+// `closedby="any"` the native `cancel` fires for outside clicks too, indistinguishably, so they would be reported as
+// `escape` and no test would catch it. Backdrop clicks are detected separately via `isDialogBackdropTarget`.
+const onCancelDialog = (e, cb, disable = false) => {
+    e.preventDefault(); // prevent closing the dialog uncontrolled by ESC
+    if (!disable) {
+        cb();
+    }
+};
+// A click/press lands on the backdrop when its target is the `<dialog>` element itself or the `.scroller` wrapper
+// (both cover the area around the panel). Any deeper target means the interaction happened inside the panel content.
+const isDialogBackdropTarget = (e) => {
+    const target = e.target;
+    return target.className === 'scroller' || target.tagName === 'DIALOG';
+};
+const onClickDialog = (e, cb, disable, isPointerDownInside = false) => {
+    // Skip dismissal when the pointer gesture *started* inside the panel (e.g. a text selection dragged out and released
+    // on the backdrop). A `click` only fires on the nearest common ancestor of `mousedown`/`mouseup`, so such a gesture
+    // retargets the resulting `click` to the backdrop and would otherwise wrongly dismiss. Mirrors `p-popover`.
+    if (!disable && !isPointerDownInside && isDialogBackdropTarget(e)) {
+        cb(); // dismiss dialog when clicked on backdrop
+    }
+};
 
 const getCDNBaseURL = () => global.PORSCHE_DESIGN_SYSTEM_CDN_URL + "/porsche-design-system";
 
@@ -3480,7 +3503,7 @@ const hasShowPickerSupport = () => (hasDocument &&
     'showPicker' in HTMLInputElement.prototype &&
     CSS.supports('selector(::-webkit-calendar-picker-indicator)'));
 
-const prefix = `[Porsche Design System v${"4.6.0-rc.2"}]` // this part isn't covered by unit tests
+const prefix = `[Porsche Design System v${"4.6.0"}]` // this part isn't covered by unit tests
     ;
 const consoleError$1 = (...messages) => {
     console.error(prefix, ...messages);
@@ -4385,4 +4408,4 @@ const getTextTagType = (host, tag) => {
     return tag;
 };
 
-export { AI_TAG_LOCALES_DEPRECATED, AI_TAG_TRANSLATIONS, DISPLAY_TAGS, HEADING_TAGS, ItemType, MARKET_LOCALES, TEXT_TAGS, anchorSlot, attributeMutationMap, buildCrestImgSrc, buildCrestSrcSet, buildFlagUrl, buildIconUrl, consoleError$1 as consoleError, createPaginationItems, createRange, createTopLayerController, crestSize, descriptionId, displaySizeToTagMap, getAiTagLanguage, getAiTagTranslation, getBannerAriaAttributes, getButtonAriaAttributes, getButtonBaseAriaAttributes, getButtonPureAriaAttributes, getCDNBaseURL, getComboboxAriaAttributes, getCurrentActivePage, getDirectChildHTMLElement, getDisplayTagType, getFieldsetAriaAttributes, getHTMLElement, getHasNativePopoverSupport, getHeadingTagType, getInlineNotificationAriaAttributes, getListboxAriaAttributes, getMaxTransitionDurationMs, getSanitizedActiveTabIndex, getSegmentedControlItemAriaAttributes, getStepperHorizontalIconName, getSvgUrl, getSwitchButtonAriaAttributes, getTagName, getTagNameWithoutPrefix, getTextTagType, getTotalPages, hasDocument, hasShowPickerSupport, hasSpecificDirectChildTag, hasVisibleIcon, hasWindow$1 as hasWindow, headerSlot, internalDrilldown, isCurrentInput, isDisabledOrLoading, isElementOfKind, isInfinitePagination, isListTypeOrdered, isSortable, isStateCompleteOrWarning, isUrl, labelId, mergeInputNativeAria, normalizeAiTagLocale, observedNodesMap, parseAndGetAriaAttributes, parseJSONAttribute, resolveAiTagTranslationLanguage, setAriaIDREF, showDialog, supportsConstructableStylesheets, supportsNativePopover, supportsOverlayTransition, tempDiv, tempIcon, tempLabel, traverseTreeAndUpdateState, updateDrilldownItemState };
+export { AI_TAG_LOCALES_DEPRECATED, AI_TAG_TRANSLATIONS, DISPLAY_TAGS, HEADING_TAGS, ItemType, MARKET_LOCALES, TEXT_TAGS, anchorSlot, attributeMutationMap, buildCrestImgSrc, buildCrestSrcSet, buildFlagUrl, buildIconUrl, consoleError$1 as consoleError, createPaginationItems, createRange, createTopLayerController, crestSize, descriptionId, displaySizeToTagMap, getAiTagLanguage, getAiTagTranslation, getBannerAriaAttributes, getButtonAriaAttributes, getButtonBaseAriaAttributes, getButtonPureAriaAttributes, getCDNBaseURL, getComboboxAriaAttributes, getCurrentActivePage, getDirectChildHTMLElement, getDisplayTagType, getFieldsetAriaAttributes, getHTMLElement, getHasNativePopoverSupport, getHeadingTagType, getInlineNotificationAriaAttributes, getListboxAriaAttributes, getMaxTransitionDurationMs, getSanitizedActiveTabIndex, getSegmentedControlItemAriaAttributes, getStepperHorizontalIconName, getSvgUrl, getSwitchButtonAriaAttributes, getTagName, getTagNameWithoutPrefix, getTextTagType, getTotalPages, hasDocument, hasShowPickerSupport, hasSpecificDirectChildTag, hasVisibleIcon, hasWindow$1 as hasWindow, headerSlot, internalDrilldown, isCurrentInput, isDialogBackdropTarget, isDisabledOrLoading, isElementOfKind, isInfinitePagination, isListTypeOrdered, isSortable, isStateCompleteOrWarning, isUrl, labelId, mergeInputNativeAria, normalizeAiTagLocale, observedNodesMap, onCancelDialog, onClickDialog, parseAndGetAriaAttributes, parseJSONAttribute, resolveAiTagTranslationLanguage, setAriaIDREF, showDialog, supportsConstructableStylesheets, supportsNativePopover, supportsOverlayTransition, tempDiv, tempIcon, tempLabel, traverseTreeAndUpdateState, updateDrilldownItemState };

package/ssr/esm/components-react/projects/react-ssr-wrapper/src/lib/dsr-components/drilldown.mjs

@@ -37,6 +37,7 @@ class DSRDrilldown extends Component {
         const style = minifyCss(getComponentCss$_(this.props.open, this.primary, this.isSecondaryDrawerVisible));
         return (jsxs(Fragment, { children: [jsxs("template", { shadowroot: "open", shadowrootmode: "open", children: [jsx("style", { dangerouslySetInnerHTML: { __html: style } }), jsx("dialog", { inert: !this.props.open, ...parseAndGetAriaAttributes(this.props.aria), children: jsxs("div", { className: "drawer", children: [jsx(PButtonPure, { className: "back", type: "button", size: "small", alignLabel: "end", stretch: true, icon: "arrow-left", hideLabel: true, children: "Back" }), jsx(PButton, { className: "dismiss-mobile", type: "button", icon: "close", compact: true, variant: "secondary", hideLabel: true, children: "Dismiss drilldown" }), jsx(PButton, { className: "dismiss-desktop", type: "button", icon: "close", variant: "secondary", hideLabel: true, children: "Dismiss drilldown" }), jsx("div", { className: "scroller", children: jsx("slot", {}) })] }) })] }), this.props.children] }));
     }
+    onDismissButtonClick = () => this.props.dismissDialog('dismiss-button');
 }
 
 export { DSRDrilldown };

package/ssr/esm/components-react/projects/react-ssr-wrapper/src/lib/dsr-components/flyout.mjs

@@ -3,7 +3,7 @@ import { splitChildren } from '../../splitChildren.mjs';
 import { Component } from 'react';
 import { minifyCss } from '../../minifyCss.mjs';
 import { getFlyoutCss as getComponentCss$V } from '../../../../../../components/dist/styles/esm/styles-entry.mjs';
-import { createTopLayerController, parseAndGetAriaAttributes, showDialog } from '../../../../../../components/dist/utils/esm/utils-entry.mjs';
+import { createTopLayerController, parseAndGetAriaAttributes, onCancelDialog, onClickDialog, showDialog } from '../../../../../../components/dist/utils/esm/utils-entry.mjs';
 import { DialogBase } from './dialog-base.mjs';
 
 /**
@@ -54,6 +54,9 @@ class DSRFlyout extends Component {
                                 ...parseAndGetAriaAttributes(this.props.aria),
                             }), children: jsx("slot", {}) })] }), this.props.children] }));
     }
+    onDialogCancel = (e) => onCancelDialog(e, () => this.props.dismissDialog('escape'));
+    onDialogBackdropClick = (e) => onClickDialog(e, () => this.props.dismissDialog('backdrop'), this.props.disableBackdropClick, this.props.isPointerDownInside);
+    onDismissButtonClick = () => this.props.dismissDialog('dismiss-button');
 }
 
 export { DSRFlyout };

package/ssr/esm/components-react/projects/react-ssr-wrapper/src/lib/dsr-components/modal.mjs

@@ -3,7 +3,7 @@ import { splitChildren } from '../../splitChildren.mjs';
 import { Component } from 'react';
 import { minifyCss } from '../../minifyCss.mjs';
 import { getModalCss as getComponentCss$C } from '../../../../../../components/dist/styles/esm/styles-entry.mjs';
-import { createTopLayerController, parseAndGetAriaAttributes, showDialog } from '../../../../../../components/dist/utils/esm/utils-entry.mjs';
+import { createTopLayerController, parseAndGetAriaAttributes, onCancelDialog, onClickDialog, showDialog } from '../../../../../../components/dist/utils/esm/utils-entry.mjs';
 import { DialogBase } from './dialog-base.mjs';
 
 /**
@@ -52,6 +52,9 @@ class DSRModal extends Component {
                                 ...parseAndGetAriaAttributes(this.props.aria),
                             }), children: jsx("slot", {}) })] }), this.props.children] }));
     }
+    onDialogCancel = (e) => onCancelDialog(e, () => this.props.dismissDialog('escape'), !this.props.dismissButton);
+    onDialogBackdropClick = (e) => onClickDialog(e, () => this.props.dismissDialog('backdrop'), this.props.disableBackdropClick, this.props.isPointerDownInside);
+    onDismissButtonClick = () => this.props.dismissDialog('dismiss-button');
 }
 
 export { DSRModal };

package/ssr/esm/components-react/projects/react-ssr-wrapper/src/lib/dsr-components/sheet.mjs

@@ -3,7 +3,7 @@ import { splitChildren } from '../../splitChildren.mjs';
 import { Component } from 'react';
 import { minifyCss } from '../../minifyCss.mjs';
 import { getSheetCss as getComponentCss$n } from '../../../../../../components/dist/styles/esm/styles-entry.mjs';
-import { createTopLayerController, parseAndGetAriaAttributes, showDialog } from '../../../../../../components/dist/utils/esm/utils-entry.mjs';
+import { createTopLayerController, parseAndGetAriaAttributes, onCancelDialog, onClickDialog, showDialog } from '../../../../../../components/dist/utils/esm/utils-entry.mjs';
 import { DialogBase } from './dialog-base.mjs';
 
 /**
@@ -49,6 +49,9 @@ class DSRSheet extends Component {
                                 ...parseAndGetAriaAttributes(this.props.aria),
                             }), children: jsx("slot", {}) })] }), this.props.children] }));
     }
+    onDialogCancel = (e) => onCancelDialog(e, () => this.props.dismissDialog('escape'), !this.props.dismissButton);
+    onDialogBackdropClick = (e) => onClickDialog(e, () => this.props.dismissDialog('backdrop'), this.props.disableBackdropClick, this.props.isPointerDownInside);
+    onDismissButtonClick = () => this.props.dismissDialog('dismiss-button');
 }
 
 export { DSRSheet };

package/ssr/esm/lib/components/drilldown.wrapper.d.ts

@@ -1,5 +1,5 @@
 import type { BaseProps } from '../../BaseProps';
-import type { SelectedAriaAttributes, DrilldownAriaAttribute, DrilldownUpdateEventDetail } from '../types';
+import type { SelectedAriaAttributes, DrilldownAriaAttribute, DrilldownDismissEventDetail, DrilldownUpdateEventDetail } from '../types';
 export type PDrilldownProps = BaseProps & {
     /**
      * Sets which `p-drilldown-item` (by `identifier`) is currently expanded to show its sub-navigation level.
@@ -10,9 +10,9 @@ export type PDrilldownProps = BaseProps & {
      */
     aria?: SelectedAriaAttributes<DrilldownAriaAttribute>;
     /**
-     * Emitted when the user closes the drilldown via the close button or Escape key.
+     * Emitted when the user closes the drilldown via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<DrilldownDismissEventDetail>) => void;
     /**
      * Emitted when the active navigation level changes, with the new `activeIdentifier` in the event detail.
      */
@@ -33,9 +33,9 @@ export declare const PDrilldown: import("react").ForwardRefExoticComponent<Omit<
      */
     aria?: SelectedAriaAttributes<DrilldownAriaAttribute>;
     /**
-     * Emitted when the user closes the drilldown via the close button or Escape key.
+     * Emitted when the user closes the drilldown via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<DrilldownDismissEventDetail>) => void;
     /**
      * Emitted when the active navigation level changes, with the new `activeIdentifier` in the event detail.
      */

package/ssr/esm/lib/components/flyout.wrapper.d.ts

@@ -1,5 +1,5 @@
 import type { BaseProps } from '../../BaseProps';
-import type { SelectedAriaAttributes, FlyoutAriaAttribute, FlyoutBackdrop, FlyoutBackground, FlyoutFooterBehavior, BreakpointCustomizable, FlyoutMotionHiddenEndEventDetail, FlyoutMotionVisibleEndEventDetail, FlyoutPosition } from '../types';
+import type { SelectedAriaAttributes, FlyoutAriaAttribute, FlyoutBackdrop, FlyoutBackground, FlyoutFooterBehavior, BreakpointCustomizable, FlyoutDismissEventDetail, FlyoutMotionHiddenEndEventDetail, FlyoutMotionVisibleEndEventDetail, FlyoutPosition } from '../types';
 export type PFlyoutProps = BaseProps & {
     /**
      * Sets ARIA attributes on the flyout dialog element for improved screen reader accessibility.
@@ -31,9 +31,9 @@ export type PFlyoutProps = BaseProps & {
      */
     fullscreen?: BreakpointCustomizable<boolean>;
     /**
-     * Emitted when the user closes the flyout via the close button, backdrop click, or Escape key.
+     * Emitted when the user closes the flyout via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<FlyoutDismissEventDetail>) => void;
     /**
      * Emitted after the flyout's close transition completes and the panel is fully hidden.
      */
@@ -84,9 +84,9 @@ export declare const PFlyout: import("react").ForwardRefExoticComponent<Omit<imp
      */
     fullscreen?: BreakpointCustomizable<boolean>;
     /**
-     * Emitted when the user closes the flyout via the close button, backdrop click, or Escape key.
+     * Emitted when the user closes the flyout via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<FlyoutDismissEventDetail>) => void;
     /**
      * Emitted after the flyout's close transition completes and the panel is fully hidden.
      */

package/ssr/esm/lib/components/modal.wrapper.d.ts

@@ -1,5 +1,5 @@
 import type { BaseProps } from '../../BaseProps';
-import type { SelectedAriaAttributes, ModalAriaAttribute, ModalBackdrop, ModalBackground, BreakpointCustomizable, ModalMotionHiddenEndEventDetail, ModalMotionVisibleEndEventDetail } from '../types';
+import type { SelectedAriaAttributes, ModalAriaAttribute, ModalBackdrop, ModalBackground, BreakpointCustomizable, ModalDismissEventDetail, ModalMotionHiddenEndEventDetail, ModalMotionVisibleEndEventDetail } from '../types';
 export type PModalProps = BaseProps & {
     /**
      * Sets ARIA attributes on the dialog element for improved accessibility when no visible heading is present.
@@ -31,9 +31,9 @@ export type PModalProps = BaseProps & {
      */
     fullscreen?: BreakpointCustomizable<boolean>;
     /**
-     * Emitted when the user closes the modal via the dismiss button, backdrop click, or Escape key.
+     * Emitted when the user closes the modal via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<ModalDismissEventDetail>) => void;
     /**
      * Emitted after the modal's close transition completes and the dialog is fully hidden.
      */
@@ -79,9 +79,9 @@ export declare const PModal: import("react").ForwardRefExoticComponent<Omit<impo
      */
     fullscreen?: BreakpointCustomizable<boolean>;
     /**
-     * Emitted when the user closes the modal via the dismiss button, backdrop click, or Escape key.
+     * Emitted when the user closes the modal via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<ModalDismissEventDetail>) => void;
     /**
      * Emitted after the modal's close transition completes and the dialog is fully hidden.
      */

package/ssr/esm/lib/components/popover.wrapper.d.ts

@@ -1,5 +1,5 @@
 import type { BaseProps } from '../../BaseProps';
-import type { SelectedAriaAttributes, PopoverAriaAttribute, PopoverDirection } from '../types';
+import type { SelectedAriaAttributes, PopoverAriaAttribute, PopoverDirection, PopoverDismissEventDetail } from '../types';
 export type PPopoverProps = BaseProps & {
     /**
      * Sets ARIA attributes on the popover panel to improve accessibility for screen readers.
@@ -19,9 +19,9 @@ export type PPopoverProps = BaseProps & {
      */
     direction?: PopoverDirection;
     /**
-     * Emitted in controlled mode when the user requests to close the popover via the Escape key, an outside click, or when keyboard focus leaves the popover (Tab / Shift+Tab).
+     * Emitted in controlled mode when the user requests to close the popover via the Escape key, an outside click, or when keyboard focus leaves the popover (Tab / Shift+Tab). The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<PopoverDismissEventDetail>) => void;
     /**
      * Controls whether the popover is visible. When set (controlled mode), visibility follows this prop and the consumer owns the open state via a slotted `button`. When omitted (uncontrolled mode), the component manages visibility itself.
      */
@@ -46,9 +46,9 @@ export declare const PPopover: import("react").ForwardRefExoticComponent<Omit<im
      */
     direction?: PopoverDirection;
     /**
-     * Emitted in controlled mode when the user requests to close the popover via the Escape key, an outside click, or when keyboard focus leaves the popover (Tab / Shift+Tab).
+     * Emitted in controlled mode when the user requests to close the popover via the Escape key, an outside click, or when keyboard focus leaves the popover (Tab / Shift+Tab). The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<PopoverDismissEventDetail>) => void;
     /**
      * Controls whether the popover is visible. When set (controlled mode), visibility follows this prop and the consumer owns the open state via a slotted `button`. When omitted (uncontrolled mode), the component manages visibility itself.
      */

package/ssr/esm/lib/components/sheet.wrapper.d.ts

@@ -1,5 +1,5 @@
 import type { BaseProps } from '../../BaseProps';
-import type { SelectedAriaAttributes, SheetAriaAttribute, SheetBackground, SheetMotionHiddenEndEventDetail, SheetMotionVisibleEndEventDetail } from '../types';
+import type { SelectedAriaAttributes, SheetAriaAttribute, SheetBackground, SheetDismissEventDetail, SheetMotionHiddenEndEventDetail, SheetMotionVisibleEndEventDetail } from '../types';
 export type PSheetProps = BaseProps & {
     /**
      * Sets ARIA attributes on the sheet dialog element for improved accessibility when the default `aria-label` is insufficient.
@@ -21,9 +21,9 @@ export type PSheetProps = BaseProps & {
      */
     dismissButton?: boolean;
     /**
-     * Emitted when the user dismisses the sheet via the close button, backdrop click, or Escape key.
+     * Emitted when the user closes the sheet via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<SheetDismissEventDetail>) => void;
     /**
      * Emitted after the sheet's close transition has fully completed and the panel is hidden.
      */
@@ -59,9 +59,9 @@ export declare const PSheet: import("react").ForwardRefExoticComponent<Omit<impo
      */
     dismissButton?: boolean;
     /**
-     * Emitted when the user dismisses the sheet via the close button, backdrop click, or Escape key.
+     * Emitted when the user closes the sheet via the dismiss button, backdrop click, or Escape key. The event detail identifies which of the three was used.
      */
-    onDismiss?: (event: CustomEvent<void>) => void;
+    onDismiss?: (event: CustomEvent<SheetDismissEventDetail>) => void;
     /**
      * Emitted after the sheet's close transition has fully completed and the panel is hidden.
      */

package/ssr/esm/lib/dsr-components/drilldown.d.ts

@@ -19,4 +19,5 @@ export declare class DSRDrilldown extends Component<any> {
     private isPointerDownInside;
     componentWillLoad(): Promise<void>;
     render(): JSX.Element;
+    private onDismissButtonClick;
 }

package/ssr/esm/lib/dsr-components/flyout.d.ts

@@ -20,4 +20,7 @@ export declare class DSRFlyout extends Component<any> {
     private isPointerDownInside;
     private topLayer;
     render(): JSX.Element;
+    private onDialogCancel;
+    private onDialogBackdropClick;
+    private onDismissButtonClick;
 }

package/ssr/esm/lib/dsr-components/modal.d.ts

@@ -17,4 +17,7 @@ export declare class DSRModal extends Component<any> {
     private isPointerDownInside;
     private topLayer;
     render(): JSX.Element;
+    private onDialogCancel;
+    private onDialogBackdropClick;
+    private onDismissButtonClick;
 }

package/ssr/esm/lib/dsr-components/sheet.d.ts

@@ -14,4 +14,7 @@ export declare class DSRSheet extends Component<any> {
     private isPointerDownInside;
     private topLayer;
     render(): JSX.Element;
+    private onDialogCancel;
+    private onDialogBackdropClick;
+    private onDismissButtonClick;
 }

package/ssr/esm/lib/types.d.ts

@@ -697,6 +697,10 @@ export type BreakpointValues<T> = {
     base: T;
 };
 export type BreakpointCustomizable<T> = T | BreakpointValues<T>;
+export type DialogDismissReason = "dismiss-button" | "backdrop" | "escape";
+export type DialogDismissEventDetail = {
+    reason: DialogDismissReason;
+};
 declare const LINK_TARGETS: readonly [
     "_self",
     "_blank",
@@ -1129,6 +1133,7 @@ export type DrilldownAriaAttribute = (typeof DRILLDOWN_ARIA_ATTRIBUTES)[number];
 export type DrilldownUpdateEventDetail = {
     activeIdentifier: string | undefined;
 };
+export type DrilldownDismissEventDetail = DialogDismissEventDetail;
 export type DrilldownLinkTarget = LinkTarget;
 export type DrilldownLinkAriaAttribute = LinkAriaAttribute;
 declare const FIELDSET_LABEL_SIZES: readonly [
@@ -1188,6 +1193,7 @@ declare const FLYOUT_ARIA_ATTRIBUTES: readonly [
 export type FlyoutAriaAttribute = (typeof FLYOUT_ARIA_ATTRIBUTES)[number];
 export type FlyoutMotionVisibleEndEventDetail = TransitionEvent;
 export type FlyoutMotionHiddenEndEventDetail = TransitionEvent;
+export type FlyoutDismissEventDetail = DialogDismissEventDetail;
 export type FlyoutBackdrop = Backdrop;
 declare const HEADING_TAGS: readonly [
     "h1",
@@ -1417,6 +1423,7 @@ export type ModalBackground = (typeof MODAL_BACKGROUNDS)[number];
 export type ModalBackdrop = Backdrop;
 export type ModalMotionVisibleEndEventDetail = TransitionEvent;
 export type ModalMotionHiddenEndEventDetail = TransitionEvent;
+export type ModalDismissEventDetail = DialogDismissEventDetail;
 declare const MODEL_SIGNATURES_MANIFEST: {
     "718": {
         src: string;
@@ -1539,6 +1546,9 @@ declare const POPOVER_ARIA_ATTRIBUTES: readonly [
     "aria-label"
 ];
 export type PopoverAriaAttribute = (typeof POPOVER_ARIA_ATTRIBUTES)[number];
+export type PopoverDismissEventDetail = {
+    reason: "outside-click" | "focus-out" | "escape";
+};
 declare const GROUP_DIRECTIONS: readonly [
     "row",
     "column"
@@ -1587,6 +1597,7 @@ declare const SHEET_BACKGROUNDS: readonly [
 export type SheetBackground = (typeof SHEET_BACKGROUNDS)[number];
 export type SheetMotionVisibleEndEventDetail = TransitionEvent;
 export type SheetMotionHiddenEndEventDetail = TransitionEvent;
+export type SheetDismissEventDetail = DialogDismissEventDetail;
 declare const SPINNER_COLORS: readonly [
     "primary",
     "inherit"