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

package/dist/types/components/link/vds-link.d.ts

@@ -1,29 +1,144 @@
 import { HTMLStencilElement } from "../../stencil-public-runtime";
+/**
+ * @component vds-link
+ * @description A link component that provides styled anchor elements with optional icons, multiple variants, sizes, and customizable positioning
+ * @example
+ * <!-- Basic link -->
+ * <vds-link
+ *   value="Click here"
+ *   url="/page"></vds-link>
+ *
+ * <!-- Link with underline -->
+ * <vds-link
+ *   value="Underlined link"
+ *   url="/about"
+ *   underline></vds-link>
+ *
+ * <!-- Link with icon on the right (default) -->
+ * <vds-link
+ *   value="External link"
+ *   url="https://example.com"
+ *   target="_blank"
+ *   rel="noopener noreferrer"
+ *   informative-icon="link-open"></vds-link>
+ *
+ * <!-- Link with icon on the left -->
+ * <vds-link
+ *   value="Home"
+ *   url="/"
+ *   informative-icon="home"
+ *   icon-position="left"></vds-link>
+ *
+ * <!-- Large primary link -->
+ * <vds-link
+ *   value="Large Link"
+ *   url="/large"
+ *   size="large"
+ *   variant="primary"></vds-link>
+ *
+ * <!-- Small secondary link -->
+ * <vds-link
+ *   value="Small Link"
+ *   url="/small"
+ *   size="small"
+ *   variant="secondary"></vds-link>
+ *
+ * <!-- Extra small link -->
+ * <vds-link
+ *   value="Tiny link"
+ *   url="/tiny"
+ *   size="extra-small"></vds-link>
+ *
+ * <!-- 2x-small link -->
+ * <vds-link
+ *   value="Smallest"
+ *   url="/smallest"
+ *   size="2x-small"></vds-link>
+ *
+ * <!-- Footer variant link -->
+ * <vds-link
+ *   value="Footer Link"
+ *   url="/footer"
+ *   variant="footer"></vds-link>
+ *
+ * <!-- Link with icon and underline -->
+ * <vds-link
+ *   value="Download"
+ *   url="/download.pdf"
+ *   informative-icon="download"
+ *   underline></vds-link>
+ *
+ * <!-- Link opening in new tab -->
+ * <vds-link
+ *   value="Open in new tab"
+ *   url="https://external.com"
+ *   target="_blank"
+ *   rel="noopener"></vds-link>
+ */
 export declare class VdsLink {
-    /** Sets the value for the label text */
+    /**
+     * Sets the label text for the link
+     * @type {string}
+     */
     value: string;
-    /** Sets icon position relative to the label text */
+    /**
+     * Sets the icon position relative to the label text
+     * @type {"right" | "left"}
+     * @default "right"
+     */
     iconPosition: "right" | "left";
-    /** Enable / Disable underline text decoration */
+    /**
+     * Enables or disables underline text decoration
+     * @type {boolean}
+     * @default false
+     */
     underline: boolean;
-    /** Sets url link for the internal href */
+    /**
+     * Sets the URL for the internal href
+     * @type {string}
+     * @default "#"
+     */
     url: string;
-    /** Sets href target */
+    /**
+     * Sets the href target attribute
+     * @type {"_self" | "_blank" | "_parent" | "_top"}
+     * @default "_self"
+     */
     target: "_self" | "_blank" | "_parent" | "_top";
-    /** Sets the link rel value */
+    /**
+     * Sets the link rel attribute value
+     * @type {string}
+     * @default null
+     */
     rel: string;
-    /** Set the link size */
+    /**
+     * Sets the link size
+     * @type {"large" | "medium" | "small" | "extra-small" | "2x-small"}
+     * @default "medium"
+     */
     size: "large" | "medium" | "small" | "extra-small" | "2x-small";
-    /** Sets the informative icon in the vds-link */
+    /**
+     * Sets the informative icon to display with the link
+     * @type {string}
+     */
     informativeIcon: string;
-    /** Sets the link variant - footer variant is the same as secondary.
-     * @tobedeprecated footer variant will be deprecated in the future.
+    /**
+     * Sets the link variant style
+     * Note: footer variant is the same as secondary and will be deprecated in the future
+     * @type {"primary" | "secondary" | "footer"}
+     * @default "primary"
+     * @deprecated footer variant will be deprecated in the future
      */
     variant: "primary" | "secondary" | "footer";
-    /** Sets the informative icon in the vds-link
-     *
-     * @returns HTMLStencilElement
+    /**
+     * Renders the informative icon with appropriate size based on link size
+     * @private
+     * @returns {HTMLStencilElement} The icon element
      */
     getIcon(): HTMLStencilElement;
+    /**
+     * Renders the component
+     * @returns {HTMLStencilElement} The rendered component
+     */
     render(): HTMLStencilElement;
 }

package/dist/types/components/menu/vds-menu.d.ts

@@ -1,49 +1,300 @@
 import { EventEmitter } from "../../stencil-public-runtime";
 import { HTMLStencilElement } from "../../stencil-public-runtime";
+/**
+ * @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 declare class VdsMenu {
+    /**
+     * Reference to the host element
+     * @type {HTMLElement}
+     */
     hostEl: HTMLElement;
-    /** Defines the position where the menu will be opened */
-    position: "top" | "bottom" | "right" | "left";
-    /** Sets the maximum width of the menu"s content */
+    /**
+     * Defines the position where the menu will be opened
+     * @type {"top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end"}
+     * @default "bottom"
+     */
+    position: "top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end";
+    /**
+     * Sets the maximum width of the menu's content
+     * @type {string}
+     */
     maxWidth: string;
-    /** Sets the maximum height of the menu"s content */
+    /**
+     * Sets the maximum height of the menu's content
+     * @type {string}
+     */
     maxHeight: string;
-    /** The type of event that will trigger the popover */
+    /**
+     * The type of event that will trigger the menu
+     * @type {"hover" | "click"}
+     * @default "click"
+     */
     event: "hover" | "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
+     */
     autoPosition: boolean;
-    /** Set backdrop when show the menu */
+    /**
+     * Sets backdrop overlay when menu is shown
+     * @type {boolean}
+     * @default false
+     */
     backdrop: boolean;
+    /**
+     * Controls whether the menu is currently opened
+     * @type {boolean}
+     * @default false
+     */
     menuOpened: boolean;
-    /** Emits event when menu gets opens */
+    /**
+     * Emitted when menu opens
+     * @event opened
+     * @type {EventEmitter<void>}
+     */
     opened: EventEmitter<void>;
-    /** Emits event when menu gets closes */
+    /**
+     * Emitted when menu closes
+     * @event closed
+     * @type {EventEmitter<void>}
+     */
     closed: EventEmitter<void>;
+    /**
+     * Reference to the action/trigger element
+     * @private
+     * @type {HTMLElement}
+     */
     private actionElementRef;
+    /**
+     * Reference to the menu container element
+     * @private
+     * @type {HTMLElement}
+     */
     private menuElementRef;
+    /**
+     * Cleanup function for floating positioning
+     * @private
+     * @type {() => void}
+     */
     private floatingCleanUp;
+    /**
+     * Indicates if this menu is a submenu
+     * @private
+     * @type {boolean}
+     * @default false
+     */
     private isSubmenu;
+    /**
+     * Constructor that initializes the cleanup function
+     */
     constructor();
+    /**
+     * Watches for menu opened state changes and manages positioning and events
+     * @returns {Promise<void>}
+     */
     emitValue(): Promise<void>;
+    /**
+     * Listens for clicks outside the component to close the menu
+     * @param {MouseEvent} evt - The mouse click event
+     * @returns {void}
+     */
     handleClickOut(evt: MouseEvent): void;
+    /**
+     * Handles mouse leave events for hover-triggered menus
+     * @private
+     * @param {Event} event - The mouse leave event
+     * @returns {void}
+     */
     handleHoverOut(event: Event): void;
+    /**
+     * Closes all nested menus recursively
+     * @private
+     * @returns {void}
+     */
     private closeNestedMenus;
+    /**
+     * Handles click events on the trigger element to open the menu
+     * @private
+     * @param {Event} evt - The click event
+     * @returns {Promise<void>}
+     */
     handleClick(evt: Event): Promise<void>;
+    /**
+     * Listens for menu item clicked events to close the menu
+     * @returns {void}
+     */
     handleMenuItemClicked(): void;
+    /**
+     * 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: CustomEvent): void;
+    /**
+     * Opens the menu programmatically
+     * @method
+     * @public
+     * @returns {Promise<void>} A promise that resolves when the menu is opened
+     */
     open(): Promise<void>;
+    /**
+     * Closes the menu programmatically
+     * @method
+     * @public
+     * @returns {Promise<void>} A promise that resolves when the menu is closed
+     */
     close(): Promise<void>;
     /**
-     *  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
      */
     getTarget(): Promise<HTMLElement | null>;
+    /**
+     * Handles hover events for hover-triggered menus
+     * @private
+     * @param {Event} event - The mouse hover event
+     * @returns {void}
+     */
     private handleHover;
+    /**
+     * Sets the max width and height CSS custom properties
+     * @private
+     * @returns {{[key: string]: string}} The CSS custom properties object
+     */
     private setMaxWidthAndHeight;
+    /**
+     * Lifecycle hook that runs before component loads
+     * Detects if this menu is a submenu and adjusts settings accordingly
+     * @returns {void}
+     */
     componentWillLoad(): void;
+    /**
+     * Lifecycle hook that runs after component is loaded
+     * Initializes element references and event listeners
+     * @returns {void}
+     */
     componentDidLoad(): void;
+    /**
+     * Lifecycle hook that runs after each render
+     * Updates floating box position
+     * @returns {void}
+     */
     componentDidRender(): void;
+    /**
+     * Lifecycle hook that runs when component is disconnected
+     * Cleans up event listeners
+     * @returns {void}
+     */
     disconnectedCallback(): void;
+    /**
+     * 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}
+     */
+    private initKeyboardNavigation;
+    /**
+     * Destroys the active keyboard navigation session.
+     * @private
+     * @returns {void}
+     */
+    private destroyKeyboardNavigation;
+    /**
+     * 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.
+     */
+    private getMenuItems;
+    /**
+     * Renders the component
+     * @returns {HTMLStencilElement} The rendered component
+     */
     render(): HTMLStencilElement;
 }

package/dist/types/components/menu-group-header/vds-menu-group-header.d.ts

@@ -1,6 +1,48 @@
 import { GroupHeaderSize } from '../base-group-header/base-group-header';
+/**
+ * @component vds-menu-group-header
+ * @description A header component for grouping menu items, providing visual separation and organization within menus
+ * @slot default - Content for the group header label
+ * @example
+ * <!-- Basic menu group header -->
+ * <vds-menu>
+ *   <vds-button slot="menu-trigger">Menu</vds-button>
+ *   <div slot="menu-content">
+ *     <vds-menu-group-header>Settings</vds-menu-group-header>
+ *     <vds-menu-item>Preferences</vds-menu-item>
+ *     <vds-menu-item>Theme</vds-menu-item>
+ *   </div>
+ * </vds-menu>
+ *
+ * <!-- Multiple grouped sections -->
+ * <vds-menu>
+ *   <vds-button slot="menu-trigger">Options</vds-button>
+ *   <div slot="menu-content">
+ *     <vds-menu-group-header>File</vds-menu-group-header>
+ *     <vds-menu-item>New</vds-menu-item>
+ *     <vds-menu-item>Open</vds-menu-item>
+ *     <vds-menu-group-header>Edit</vds-menu-group-header>
+ *     <vds-menu-item>Cut</vds-menu-item>
+ *     <vds-menu-item>Copy</vds-menu-item>
+ *   </div>
+ * </vds-menu>
+ *
+ * <!-- Small size group header -->
+ * <vds-menu-group-header size="small">Actions</vds-menu-group-header>
+ *
+ * <!-- Large size group header -->
+ * <vds-menu-group-header size="large">Main Menu</vds-menu-group-header>
+ */
 export declare class VdsMenuGroupHeader {
-    /** Size of the group header */
+    /**
+     * Sets the size of the group header
+     * @type {GroupHeaderSize}
+     * @default 'medium'
+     */
     size: GroupHeaderSize;
+    /**
+     * Renders the component
+     * @returns {HTMLElement} The rendered component
+     */
     render(): any;
 }