@momentum-design/components 0.118.5 → 0.119.0

package/dist/components/popover/index.js

@@ -1,5 +1,7 @@
 import Popover from './popover.component';
+import { PopoverPortal, TAG_NAME as POPOVER_PORTAL_TAG_NAME } from './popover.portal.component';
 import { TAG_NAME } from './popover.constants';
 import '../button';
 Popover.register(TAG_NAME);
+PopoverPortal.register(POPOVER_PORTAL_TAG_NAME);
 export default Popover;

package/dist/components/popover/popover.component.d.ts

@@ -3,20 +3,56 @@ import { Component } from '../../models';
 import type { PopoverColor, PopoverPlacement, PopoverStrategy, PopoverTrigger } from './popover.types';
 declare const Popover_base: import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/BackdropMixin").BackdropMixinInterface> & import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/PreventScrollMixin").PreventScrollMixinInterface> & import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/FocusTrapMixin").FocusTrapClassInterface> & typeof Component;
 /**
- * Popover component is a lightweight floating UI element that displays additional content when triggered.
- * It can be used for tooltips, dropdowns, or contextual menus.
+ * Popover is genric overlay which can be trigered by any actinable element.
+ *
+ * It can be used for tooltips, dropdowns, menus or any showing any other contextual content.
+ *
  * The popover automatically positions itself based on available space and
- * supports dynamic height adjustments with scrollable content when needed。
+ * supports dynamic height adjustments with scrollable content when needed.
+ * It uses [Floating UI](https://floating-ui.com/) for maintaining the position of the popover.
+ *
+ * ## Limitations
+ *
+ * ### On trigger for multiple popovers
+ *
+ * A component (button, etc.) can trigger more than one popover, but only one of them should change the
+ * aria-expanded and aria-haspopup attributes on the trigger.
+ *
+ * To prevent unexpected attribute changes on the trigger `disable-aria-expanded` attribute must be set on all linked
+ * Popoers except one.
  *
- * Note:
- *  - A component (button) can trigger more than one popover, but only one of them should change the
- *    aria-expanded and aria-haspopup, the rest of the popovers must have `disable-aria-expanded` attribute.
+ * ### React Popover with append-to attribute
+ *
+ * React mounts the popover based on the virtual DOM, but when the append-to attribute is set, the popover removes itself
+ * and mounts to the specified element. React will not know about the move and will not know about the
+ * newly created mdc-popoverportal element either. This throws a `NotFoundError` error when the Popover is directly
+ * added/removed by React, for example:
+ *
+ * ```tsx
+ * const SomeComponent = () => {
+ *    const [isOpen, setIsOpen] = useState(false);
+ *    return (<div>
+ *      {isOpen && <Popover append-to="some-element-id">...</mdc-popover>}
+ *    </div>);
+ * }
+ * ```
+ * As a workaround Popover need to wrap with any other element/component, for example:
+ * ```tsx
+ * const SomeComponent = () => {
+ *    const [isOpen, setIsOpen] = useState(false);
+ *    return (<div>
+ *      {isOpen && <div>
+ *        <Popover append-to="some-element-id">...</mdc-popover>
+ *      <div>}
+ *    </div>);
+ * }
+ * ```
+ * Note the wrapper <div> around the Popover component (React.Fragment does not work).
  *
  * @dependency mdc-button
  *
  * @tagname mdc-popover
  *
- *
  * @event shown - (React: onShown) This event is dispatched when the popover is shown
  * @event hidden - (React: onHidden) This event is dispatched when the popover is hidden
  * @event created - (React: onCreated) This event is dispatched when the popover is created (added to the DOM)
@@ -312,9 +348,9 @@ declare class Popover extends Popover_base {
      */
     get triggerElement(): HTMLElement | null;
     constructor();
+    private parseTrigger;
     protected firstUpdated(changedProperties: PropertyValues): Promise<void>;
     connectedCallback(): void;
-    private parseTrigger;
     disconnectedCallback(): Promise<void>;
     /**
      * Sets up the trigger related event listeners, based on the trigger type.

package/dist/components/popover/popover.component.js

@@ -22,20 +22,56 @@ import { popoverStack } from './popover.stack';
 import styles from './popover.styles';
 import { PopoverUtils } from './popover.utils';
 /**
- * Popover component is a lightweight floating UI element that displays additional content when triggered.
- * It can be used for tooltips, dropdowns, or contextual menus.
+ * Popover is genric overlay which can be trigered by any actinable element.
+ *
+ * It can be used for tooltips, dropdowns, menus or any showing any other contextual content.
+ *
  * The popover automatically positions itself based on available space and
- * supports dynamic height adjustments with scrollable content when needed。
+ * supports dynamic height adjustments with scrollable content when needed.
+ * It uses [Floating UI](https://floating-ui.com/) for maintaining the position of the popover.
+ *
+ * ## Limitations
+ *
+ * ### On trigger for multiple popovers
+ *
+ * A component (button, etc.) can trigger more than one popover, but only one of them should change the
+ * aria-expanded and aria-haspopup attributes on the trigger.
+ *
+ * To prevent unexpected attribute changes on the trigger `disable-aria-expanded` attribute must be set on all linked
+ * Popoers except one.
+ *
+ * ### React Popover with append-to attribute
+ *
+ * React mounts the popover based on the virtual DOM, but when the append-to attribute is set, the popover removes itself
+ * and mounts to the specified element. React will not know about the move and will not know about the
+ * newly created mdc-popoverportal element either. This throws a `NotFoundError` error when the Popover is directly
+ * added/removed by React, for example:
  *
- * Note:
- *  - A component (button) can trigger more than one popover, but only one of them should change the
- *    aria-expanded and aria-haspopup, the rest of the popovers must have `disable-aria-expanded` attribute.
+ * ```tsx
+ * const SomeComponent = () => {
+ *    const [isOpen, setIsOpen] = useState(false);
+ *    return (<div>
+ *      {isOpen && <Popover append-to="some-element-id">...</mdc-popover>}
+ *    </div>);
+ * }
+ * ```
+ * As a workaround Popover need to wrap with any other element/component, for example:
+ * ```tsx
+ * const SomeComponent = () => {
+ *    const [isOpen, setIsOpen] = useState(false);
+ *    return (<div>
+ *      {isOpen && <div>
+ *        <Popover append-to="some-element-id">...</mdc-popover>
+ *      <div>}
+ *    </div>);
+ * }
+ * ```
+ * Note the wrapper <div> around the Popover component (React.Fragment does not work).
  *
  * @dependency mdc-button
  *
  * @tagname mdc-popover
  *
- *
  * @event shown - (React: onShown) This event is dispatched when the popover is shown
  * @event hidden - (React: onHidden) This event is dispatched when the popover is hidden
  * @event created - (React: onCreated) This event is dispatched when the popover is created (added to the DOM)
@@ -632,12 +668,12 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
     }
     async firstUpdated(changedProperties) {
         super.firstUpdated(changedProperties);
-        this.style.zIndex = `${this.zIndex}`;
-        this.utils.setupAppendTo();
         PopoverEventManager.onCreatedPopover(this);
     }
     connectedCallback() {
         super.connectedCallback();
+        this.style.zIndex = `${this.zIndex}`;
+        this.utils.setupAppendTo();
         this.setupTriggerListeners();
     }
     async disconnectedCallback() {
@@ -656,6 +692,7 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
                 this.connectedTooltip.shouldSuppressOpening = false;
             }
         }
+        this.utils.cleanupAppendTo();
         PopoverEventManager.onDestroyedPopover(this);
         popoverStack.remove(this);
     }
@@ -683,8 +720,13 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
         if (changedProperties.has('zIndex')) {
             this.setAttribute('z-index', `${this.zIndex}`);
         }
-        if (changedProperties.has('append-to')) {
-            this.utils.setupAppendTo();
+        if (changedProperties.has('appendTo')) {
+            if (this.appendTo) {
+                this.utils.setupAppendTo();
+            }
+            else {
+                this.utils.cleanupAppendTo();
+            }
         }
         if (changedProperties.has('interactive') ||
             changedProperties.has('aria-label') ||

package/dist/components/popover/popover.portal.component.d.ts

@@ -0,0 +1,29 @@
+import { Component } from '../../models';
+export declare const TAG_NAME: "mdc-popoverportal";
+/**
+ * PopoverPortal in a placeholder component
+ *
+ * When the popover appended to another container, this component is used to mark the original place of the
+ * popover in the DOM. When the portal removed from the DOM, we remove the popover from the container as well.
+ *
+ * We need this behavior to support on hover menus. Without the portal:
+ * - Each time when then consumer renders the menu we append a new instance of the popover to the container which
+ *   cause memory leak.
+ * - Trigger component will open all popovers at once, because all of them has the same triggerID and all
+ *   listeners attached to the document.
+ *
+ * Portal component make sure the popover clean up when it was normally (without append-to) removed from the DOM.
+ * This is especially important when the popover is used in a framework like React or Angular, where virtual does not
+ * know about the popover moved to another place in the DOM.
+ *
+ * @internal
+ */
+export declare class PopoverPortal extends Component {
+    onDisconnect: Function | undefined;
+    connectedCallback(): void;
+    /**
+     * When the portal removed from the DOM, we remove the popover from the container as well.
+     * @internal
+     */
+    disconnectedCallback(): void;
+}

package/dist/components/popover/popover.portal.component.js

@@ -0,0 +1,37 @@
+import { Component } from '../../models';
+import utils from '../../utils/tag-name';
+export const TAG_NAME = utils.constructTagName('popoverportal');
+/**
+ * PopoverPortal in a placeholder component
+ *
+ * When the popover appended to another container, this component is used to mark the original place of the
+ * popover in the DOM. When the portal removed from the DOM, we remove the popover from the container as well.
+ *
+ * We need this behavior to support on hover menus. Without the portal:
+ * - Each time when then consumer renders the menu we append a new instance of the popover to the container which
+ *   cause memory leak.
+ * - Trigger component will open all popovers at once, because all of them has the same triggerID and all
+ *   listeners attached to the document.
+ *
+ * Portal component make sure the popover clean up when it was normally (without append-to) removed from the DOM.
+ * This is especially important when the popover is used in a framework like React or Angular, where virtual does not
+ * know about the popover moved to another place in the DOM.
+ *
+ * @internal
+ */
+export class PopoverPortal extends Component {
+    connectedCallback() {
+        super.connectedCallback();
+        // We don't want the portal to be focusable or visible for screen readers
+        this.ariaHidden = 'true';
+    }
+    /**
+     * When the portal removed from the DOM, we remove the popover from the container as well.
+     * @internal
+     */
+    disconnectedCallback() {
+        var _a;
+        super.disconnectedCallback();
+        (_a = this.onDisconnect) === null || _a === void 0 ? void 0 : _a.call(this);
+    }
+}

package/dist/components/popover/popover.utils.d.ts

@@ -2,6 +2,17 @@ import type Popover from './popover.component';
 export declare class PopoverUtils {
     /** @internal */
     private popover;
+    /**
+     * The portal element used when the popover is appended to another container.
+     * @internal
+     */
+    private portalElement;
+    /**
+     * Flag to indicate if the popover was diconnected because it was appended to another container, or
+     * it was actually removed from the DOM.
+     * @internal
+     */
+    private disconnectAfterAppendTo;
     /** @internal */
     private arrowPixelChange;
     constructor(popover: Popover);
@@ -24,6 +35,10 @@ export declare class PopoverUtils {
      * DOM element by its ID, and appends this popover as a child of that element.
      */
     setupAppendTo(): void;
+    /**
+     * Remove portal component to when the popover appended to somewhere else and removed from the DOM
+     */
+    cleanupAppendTo(): void;
     /**
      * Sets up the aria labels
      */

package/dist/components/popover/popover.utils.js

@@ -1,6 +1,18 @@
 import { ROLE } from '../../utils/roles';
+import { TAG_NAME as POPOVER_PORTAL_TAG_NAME } from './popover.portal.component';
 export class PopoverUtils {
     constructor(popover) {
+        /**
+         * The portal element used when the popover is appended to another container.
+         * @internal
+         */
+        this.portalElement = null;
+        /**
+         * Flag to indicate if the popover was diconnected because it was appended to another container, or
+         * it was actually removed from the DOM.
+         * @internal
+         */
+        this.disconnectAfterAppendTo = false;
         /** @internal */
         this.arrowPixelChange = false;
         this.popover = popover;
@@ -78,13 +90,30 @@ export class PopoverUtils {
      * DOM element by its ID, and appends this popover as a child of that element.
      */
     setupAppendTo() {
+        var _a, _b;
         if (this.popover.appendTo) {
-            const appendToElement = document.getElementById(this.popover.appendTo);
-            if (appendToElement) {
-                appendToElement.appendChild(this.popover);
+            const appendToEl = document.getElementById(this.popover.appendTo);
+            if (appendToEl && !Array.from(appendToEl.children).includes(this.popover)) {
+                this.disconnectAfterAppendTo = true;
+                this.portalElement = document.createElement(POPOVER_PORTAL_TAG_NAME);
+                this.portalElement.onDisconnect = () => {
+                    this.popover.remove();
+                    this.portalElement = null;
+                };
+                (_b = (_a = this.popover.parentElement) === null || _a === void 0 ? void 0 : _a.appendChild) === null || _b === void 0 ? void 0 : _b.call(_a, this.portalElement);
+                appendToEl.appendChild(this.popover);
             }
         }
     }
+    /**
+     * Remove portal component to when the popover appended to somewhere else and removed from the DOM
+     */
+    cleanupAppendTo() {
+        if (!this.disconnectAfterAppendTo && this.portalElement) {
+            this.portalElement.remove();
+        }
+        this.disconnectAfterAppendTo = false;
+    }
     /**
      * Sets up the aria labels
      */