@momentum-design/components 0.129.44 → 0.129.46

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
@@ -24,3 +25,93 @@ export declare const isAfter: (nodeA: Element, nodeB: Element) => boolean;
  * @see [compareDocumentPosition](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition)
  */
 export declare const isBefore: (nodeA: Element, nodeB: Element) => boolean;
+/**
+ * Checks if the element has no client rectangles (not visible in the viewport).
+ *
+ * @param element - The element to check.
+ * @returns True if the element has no client rectangles.
+ */
+export declare const hasNoClientRects: (element: HTMLElement) => boolean;
+/**
+ * Checks if the element has zero dimensions (width and height are both 0).
+ *
+ * @param element - The element to check.
+ * @returns True if the element has zero dimensions.
+ */
+export declare const hasZeroDimensions: (element: HTMLElement) => boolean;
+/**
+ * Determines if the element is not visible in the DOM.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is not visible.
+ */
+export declare const isNotVisible: (element: HTMLElement) => boolean;
+/**
+ * Checks if the element has inline styles that make it hidden.
+ *
+ * @param element - The element to check.
+ * @returns True if the element has inline styles that make it hidden.
+ */
+export declare const hasHiddenStyle: (element: HTMLElement) => boolean;
+/**
+ * Checks if the element is hidden by a computed style.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is hidden by a computed style.
+ */
+export declare const hasComputedHidden: (element: HTMLElement) => boolean;
+/**
+ * Checks if the element is hidden from the user.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is hidden.
+ */
+export declare const isHidden: (element: HTMLElement) => boolean;
+/**
+ * Checks if the element is disabled.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is disabled.
+ */
+export declare const isDisabled: (element: any) => any;
+/**
+ * Checks if the element is not tabbable.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is not tabbable.
+ */
+export declare const isTabbable: (element: HTMLElement) => boolean;
+/**
+ * Checks if the element is interactive.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is interactive.
+ */
+export declare const isInteractiveElement: (element: HTMLElement) => boolean;
+/**
+ * Checks if the element is focusable.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is focusable.
+ */
+export declare const isFocusable: (element: HTMLElement) => boolean;
+/**
+ * Recursively finds all focusable elements within the given root and its descendants.
+ *
+ * Make sure this is performant, as it will be called multiple times.
+ *
+ * @param root - The root element to search for focusable elements.
+ * @returns The list of focusable elements.
+ */
+export declare const findFocusable: (root: ShadowRoot | HTMLElement | null) => HTMLElement[];
+/**
+ * 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

@@ -25,3 +25,174 @@ export const isAfter = (nodeA, nodeB) => !!(nodeA.compareDocumentPosition(nodeB)
  * @see [compareDocumentPosition](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition)
  */
 export const isBefore = (nodeA, nodeB) => !!(nodeA.compareDocumentPosition(nodeB) & Node.DOCUMENT_POSITION_FOLLOWING);
+/**
+ * Checks if the element has no client rectangles (not visible in the viewport).
+ *
+ * @param element - The element to check.
+ * @returns True if the element has no client rectangles.
+ */
+export const hasNoClientRects = (element) => element.getClientRects().length === 0;
+/**
+ * Checks if the element has zero dimensions (width and height are both 0).
+ *
+ * @param element - The element to check.
+ * @returns True if the element has zero dimensions.
+ */
+export const hasZeroDimensions = (element) => {
+    const { width, height } = element.getBoundingClientRect();
+    const { offsetWidth, offsetHeight } = element;
+    return offsetWidth + offsetHeight + height + width === 0;
+};
+/**
+ * Determines if the element is not visible in the DOM.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is not visible.
+ */
+export const isNotVisible = (element) => hasZeroDimensions(element) || hasNoClientRects(element);
+/**
+ * Checks if the element has inline styles that make it hidden.
+ *
+ * @param element - The element to check.
+ * @returns True if the element has inline styles that make it hidden.
+ */
+export const hasHiddenStyle = (element) => {
+    const { display, opacity, visibility } = element.style;
+    return display === 'none' || opacity === '0' || visibility === 'hidden' || visibility === 'collapse';
+};
+/**
+ * Checks if the element is hidden by a computed style.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is hidden by a computed style.
+ */
+export const hasComputedHidden = (element) => {
+    const computedStyle = getComputedStyle(element);
+    return computedStyle.visibility === 'hidden' || computedStyle.height === '0' || computedStyle.display === 'none';
+};
+/**
+ * Checks if the element is hidden from the user.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is hidden.
+ */
+export const isHidden = (element) => element.hasAttribute('hidden') ||
+    element.getAttribute('aria-hidden') === 'true' ||
+    hasHiddenStyle(element) ||
+    isNotVisible(element) ||
+    hasComputedHidden(element);
+/**
+ * Checks if the element is disabled.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is disabled.
+ */
+export const isDisabled = (element) => element.disabled;
+/**
+ * Checks if the element is not tabbable.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is not tabbable.
+ */
+export const isTabbable = (element) => element.getAttribute('tabindex') !== '-1';
+/**
+ * Checks if the element is interactive.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is interactive.
+ */
+export const isInteractiveElement = (element) => {
+    const interactiveTags = new Set(['BUTTON', 'DETAILS', 'EMBED', 'IFRAME', 'SELECT', 'TEXTAREA']);
+    if (interactiveTags.has(element.tagName)) {
+        return true;
+    }
+    if (element instanceof HTMLAnchorElement && element.hasAttribute('href')) {
+        return true;
+    }
+    if (element instanceof HTMLInputElement && element.type !== 'hidden') {
+        return true;
+    }
+    if ((element instanceof HTMLAudioElement || element instanceof HTMLVideoElement) &&
+        element.hasAttribute('controls')) {
+        return true;
+    }
+    if ((element instanceof HTMLImageElement || element instanceof HTMLObjectElement) && element.hasAttribute('usemap')) {
+        return true;
+    }
+    if (element.hasAttribute('tabindex') && element.tabIndex > -1) {
+        return true;
+    }
+    return false;
+};
+/**
+ * Checks if the element is focusable.
+ *
+ * @param element - The element to check.
+ * @returns True if the element is focusable.
+ */
+export const isFocusable = (element) => !isDisabled(element) && isTabbable(element) && !isHidden(element) && isInteractiveElement(element);
+/**
+ * Recursively finds all focusable elements within the given root and its descendants.
+ *
+ * Make sure this is performant, as it will be called multiple times.
+ *
+ * @param root - The root element to search for focusable elements.
+ * @returns The list of focusable elements.
+ */
+export const findFocusable = (root) => {
+    if (!root) {
+        return [];
+    }
+    const matches = new Set();
+    const finder = (root) => {
+        if (root instanceof HTMLElement && isFocusable(root)) {
+            matches.add(root);
+        }
+        let children = [];
+        if (root instanceof HTMLElement && root.shadowRoot) {
+            children = Array.from(root.shadowRoot.children);
+        }
+        else if (root.children.length) {
+            children = Array.from(root.children);
+        }
+        children.forEach((child) => {
+            const element = child;
+            if (isFocusable(element)) {
+                matches.add(element);
+            }
+            if (element.shadowRoot) {
+                finder(element.shadowRoot);
+            }
+            else if (element.tagName === 'SLOT') {
+                const assignedNodes = element.assignedElements({ flatten: true });
+                assignedNodes.forEach(node => {
+                    if (node instanceof HTMLElement) {
+                        finder(node);
+                    }
+                });
+            }
+            else {
+                finder(element);
+            }
+        });
+    };
+    finder(root);
+    return [...matches];
+};
+/**
+ * Get the active element from the DOM, including shadow DOMs
+ */
+export const getDomActiveElement = (root = document) => {
+    var _a;
+    let { activeElement } = root;
+    while ((_a = activeElement === null || activeElement === void 0 ? void 0 : activeElement.shadowRoot) === null || _a === void 0 ? void 0 : _a.activeElement)
+        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/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/dist/utils/mixins/{FocusTrapMixin.d.ts → focus/FocusTrapMixin.d.ts}

@@ -1,5 +1,5 @@
-import type { Component } from '../../models';
-import type { Constructor } from './index.types';
+import type { Component } from '../../../models';
+import type { Constructor } from '../index.types';
 export declare abstract class FocusTrapClassInterface {
     protected abstract focusTrap: boolean;
     setInitialFocus(elementIndexToReceiveFocus?: number): void;

package/dist/utils/mixins/focus/FocusTrapMixin.js

@@ -0,0 +1,190 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+/* eslint-disable no-use-before-define */
+/* eslint-disable max-classes-per-file */
+import { property } from 'lit/decorators.js';
+import { findFocusable } from '../../dom';
+import { FocusTrapStack } from './FocusTrapStack';
+export const FocusTrapMixin = (superClass) => {
+    class FocusTrap extends superClass {
+        constructor() {
+            super(...arguments);
+            /**
+             * Determines whether focus should wrap around when reaching the first or last focusable element.
+             * If true, focus will cycle from end to start and vice versa.
+             *
+             * This only applies when `focusTrap` is true.
+             * @default true
+             */
+            this.shouldFocusTrapWrap = true;
+            /** @internal */
+            this.focusTrapIndex = -1;
+            /** @internal */
+            this.focusableElements = [];
+            /** @internal */
+            this.isFocusTrapActivated = false;
+        }
+        setIsFocusTrapActivated(isActivated) {
+            this.isFocusTrapActivated = isActivated;
+        }
+        /**
+         * Activate the focus trap
+         */
+        activateFocusTrap() {
+            this.setIsFocusTrapActivated(true);
+            FocusTrapStack.activate(this);
+        }
+        /**
+         * Deactivate the focus trap.
+         */
+        deactivateFocusTrap() {
+            this.setIsFocusTrapActivated(false);
+            FocusTrapStack.deactivate(this);
+            this.focusTrapIndex = -1;
+        }
+        /**
+         * Updates the list of focusable elements within the component's shadow root.
+         */
+        setFocusableElements() {
+            if (!this.shadowRoot)
+                return;
+            this.focusableElements = findFocusable(this.shadowRoot);
+        }
+        /**
+         * Sets the initial focus within the container.
+         *
+         * @param elementIndexToReceiveFocus - The index of the preferable element to focus.
+         */
+        setInitialFocus(elementIndexToReceiveFocus = 0) {
+            this.setFocusableElements();
+            if (this.focusableElements.length === 0 || !this.focusTrap) {
+                return;
+            }
+            if (this.focusableElements[elementIndexToReceiveFocus]) {
+                this.focusTrapIndex = elementIndexToReceiveFocus;
+                this.focusableElements[elementIndexToReceiveFocus].focus({ preventScroll: true });
+            }
+        }
+        /**
+         * Calculates the next index for the focus trap.
+         *
+         * @param currentIndex - The current index.
+         * @param step - The step to calculate the next index.
+         * @returns The next index.
+         */
+        calculateNextIndex(currentIndex, step) {
+            const { length } = this.focusableElements;
+            if (currentIndex === -1) {
+                return step > 0 ? 0 : length - 1;
+            }
+            let nextIndex = currentIndex + step;
+            if (this.shouldFocusTrapWrap) {
+                if (nextIndex < 0)
+                    nextIndex = length - 1;
+                if (nextIndex >= length)
+                    nextIndex = 0;
+            }
+            else {
+                if (nextIndex < 0)
+                    nextIndex = 0;
+                if (nextIndex >= length)
+                    nextIndex = length - 1;
+            }
+            return nextIndex;
+        }
+        /**
+         * Returns the deepest active element in the shadow DOM.
+         *
+         * @returns The deepest active element.
+         */
+        getDeepActiveElement() {
+            var _a;
+            let host = document.activeElement || document.body;
+            while (host instanceof HTMLElement && ((_a = host.shadowRoot) === null || _a === void 0 ? void 0 : _a.activeElement)) {
+                host = host.shadowRoot.activeElement;
+            }
+            return host || document.body;
+        }
+        /**
+         * Finds the index of the active element within the focusable elements.
+         *
+         * @param activeElement - The active element.
+         * @returns The index of the active element.
+         */
+        findElement(activeElement) {
+            return this.focusableElements.findIndex(element => this.isEqualFocusNode(activeElement, element));
+        }
+        /**
+         * Checks if the active element is equal to the given element.
+         *
+         * @param activeElement - The active element.
+         * @param element - The element to compare.
+         * @returns True if the active element is equal to the given element.
+         */
+        isEqualFocusNode(activeElement, element) {
+            if (activeElement.nodeType >= 0) {
+                return element.isEqualNode(activeElement) && element === activeElement;
+            }
+            return false;
+        }
+        /**
+         * Traps focus within the container.
+         *
+         * @param direction - The direction of the focus trap.
+         * If true, the focus will be trapped in the previous element.
+         */
+        trapFocus(event) {
+            // calculate the focusable elements
+            this.setFocusableElements();
+            if (this.focusableElements.length === 0) {
+                return;
+            }
+            const activeElement = this.getDeepActiveElement();
+            const activeIndex = this.findElement(activeElement);
+            const direction = event.shiftKey;
+            if (direction) {
+                this.focusTrapIndex = this.calculateNextIndex(activeIndex, -1);
+            }
+            else {
+                this.focusTrapIndex = this.calculateNextIndex(activeIndex, 1);
+            }
+            const nextElement = this.focusableElements[this.focusTrapIndex];
+            if (nextElement.tagName === 'IFRAME') {
+                // If the next element is an iframe we should not focus it manually
+                // but just let the browser handle it.
+                // this only works if there are focusable elements around the iframe!
+                return;
+            }
+            if (nextElement) {
+                event.preventDefault();
+                nextElement.focus();
+            }
+        }
+        /**
+         * Traps focus within the container.
+         *
+         * @param event - The keyboard event.
+         */
+        // @ts-ignore - this is a method which will be called in the stack
+        handleTabKeydown(event) {
+            if (!this.isFocusTrapActivated) {
+                return;
+            }
+            if (event.key === 'Tab') {
+                this.trapFocus(event);
+            }
+        }
+    }
+    __decorate([
+        property({ type: Boolean, reflect: true, attribute: 'should-focus-trap-wrap' }),
+        __metadata("design:type", Boolean)
+    ], FocusTrap.prototype, "shouldFocusTrapWrap", void 0);
+    return FocusTrap;
+};

package/dist/utils/mixins/focus/FocusTrapStack.d.ts

@@ -0,0 +1,32 @@
+/**
+ * FocusTrapStack manages a stack of active focus traps,
+ * ensuring only one focus trap is active at a time.
+ *
+ * This also makes sure there is only one keydown listener active at a time,
+ * which is necessary to handle focus trapping correctly.
+ *
+ * Handling iFrames is supported, as long as there are focusable elements around the iFrame.
+ * Otherwise it will not work as expected.
+ */
+export declare class FocusTrapStack {
+    private static stack;
+    static get stackArray(): any[];
+    static getActiveTrap(): any;
+    private static currentKeydownListener;
+    private static addKeydownListener;
+    private static removeKeydownListener;
+    /**
+     * Activates a focus trap by adding it to the stack.
+     * It deactivates all other traps in the stack to ensure only one trap is active
+     *
+     * @param trap - The focus trap to activate.
+     */
+    static activate(trap: any): void;
+    /**
+     * Deactivates a focus trap by removing it from the stack.
+     * Activates the previous trap in the stack if any.
+     *
+     * @param trap - The focus trap to deactivate.
+     */
+    static deactivate(trap: any): void;
+}

package/dist/utils/mixins/focus/FocusTrapStack.js

@@ -0,0 +1,69 @@
+/**
+ * FocusTrapStack manages a stack of active focus traps,
+ * ensuring only one focus trap is active at a time.
+ *
+ * This also makes sure there is only one keydown listener active at a time,
+ * which is necessary to handle focus trapping correctly.
+ *
+ * Handling iFrames is supported, as long as there are focusable elements around the iFrame.
+ * Otherwise it will not work as expected.
+ */
+export class FocusTrapStack {
+    static get stackArray() {
+        return Array.from(this.stack);
+    }
+    static getActiveTrap() {
+        return this.stackArray.at(-1);
+    }
+    static addKeydownListener(keydownListener) {
+        this.currentKeydownListener = keydownListener;
+        document.addEventListener('keydown', keydownListener);
+    }
+    static removeKeydownListener() {
+        if (this.currentKeydownListener) {
+            document.removeEventListener('keydown', this.currentKeydownListener);
+        }
+    }
+    /**
+     * Activates a focus trap by adding it to the stack.
+     * It deactivates all other traps in the stack to ensure only one trap is active
+     *
+     * @param trap - The focus trap to activate.
+     */
+    static activate(trap) {
+        // Deactivate all other traps
+        this.stackArray.forEach(activeTrap => {
+            if (activeTrap !== trap) {
+                activeTrap.setIsFocusTrapActivated(false);
+            }
+        });
+        this.stack.add(trap);
+        // remove the current keydown listener if it exists
+        // and add a new one for the current trap
+        this.removeKeydownListener();
+        this.addKeydownListener(trap.handleTabKeydown.bind(trap));
+    }
+    /**
+     * Deactivates a focus trap by removing it from the stack.
+     * Activates the previous trap in the stack if any.
+     *
+     * @param trap - The focus trap to deactivate.
+     */
+    static deactivate(trap) {
+        if (!this.stack.has(trap)) {
+            return;
+        }
+        this.stack.delete(trap);
+        this.removeKeydownListener();
+        // activate the previous trap in the stack if any
+        if (this.stack.size > 0) {
+            const lastTrap = this.stackArray.pop();
+            if (lastTrap) {
+                lastTrap.setIsFocusTrapActivated(true);
+                this.addKeydownListener(lastTrap.handleTabKeydown.bind(lastTrap));
+            }
+        }
+    }
+}
+FocusTrapStack.stack = new Set();
+FocusTrapStack.currentKeydownListener = null;

package/package.json

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