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

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

@@ -4,52 +4,249 @@ export interface MenuItemClickedEvent {
     value: string;
     event: MouseEvent;
 }
+/**
+ * @component vds-menu-item
+ * @description An interactive menu item component for displaying options within menus. Supports icons, checkmarks, checkboxes, links, and submenu indicators. Can be used within vds-menu for building navigation, actions, or selection interfaces.
+ *
+ * @example
+ * <!-- Basic menu item -->
+ * <vds-menu-item value="Profile"></vds-menu-item>
+ *
+ * @example
+ * <!-- Menu item with icon -->
+ * <vds-menu-item icon="user" value="Account Settings"></vds-menu-item>
+ *
+ * @example
+ * <!-- Menu item as link -->
+ * <vds-menu-item
+ *   value="Documentation"
+ *   link-href="https://example.com/docs"
+ *   link-target="_blank"
+ *   link-rel="noopener noreferrer">
+ * </vds-menu-item>
+ *
+ * @example
+ * <!-- Menu item with checkmark (single selection) -->
+ * <vds-menu-item
+ *   value="Option A"
+ *   has-checkmark="true"
+ *   is-selected="true"
+ *   checkmark-variant="checkmark">
+ * </vds-menu-item>
+ *
+ * @example
+ * <!-- Menu item with checkbox (multi-selection) -->
+ * <vds-menu-item
+ *   value="Feature 1"
+ *   has-checkmark="true"
+ *   checkmark-variant="checkbox"
+ *   is-selected="true">
+ * </vds-menu-item>
+ *
+ * @example
+ * <!-- Menu item with children indicator -->
+ * <vds-menu-item
+ *   value="More Options"
+ *   has-children="true">
+ * </vds-menu-item>
+ *
+ * @example
+ * <!-- Danger state menu item -->
+ * <vds-menu-item
+ *   value="Delete Account"
+ *   icon="trash"
+ *   danger="true">
+ * </vds-menu-item>
+ *
+ * @example
+ * <!-- Large size menu item -->
+ * <vds-menu-item
+ *   value="Large Item"
+ *   size="large"
+ *   icon="module-settings">
+ * </vds-menu-item>
+ *
+ * @example
+ * <!-- Checkmark at end alignment -->
+ * <vds-menu-item
+ *   value="Selected Option"
+ *   has-checkmark="true"
+ *   is-selected="true"
+ *   checkmark-alignment="end">
+ * </vds-menu-item>
+ *
+ * @example
+ * <!-- Disabled menu item -->
+ * <vds-menu-item
+ *   value="Unavailable Option"
+ *   disabled="true">
+ * </vds-menu-item>
+ *
+ * @slot - Default slot for custom content in place of the value prop
+ */
 export declare class VdsMenuItem {
-    /** Puts the VdsMenuItem in disabled state */
+    /**
+     * Puts the VdsMenuItem in disabled state
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Define the icon value */
+    /**
+     * Define the icon value
+     * @type {string}
+     */
     icon: string;
-    /** Define item as active when is true */
+    /**
+     * Define item as active when is true
+     * @type {boolean}
+     * @default false
+     */
     isActive: boolean;
-    /** Shows arrow when there are children */
+    /**
+     * Shows arrow when there are children
+     * @type {boolean}
+     * @default false
+     */
     hasChildren: boolean;
-    /** Defines the element as a link */
+    /**
+     * Defines the element as a link
+     * @type {string}
+     * @default null
+     */
     linkHref: string;
-    /** Sets the link target value */
+    /**
+     * Sets the link target value
+     * @type {"_self" | "_blank" | "_parent" | "_top"}
+     * @default "_self"
+     */
     linkTarget: "_self" | "_blank" | "_parent" | "_top";
-    /** Sets the link rel value */
+    /**
+     * Sets the link rel value
+     * @type {string}
+     * @default null
+     */
     linkRel: string;
-    /** Define text value */
+    /**
+     * Define text value
+     * @type {string}
+     */
     value: string;
-    /** Define aria-label */
+    /**
+     * Define aria-label
+     * @type {string}
+     */
     setAriaLabel: string;
-    /** Set size of menu item */
+    /**
+     * Set size of menu item
+     * @type {"medium" | "large"}
+     * @default "medium"
+     */
     size: "medium" | "large";
-    /** Shows checkmark */
+    /**
+     * Shows checkmark
+     * @type {boolean}
+     * @default false
+     */
     hasCheckmark: boolean;
-    /** Set state of checkmark */
+    /**
+     * Set state of checkmark
+     * @type {boolean}
+     * @default false
+     */
     isSelected: boolean;
-    /** When has-checkmark is true, sets the checks element as checkmark or checkbox.  */
+    /**
+     * When has-checkmark is true, sets the checks element as checkmark or checkbox.
+     * @type {"checkbox" | "checkmark"}
+     * @default "checkmark"
+     */
     checkmarkVariant: "checkbox" | "checkmark";
-    /** When has-checkmark is true, sets the checks element at the beginning or end.  */
+    /**
+     * When has-checkmark is true, sets the checks element at the beginning or end.
+     * @type {"start" | "end"}
+     * @default "start"
+     */
     checkmarkAlignment: "start" | "end";
-    /** Sets the menu item to danger state.  */
+    /**
+     * Sets the menu item to danger state.
+     * @type {boolean}
+     * @default false
+     */
     danger: boolean;
-    /** Emits event when item gets clicked */
+    /**
+     * Emits event when item gets clicked
+     * @event clicked
+     * @type {EventEmitter<MenuItemClickedEvent>}
+     */
     clicked: EventEmitter<MenuItemClickedEvent>;
-    /** Emits event when item is selected */
+    /**
+     * Emits event when item is selected
+     * @event selected
+     * @type {EventEmitter<MouseEvent>}
+     */
     selected: EventEmitter<MouseEvent>;
-    /** Emits event when item is deselected */
+    /**
+     * Emits event when item is deselected
+     * @event deselected
+     * @type {EventEmitter<MouseEvent>}
+     */
     deselected: EventEmitter<MouseEvent>;
     hostEl: HTMLElement;
+    /**
+     * Watch for changes to isSelected and update isActive state
+     * @private
+     */
     updateItemState(): void;
+    /**
+     * Handle click event on menu item
+     * @private
+     * @param {MouseEvent} evt - The mouse event
+     */
     private handleClick;
+    /**
+     * Handle selection/deselection of menu item
+     * @private
+     * @param {MouseEvent} evt - The mouse event
+     */
     private handleSelected;
+    /**
+     * Generate checkmark icon button
+     * @private
+     * @returns {HTMLElement} The checkmark icon button element
+     */
     private generateCheckmarkIconButton;
+    /**
+     * Generate informative icon
+     * @private
+     * @returns {HTMLElement} The informative icon element
+     */
     private generateInformativeIcon;
+    /**
+     * Generate checkbox element
+     * @private
+     * @returns {HTMLElement} The checkbox element
+     */
     private generateCheckbox;
+    /**
+     * Generate label element
+     * @private
+     * @returns {HTMLElement} The label element
+     */
     private generateLabel;
+    /**
+     * Generate children icon button to indicate submenu
+     * @private
+     * @returns {HTMLElement} The children icon button element
+     */
     private generateChildrenIconButton;
+    /**
+     * Get aria-label text, using setAriaLabel prop or falling back to value
+     * @private
+     * @returns {string} The aria-label text
+     */
     private setAriaLabelText;
+    /**
+     * Render the menu item component
+     * @returns {HTMLStencilElement} The rendered menu item element
+     */
     render(): HTMLStencilElement;
 }

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

@@ -1,3 +1,63 @@
+/**
+ * @component vds-menu-list
+ * @description A container component for organizing and displaying a list of menu items. Provides consistent spacing and styling for menu item collections within menus or navigation interfaces.
+ *
+ * @example
+ * <!-- Basic menu list with items -->
+ * <vds-menu-list>
+ *   <vds-menu-item value="Profile"></vds-menu-item>
+ *   <vds-menu-item value="Settings"></vds-menu-item>
+ *   <vds-menu-item value="Logout"></vds-menu-item>
+ * </vds-menu-list>
+ *
+ * @example
+ * <!-- Menu list with icons -->
+ * <vds-menu-list>
+ *   <vds-menu-item icon="user" value="Account"></vds-menu-item>
+ *   <vds-menu-item icon="module-settings" value="Preferences"></vds-menu-item>
+ *   <vds-menu-item icon="information" value="Help Center"></vds-menu-item>
+ * </vds-menu-list>
+ *
+ * @example
+ * <!-- Menu list with grouped sections -->
+ * <vds-menu-list>
+ *   <vds-menu-group-header value="Account"></vds-menu-group-header>
+ *   <vds-menu-item icon="user" value="Profile"></vds-menu-item>
+ *   <vds-menu-item icon="module-settings" value="Settings"></vds-menu-item>
+ *   <vds-menu-group-header value="Actions"></vds-menu-group-header>
+ *   <vds-menu-item icon="logout" value="Sign Out" danger="true"></vds-menu-item>
+ * </vds-menu-list>
+ *
+ * @example
+ * <!-- Menu list with selectable items -->
+ * <vds-menu-list>
+ *   <vds-menu-item value="Option A" has-checkmark="true" is-selected="true"></vds-menu-item>
+ *   <vds-menu-item value="Option B" has-checkmark="true"></vds-menu-item>
+ *   <vds-menu-item value="Option C" has-checkmark="true"></vds-menu-item>
+ * </vds-menu-list>
+ *
+ * @example
+ * <!-- Menu list with links -->
+ * <vds-menu-list>
+ *   <vds-menu-item value="Home" link-href="/home"></vds-menu-item>
+ *   <vds-menu-item value="About" link-href="/about"></vds-menu-item>
+ *   <vds-menu-item value="Contact" link-href="/contact"></vds-menu-item>
+ * </vds-menu-list>
+ *
+ * @example
+ * <!-- Menu list with nested submenus -->
+ * <vds-menu-list>
+ *   <vds-menu-item value="File" has-children="true"></vds-menu-item>
+ *   <vds-menu-item value="Edit" has-children="true"></vds-menu-item>
+ *   <vds-menu-item value="View" has-children="true"></vds-menu-item>
+ * </vds-menu-list>
+ *
+ * @slot - Default slot for menu items, group headers, or other menu content
+ */
 export declare class VdsMenuList {
+    /**
+     * Render the menu list component
+     * @returns {HTMLElement} The rendered menu list container
+     */
     render(): any;
 }

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

@@ -2,32 +2,195 @@ import { EventEmitter } from '../../stencil-public-runtime';
 import { HTMLStencilElement } from '../../stencil-public-runtime';
 import { Colors } from '../../definitions/colors';
 import { NotificationsCustomColors, NotificationStatus } from './vds-notification-utils';
-export declare class VdsNotification {
-    /** Define variant of the notification */
+/**
+ * @component vds-notification
+ * @description A notification component for displaying informational messages, alerts, warnings, and status updates. Supports both inline and toast variants with customizable icons, colors, and actions.
+ *
+ * @example
+ * <!-- Basic informative notification -->
+ * <vds-notification variant="inline" status="informative">
+ *   <span slot="header">Information</span>
+ *   <span slot="body">This is an informative message.</span>
+ * </vds-notification>
+ *
+ * @example
+ * <!-- Toast notification -->
+ * <vds-notification variant="toast" status="healthy">
+ *   <span slot="header">Success!</span>
+ *   <span slot="body">Your changes have been saved successfully.</span>
+ * </vds-notification>
+ *
+ * @example
+ * <!-- Warning notification -->
+ * <vds-notification variant="inline" status="warning">
+ *   <span slot="header">Warning</span>
+ *   <span slot="body">Please review the following issues before proceeding.</span>
+ * </vds-notification>
+ *
+ * @example
+ * <!-- Danger notification -->
+ * <vds-notification variant="inline" status="danger">
+ *   <span slot="header">Error</span>
+ *   <span slot="body">An error occurred while processing your request.</span>
+ * </vds-notification>
+ *
+ * @example
+ * <!-- Notification with actions -->
+ * <vds-notification variant="inline" status="informative">
+ *   <span slot="header">Update Available</span>
+ *   <span slot="body">A new version is available.</span>
+ *   <div slot="actions">
+ *     <vds-button variant="primary" size="small">Update Now</vds-button>
+ *     <vds-button variant="secondary" size="small">Later</vds-button>
+ *   </div>
+ * </vds-notification>
+ *
+ * @example
+ * <!-- Toast notification with actions -->
+ * <vds-notification variant="toast" status="healthy">
+ *   <span slot="header">File Uploaded</span>
+ *   <span slot="body">Your document has been uploaded successfully.</span>
+ *   <div slot="actions">
+ *     <vds-button variant="text" size="small">View</vds-button>
+ *   </div>
+ * </vds-notification>
+ *
+ * @example
+ * <!-- Custom notification with custom colors and icon -->
+ * <vds-notification
+ *   variant="inline"
+ *   status="custom"
+ *   icon="star"
+ *   colors='{ "background": "color-background-brand", "border": "color-border-brand", "icon": "color-icon-brand" }'>
+ *   <span slot="header">Custom Notification</span>
+ *   <span slot="body">This notification uses custom colors and icon.</span>
+ * </vds-notification>
+ *
+ * @example
+ * <!-- Notification without close button -->
+ * <vds-notification
+ *   variant="inline"
+ *   status="informative"
+ *   show-close-button="false">
+ *   <span slot="header">Persistent Message</span>
+ *   <span slot="body">This notification cannot be closed by the user.</span>
+ * </vds-notification>
+ *
+ * @example
+ * <!-- Notification that hides on close (doesn't remove from DOM) -->
+ * <vds-notification
+ *   variant="inline"
+ *   status="informative"
+ *   remove-on-close="false">
+ *   <span slot="header">Dismissible</span>
+ *   <span slot="body">This notification will hide but remain in the DOM when closed.</span>
+ * </vds-notification>
+ *
+ * @slot header - Content for the notification header/title
+ * @slot body - Content for the notification message body
+ * @slot actions - Action buttons or links to display in the notification
+ */ export declare class VdsNotification {
+    /**
+     * Define variant of the notification
+     * @type {"toast" | "inline"}
+     * @default "inline"
+     */
     variant: "toast" | "inline";
-    /** Define status type of the notification */
+    /**
+     * Define status type of the notification
+     * @type {NotificationStatus}
+     * @default "informative"
+     */
     status: NotificationStatus;
-    /** Define custom status color of notification */
+    /**
+     * Define custom status color of notification
+     * @type {NotificationsCustomColors}
+     */
     colors?: NotificationsCustomColors;
-    /** Define custom Icon for the notification */
+    /**
+     * Define custom Icon for the notification
+     * @type {string}
+     */
     icon?: string;
-    /** Show / Hide the notification close button */
+    /**
+     * Show / Hide the notification close button
+     * @type {boolean}
+     * @default true
+     */
     showCloseButton: boolean;
-    /** When set to true, the element will be removed from DOM when pressing the close button. */
+    /**
+     * When set to true, the element will be removed from DOM when pressing the close button.
+     * @type {boolean}
+     * @default true
+     */
     removeOnClose: boolean;
     currentIcon: string;
     currentColor: Colors;
     hostEl: HTMLElement;
-    /** Emits event when popover gets closed */
-    closed: EventEmitter<void>;
+    /**
+     * Emits event when notification gets closed
+     * @event closed
+     * @type {EventEmitter<void>}
+     */
+    closed: EventEmitter<void>; /**
+     * Set custom background color style
+     * @private
+     * @param {NotificationsCustomColors} customization - Custom color configuration
+     * @returns {{ [key: string]: string }} Style object with background color
+     */
     private setCustomBackground;
+    /**
+     * Set custom border color style
+     * @private
+     * @param {NotificationsCustomColors} customization - Custom color configuration
+     * @returns {{ [key: string]: string }} Style object with border color
+     */
     private setCustomBorder;
+    /**
+     * Set custom icon color style
+     * @private
+     * @param {NotificationsCustomColors} customization - Custom color configuration
+     * @returns {{ [key: string]: string }} Style object with icon color
+     */
     private setCustomIcon;
+    /**
+     * Combine all custom color styles
+     * @private
+     * @returns {{ [key: string]: string }} Combined style object with all custom colors
+     */
     private setCustomColors;
+    /**
+     * Set icon and color based on notification status
+     * @private
+     */
     private setIcon;
+    /**
+     * Handle close action - emit event and optionally remove from DOM
+     * @private
+     */
     private handleClose;
+    /**
+     * Close the notification from other element
+     * @method
+     * @public
+     * @returns {Promise<void>}
+     */
     close(): Promise<void>;
+    /**
+     * Render close button if showCloseButton is true
+     * @private
+     * @returns {HTMLElement | null} Close button element or null
+     */
     private showCloseBtn;
+    /**
+     * Render actions slot area
+     * @private
+     * @returns {HTMLStencilElement} Actions container element
+     */
     private renderActions;
+    /**
+     * Render the notification component
+     * @returns {HTMLStencilElement} The rendered notification element
+     */
     render(): HTMLStencilElement;
 }