@telesign/boreal-web-components 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/collection/mixins/menu-behavior.mixin.js

@@ -0,0 +1,119 @@
+import { handleMenuKeyNavigation, resolveMenuItemRole, resolveAriaSelected, resolveTabIndex, KEYBOARD, preventNavigationKeys, } from "../utils/index";
+/**
+ * A Mixin that provides menu item behaviors, including ARIA roles,
+ * focus management, and keyboard navigation logic.
+ * This mixin is designed to be used with Stencil components that represent items within a menu or listbox,
+ * allowing them to automatically adapt their behavior based on the context of their parent container.
+ *
+ * The mixin includes:
+ * - Dynamic ARIA role resolution based on the nearest parent menu or listbox.
+ * - Computation of aria-selected and tabIndex attributes for accessibility.
+ * - A method to handle keyboard navigation (Arrow keys, Enter, Space) within the menu context.
+ *
+ * @typeParam B - The base constructor type.
+ * @param {B} Base - The base component class to be extended.
+ * @returns {MenuBehaviorMixin} - A class with injected menu behaviors.
+ *
+ * @example
+ * ```tsx
+ * import { Component, h } from '@stencil/core';
+ * import { MenuItemBehavior } from '@/mixins/menu-behavior.mixin';
+ *
+ * @Component({
+ *  tag: 'my-menu-item',
+ *  styleUrl: 'my-menu-item.scss',
+ * })
+ * export class MyMenuItem extends Mixin(MenuItemBehavior) {
+ *   @Element() el!: HTMLElement;
+ *   @Prop() disabled: boolean = false;
+ *   @Prop() selected: boolean = false;
+ *
+ *   private handleKeyDown = (e: KeyboardEvent) => {
+ *     if (this.disabled) return;
+ *     this.handleKeyDownLogic(e, () => this.handleSelection());
+ *   };
+ *
+ *  render() {
+ *   return (
+ *    <Host
+ *      role={this.menuItemRole}
+ *      aria-selected={this.ariaSelected}
+ *      tabIndex={ this.itemTabIndex}
+ *      onKeyDown={this.handleKeyDown} >
+ *      <slot />
+ *    </Host>
+ *   );
+ *  }
+ * } ```
+ *
+ *
+ */
+export const MenuItemBehavior = (Base) => {
+    class MenuBehaviorMixin extends Base {
+        constructor() {
+            super(...arguments);
+            this.disabled = false;
+            this.selected = false;
+            this.activeItem = false;
+        }
+        /**
+         * Finds the closest parent element with a role of 'menu' or 'listbox'.
+         * @returns {HTMLElement | null} - The parent menu or listbox element, or null if not found.
+         */
+        get parent() {
+            return this.el.closest('[role="menu"], [role="listbox"]');
+        }
+        /**
+         * Detects the ARIA role of the nearest parent menu or listbox.
+         * @returns {MenuRole | null} - 'menu', 'listbox', or null if not found.
+         */
+        get parentRole() {
+            const parent = this.parent;
+            return parent !== null ? parent.getAttribute('role') : null;
+        }
+        /**
+         * Resolves the specific item role ('menuitem' or 'option').
+         * Defaults to 'menuitem' if no parent is detected.
+         * @returns {MenuItemRole}
+         */
+        get menuItemRole() {
+            return resolveMenuItemRole(this.parentRole || 'menu');
+        }
+        /**
+         * Returns the 'aria-selected' value as a string for listbox options.
+         * @returns {string | null}
+         */
+        get ariaSelected() {
+            return resolveAriaSelected(this.menuItemRole, this.selected);
+        }
+        /**
+         * Calculates the tabIndex for the item.
+         * @returns {number} 0 for focusable menu items, -1 otherwise.
+         */
+        get itemTabIndex() {
+            return resolveTabIndex(this.menuItemRole, this.disabled, this.activeItem);
+        }
+        /**
+         * Processes keyboard events for arrow navigation and activation.
+         * @param {KeyboardEvent} e - The native keyboard event.
+         * @param {() => void} onActivate - Function to execute when Enter or Space is pressed.
+         * @example
+         * // Inside a component's keydown listener:
+         * this.handleKeyDownLogic(event, () => this.emitSelection());
+         */
+        handleKeyDownLogic(e, onActivate) {
+            preventNavigationKeys(e);
+            if (e.key === KEYBOARD.Enter || e.key === KEYBOARD.Space) {
+                onActivate();
+                return;
+            }
+            const parent = this.parent;
+            if (parent === null)
+                return;
+            const items = Array.from(parent.querySelectorAll(`${this.el.tagName.toLocaleLowerCase()}:not([disabled]):not([variant="label"])`));
+            const currentIndex = items.indexOf(this.el);
+            handleMenuKeyNavigation(e, items, currentIndex);
+        }
+    }
+    return MenuBehaviorMixin;
+};