@momentum-design/components 0.129.43 → 0.129.45

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.43",
+  "version": "0.129.45",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=8.0.0"