@momentum-design/components 0.129.43 → 0.129.45

package/dist/react/checkbox/index.d.ts

@@ -11,6 +11,7 @@ import type { Events } from '../../components/checkbox/checkbox.types';
  * **Note:** This component internally renders a native checkbox input element with custom styling.
  *
  * ## When to use
+ *
  * Use checkboxes when users can select multiple options from a list, or when a single checkbox represents a binary choice (e.g., agreeing to terms).
  *
  * ## Accessibility

package/dist/react/checkbox/index.js

@@ -12,6 +12,7 @@ import { TAG_NAME } from '../../components/checkbox/checkbox.constants';
  * **Note:** This component internally renders a native checkbox input element with custom styling.
  *
  * ## When to use
+ *
  * Use checkboxes when users can select multiple options from a list, or when a single checkbox represents a binary choice (e.g., agreeing to terms).
  *
  * ## Accessibility

package/dist/utils/dom.d.ts

@@ -24,3 +24,86 @@ 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;

package/dist/utils/dom.js

@@ -25,3 +25,167 @@ 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;
+};

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

@@ -0,0 +1,69 @@
+import { LitElement } from 'lit';
+import type { Constructor } from './index.types';
+export declare const ACTIONS: {
+    /** Action key, e.g., Enter */
+    readonly ENTER: "enter";
+    /** Back key, e.g., Escape/Back/Cancel */
+    readonly ESCAPE: "escape";
+    /** Navigation key up */
+    readonly UP: "up";
+    /** Navigation key down */
+    readonly DOWN: "down";
+    /** Navigation key left */
+    readonly LEFT: "left";
+    /** Navigation key right */
+    readonly RIGHT: "right";
+    /** Space key, some actions and scrolling */
+    readonly SPACE: "space";
+    /** Tab key */
+    readonly TAB: "tab";
+    /** Home key */
+    readonly HOME: "home";
+    /** End key */
+    readonly END: "end";
+};
+export type Actions = (typeof ACTIONS)[keyof typeof ACTIONS];
+export interface KeyToActionInterface {
+    /**
+     * Returns a (abstract) action for the given keyboard event based on the current spatial navigation context
+     *
+     * @param evt - The keyboard event
+     * @param applyWritingDirection - For right-to-left writing direction, left/right actions are swapped if set to true
+     * @returns The mapped key or `undefined` if no mapping exists
+     */
+    getActionForKeyEvent(evt: KeyboardEvent, applyWritingDirection?: boolean): Actions | undefined;
+}
+/**
+ * Mixin to provide abstract key mapping for navigation and actions keys.
+ *
+ * Instead of using hardcoded key names this mixin provides a way to map keys to abstract actions
+ * and use different key mappings based on context.
+ *
+ * All components should implement this mixin if it handles keyboard events for navigation or actions,
+ * e.g. buttons, lists, popups, etc.
+ *
+ * Navigation keys mapped directly:
+ * - 'up'
+ * - 'down'
+ * - 'left'
+ * - 'right'
+ * - 'tab'
+ * - 'home'
+ * - 'end'
+ *
+ * Action keys:
+ * - 'action' (Enter key)
+ * - 'abort' (Escape/Back key)
+ *
+ * Special keys:
+ * - 'space' (Space key)
+ *
+ * Space is separated from action keys as it is
+ *  - not always trigger the same action as the enter key
+ *  - not every platform has a space key equivalent for example on a TV remote or gamepad
+ *  - often used for scrolling as well.
+ *
+ *  From the above lists only 'up', 'down', 'left', 'right', 'action' and 'abort' are mandatory to implement,
+ *  because those are essential for spatial navigation and basic actions and all platforms have equivalents for those.
+ */
+export declare const KeyToActionMixin: <T extends Constructor<LitElement>>(superClass: T) => Constructor<KeyToActionInterface> & T;

package/dist/utils/mixins/KeyToActionMixin.js

@@ -0,0 +1,92 @@
+import { KEYS } from '../keys';
+export const ACTIONS = {
+    /** Action key, e.g., Enter */
+    ENTER: 'enter',
+    /** Back key, e.g., Escape/Back/Cancel */
+    ESCAPE: 'escape',
+    /** Navigation key up */
+    UP: 'up',
+    /** Navigation key down */
+    DOWN: 'down',
+    /** Navigation key left */
+    LEFT: 'left',
+    /** Navigation key right */
+    RIGHT: 'right',
+    /** Space key, some actions and scrolling */
+    SPACE: 'space',
+    /** Tab key */
+    TAB: 'tab',
+    /** Home key */
+    HOME: 'home',
+    /** End key */
+    END: 'end',
+};
+/**
+ * Default key to action mapping if no spatial navigation context is available
+ */
+const DEFAULT_KEY_TO_ACTION = {
+    [KEYS.ARROW_UP]: ACTIONS.UP,
+    [KEYS.ARROW_DOWN]: ACTIONS.DOWN,
+    [KEYS.ARROW_LEFT]: ACTIONS.LEFT,
+    [KEYS.ARROW_RIGHT]: ACTIONS.RIGHT,
+    [KEYS.ENTER]: ACTIONS.ENTER,
+    [KEYS.SPACE]: ACTIONS.SPACE,
+    [KEYS.ESCAPE]: ACTIONS.ESCAPE,
+    [KEYS.TAB]: ACTIONS.TAB,
+    [KEYS.HOME]: ACTIONS.HOME,
+    [KEYS.END]: ACTIONS.END,
+};
+/**
+ * Mixin to provide abstract key mapping for navigation and actions keys.
+ *
+ * Instead of using hardcoded key names this mixin provides a way to map keys to abstract actions
+ * and use different key mappings based on context.
+ *
+ * All components should implement this mixin if it handles keyboard events for navigation or actions,
+ * e.g. buttons, lists, popups, etc.
+ *
+ * Navigation keys mapped directly:
+ * - 'up'
+ * - 'down'
+ * - 'left'
+ * - 'right'
+ * - 'tab'
+ * - 'home'
+ * - 'end'
+ *
+ * Action keys:
+ * - 'action' (Enter key)
+ * - 'abort' (Escape/Back key)
+ *
+ * Special keys:
+ * - 'space' (Space key)
+ *
+ * Space is separated from action keys as it is
+ *  - not always trigger the same action as the enter key
+ *  - not every platform has a space key equivalent for example on a TV remote or gamepad
+ *  - often used for scrolling as well.
+ *
+ *  From the above lists only 'up', 'down', 'left', 'right', 'action' and 'abort' are mandatory to implement,
+ *  because those are essential for spatial navigation and basic actions and all platforms have equivalents for those.
+ */
+export const KeyToActionMixin = (superClass) => {
+    class InnerMixinClass extends superClass {
+        /** @see KeyToActionInterface.getMappedKeyFromEvent */
+        getActionForKeyEvent(evt, applyWritingDirection = false) {
+            const mapping = DEFAULT_KEY_TO_ACTION;
+            const key = mapping[evt.key];
+            if (applyWritingDirection) {
+                const isRtl = window.getComputedStyle(this).direction === 'rtl';
+                if (!isRtl)
+                    return key;
+                if (key === ACTIONS.LEFT)
+                    return ACTIONS.RIGHT;
+                if (key === ACTIONS.RIGHT)
+                    return ACTIONS.LEFT;
+            }
+            return key;
+        }
+    }
+    // Cast return type to your mixin's interface intersected with the superClass type
+    return InnerMixinClass;
+};

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

@@ -1,6 +1,7 @@
 import type { Component } from '../../models';
 import type { BaseArray } from '../virtualIndexArray';
 import type { Constructor } from './index.types';
+import { KeyToActionInterface } from './KeyToActionMixin';
 export declare abstract class ListNavigationMixinInterface {
     protected loop: 'true' | 'false';
     protected propagateAllKeyEvents: boolean;
@@ -29,4 +30,4 @@ export declare abstract class ListNavigationMixinInterface {
  * ```
  * @param superClass - The class to extend with the mixin.
  */
-export declare const ListNavigationMixin: <T extends Constructor<Component>>(superClass: T) => Constructor<Component & ListNavigationMixinInterface> & T;
+export declare const ListNavigationMixin: <T extends Constructor<Component>>(superClass: T) => Constructor<Component & ListNavigationMixinInterface & KeyToActionInterface> & T;

package/dist/utils/mixins/ListNavigationMixin.js

@@ -1,4 +1,4 @@
-import { KEYS } from '../keys';
+import { ACTIONS, KeyToActionMixin } from './KeyToActionMixin';
 /**
  * This mixin extends the passed class with list like navigation capabilities.
  *
@@ -18,7 +18,7 @@ import { KEYS } from '../keys';
  * @param superClass - The class to extend with the mixin.
  */
 export const ListNavigationMixin = (superClass) => {
-    class InnerMixinClass extends superClass {
+    class InnerMixinClass extends KeyToActionMixin(superClass) {
         constructor(...rest) {
             super(...rest);
             /**
@@ -92,10 +92,9 @@ export const ListNavigationMixin = (superClass) => {
          * @internal
          */
         handleNavigationKeyDown(event) {
-            const keysToHandle = new Set([KEYS.ARROW_DOWN, KEYS.ARROW_UP, KEYS.HOME, KEYS.END]);
-            const isRtl = window.getComputedStyle(this).direction === 'rtl';
-            const targetKey = this.resolveDirectionKey(event.key, isRtl);
-            if (!keysToHandle.has(targetKey)) {
+            const action = this.getActionForKeyEvent(event, true);
+            const actionsToHandle = new Set([ACTIONS.DOWN, ACTIONS.UP, ACTIONS.HOME, ACTIONS.END]);
+            if (!action || !actionsToHandle.has(action)) {
                 return;
             }
             const target = event.target;
@@ -103,25 +102,25 @@ export const ListNavigationMixin = (superClass) => {
             if (currentIndex === -1)
                 return;
             this.resetTabIndexes(currentIndex);
-            switch (targetKey) {
-                case KEYS.HOME: {
+            switch (action) {
+                case ACTIONS.HOME: {
                     // Move focus to the first item
                     this.resetTabIndexAndSetFocus(0, currentIndex);
                     break;
                 }
-                case KEYS.END: {
+                case ACTIONS.END: {
                     // Move focus to the last item
                     this.resetTabIndexAndSetFocus(this.navItems.length - 1, currentIndex);
                     break;
                 }
-                case KEYS.ARROW_DOWN: {
+                case ACTIONS.DOWN: {
                     // Move focus to the next item
                     const eolIndex = this.shouldLoop() ? 0 : currentIndex;
                     const newIndex = currentIndex + 1 === this.navItems.length ? eolIndex : currentIndex + 1;
                     this.resetTabIndexAndSetFocus(newIndex, currentIndex);
                     break;
                 }
-                case KEYS.ARROW_UP: {
+                case ACTIONS.UP: {
                     // Move focus to the prev item
                     const eolIndex = this.shouldLoop() ? this.navItems.length - 1 : currentIndex;
                     const newIndex = currentIndex - 1 === -1 ? eolIndex : currentIndex - 1;
@@ -204,28 +203,6 @@ export const ListNavigationMixin = (superClass) => {
                 }
             }
         }
-        /**
-         * Resolves the key pressed by the user based on the direction of the layout.
-         * This method is used to handle keyboard navigation in a right-to-left (RTL) layout.
-         * It checks if the layout is RTL and adjusts the arrow keys accordingly.
-         * For example, in RTL, the left arrow key behaves like the right arrow key and vice versa.
-         *
-         * @param key - The key pressed by the user.
-         * @param isRtl - A boolean indicating if the layout is right-to-left (RTL).
-         * @returns - The resolved key based on the direction.
-         */
-        resolveDirectionKey(key, isRtl) {
-            if (!isRtl)
-                return key;
-            switch (key) {
-                case KEYS.ARROW_LEFT:
-                    return KEYS.ARROW_RIGHT;
-                case KEYS.ARROW_RIGHT:
-                    return KEYS.ARROW_LEFT;
-                default:
-                    return key;
-            }
-        }
         shouldLoop() {
             return this.loop !== 'false';
         }

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;