wabtec-internal-volt-basic-components 1.2.0 → 1.4.0

package/dist/collection/components/menu/vds-menu.js

@@ -2,42 +2,170 @@ import { Host, h } from "@stencil/core";
 import { updateFloatingBoxPosition } from "../../utils/floating-engine-utils";
 import { combineClasses } from "../../utils/combine-classes";
 import { queryElementFromShadowRoot } from "../../utils/node-utils";
+import { KeyboardNavigation } from "../../utils/keyboard-navigation";
+import { getDeepActiveElement } from "../../utils/get-deep-active-element";
+/**
+ * @component vds-menu
+ * @description A menu component that displays a floating menu with customizable positioning, trigger events (click/hover), and support for nested submenus
+ * @slot menu-trigger - The element that triggers the menu (button, icon, etc.)
+ * @slot menu-content - The content of the menu (menu items, groups, etc.)
+ * @example
+ * <!-- Basic menu with click trigger -->
+ * <vds-menu>
+ *   <vds-button slot="menu-trigger">Menu</vds-button>
+ *   <div slot="menu-content">
+ *     <vds-menu-item>Option 1</vds-menu-item>
+ *     <vds-menu-item>Option 2</vds-menu-item>
+ *     <vds-menu-item>Option 3</vds-menu-item>
+ *   </div>
+ * </vds-menu>
+ *
+ * <!-- Menu with hover trigger -->
+ * <vds-menu event="hover">
+ *   <vds-button slot="menu-trigger">Hover Menu</vds-button>
+ *   <div slot="menu-content">
+ *     <vds-menu-item>Item 1</vds-menu-item>
+ *     <vds-menu-item>Item 2</vds-menu-item>
+ *   </div>
+ * </vds-menu>
+ *
+ * <!-- Menu with custom position -->
+ * <vds-menu position="top">
+ *   <vds-icon-button slot="menu-trigger" icon="more-vertical"></vds-icon-button>
+ *   <div slot="menu-content">
+ *     <vds-menu-item>Edit</vds-menu-item>
+ *     <vds-menu-item>Delete</vds-menu-item>
+ *   </div>
+ * </vds-menu>
+ *
+ * <!-- Menu with max width and height -->
+ * <vds-menu max-width="300px" max-height="400px">
+ *   <vds-button slot="menu-trigger">Options</vds-button>
+ *   <div slot="menu-content">
+ *     <vds-menu-item>Option 1</vds-menu-item>
+ *     <vds-menu-item>Option 2</vds-menu-item>
+ *     <vds-menu-item>Option 3</vds-menu-item>
+ *     <vds-menu-item>Option 4</vds-menu-item>
+ *     <vds-menu-item>Option 5</vds-menu-item>
+ *   </div>
+ * </vds-menu>
+ *
+ * <!-- Menu with backdrop -->
+ * <vds-menu backdrop>
+ *   <vds-button slot="menu-trigger">Menu with Backdrop</vds-button>
+ *   <div slot="menu-content">
+ *     <vds-menu-item>Action 1</vds-menu-item>
+ *     <vds-menu-item>Action 2</vds-menu-item>
+ *   </div>
+ * </vds-menu>
+ *
+ * <!-- Nested submenu -->
+ * <vds-menu>
+ *   <vds-button slot="menu-trigger">Main Menu</vds-button>
+ *   <div slot="menu-content">
+ *     <vds-menu-item>Option 1</vds-menu-item>
+ *     <vds-menu position="right">
+ *       <vds-menu-item slot="menu-trigger">Submenu</vds-menu-item>
+ *       <div slot="menu-content">
+ *         <vds-menu-item>Sub-option 1</vds-menu-item>
+ *         <vds-menu-item>Sub-option 2</vds-menu-item>
+ *       </div>
+ *     </vds-menu>
+ *     <vds-menu-item>Option 3</vds-menu-item>
+ *   </div>
+ * </vds-menu>
+ *
+ * <!-- Menu with auto positioning -->
+ * <vds-menu auto-position>
+ *   <vds-button slot="menu-trigger">Auto Position</vds-button>
+ *   <div slot="menu-content">
+ *     <vds-menu-item>Item 1</vds-menu-item>
+ *     <vds-menu-item>Item 2</vds-menu-item>
+ *   </div>
+ * </vds-menu>
+ */
 export class VdsMenu {
+    /**
+     * Constructor that initializes the cleanup function
+     */
     constructor() {
-        /** Defines the position where the menu will be opened */
+        /**
+         * Defines the position where the menu will be opened
+         * @type {"top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end"}
+         * @default "bottom"
+         */
         this.position = "bottom";
-        /** The type of event that will trigger the popover */
+        /**
+         * The type of event that will trigger the menu
+         * @type {"hover" | "click"}
+         * @default "click"
+         */
         this.event = "click";
-        /** Toggles the floating container auto-positioning based on available window space.
+        /**
+         * Toggles the floating container auto-positioning based on available window space
          * False by default as it may cause positioning issues in some situations, use with caution
-         * */
+         * @type {boolean}
+         * @default false
+         */
         this.autoPosition = false;
-        /** Set backdrop when show the menu */
+        /**
+         * Sets backdrop overlay when menu is shown
+         * @type {boolean}
+         * @default false
+         */
         this.backdrop = false;
+        /**
+         * Controls whether the menu is currently opened
+         * @type {boolean}
+         * @default false
+         */
         this.menuOpened = false;
+        /**
+         * Indicates if this menu is a submenu
+         * @private
+         * @type {boolean}
+         * @default false
+         */
         this.isSubmenu = false;
         this.floatingCleanUp = () => { };
     }
+    /**
+     * Watches for menu opened state changes and manages positioning and events
+     * @returns {Promise<void>}
+     */
     async emitValue() {
         if (this.menuOpened) {
             this.opened.emit();
             this.menuElementRef.style.display = "inline-flex";
             this.floatingCleanUp = await updateFloatingBoxPosition(this.actionElementRef, this.menuElementRef, null, this.position, this.autoPosition);
+            this.initKeyboardNavigation();
         }
         else {
+            this.destroyKeyboardNavigation();
             this.closeNestedMenus();
             this.closed.emit();
             this.menuElementRef.style.display = "none";
             this.floatingCleanUp();
         }
     }
-    /* Close the menu when click outside */
+    /**
+     * Listens for clicks outside the component to close the menu
+     * @param {MouseEvent} evt - The mouse click event
+     * @returns {void}
+     */
     handleClickOut(evt) {
-        const isClickInside = this.hostEl.contains(evt.target);
-        if (!isClickInside && !this.backdrop) {
-            this.menuOpened = false;
+        const path = evt.composedPath ? evt.composedPath() : [];
+        const isClickInside = path.includes(this.hostEl);
+        if (!isClickInside) {
+            this.close();
         }
     }
+    /**
+     * Handles mouse leave events for hover-triggered menus
+     * @private
+     * @param {Event} event - The mouse leave event
+     * @returns {void}
+     */
     handleHoverOut(event) {
         if (this.event === "hover") {
             const hoveredElement = event.target;
@@ -46,9 +174,14 @@ export class VdsMenu {
             }
         }
     }
-    /* Close all nested menus recursively */
+    /**
+     * Closes all nested menus recursively
+     * @private
+     * @returns {void}
+     */
     closeNestedMenus() {
-        const menuContent = this.menuElementRef.querySelector('slot[name="menu-content"]');
+        var _a;
+        const menuContent = (_a = this.menuElementRef) === null || _a === void 0 ? void 0 : _a.querySelector('slot[name="menu-content"]');
         if (menuContent) {
             const elements = Array.from(menuContent.children);
             for (const element of elements) {
@@ -59,7 +192,12 @@ export class VdsMenu {
             }
         }
     }
-    /* Open the menu with click on the trigger element  */
+    /**
+     * Handles click events on the trigger element to open the menu
+     * @private
+     * @param {Event} evt - The click event
+     * @returns {Promise<void>}
+     */
     async handleClick(evt) {
         if (this.event === "click") {
             const clickedElement = evt.target;
@@ -68,26 +206,63 @@ export class VdsMenu {
             }
         }
     }
-    /* Listen when Menu Item element is clicked to close Menu window */
+    /**
+     * Listens for menu item clicked events to close the menu
+     * @returns {void}
+     */
     handleMenuItemClicked() {
         this.close();
     }
-    /* Open the menu from other element  */
+    /**
+     * Re-activates keyboard navigation on the direct parent menu when a child submenu
+     * closes itself via keyboard (Escape).
+     * @private
+     * @param {CustomEvent} evt - Event emitted by a child submenu after keyboard close.
+     * @returns {void}
+     */
+    handleSubmenuKeyboardClosed(evt) {
+        var _a;
+        const submenuEl = evt.target;
+        const directParentMenu = (_a = submenuEl === null || submenuEl === void 0 ? void 0 : submenuEl.parentElement) === null || _a === void 0 ? void 0 : _a.closest("vds-menu");
+        if (directParentMenu === this.hostEl && this.menuOpened) {
+            this.initKeyboardNavigation();
+            evt.stopPropagation();
+        }
+    }
+    /**
+     * Opens the menu programmatically
+     * @method
+     * @public
+     * @returns {Promise<void>} A promise that resolves when the menu is opened
+     */
     async open() {
         this.menuOpened = true;
     }
-    /* Close the menu from other element  */
+    /**
+     * Closes the menu programmatically
+     * @method
+     * @public
+     * @returns {Promise<void>} A promise that resolves when the menu is closed
+     */
     async close() {
         this.closeNestedMenus();
         this.menuOpened = false;
     }
     /**
-     *  Gets the target that will manage the menu
-     *  returns a promise with the target HTMLElement.
+     * Gets the target trigger element that manages the menu
+     * @method
+     * @public
+     * @returns {Promise<HTMLElement | null>} A promise that resolves with the target HTML element
      */
     async getTarget() {
         return document.querySelector(".vds__menu--trigger");
     }
+    /**
+     * Handles hover events for hover-triggered menus
+     * @private
+     * @param {Event} event - The mouse hover event
+     * @returns {void}
+     */
     handleHover(event) {
         if (this.event === "hover") {
             const hoveredElement = event.target;
@@ -96,9 +271,19 @@ export class VdsMenu {
             }
         }
     }
+    /**
+     * Sets the max width and height CSS custom properties
+     * @private
+     * @returns {{[key: string]: string}} The CSS custom properties object
+     */
     setMaxWidthAndHeight() {
         return { "--menu-max-width": this.maxWidth, "--menu-max-height": this.maxHeight };
     }
+    /**
+     * Lifecycle hook that runs before component loads
+     * Detects if this menu is a submenu and adjusts settings accordingly
+     * @returns {void}
+     */
     componentWillLoad() {
         const triggerItem = Array.from(this.hostEl.children).find((child) => child.matches('vds-menu-item[slot="menu-trigger"]'));
         if (triggerItem) {
@@ -107,40 +292,103 @@ export class VdsMenu {
             this.autoPosition = false;
         }
     }
+    /**
+     * Lifecycle hook that runs after component is loaded
+     * Initializes element references and event listeners
+     * @returns {void}
+     */
     componentDidLoad() {
         this.actionElementRef = queryElementFromShadowRoot(this.hostEl, ".vds__menu--trigger");
         this.menuElementRef = queryElementFromShadowRoot(this.hostEl, ".vds__menu--container");
-        if (this.event === "click") {
-            this.actionElementRef.addEventListener("click", this.handleClick.bind(this));
-        }
-        else if (this.event === "hover") {
+        if (this.event === "hover") {
             this.actionElementRef.addEventListener("mouseenter", this.handleHover.bind(this));
             this.menuElementRef.addEventListener("mouseleave", this.handleHoverOut.bind(this));
         }
     }
+    /**
+     * Lifecycle hook that runs after each render
+     * Updates floating box position
+     * @returns {void}
+     */
     componentDidRender() {
         updateFloatingBoxPosition(this.actionElementRef, this.menuElementRef, null, this.position, this.autoPosition);
     }
+    /**
+     * Lifecycle hook that runs when component is disconnected
+     * Cleans up event listeners
+     * @returns {void}
+     */
     disconnectedCallback() {
+        this.destroyKeyboardNavigation();
         window.removeEventListener("click", this.handleClickOut.bind(this));
-        if (this.event === "click") {
-            this.actionElementRef.removeEventListener("click", this.handleClick.bind(this));
-        }
-        else if (this.event === "hover") {
+        if (this.event === "hover") {
             this.actionElementRef.removeEventListener("mouseenter", this.handleHover.bind(this));
             this.menuElementRef.removeEventListener("mouseleave", this.handleHoverOut.bind(this));
         }
     }
+    /**
+     * Initialises keyboard navigation for the open menu and wires close handoff.
+     * For submenu instances, Escape close notifies parent menu to restore its
+     * keyboard navigation context.
+     * @private
+     * @returns {void}
+     */
+    initKeyboardNavigation() {
+        const menuItems = this.getMenuItems();
+        if (menuItems.length === 0) {
+            return;
+        }
+        const triggerEl = getDeepActiveElement();
+        KeyboardNavigation.subscribe(menuItems, triggerEl, () => {
+            this.close();
+            if (this.isSubmenu) {
+                this.hostEl.dispatchEvent(new CustomEvent("submenuKeyboardClosed", { bubbles: true, composed: true }));
+            }
+        });
+    }
+    /**
+     * Destroys the active keyboard navigation session.
+     * @private
+     * @returns {void}
+     */
+    destroyKeyboardNavigation() {
+        KeyboardNavigation.unsubscribe();
+    }
+    /**
+     * Returns focusable buttons for non-disabled items that are navigable in this menu:
+     * direct items (excluding this menu's own slot="menu-trigger" item), plus
+     * trigger items of immediate child submenus.
+     * @private
+     * @returns {HTMLElement[]} An array of focusable menu item buttons.
+     */
+    getMenuItems() {
+        return Array.from(this.hostEl.querySelectorAll('vds-menu-item:not([disabled])'))
+            .filter(item => {
+            var _a;
+            const parentMenu = item.closest('vds-menu');
+            if (parentMenu === this.hostEl && item.getAttribute('slot') === 'menu-trigger')
+                return false;
+            if (parentMenu === this.hostEl)
+                return true;
+            return item.getAttribute('slot') === 'menu-trigger' && ((_a = parentMenu === null || parentMenu === void 0 ? void 0 : parentMenu.parentElement) === null || _a === void 0 ? void 0 : _a.closest('vds-menu')) === this.hostEl;
+        })
+            .map(item => { var _a; return (_a = item.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector('button:not([disabled])'); })
+            .filter((btn) => btn != null);
+    }
+    /**
+     * Renders the component
+     * @returns {HTMLStencilElement} The rendered component
+     */
     render() {
-        return (h(Host, { key: '185c3d3c12da29c2363fbf715bd3d12245a111d2', style: this.setMaxWidthAndHeight() }, this.backdrop && this.menuOpened ? h("div", { class: "vds__menu--backdrop", onClick: () => this.close() }) : null, h("div", { key: 'e84681c10210cfe5cba84d46e19598098de5d37d', class: "vds__menu--trigger", onClick: (evt) => {
+        return (h(Host, { key: 'd275e4bef8b642d3c7c8043d54f8e093a819adef', style: this.setMaxWidthAndHeight() }, this.backdrop && this.menuOpened ? h("div", { class: "vds__menu--backdrop", onClick: () => this.close() }) : null, h("div", { key: '2dd7b7b0a7d422319864eafca29e7bb7fd4992eb', class: "vds__menu--trigger", onClick: (evt) => {
                 this.handleClick(evt);
             }, ref: (triggerEl) => {
                 if (triggerEl)
                     this.actionElementRef = triggerEl;
-            } }, h("slot", { key: '70df140c8aa15ff63e19c18dff56fc5b4dac5b13', name: "menu-trigger" })), h("div", { key: '02443d9bf4a8f69a87908040b9aa13379189e893', class: combineClasses("vds__menu--container", this.maxHeight ? "has-scroll" : "", this.isSubmenu ? `vds__menu--submenu-${this.position}` : ""), ref: (menuEl) => {
+            } }, h("slot", { key: 'cb83769f034ff093d65ee3a3d727d932c7409019', name: "menu-trigger" })), h("div", { key: '40ef89ad06ddede8708528d7e1248de125ba05ab', class: combineClasses("vds__menu--container", this.maxHeight ? "has-scroll" : "", this.isSubmenu ? `vds__menu--submenu-${this.position}` : ""), ref: (menuEl) => {
                 if (menuEl)
                     this.menuElementRef = menuEl;
-            } }, h("slot", { key: 'aa734575ff1f0d854e1aa13d19020d51954369d4', name: "menu-content" }))));
+            } }, h("slot", { key: 'eeb076b4955063f23513137ceb7edab4486f0d4b', name: "menu-content" }))));
     }
     static get is() { return "vds-menu"; }
     static get encapsulation() { return "shadow"; }
@@ -160,14 +408,20 @@ export class VdsMenu {
                 "type": "string",
                 "mutable": true,
                 "complexType": {
-                    "original": "\"top\" | \"bottom\" | \"right\" | \"left\"",
-                    "resolved": "\"bottom\" | \"left\" | \"right\" | \"top\"",
+                    "original": "\"top\" | \"bottom\" | \"right\" | \"left\" | \"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"",
+                    "resolved": "\"bottom\" | \"bottom-end\" | \"bottom-start\" | \"left\" | \"right\" | \"top\" | \"top-end\" | \"top-start\"",
                     "references": {}
                 },
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"top\" | \"bottom\" | \"right\" | \"left\" | \"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"bottom\""
+                        }],
                     "text": "Defines the position where the menu will be opened"
                 },
                 "getter": false,
@@ -187,8 +441,11 @@ export class VdsMenu {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the maximum width of the menu\"s content"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Sets the maximum width of the menu's content"
                 },
                 "getter": false,
                 "setter": false,
@@ -206,8 +463,11 @@ export class VdsMenu {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the maximum height of the menu\"s content"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Sets the maximum height of the menu's content"
                 },
                 "getter": false,
                 "setter": false,
@@ -225,8 +485,14 @@ export class VdsMenu {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "The type of event that will trigger the popover"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"hover\" | \"click\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"click\""
+                        }],
+                    "text": "The type of event that will trigger the menu"
                 },
                 "getter": false,
                 "setter": false,
@@ -245,8 +511,14 @@ export class VdsMenu {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Toggles the floating container auto-positioning based on available window space. \nFalse by default as it may cause positioning issues in some situations, use with caution"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Toggles the floating container auto-positioning based on available window space\nFalse by default as it may cause positioning issues in some situations, use with caution"
                 },
                 "getter": false,
                 "setter": false,
@@ -265,8 +537,14 @@ export class VdsMenu {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Set backdrop when show the menu"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Sets backdrop overlay when menu is shown"
                 },
                 "getter": false,
                 "setter": false,
@@ -289,8 +567,14 @@ export class VdsMenu {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emits event when menu gets opens"
+                    "tags": [{
+                            "name": "event",
+                            "text": "opened"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<void>}"
+                        }],
+                    "text": "Emitted when menu opens"
                 },
                 "complexType": {
                     "original": "void",
@@ -304,8 +588,14 @@ export class VdsMenu {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emits event when menu gets closes"
+                    "tags": [{
+                            "name": "event",
+                            "text": "closed"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<void>}"
+                        }],
+                    "text": "Emitted when menu closes"
                 },
                 "complexType": {
                     "original": "void",
@@ -329,8 +619,17 @@ export class VdsMenu {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "",
-                    "tags": []
+                    "text": "Opens the menu programmatically",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": "A promise that resolves when the menu is opened"
+                        }]
                 }
             },
             "close": {
@@ -346,8 +645,17 @@ export class VdsMenu {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "",
-                    "tags": []
+                    "text": "Closes the menu programmatically",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": "A promise that resolves when the menu is closed"
+                        }]
                 }
             },
             "getTarget": {
@@ -367,8 +675,17 @@ export class VdsMenu {
                     "return": "Promise<HTMLElement>"
                 },
                 "docs": {
-                    "text": "Gets the target that will manage the menu\nreturns a promise with the target HTMLElement.",
-                    "tags": []
+                    "text": "Gets the target trigger element that manages the menu",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": "A promise that resolves with the target HTML element"
+                        }]
                 }
             }
         };
@@ -393,7 +710,12 @@ export class VdsMenu {
                 "target": undefined,
                 "capture": false,
                 "passive": false
+            }, {
+                "name": "submenuKeyboardClosed",
+                "method": "handleSubmenuKeyboardClosed",
+                "target": undefined,
+                "capture": false,
+                "passive": false
             }];
     }
 }
-//# sourceMappingURL=vds-menu.js.map

package/dist/collection/components/menu/vds-menu.stories.js

@@ -7,7 +7,7 @@ export default {
     },
     argTypes: {
         position: {
-            options: ['left', 'right', 'top', 'bottom'],
+            options: ['left', 'right', 'top', 'bottom', 'top-start', 'top-end', 'bottom-start', 'bottom-end'],
             control: { type: 'select' },
         },
         event: {
@@ -223,4 +223,3 @@ NestedUsage.args = {
     backdrop: 'false',
     autoPosition: false
 };
-//# sourceMappingURL=vds-menu.stories.js.map