@momentum-design/components 0.104.17 → 0.105.1

package/dist/utils/mixins/ItemCollectionMixin.js

@@ -0,0 +1,89 @@
+import { isBefore } from '../dom';
+import { LIFE_CYCLE_EVENTS } from './lifecycle/lifecycle.contants';
+/**
+ * This mixin collects and cache items based on the `created` and `destroyed` lifecycle events.
+ * Also provides methods to manage the item cache.
+ *
+ * @example
+ * ```ts
+ * // Add and remove item based on the disabled state
+ * class ListBox extends ItemCollectionMixin<Option, typeof Component>(Component) {
+ *    constructor() {
+ *      super();
+ *      this.addEventListener('modified', this.handleModifiedEvent);
+ *    }
+ *
+ *    handleModifiedEvent(event: LifeCycleModifiedEvent) {
+ *      if (event.details.change === 'enabled') {
+ *         this.addItemToCacheAt(event.target);
+ *      } else if (event.details.change === 'disabled') {
+ *         this.removeItemFromCache(event.target)
+ *      }
+ *    }
+ * }
+ * ```
+ *
+ * @param superClass - The class to extend with the mixin.
+ */
+export const ItemCollectionMixin = (superClass) => {
+    class InnerMixinClass extends superClass {
+        /** @see ItemCollectionMixinInterface.items */
+        get items() {
+            return this.itemCache;
+        }
+        constructor(...rest) {
+            super(...rest);
+            this.itemCache = [];
+            this.addEventListener(LIFE_CYCLE_EVENTS.CREATED, this.itemCreationHandler);
+            this.addEventListener(LIFE_CYCLE_EVENTS.DESTROYED, this.itemDestroyHandler);
+        }
+        /**
+         * Handles the item creation event.
+         *
+         * @param event - The event triggered when an item is created.
+         */
+        itemCreationHandler(event) {
+            const newItem = event.target;
+            this.addItemToCacheAt(newItem);
+        }
+        /**
+         * Handles the item destroy event.
+         *
+         * @param event - The event triggered when an item is destroyed.
+         */
+        itemDestroyHandler(event) {
+            const removedItem = event.target;
+            this.removeItemFromCache(removedItem);
+        }
+        /** @see ItemCollectionMixinInterface.isValidItem */
+        isValidItem(item) {
+            return !!item;
+        }
+        /** @see ItemCollectionMixinInterface.addItemToCacheAt */
+        addItemToCacheAt(newItem, index) {
+            if (this.isValidItem(newItem) && !this.itemCache.includes(newItem)) {
+                const idx = index === undefined ? this.itemCache.findIndex(e => isBefore(newItem, e)) : index;
+                if (idx === -1) {
+                    this.itemCache.push(newItem);
+                }
+                else if (idx >= 0) {
+                    this.itemCache.splice(idx, 0, newItem);
+                }
+            }
+        }
+        /** @see ItemCollectionMixinInterface.removeItemFromCache */
+        removeItemFromCache(item) {
+            const idx = this.itemCache.indexOf(item);
+            if (idx !== -1) {
+                this.itemCache.splice(idx, 1);
+            }
+        }
+        /** @see ItemCollectionMixinInterface.setItemCache */
+        setItemCache(items) {
+            this.itemCache.length = 0;
+            this.itemCache.push(...(items || []));
+        }
+    }
+    // Cast return type to your mixin's interface intersected with the superClass type
+    return InnerMixinClass;
+};

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

@@ -0,0 +1,28 @@
+import type { Component } from '../../models';
+import type { Constructor } from './index.types';
+export declare abstract class ListNavigationMixinInterface {
+    protected loop: boolean;
+    protected propagateAllKeyEvents: boolean;
+    protected resetTabIndexes(index: number): void;
+    protected abstract get navItems(): HTMLElement[];
+    protected resetTabIndexAndSetFocus(newIndex: number, oldIndex?: number, focusNewItem?: boolean): void;
+}
+/**
+ * This mixin extends the passed class with list like navigation capabilities.
+ *
+ * It handles up and down arrow keys, home and end keys to navigate through a list of items.
+ * Key mapping aligned to reading direction (RTL or LTR).
+ *
+ * @example
+ * ```ts
+ * class MyComponent extends ListNavigationMixin(Component) {
+ *   protected override loop = false; // Enable looping navigation
+ *
+ *   protected get navItems() {
+ *      return this.shadowRoot?.querySelectorAll('.mdc-listitem') || [];
+ *   }
+ * }
+ * ```
+ * @param superClass - The class to extend with the mixin.
+ */
+export declare const ListNavigationMixin: <T extends Constructor<Component>>(superClass: T) => Constructor<Component & ListNavigationMixinInterface> & T;

package/dist/utils/mixins/ListNavigationMixin.js

@@ -0,0 +1,199 @@
+import { KEYS } from '../keys';
+/**
+ * This mixin extends the passed class with list like navigation capabilities.
+ *
+ * It handles up and down arrow keys, home and end keys to navigate through a list of items.
+ * Key mapping aligned to reading direction (RTL or LTR).
+ *
+ * @example
+ * ```ts
+ * class MyComponent extends ListNavigationMixin(Component) {
+ *   protected override loop = false; // Enable looping navigation
+ *
+ *   protected get navItems() {
+ *      return this.shadowRoot?.querySelectorAll('.mdc-listitem') || [];
+ *   }
+ * }
+ * ```
+ * @param superClass - The class to extend with the mixin.
+ */
+export const ListNavigationMixin = (superClass) => {
+    class InnerMixinClass extends superClass {
+        constructor(...rest) {
+            super(...rest);
+            /**
+             * Whether to loop navigation when reaching the end of the list.
+             * If true, pressing the down arrow on the last item will focus the first item,
+             * and pressing the up arrow on the first item will focus the last item.
+             * If false, navigation will stop at the first or last item.
+             *
+             * @default true
+             * @internal
+             */
+            this.loop = true;
+            /**
+             * Whether to propagate all key events to parent components.
+             * If true, all key events will bubble up and can be handled by parent components.
+             * If false, navigation key events handled by this mixin will not propagate further.
+             *
+             * @default false
+             * @internal
+             */
+            this.propagateAllKeyEvents = false;
+            /**
+             * Handles keydown events for navigation within the list.
+             * It allows users to navigate through the list items using arrow keys, home, and end keys.
+             * The navigation is based on the current focused item and the direction of the layout (RTL or LTR).
+             *
+             * By default, it will stop propagation for key events which are handled by the component.
+             * Check the mixin options to change this behavior.
+             *
+             * @param event - The keyboard event triggered by user interaction.
+             * @internal
+             */
+            this.handleNavigationKeyDown = (event) => {
+                let isKeyHandled = false;
+                const target = event.target;
+                const currentIndex = this.getCurrentIndex(target);
+                if (currentIndex === -1)
+                    return;
+                this.resetTabIndexes(currentIndex);
+                const isRtl = window.getComputedStyle(this).direction === 'rtl';
+                const targetKey = this.resolveDirectionKey(event.key, isRtl);
+                switch (targetKey) {
+                    case KEYS.HOME: {
+                        // Move focus to the first item
+                        this.resetTabIndexAndSetFocus(0, currentIndex);
+                        isKeyHandled = true;
+                        break;
+                    }
+                    case KEYS.END: {
+                        // Move focus to the last item
+                        this.resetTabIndexAndSetFocus(this.navItems.length - 1, currentIndex);
+                        isKeyHandled = true;
+                        break;
+                    }
+                    case KEYS.ARROW_DOWN: {
+                        // Move focus to the next item
+                        const eolIndex = this.loop ? 0 : currentIndex;
+                        const newIndex = currentIndex + 1 === this.navItems.length ? eolIndex : currentIndex + 1;
+                        this.resetTabIndexAndSetFocus(newIndex, currentIndex);
+                        isKeyHandled = true;
+                        break;
+                    }
+                    case KEYS.ARROW_UP: {
+                        // Move focus to the prev item
+                        const eolIndex = this.loop ? this.navItems.length - 1 : currentIndex;
+                        const newIndex = currentIndex - 1 === -1 ? eolIndex : currentIndex - 1;
+                        this.resetTabIndexAndSetFocus(newIndex, currentIndex);
+                        isKeyHandled = true;
+                        break;
+                    }
+                    default:
+                        break;
+                }
+                // When the component consume any of the pressed key, we need to stop propagation
+                // to prevent the event from bubbling up and being handled by parent components which might use the same key.
+                if (isKeyHandled && !this.propagateAllKeyEvents) {
+                    event.stopPropagation();
+                    event.preventDefault();
+                }
+            };
+            /**
+             * Handles click events on the navigation items.
+             * It retrieves the index of the clicked item and resets the tabindex accordingly.
+             *
+             * @param event - The mouse event triggered by user interaction.
+             * @internal
+             */
+            this.handleNavigationClick = (event) => {
+                const newIndex = this.getCurrentIndex(event.target);
+                this.resetTabIndexes(newIndex);
+            };
+            this.addEventListener('keydown', this.handleNavigationKeyDown);
+            this.addEventListener('click', this.handleNavigationClick);
+        }
+        /**
+         * Reset tabindex and set focus to the first item in the list after the component is first updated.
+         *
+         * @param changedProperties - The properties that have changed since the last update.
+         */
+        async firstUpdated(changedProperties) {
+            super.firstUpdated(changedProperties);
+            this.resetTabIndexAndSetFocus(0, undefined, false);
+        }
+        /**
+         * Retrieves the current index of the item that triggered the event.
+         *
+         * @param target - The target element that triggered the event.
+         * @returns - The index of the current item in the `navItems` array.
+         */
+        getCurrentIndex(target) {
+            return this.navItems.findIndex(node => node === target);
+        }
+        /**
+         * Reset all tabindex to -1 and set the tabindex of the current item to 0
+         *
+         * @param index - The index of the currently focused item.
+         */
+        resetTabIndexes(index) {
+            if (this.navItems.length > 0) {
+                this.navItems.forEach(item => item.setAttribute('tabindex', '-1'));
+                const currentIndex = this.navItems[index] ? index : 0;
+                this.navItems[currentIndex].setAttribute('tabindex', '0');
+                this.navItems[currentIndex].focus();
+            }
+        }
+        /**
+         * Resets the tabindex of the currently focused item and sets focus to a new item.
+         *
+         * @param newIndex - The index of the new item to focus.
+         * @param oldIndex - The index of the currently focused item.
+         * @param focusNewItem - Call focus() on the new item or not. It should be false during firstUpdate
+         * @returns - This method does not return anything.
+         */
+        resetTabIndexAndSetFocus(newIndex, oldIndex, focusNewItem = true) {
+            const { navItems } = this;
+            if (navItems.length === 0)
+                return;
+            // Ensure newIndex is valid
+            const newIdx = navItems[newIndex] ? newIndex : 0;
+            const newItem = navItems[newIdx];
+            if (newIndex === oldIndex && newItem && newItem.getAttribute('tabindex') === '0') {
+                return;
+            }
+            if (oldIndex !== undefined && navItems[oldIndex]) {
+                // Reset tabindex of the old item
+                navItems[oldIndex].setAttribute('tabindex', '-1');
+            }
+            newItem.setAttribute('tabindex', '0');
+            if (focusNewItem) {
+                newItem.focus();
+            }
+        }
+        /**
+         * 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;
+            }
+        }
+    }
+    // Cast return type to your mixin's interface intersected with the superClass type
+    return InnerMixinClass;
+};

package/dist/utils/mixins/lifecycle/CaptureDestroyEventForChildElement.d.ts

@@ -0,0 +1,30 @@
+import type { LitElement } from 'lit';
+import type { Constructor } from '../index.types';
+export declare class CaptureDestroyEventForChildElementInterface {
+}
+/**
+ * Mixin to re-dispatch elements destroy event.
+ *
+ *
+ * It is necessary because `destroyed` event emitted in the `disconnectedCallback` of the item
+ * it executes after the item disconnected from the DOM tree. The event can not bubble up to the
+ * parent component, but we still can listen to it when we do it directly on it.
+ *
+ * Use {@link LifeCycleMixin} on the child component to emit the `created` and `destroyed` events
+ *
+ * @example
+ * ```ts
+ * // Add created and destroyed event listeners
+ * class MyComponent extends DestroyItemMixin(Component) {
+ *    constructor() {
+ *       super();
+ *       this.addEventListener('created' this.handleItemCreation);
+ *       this.addEventListener('destroyed', this.handleItemRemovedEvent);
+ *    }
+ *    // ...
+ * }
+ * ```
+ *
+ * @param superClass - The class to extend with the mixin.
+ */
+export declare const CaptureDestroyEventForChildElement: <T extends Constructor<LitElement>>(superClass: T) => Constructor<CaptureDestroyEventForChildElementInterface> & T;

package/dist/utils/mixins/lifecycle/CaptureDestroyEventForChildElement.js

@@ -0,0 +1,65 @@
+import { LIFE_CYCLE_EVENTS } from './lifecycle.contants';
+/**
+ * Mixin to re-dispatch elements destroy event.
+ *
+ *
+ * It is necessary because `destroyed` event emitted in the `disconnectedCallback` of the item
+ * it executes after the item disconnected from the DOM tree. The event can not bubble up to the
+ * parent component, but we still can listen to it when we do it directly on it.
+ *
+ * Use {@link LifeCycleMixin} on the child component to emit the `created` and `destroyed` events
+ *
+ * @example
+ * ```ts
+ * // Add created and destroyed event listeners
+ * class MyComponent extends DestroyItemMixin(Component) {
+ *    constructor() {
+ *       super();
+ *       this.addEventListener('created' this.handleItemCreation);
+ *       this.addEventListener('destroyed', this.handleItemRemovedEvent);
+ *    }
+ *    // ...
+ * }
+ * ```
+ *
+ * @param superClass - The class to extend with the mixin.
+ */
+export const CaptureDestroyEventForChildElement = (superClass) => {
+    class InnerMixinClass extends superClass {
+        constructor(...rest) {
+            super(...rest);
+            /**
+             * Register destroy event listener on the item when it is created.
+             *
+             * @param event - The event triggered when an item is created.
+             */
+            this.handleItemCreation = (event) => {
+                const item = event.target;
+                if (item) {
+                    item.addEventListener(LIFE_CYCLE_EVENTS.DESTROYED, this.handleItemRemovedEvent);
+                }
+            };
+            /**
+             * Handles the item removed event to clean up listeners and re-dispatch the destroy event.
+             *
+             * @param event - The event triggered when an item is changed.
+             */
+            this.handleItemRemovedEvent = (event) => {
+                event.stopImmediatePropagation();
+                if (event.target && event.type === LIFE_CYCLE_EVENTS.DESTROYED) {
+                    event.target.removeEventListener(LIFE_CYCLE_EVENTS.DESTROYED, this.handleItemRemovedEvent);
+                    // Re-dispatch the destroy event to allow parent components to handle it.
+                    // We need to create a new event instance, otherwise we will get an error:
+                    // Uncaught InvalidStateError: Failed to execute 'dispatchEvent' on 'EventTarget': The event is already being dispatched.
+                    const evt = new Event(event.type, { bubbles: event.bubbles, composed: event.composed });
+                    // Also, we need to make sure `dispatchEvent` will not change the target of the event.
+                    Object.defineProperty(evt, 'target', { set() { }, get: () => event.target });
+                    this.dispatchEvent(evt);
+                }
+            };
+            this.addEventListener(LIFE_CYCLE_EVENTS.CREATED, this.handleItemCreation);
+        }
+    }
+    // Cast return type to your mixin's interface intersected with the superClass type
+    return InnerMixinClass;
+};

package/dist/utils/mixins/lifecycle/LifeCycleMixin.d.ts

@@ -0,0 +1,33 @@
+import type { LitElement } from 'lit';
+import type { Constructor } from '../index.types';
+export declare class LifeCycleMixinInterface {
+    /**
+     * Dispatches a 'LifeCycleModifiedEvent' event for the passed changed type.
+     *
+     * @param change - The type of change that occurred, e.g., 'disabled'.
+     */
+    protected dispatchModifiedEvent(change: string): void;
+}
+/**
+ * Mixin to create Lifecycle Manager compatible events for the component.
+ *
+ * Emits 'created' and 'destroyed' events when the component is connected or disconnected from the DOM.
+ * Also provides a method to dispatch 'LifeCycleModifiedEvent' for changes in the component's state.
+ *
+ * Use {@link CaptureDestroyEventForChildElement} to propagate the "destroyed" events to the parent component.
+ *
+ * @example
+ * ```ts
+ *  // Add disabled state change event
+ *  class ItemComponent extends LifeCycleMixin(Component) {
+ *    public override update(changedProperties: PropertyValues): void {
+ *     super.update(changedProperties);
+ *
+ *     if (changedProperties.has('disabled')) {
+ *       this.dispatchModifiedEvent(this.disabled ? 'disabled' : 'enabled');
+ *     }
+ *   }
+ *  }
+ * ```
+ */
+export declare const LifeCycleMixin: <T extends Constructor<LitElement>>(superClass: T) => Constructor<LifeCycleMixinInterface> & T;

package/dist/utils/mixins/lifecycle/LifeCycleMixin.js

@@ -0,0 +1,41 @@
+import { LIFE_CYCLE_EVENTS } from './lifecycle.contants';
+/**
+ * Mixin to create Lifecycle Manager compatible events for the component.
+ *
+ * Emits 'created' and 'destroyed' events when the component is connected or disconnected from the DOM.
+ * Also provides a method to dispatch 'LifeCycleModifiedEvent' for changes in the component's state.
+ *
+ * Use {@link CaptureDestroyEventForChildElement} to propagate the "destroyed" events to the parent component.
+ *
+ * @example
+ * ```ts
+ *  // Add disabled state change event
+ *  class ItemComponent extends LifeCycleMixin(Component) {
+ *    public override update(changedProperties: PropertyValues): void {
+ *     super.update(changedProperties);
+ *
+ *     if (changedProperties.has('disabled')) {
+ *       this.dispatchModifiedEvent(this.disabled ? 'disabled' : 'enabled');
+ *     }
+ *   }
+ *  }
+ * ```
+ */
+export const LifeCycleMixin = (superClass) => {
+    class InnerMixinClass extends superClass {
+        connectedCallback() {
+            super.connectedCallback();
+            this.dispatchEvent(new Event(LIFE_CYCLE_EVENTS.CREATED, { bubbles: true, composed: true }));
+        }
+        disconnectedCallback() {
+            super.disconnectedCallback();
+            this.dispatchEvent(new Event(LIFE_CYCLE_EVENTS.DESTROYED, { bubbles: true, composed: true }));
+        }
+        /** @see LifeCycleMixinInterface.dispatchModifiedEvent */
+        dispatchModifiedEvent(change) {
+            this.dispatchEvent(new CustomEvent(LIFE_CYCLE_EVENTS.MODIFIED, { detail: { change }, bubbles: true, composed: true }));
+        }
+    }
+    // Cast return type to your mixin's interface intersected with the superClass type
+    return InnerMixinClass;
+};

package/dist/utils/mixins/lifecycle/LifeCycleModifiedEvent.d.ts

@@ -0,0 +1,19 @@
+import { TypedCustomEvent } from '../../types';
+/**
+ * Event fired when a modification occurs in the managed component.
+ *
+ * For example, when an item disabled, etc.
+ *
+ * @example
+ * ```ts
+ *  this.dispatchEvent(new CustomEvent('modified', {change: 'disabled'}));
+ * ```
+ */
+export type LifeCycleModifiedEvent = TypedCustomEvent<Element, {
+    change: string;
+}>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        modified: LifeCycleModifiedEvent;
+    }
+}

package/dist/utils/mixins/lifecycle/LifeCycleModifiedEvent.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/mixins/lifecycle/lifecycle.contants.d.ts

@@ -0,0 +1,5 @@
+export declare const LIFE_CYCLE_EVENTS: {
+    CREATED: string;
+    DESTROYED: string;
+    MODIFIED: string;
+};

package/dist/utils/mixins/lifecycle/lifecycle.contants.js

@@ -0,0 +1,5 @@
+export const LIFE_CYCLE_EVENTS = {
+    CREATED: 'created',
+    DESTROYED: 'destroyed',
+    MODIFIED: 'modified',
+};

package/package.json

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