@momentum-design/components 0.129.45 → 0.129.47

package/dist/utils/controllers/DepthManager.d.ts

@@ -0,0 +1,202 @@
+import { ReactiveController } from 'lit';
+import type { Component } from '../../models';
+/**
+ * Types of changes that can occur in the stack
+ *
+ * - 'added': An element was added to the stack, e.g.: pushed
+ * - 'removed': An element was removed from the stack, e.g.: popped or removed
+ * - 'moved': An element's position in the stack changed e.g.: another element above it was removed
+ */
+export type StackChange = 'added' | 'removed' | 'moved';
+/**
+ * A component that can be managed by the DepthManager stack.
+ *
+ * These elements can receive notifications when their position in the stack changes
+ * if they implement the `onComponentStackChanged` callback.
+ */
+export interface StackedOverlayComponent extends Component {
+    /**
+     * Callback invoked when the component's position in the stack changes.
+     *
+     * @param change - The type of change that occurred in the stack.
+     */
+    onComponentStackChanged?: (change: StackChange) => void;
+    /**
+     * ID of the trigger element associated with this overlay component
+     */
+    triggerID?: string;
+}
+/**
+ * Predicate function used to determine whether to pop an item from the stack.
+ * - Returns true to pop the item.
+ * - Returns false to stop popping items.
+ * - Returns 'skip' to skip the item without popping it.
+ */
+type PopPredicateFn = (item: StackedOverlayComponent, idx: number) => true | false | 'skip';
+export declare const OVERLAY_BACKDROP_Z_INDEX_OFFSET = -2;
+export declare const OVERLAY_TRIGGER_Z_INDEX_OFFSET = -1;
+/**
+ * DepthManager is a controller that manages a stack of elements to control their depth (z-index).
+ *
+ * It uses a global stack to keep track of the order of elements, allowing for proper layering of overlays.
+ *
+ * ## Use Case
+ *
+ * ### Pop single overlay
+ *
+ * The easiest one, usually the host removes itself from the stack when it is closed, with the `popHost` method.
+ *
+ * ### Pop until specific overlay
+ *
+ * When the chain of nested popover (e.g.: submenus) opened and the user closes other than the last one,
+ * we have to close all overlays stacked above the specific one. In this case, the `popItem` or directly the `pupUntil` method is used.
+ *
+ * ### Closing "sibling" overlays
+ *
+ * In some cases, multiple overlays can be opened from the same trigger (e.g.: tooltip, context menu, etc.), we can not close
+ * all overlays above the specific one, because they independently opened.
+ *
+ * `popUntil` method can handle this case by skipping the overlays which share the same trigger ID as the specified one.
+ *
+ * ### Manually removing overlays
+ *
+ * When the user switch from one sub-menu to another, we need to close all sub-menus from common parent menu.
+ * DepthManager does not have built-in solution for this case. The host component need to make sure the submenu
+ * hide before the new one is shown.
+ *
+ * @example
+ * ```ts
+ * // Add and remove item based on the disabled state
+ * class Container extends Component {
+ *    private this.depthManager = new DepthManager<>(this);
+ *
+ *    constructor() {
+ *      super();
+ *      this.addEventListener('modified', this.handleModifiedEvent);
+ *    }
+ *
+ *    openOverlay() {
+ *       this.depthManager.pushHost()
+ *    }
+ *
+ *    closeOverlay() {
+ *      this.depthManager.popHost()
+ *    }
+ *
+ *    onComponentStackChanged (change: StackChange) {
+ *       switch (change) {
+ *          case 'added':
+ *             return;
+ *          case 'removed':
+ *             return this.closeOverlay()
+ *          case 'moved':
+ *             return this.requestUpdate('zIndex');
+ *       }
+ *    }
+ * }
+ * ```
+ */
+export declare class DepthManager implements ReactiveController {
+    private readonly host;
+    /**
+     * Creates an instance of DepthManager.
+     */
+    constructor(host: StackedOverlayComponent);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * Gets the total number of elements in the stack
+     */
+    get length(): number;
+    /**
+     * Adds host element to the stack
+     *
+     * @returns push was successful (true) or not (false)
+     */
+    pushHost(): boolean;
+    /**
+     * Pops all the items above the host and then pops the host itself
+     *
+     * @returns The host if it was in the stack, undefined otherwise
+     */
+    popHost(): StackedOverlayComponent | undefined;
+    /**
+     * Pops all the items above the specified item and then pops the item itself
+     *
+     * @param item - The item to pop
+     * @returns The item if it was in the stack, undefined otherwise
+     */
+    popItem(item: StackedOverlayComponent): StackedOverlayComponent | undefined;
+    /**
+     * Removes the last element from the stack
+     *
+     * @returns The last element in the stack
+     */
+    pop(): StackedOverlayComponent | undefined;
+    /**
+     * Removes elements from the stack until the predicate function returns false
+     *
+     * Note: it will remove the
+     *
+     * @param predicateFn - The predicate function to test each element
+     * @returns The removed elements
+     */
+    popUntil(predicateFn: PopPredicateFn): StackedOverlayComponent[];
+    /**
+     * Returns the last element in the stack
+     * without removing it
+     *
+     * @returns The last element in the stack
+     */
+    peek(): StackedOverlayComponent | undefined;
+    /**
+     * Removes one or more elements from the stack without popping others.
+     *
+     * It notifies the elements on the stack which were removed and those which changed position.
+     * Items removed in bach, notify moved items only once.
+     *
+     * @param elements - Popover instance
+     * @returns undefined when the element was not found, the removed element otherwise
+     */
+    remove(elements: StackedOverlayComponent[]): StackedOverlayComponent[];
+    /**
+     * Checks if the stack has a specific element
+     *
+     * @param element - Popover instance
+     * @returns True if the stack has the element, false otherwise
+     */
+    has(element: StackedOverlayComponent): boolean;
+    /**
+     * Gets the depth of the host element in the stack
+     */
+    getHostDepth(): number;
+    /**
+     * Gets the depth of the element in the stack
+     * @param element - The element to get the depth of
+     */
+    getElementDepth(element: StackedOverlayComponent): number;
+    /**
+     * Gets the z-index of the host element in the stack
+     */
+    getHostZIndex(): number;
+    /**
+     * Gets the z-index of the element in the stack
+     * @param element - The element to get the z-index of
+     *
+     * @returns The z-index of the element if found, otherwise returns -1
+     */
+    getItemZIndex(element: StackedOverlayComponent): number;
+    /**
+     * Checks if host is at the top of the stack
+     *
+     * @returns True if host is on top, false otherwise
+     */
+    isHostOnTop(): boolean;
+    /**
+     * Clears the stack
+     *
+     * Pops all elements from the stack one-by-one.
+     */
+    clear(): void;
+}
+export {};

package/dist/utils/controllers/DepthManager.js

@@ -0,0 +1,259 @@
+/**
+ * Global stack of elements managed by DepthManager
+ * @internal
+ */
+const elementStack = [];
+/**
+ * Initial z-index for the first element in the stack
+ */
+const BASE_Z_INDEX = 1000;
+/**
+ * Number of z-index levels per element in the stack
+ * @internal
+ * - level -2: level of backdrop (if any)
+ * - level -1: level of trigger component (if any)
+ * - level  0: z-index of the overlay element (e.g. popover, dialog, etc.)
+ */
+const NUMBER_OF_Z_INDEX_LEVELS_PER_ELEMENT = 3;
+export const OVERLAY_BACKDROP_Z_INDEX_OFFSET = -2;
+export const OVERLAY_TRIGGER_Z_INDEX_OFFSET = -1;
+/**
+ * DepthManager is a controller that manages a stack of elements to control their depth (z-index).
+ *
+ * It uses a global stack to keep track of the order of elements, allowing for proper layering of overlays.
+ *
+ * ## Use Case
+ *
+ * ### Pop single overlay
+ *
+ * The easiest one, usually the host removes itself from the stack when it is closed, with the `popHost` method.
+ *
+ * ### Pop until specific overlay
+ *
+ * When the chain of nested popover (e.g.: submenus) opened and the user closes other than the last one,
+ * we have to close all overlays stacked above the specific one. In this case, the `popItem` or directly the `pupUntil` method is used.
+ *
+ * ### Closing "sibling" overlays
+ *
+ * In some cases, multiple overlays can be opened from the same trigger (e.g.: tooltip, context menu, etc.), we can not close
+ * all overlays above the specific one, because they independently opened.
+ *
+ * `popUntil` method can handle this case by skipping the overlays which share the same trigger ID as the specified one.
+ *
+ * ### Manually removing overlays
+ *
+ * When the user switch from one sub-menu to another, we need to close all sub-menus from common parent menu.
+ * DepthManager does not have built-in solution for this case. The host component need to make sure the submenu
+ * hide before the new one is shown.
+ *
+ * @example
+ * ```ts
+ * // Add and remove item based on the disabled state
+ * class Container extends Component {
+ *    private this.depthManager = new DepthManager<>(this);
+ *
+ *    constructor() {
+ *      super();
+ *      this.addEventListener('modified', this.handleModifiedEvent);
+ *    }
+ *
+ *    openOverlay() {
+ *       this.depthManager.pushHost()
+ *    }
+ *
+ *    closeOverlay() {
+ *      this.depthManager.popHost()
+ *    }
+ *
+ *    onComponentStackChanged (change: StackChange) {
+ *       switch (change) {
+ *          case 'added':
+ *             return;
+ *          case 'removed':
+ *             return this.closeOverlay()
+ *          case 'moved':
+ *             return this.requestUpdate('zIndex');
+ *       }
+ *    }
+ * }
+ * ```
+ */
+export class DepthManager {
+    /**
+     * Creates an instance of DepthManager.
+     */
+    constructor(host) {
+        this.host = host;
+        host.addController(this);
+    }
+    hostConnected() { }
+    hostDisconnected() {
+        // Remove this instance from the global stack on disconnect
+        this.remove([this.host]);
+    }
+    /**
+     * Gets the total number of elements in the stack
+     */
+    get length() {
+        return elementStack.length;
+    }
+    /**
+     * Adds host element to the stack
+     *
+     * @returns push was successful (true) or not (false)
+     */
+    pushHost() {
+        var _a, _b;
+        if (!this.has(this.host)) {
+            elementStack.push(this.host);
+            (_b = (_a = this.host).onComponentStackChanged) === null || _b === void 0 ? void 0 : _b.call(_a, 'added');
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Pops all the items above the host and then pops the host itself
+     *
+     * @returns The host if it was in the stack, undefined otherwise
+     */
+    popHost() {
+        return this.popItem(this.host);
+    }
+    /**
+     * Pops all the items above the specified item and then pops the item itself
+     *
+     * @param item - The item to pop
+     * @returns The item if it was in the stack, undefined otherwise
+     */
+    popItem(item) {
+        if (this.has(item)) {
+            const untilItemIdx = elementStack.indexOf(item) - 1;
+            this.popUntil((it, idx) => {
+                // This can handle the case when multiple overlays share the same trigger (id), e.g.: tooltip, etc.
+                if (it !== item && it.triggerID === item.triggerID)
+                    return 'skip';
+                return idx !== untilItemIdx;
+            });
+        }
+        return undefined;
+    }
+    /**
+     * Removes the last element from the stack
+     *
+     * @returns The last element in the stack
+     */
+    pop() {
+        var _a;
+        const popped = elementStack.pop();
+        (_a = popped === null || popped === void 0 ? void 0 : popped.onComponentStackChanged) === null || _a === void 0 ? void 0 : _a.call(popped, 'removed');
+        return popped;
+    }
+    /**
+     * Removes elements from the stack until the predicate function returns false
+     *
+     * Note: it will remove the
+     *
+     * @param predicateFn - The predicate function to test each element
+     * @returns The removed elements
+     */
+    popUntil(predicateFn) {
+        const poppedElements = [];
+        for (let i = elementStack.length - 1; i >= 0; i -= 1) {
+            const item = elementStack[i];
+            const result = predicateFn(item, i);
+            if (result === false)
+                break;
+            if (result !== 'skip')
+                poppedElements.push(item);
+        }
+        return this.remove(poppedElements);
+    }
+    /**
+     * Returns the last element in the stack
+     * without removing it
+     *
+     * @returns The last element in the stack
+     */
+    peek() {
+        return elementStack.at(-1);
+    }
+    /**
+     * Removes one or more elements from the stack without popping others.
+     *
+     * It notifies the elements on the stack which were removed and those which changed position.
+     * Items removed in bach, notify moved items only once.
+     *
+     * @param elements - Popover instance
+     * @returns undefined when the element was not found, the removed element otherwise
+     */
+    remove(elements) {
+        var _a, _b;
+        const removedElements = elements.filter(el => elementStack.includes(el));
+        const updateStackFrom = removedElements.reduce((idx, el) => Math.min(idx, elementStack.indexOf(el)), Infinity);
+        // Remove elements from the stack
+        removedElements.forEach(el => {
+            var _a;
+            elementStack.splice(elementStack.indexOf(el), 1);
+            (_a = el === null || el === void 0 ? void 0 : el.onComponentStackChanged) === null || _a === void 0 ? void 0 : _a.call(el, 'removed');
+        });
+        // Notify elements about the move
+        for (let i = updateStackFrom; i < elementStack.length; i += 1) {
+            (_b = (_a = elementStack[i]).onComponentStackChanged) === null || _b === void 0 ? void 0 : _b.call(_a, 'moved');
+        }
+        return removedElements;
+    }
+    /**
+     * Checks if the stack has a specific element
+     *
+     * @param element - Popover instance
+     * @returns True if the stack has the element, false otherwise
+     */
+    has(element) {
+        return elementStack.includes(element);
+    }
+    /**
+     * Gets the depth of the host element in the stack
+     */
+    getHostDepth() {
+        return this.getElementDepth(this.host);
+    }
+    /**
+     * Gets the depth of the element in the stack
+     * @param element - The element to get the depth of
+     */
+    getElementDepth(element) {
+        return elementStack.indexOf(element);
+    }
+    /**
+     * Gets the z-index of the host element in the stack
+     */
+    getHostZIndex() {
+        return this.getItemZIndex(this.host);
+    }
+    /**
+     * Gets the z-index of the element in the stack
+     * @param element - The element to get the z-index of
+     *
+     * @returns The z-index of the element if found, otherwise returns -1
+     */
+    getItemZIndex(element) {
+        const depth = this.getElementDepth(element);
+        return depth >= 0 ? BASE_Z_INDEX + depth * NUMBER_OF_Z_INDEX_LEVELS_PER_ELEMENT : -1;
+    }
+    /**
+     * Checks if host is at the top of the stack
+     *
+     * @returns True if host is on top, false otherwise
+     */
+    isHostOnTop() {
+        return this.peek() === this.host;
+    }
+    /**
+     * Clears the stack
+     *
+     * Pops all elements from the stack one-by-one.
+     */
+    clear() {
+        this.popUntil(() => true);
+    }
+}

package/dist/utils/dom.d.ts

@@ -1,3 +1,4 @@
+import type { OverflowMixinInterface } from './mixins/OverflowMixin';
 /**
  * nodeB precedes nodeA in either a pre-order depth-first traversal of a tree containing both
  * (e.g., as a descendant or preceding sibling or a descendant of a preceding sibling or
@@ -107,3 +108,10 @@ export declare const findFocusable: (root: ShadowRoot | HTMLElement | null) => H
  * Get the active element from the DOM, including shadow DOMs
  */
 export declare const getDomActiveElement: (root?: Document) => Element | null;
+/**
+ * Type guard to check if an element inherits the OverflowMixin.
+ *
+ * @param element - The element to check
+ * @returns True if the element has the OverflowMixin methods
+ */
+export declare const hasOverflowMixin: <T extends HTMLElement>(element: T) => element is T & OverflowMixinInterface;

package/dist/utils/dom.js

@@ -189,3 +189,10 @@ export const getDomActiveElement = (root = document) => {
         activeElement = activeElement.shadowRoot.activeElement;
     return activeElement;
 };
+/**
+ * Type guard to check if an element inherits the OverflowMixin.
+ *
+ * @param element - The element to check
+ * @returns True if the element has the OverflowMixin methods
+ */
+export const hasOverflowMixin = (element) => 'isWidthOverflowing' in element && typeof element.isWidthOverflowing === 'function';

package/dist/utils/mixins/BackdropMixin.js

@@ -1,3 +1,4 @@
+import { OVERLAY_BACKDROP_Z_INDEX_OFFSET, OVERLAY_TRIGGER_Z_INDEX_OFFSET } from '../controllers/DepthManager';
 export const BackdropMixin = (superClass) => {
     class Backdrop extends superClass {
         constructor() {
@@ -11,6 +12,20 @@ export const BackdropMixin = (superClass) => {
             this.isBackdropInvisible = false;
             /** @internal */
             this.backdropElement = null;
+            /** @internal */
+            this.triggerElementCache = null;
+        }
+        update(changedProperties) {
+            var _a;
+            super.update(changedProperties);
+            if (changedProperties.has('zIndex') && this.backdropElement) {
+                // Update the backdrop z-index if the zIndex property changes
+                this.backdropElement.style.zIndex = `${this.zIndex + OVERLAY_BACKDROP_Z_INDEX_OFFSET}`;
+                const triggerEl = (_a = this.triggerElementCache) === null || _a === void 0 ? void 0 : _a.deref();
+                if (triggerEl) {
+                    triggerEl.style.zIndex = `${this.zIndex + OVERLAY_TRIGGER_Z_INDEX_OFFSET}`;
+                }
+            }
         }
         /**
          * Creates a backdrop element with the specified class name prefix.
@@ -30,7 +45,7 @@ export const BackdropMixin = (superClass) => {
           width: 100%;
           height: 100%;
           background: ${this.isBackdropInvisible ? `transparent` : `var(--mds-color-theme-common-overlays-secondary-normal)`};
-          z-index: ${this.zIndex - 2};
+          z-index: ${this.zIndex + OVERLAY_BACKDROP_Z_INDEX_OFFSET};
         }
       `;
             backdrop.appendChild(styleElement);
@@ -63,13 +78,14 @@ export const BackdropMixin = (superClass) => {
             if (!element) {
                 return;
             }
+            this.triggerElementCache = new WeakRef(element);
             // Store the original z-index and position of the element
             this.elementOriginalStyle = {
                 zIndex: element.style.zIndex,
                 position: element.style.position,
             };
             // Set the z-index and position to ensure the element is above the backdrop
-            element.style.zIndex = `${this.zIndex - 1}`;
+            element.style.zIndex = `${this.zIndex + OVERLAY_TRIGGER_Z_INDEX_OFFSET}`;
             // Only set the position to relative if it is not already set to fixed or absolute
             if (!['fixed', 'absolute'].includes(window.getComputedStyle(element).position)) {
                 element.style.position = 'relative';
@@ -93,6 +109,7 @@ export const BackdropMixin = (superClass) => {
             element.style.position = this.elementOriginalStyle.position;
             // Clear the stored original style
             this.elementOriginalStyle = undefined;
+            this.triggerElementCache = null;
         }
     }
     return Backdrop;

package/dist/utils/mixins/FocusTrapMixin.js

@@ -0,0 +1 @@
+"use strict";

package/dist/utils/mixins/OverflowMixin.d.ts

@@ -0,0 +1,7 @@
+import { LitElement } from 'lit';
+import type { Constructor } from './index.types';
+export declare abstract class OverflowMixinInterface {
+    protected get overflowElement(): HTMLElement;
+    isWidthOverflowing(): boolean;
+}
+export declare const OverflowMixin: <T extends Constructor<LitElement>>(superClass: T) => Constructor<OverflowMixinInterface> & T;

package/dist/utils/mixins/OverflowMixin.js

@@ -0,0 +1,23 @@
+export const OverflowMixin = (superClass) => {
+    class InnerMixinClass extends superClass {
+        /**
+         * Gets the element whose overflow will be monitored.
+         *
+         * @internal
+         */
+        get overflowElement() {
+            return this;
+        }
+        /**
+         * Determines if the content of the overflow element is overflowing its width.
+         *
+         * @returns True if the scroll width of the overflow element is greater than its client width.
+         */
+        isWidthOverflowing() {
+            const el = this.overflowElement;
+            return el.scrollWidth > el.clientWidth;
+        }
+    }
+    // Cast return type to your mixin's interface intersected with the superClass type
+    return InnerMixinClass;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@momentum-design/components",
   "packageManager": "yarn@3.2.4",
-  "version": "0.129.45",
+  "version": "0.129.47",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=8.0.0"

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

@@ -1,53 +0,0 @@
-import type Popover from './popover.component';
-/**
- * Manages a stack of popovers to control their order and lifecycle.
- * This class allows adding, removing, and retrieving popovers
- * while maintaining their stacking behavior.
- *
- */
-declare class PopoverStack {
-    /**
-     * Stack to maintain the order of popovers
-     * @internal
-     */
-    private stack;
-    /**
-     * Adds a popover to the stack
-     *
-     * @param popover - Popover instance
-     * @returns The new depth of the stack
-     */
-    push(popover: Popover): number;
-    /**
-     * Removes the last popover from the stack
-     *
-     * @returns The last popover in the stack
-     */
-    pop(): Popover | undefined;
-    /**
-     * Returns the last popover in the stack
-     * without removing it
-     *
-     * @returns The last popover in the stack
-     */
-    peek(): Popover | undefined;
-    /**
-     * Removes a popover from the stack
-     *
-     * @param popover - Popover instance
-     */
-    remove(popover: Popover): void;
-    /**
-     * Checks if the stack has a specific popover
-     *
-     * @param popover - Popover instance
-     * @returns True if the stack has the popover, false otherwise
-     */
-    has(popover: Popover): boolean;
-    /**
-     * Clears the stack
-     */
-    clear(): void;
-}
-export declare const popoverStack: PopoverStack;
-export {};