@porsche-design-system/components-react 4.3.0 → 4.4.0-rc.0

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

@@ -1,24 +1,25 @@
 "use client";
 import { jsx } from 'react/jsx-runtime';
 import { forwardRef, useRef } from 'react';
-import { usePrefix, useBrowserLayoutEffect, useMergedClass } from '../../hooks.mjs';
+import { useEventCallback, usePrefix, useBrowserLayoutEffect, useMergedClass } from '../../hooks.mjs';
 import { syncRef } from '../../utils.mjs';
 import { DSRPopover } from '../dsr-components/popover.mjs';
 
-const PPopover = /*#__PURE__*/ forwardRef(({ aria, description, direction = 'bottom', className, children, ...rest }, ref) => {
+const PPopover = /*#__PURE__*/ forwardRef(({ aria, compact, description, direction = 'bottom', onDismiss, open, className, children, ...rest }, ref) => {
     const elementRef = useRef(undefined);
+    useEventCallback(elementRef, 'dismiss', onDismiss);
     const WebComponentTag = usePrefix('p-popover');
-    const propsToSync = [aria, description, direction];
+    const propsToSync = [aria, compact, description, direction, open];
     useBrowserLayoutEffect(() => {
         const { current } = elementRef;
-        ['aria', 'description', 'direction'].forEach((propName, i) => (current[propName] = propsToSync[i]));
+        ['aria', 'compact', 'description', 'direction', 'open'].forEach((propName, i) => (current[propName] = propsToSync[i]));
     }, propsToSync);
     const props = {
         ...rest,
         // @ts-ignore
         ...(!process.browser
             ? {
-                children: (jsx(DSRPopover, { aria, description, direction, children })),
+                children: (jsx(DSRPopover, { aria, compact, description, direction, open, children })),
             }
             : {
                 children,

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

@@ -1,35 +1,80 @@
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
-import { Component } from 'react';
-import '../../provider.mjs';
 import { splitChildren } from '../../splitChildren.mjs';
+import { Component } from 'react';
 import { minifyCss } from '../../minifyCss.mjs';
 import { getPopoverCss as getComponentCss$v } from '../../../../../../components/dist/styles/esm/styles-entry.mjs';
-import { getHasNativePopoverSupport, parseAndGetAriaAttributes } from '../../../../../../components/dist/utils/esm/utils-entry.mjs';
-import { PIcon } from '../components/icon.wrapper.mjs';
+import { createTopLayerController, parseAndGetAriaAttributes } from '../../../../../../components/dist/utils/esm/utils-entry.mjs';
 
 /**
- * @slot {"name": "", "description": "Default slot for the popover content." }
+ * @slot {"name": "", "description": "Default slot for the popover content. Ignored when the `description` prop is set, which takes precedence." }
  * @slot {"name": "button", "description": "Renders a custom trigger button. When used, the default info button is replaced." }
+ *
+ * @controlled {"props": ["open"], "event": "dismiss"}
  */
+// The panel is a native `[popover="manual"]` element that the component promotes to the `#top-layer` itself, so it
+// always renders above surrounding content regardless of ancestor stacking contexts. The component supports two modes:
+// - uncontrolled: `open` is omitted and the component owns visibility via the internal `isOpen` state (toggled by the
+//   default info button or a slotted trigger); dismissal closes it directly.
+// - controlled: `open` is a boolean and the consumer owns visibility via a slotted `button`; dismissal only emits
+//   `dismiss` and the consumer flips `open`. See `isControlled` / `effectiveOpen` for how the two are reconciled.
 class DSRPopover extends Component {
     host;
     isOpen = false;
-    popover;
-    button;
-    slottedButton;
-    arrow;
+    // The `[popover]` panel element on the #top-layer that holds the content and the arrow.
+    refPopover;
+    // The default info button rendered in the Shadow DOM (only present when no `button` slot is used).
+    refButton;
+    // The `<slot name="button">` element (only present when a custom trigger is projected); its assigned element is the
+    // actual trigger, see `triggerElement`.
+    refSlotButton;
+    // The visual arrow pointing from the panel to the trigger; positioned by Floating UI's `arrow` middleware.
+    refArrow;
+    // Teardown for the active Floating UI `autoUpdate` subscription; `undefined` while not positioning.
     cleanUpAutoUpdate;
-    hasNativePopoverSupport = getHasNativePopoverSupport();
-    // TODO: This should be updated when slot is changed
-    hasSlottedButton;
+    // The trigger element `autoUpdate` is currently anchored to, so it can be rebound when the trigger identity changes.
+    boundTriggerElement;
+    // Tracks whether the document-level dismiss listeners (outside click / Escape / pointer) are currently registered.
+    hasDismissListeners = false;
+    // Tracks whether a pointer button is currently pressed. Lets `onFocusout` defer pointer-driven focus loss (a click on
+    // an outside element, already handled by `onClickOutside`) to that handler, so a single outside pointer interaction
+    // emits `dismiss` once instead of twice. `onFocusout` then only dismisses on keyboard focus moves (Tab / Shift+Tab).
+    isPointerInteraction = false;
+    // Tracks whether the current pointer gesture *started* inside the trigger or panel. A `click` only fires on the
+    // nearest common ancestor of `mousedown`/`mouseup`, so pressing inside the panel (e.g. starting a text selection),
+    // dragging out and releasing outside retargets the resulting `click` to an ancestor *outside* the popover. Without
+    // this flag `onClickOutside` would then wrongly dismiss. Captured at `pointerdown` time (where `composedPath()` is
+    // still valid) and consumed on the following `click`, so dismissal only happens when the gesture started outside too.
+    isPointerDownInside = false;
+    // Keeps the panel on the #top-layer during its fade-out (Chromium via `overlay`; Safari/Firefox via a deferred hide).
+    topLayer = createTopLayerController({
+        getElement: () => this.props.refPopover,
+        isShown: () => !!this.props.refPopover?.matches(':popover-open'),
+        show: () => this.props.refPopover?.showPopover(),
+        hide: () => this.props.refPopover?.hidePopover(),
+    });
+    get isControlled() {
+        // Controlled mode is opted into purely by passing a boolean `open`; an omitted (`undefined`) prop means the
+        // component manages its own visibility.
+        return typeof this.props.open === 'boolean';
+    }
+    get effectiveOpen() {
+        // Single source of truth for "is the panel currently open", regardless of mode: the consumer-owned `open` prop in
+        // controlled mode, the internal `isOpen` state otherwise. All render/positioning/dismissal logic reads this.
+        return this.props.isControlled ? this.props.open : this.props.isOpen;
+    }
+    get triggerElement() {
+        // Resolves the element that actually acts as the trigger: the default info button in the Shadow DOM, or — when a
+        // custom trigger is projected through the `button` slot — the assigned light-DOM element itself (not the `<slot>`).
+        // Using the assigned element gives Floating UI an accurate anchor rect and lets `:host` use `display: contents`.
+        // Kept correct across dynamic slot changes by the `observeChildren` re-render in `connectedCallback`.
+        return this.props.refButton ?? ((this.props.refSlotButton)?.assignedElements()[0]);
+    }
     render() {
         const { namedSlotChildren} = splitChildren(this.props.children);
         const hasSlottedButton = namedSlotChildren.filter(({ props: { slot } }) => slot === 'button').length > 0;
-        const style = minifyCss(getComponentCss$v()).replace(/(:host {[\S\s]+?})[\S\s]+(button {[\S\s]+?})[\S\s]+(.icon {[\S\s]+?})[\S\s]+(.label {[\S\s]+?})[\S\s]+/, '$1\n$2\n$3\n$4');
-        return (jsxs(Fragment, { children: [jsxs("template", { shadowroot: "open", shadowrootmode: "open", children: [jsx("style", { dangerouslySetInnerHTML: { __html: style } }), jsxs(Fragment, { children: [hasSlottedButton ? (jsx("slot", { name: "button" })) : (jsxs("button", { type: "button", ...parseAndGetAriaAttributes({
-                                        ...parseAndGetAriaAttributes(this.props.aria),
-                                        ...{ 'aria-expanded': this.props.isOpen },
-                                    }), children: [jsx(PIcon, { className: "icon", name: "information" }), jsx("span", { className: "label", children: "More information" })] })), this.props.isOpen && (jsxs("div", { popover: "auto", children: [jsx("div", { className: "arrow" }), jsx("div", { className: "content", children: this.props.description ? jsx("p", { children: this.props.description }) : jsx("slot", {}) })] }))] })] }), this.props.children] }));
+        const id = 'popover';
+        const style = minifyCss(getComponentCss$v(this.props.effectiveOpen, this.props.compact).replace(/(:host {[\S\s]+?})[\S\s]+(button {[\S\s]+?})[\S\s]+(.icon {[\S\s]+?})[\S\s]+(.label {[\S\s]+?})[\S\s]+/, '$1\n$2\n$3\n$4'));
+        return (jsxs(Fragment, { children: [jsxs("template", { shadowroot: "open", shadowrootmode: "open", children: [jsx("style", { dangerouslySetInnerHTML: { __html: style } }), jsxs(Fragment, { children: [hasSlottedButton ? (jsx("slot", { name: "button" })) : (jsx("button", { type: "button", "aria-label": "More information", "aria-details": id, ...parseAndGetAriaAttributes(this.props.aria), "aria-expanded": this.props.effectiveOpen ? 'true' : 'false' })), jsxs("div", { id: id, popover: "manual", inert: !this.props.effectiveOpen, children: [jsx("div", { className: "arrow" }), this.props.description ? jsx("p", { children: this.props.description }) : jsx("slot", {})] })] })] }), this.props.children] }));
     }
 }
 

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

@@ -6,7 +6,11 @@ export type PPopoverProps = BaseProps & {
      */
     aria?: SelectedAriaAttributes<PopoverAriaAttribute>;
     /**
-     * Sets the text content displayed inside the popover panel when it is open, providing contextual help or information.
+     * Reduces padding and spacing for a more compact layout, useful in space-constrained interfaces.
+     */
+    compact?: boolean;
+    /**
+     * Sets the text content displayed inside the popover panel when it is open, providing contextual help or information. Takes precedence over the default slot when both are provided.
      */
     description?: string;
     /**
@@ -14,6 +18,14 @@ export type PPopoverProps = BaseProps & {
      * @default 'bottom'
      */
     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).
+     */
+    onDismiss?: (event: CustomEvent<void>) => 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.
+     */
+    open?: boolean;
 };
 export declare const PPopover: import("react").ForwardRefExoticComponent<Omit<import("react").DOMAttributes<{}>, "onChange" | "onInput" | "onToggle"> & Pick<import("react").HTMLAttributes<{}>, "suppressHydrationWarning" | "autoFocus" | "className" | "dir" | "hidden" | "id" | "inert" | "inputMode" | "lang" | "slot" | "style" | "tabIndex" | "title" | "translate" | "role"> & {
     /**
@@ -21,7 +33,11 @@ export declare const PPopover: import("react").ForwardRefExoticComponent<Omit<im
      */
     aria?: SelectedAriaAttributes<PopoverAriaAttribute>;
     /**
-     * Sets the text content displayed inside the popover panel when it is open, providing contextual help or information.
+     * Reduces padding and spacing for a more compact layout, useful in space-constrained interfaces.
+     */
+    compact?: boolean;
+    /**
+     * Sets the text content displayed inside the popover panel when it is open, providing contextual help or information. Takes precedence over the default slot when both are provided.
      */
     description?: string;
     /**
@@ -29,6 +45,14 @@ export declare const PPopover: import("react").ForwardRefExoticComponent<Omit<im
      * @default 'bottom'
      */
     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).
+     */
+    onDismiss?: (event: CustomEvent<void>) => 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.
+     */
+    open?: boolean;
 } & {
     children?: import("react").ReactNode | undefined;
 } & import("react").RefAttributes<HTMLElement>>;

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

@@ -1,18 +1,26 @@
 import { Component } from 'react';
 import type { JSX } from 'react';
 /**
- * @slot {"name": "", "description": "Default slot for the popover content." }
+ * @slot {"name": "", "description": "Default slot for the popover content. Ignored when the `description` prop is set, which takes precedence." }
  * @slot {"name": "button", "description": "Renders a custom trigger button. When used, the default info button is replaced." }
+ *
+ * @controlled {"props": ["open"], "event": "dismiss"}
  */
 export declare class DSRPopover extends Component<any> {
     host: HTMLElement;
     private isOpen;
-    private popover;
-    private button;
-    private slottedButton;
-    private arrow;
+    private refPopover;
+    private refButton;
+    private refSlotButton;
+    private refArrow;
     private cleanUpAutoUpdate;
-    private hasNativePopoverSupport;
-    private hasSlottedButton;
+    private boundTriggerElement;
+    private hasDismissListeners;
+    private isPointerInteraction;
+    private isPointerDownInside;
+    private topLayer;
+    private get isControlled();
+    private get effectiveOpen();
+    private get triggerElement();
     render(): JSX.Element;
 }