@momentum-design/components 0.129.42 → 0.129.44

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/react/coachmark/index.d.ts

@@ -2,8 +2,22 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/coachmark';
 import type { Events as EventsInherited } from '../../components/popover/popover.types';
 /**
+ * A Coachmark is a contextual guidance component used to highlight a specific UI element and explain its purpose or functionality.
+ * It is typically shown as part of onboarding, feature discovery, or progressive education within the product.
+ *
  * Coachmark component based on top of the popover component,
  * with the default value of certain properties changed.
+ * Coachmark component will always have an arrow attached to it.
+ * The color of the coachmark is contrast.
+ *
+ * ## When to use
+ * - Introducing a new or complex feature to users.
+ * - Drawing attention to a UI element that might otherwise be missed.
+ * - Providing step-by-step guidance in an onboarding or walkthrough flow.
+ *
+ * ## Accessibility
+ * - The default role of coachmark is `"dialog"`, which can be changed via the `role` attribute.
+ * - aria-label or aria-labelledby can be provided to give the coachmark an accessible name.
  *
  * @dependency mdc-popover
  *
@@ -25,7 +39,6 @@ import type { Events as EventsInherited } from '../../components/popover/popover
  * @cssproperty --mdc-popover-elevation-3 - elevation of the popover
  *
  * @slot - Default slot for modal container
- *
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {
     onShown: EventName<EventsInherited["onShownEvent"]>;

package/dist/react/coachmark/index.js

@@ -3,8 +3,22 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/coachmark';
 import { TAG_NAME } from '../../components/coachmark/coachmark.constants';
 /**
+ * A Coachmark is a contextual guidance component used to highlight a specific UI element and explain its purpose or functionality.
+ * It is typically shown as part of onboarding, feature discovery, or progressive education within the product.
+ *
  * Coachmark component based on top of the popover component,
  * with the default value of certain properties changed.
+ * Coachmark component will always have an arrow attached to it.
+ * The color of the coachmark is contrast.
+ *
+ * ## When to use
+ * - Introducing a new or complex feature to users.
+ * - Drawing attention to a UI element that might otherwise be missed.
+ * - Providing step-by-step guidance in an onboarding or walkthrough flow.
+ *
+ * ## Accessibility
+ * - The default role of coachmark is `"dialog"`, which can be changed via the `role` attribute.
+ * - aria-label or aria-labelledby can be provided to give the coachmark an accessible name.
  *
  * @dependency mdc-popover
  *
@@ -26,7 +40,6 @@ import { TAG_NAME } from '../../components/coachmark/coachmark.constants';
  * @cssproperty --mdc-popover-elevation-3 - elevation of the popover
  *
  * @slot - Default slot for modal container
- *
  */
 const reactWrapper = createComponent({
     tagName: TAG_NAME,

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/package.json

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