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

package/dist/types/components/sidenav-item-button/vds-sidenav-item-button.d.ts

@@ -1,24 +1,153 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @component vds-sidenav-item-button
+ * @description A button component designed for side navigation bars. Supports expanded/collapsed states, primary/secondary variants, icons, and static mode. Ideal for action buttons within side navigation menus like "Create New", "Settings", or "Add Item".
+ *
+ * @example
+ * <!-- Basic primary button (collapsed) -->
+ * <vds-sidenav-item-button
+ *   icon="add"
+ *   value="Create">
+ * </vds-sidenav-item-button>
+ *
+ * @example
+ * <!-- Expanded primary button -->
+ * <vds-sidenav-item-button
+ *   icon="add"
+ *   value="Create New"
+ *   expanded="true"
+ *   variant="primary">
+ * </vds-sidenav-item-button>
+ *
+ * @example
+ * <!-- Secondary variant button -->
+ * <vds-sidenav-item-button
+ *   icon="module-settings"
+ *   value="Settings"
+ *   expanded="true"
+ *   variant="secondary">
+ * </vds-sidenav-item-button>
+ *
+ * @example
+ * <!-- Static mode button (always visible, no collapse) -->
+ * <vds-sidenav-item-button
+ *   icon="information"
+ *   value="Help & Support"
+ *   is-static="true">
+ * </vds-sidenav-item-button>
+ *
+ * @example
+ * <!-- Disabled button -->
+ * <vds-sidenav-item-button
+ *   icon="upload"
+ *   value="Upload"
+ *   expanded="true"
+ *   disabled="true">
+ * </vds-sidenav-item-button>
+ *
+ * @example
+ * <!-- Button with aria label -->
+ * <vds-sidenav-item-button
+ *   icon="add"
+ *   value="New"
+ *   expanded="true"
+ *   set-aria-label="Create new project">
+ * </vds-sidenav-item-button>
+ *
+ * @example
+ * <!-- Icon-only collapsed buttons -->
+ * <div style="display: flex; flex-direction: column; gap: 8px;">
+ *   <vds-sidenav-item-button icon="add" value="Create" variant="primary"></vds-sidenav-item-button>
+ *   <vds-sidenav-item-button icon="filter" value="Filter" variant="secondary"></vds-sidenav-item-button>
+ * </div>
+ *
+ * @example
+ * <!-- Button with custom slot content -->
+ * <vds-sidenav-item-button icon="star" expanded="true">
+ *   <strong>Premium Feature</strong>
+ * </vds-sidenav-item-button>
+ *
+ * @example
+ * <!-- Static button at bottom of sidenav -->
+ * <div style="position: fixed; bottom: 20px; width: 240px;">
+ *   <vds-sidenav-item-button
+ *     icon="logout"
+ *     value="Sign Out"
+ *     is-static="true"
+ *     variant="secondary">
+ *   </vds-sidenav-item-button>
+ * </div>
+ *
+ * @slot - Default slot for custom button text content (used when value prop is not provided)
+ */
 export declare class VdsSidenavItemButton {
-    /** Puts the navItem in disabled state */
+    /**
+     * Puts the navItem in disabled state
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** When true expands the nav item to show both text and icon. When false, only shows the icon */
+    /**
+     * When true expands the nav item to show both text and icon. When false, only shows the icon
+     * @type {boolean}
+     * @default false
+     */
     expanded: boolean;
-    /** Define the icon value */
+    /**
+     * Define the icon value
+     * @type {string}
+     */
     icon: string;
-    /** Toggles static mode in nav-item */
+    /**
+     * Toggles static mode in nav-item
+     * @type {boolean}
+     * @default false
+     */
     isStatic: boolean;
-    /** Define text value */
+    /**
+     * Define text value
+     * @type {string}
+     */
     value: string;
-    /** Define aria label value */
+    /**
+     * Define aria label value
+     * @type {string}
+     */
     setAriaLabel: string;
-    /** Define variant */
+    /**
+     * Define variant
+     * @type {"primary" | "secondary"}
+     * @default "primary"
+     */
     variant: "primary" | "secondary";
-    /** Emits event when item gets clicked */
+    /**
+     * Emits event when item gets clicked
+     * @event clicked
+     * @type {EventEmitter<MouseEvent>}
+     */
     clicked: EventEmitter<MouseEvent>;
+    /**
+     * Handle click event on sidenav button
+     * @private
+     * @param {MouseEvent} evt - The mouse event
+     */
     private handleClick;
+    /**
+     * Generate informative icon with appropriate color based on variant and disabled state
+     * @private
+     * @returns {HTMLStencilElement} Icon element
+     */
     private generateInformativeIcon;
+    /**
+     * Generate label element with appropriate styling based on state
+     * @private
+     * @returns {HTMLStencilElement} Label element
+     */
     private generateLabel;
+    /**
+     * Render the sidenav item button component
+     * @returns {HTMLStencilElement} The rendered sidenav item button element
+     */
     render(): HTMLStencilElement;
 }

package/dist/types/components/sidenav-item-category/vds-sidenav-item-category.d.ts

@@ -1,24 +1,168 @@
 import { HTMLStencilElement } from '../../stencil-public-runtime';
 import { GroupHeaderSize } from '../base-group-header/base-group-header';
+/**
+ * @component vds-sidenav-item-category
+ * @description A category/section container component for organizing side navigation items into logical groups. Supports expanded/collapsed states with headers, dividers, and optional action slots. Automatically propagates state to child navigation items.
+ *
+ * @example
+ * <!-- Basic collapsed category -->
+ * <vds-sidenav-item-category>
+ *   <vds-sidenav-item slot="category-items" icon="home" value="Home"></vds-sidenav-item>
+ *   <vds-sidenav-item slot="category-items" icon="user" value="Profile"></vds-sidenav-item>
+ * </vds-sidenav-item-category>
+ *
+ * @example
+ * <!-- Expanded category with header -->
+ * <vds-sidenav-item-category value="Main Navigation" expanded="true">
+ *   <vds-sidenav-item slot="category-items" icon="dashboard" value="Dashboard"></vds-sidenav-item>
+ *   <vds-sidenav-item slot="category-items" icon="analytics" value="Analytics"></vds-sidenav-item>
+ *   <vds-sidenav-item slot="category-items" icon="document" value="Reports"></vds-sidenav-item>
+ * </vds-sidenav-item-category>
+ *
+ * @example
+ * <!-- Static category (always visible header) -->
+ * <vds-sidenav-item-category value="Settings" is-static="true">
+ *   <vds-sidenav-item slot="category-items" icon="module-settings" value="Preferences"></vds-sidenav-item>
+ *   <vds-sidenav-item slot="category-items" icon="lock-closed" value="Security"></vds-sidenav-item>
+ * </vds-sidenav-item-category>
+ *
+ * @example
+ * <!-- Category with action slot -->
+ * <vds-sidenav-item-category value="Projects" expanded="true">
+ *   <vds-icon-button slot="action-slot" icon="add" variant="secondary" size="small"></vds-icon-button>
+ *   <vds-sidenav-item slot="category-items" icon="folder-closed" value="Project A"></vds-sidenav-item>
+ *   <vds-sidenav-item slot="category-items" icon="folder-closed" value="Project B"></vds-sidenav-item>
+ * </vds-sidenav-item-category>
+ *
+ * @example
+ * <!-- Large size category header -->
+ * <vds-sidenav-item-category value="Resources" expanded="true" size="large">
+ *   <vds-sidenav-item slot="category-items" icon="document" value="Documents"></vds-sidenav-item>
+ *   <vds-sidenav-item slot="category-items" icon="image" value="Images"></vds-sidenav-item>
+ *   <vds-sidenav-item slot="category-items" icon="camera-video" value="Videos"></vds-sidenav-item>
+ * </vds-sidenav-item-category>
+ *
+ * @example
+ * <!-- Small size category header -->
+ * <vds-sidenav-item-category value="Quick Links" expanded="true" size="small">
+ *   <vds-sidenav-item slot="category-items" icon="link-open" value="Documentation"></vds-sidenav-item>
+ *   <vds-sidenav-item slot="category-items" icon="information" value="Support"></vds-sidenav-item>
+ * </vds-sidenav-item-category>
+ *
+ * @example
+ * <!-- Multiple categories in sidebar -->
+ * <vds-sidenav style="width: 240px;">
+ *   <vds-sidenav-item-category value="Main" expanded="true">
+ *     <vds-sidenav-item slot="category-items" icon="home" value="Home" is-active="true"></vds-sidenav-item>
+ *     <vds-sidenav-item slot="category-items" icon="dashboard" value="Dashboard"></vds-sidenav-item>
+ *   </vds-sidenav-item-category>
+ *
+ *   <vds-sidenav-item-category value="Management" expanded="true">
+ *     <vds-sidenav-item slot="category-items" icon="user-group" value="Users"></vds-sidenav-item>
+ *     <vds-sidenav-item slot="category-items" icon="module-settings" value="Settings"></vds-sidenav-item>
+ *   </vds-sidenav-item-category>
+ * </vds-sidenav>
+ *
+ * @example
+ * <!-- Category with app items -->
+ * <vds-sidenav-item-category value="Workspaces" expanded="true">
+ *   <vds-icon-button slot="action-slot" icon="add" variant="secondary" size="small"></vds-icon-button>
+ *   <vds-sidenav-item-app slot="category-items" value="Main Workspace">
+ *     <vds-avatar slot="img" name="Main" size="small"></vds-avatar>
+ *   </vds-sidenav-item-app>
+ *   <vds-sidenav-item-app slot="category-items" value="Personal">
+ *     <vds-avatar slot="img" name="Personal" size="small"></vds-avatar>
+ *   </vds-sidenav-item-app>
+ * </vds-sidenav-item-category>
+ *
+ * @example
+ * <!-- Collapsed categories with dividers -->
+ * <vds-sidenav style="width: 60px;">
+ *   <vds-sidenav-item-category>
+ *     <vds-sidenav-item slot="category-items" icon="home" value="Home"></vds-sidenav-item>
+ *   </vds-sidenav-item-category>
+ *
+ *   <vds-sidenav-item-category>
+ *     <vds-sidenav-item slot="category-items" icon="module-settings" value="Settings"></vds-sidenav-item>
+ *   </vds-sidenav-item-category>
+ * </vds-sidenav>
+ *
+ * @example
+ * <!-- Hierarchical navigation structure -->
+ * <vds-sidenav-item-category value="Admin" expanded="true">
+ *   <vds-sidenav-item slot="category-items" icon="user-group" value="User Management" has-children="true"></vds-sidenav-item>
+ *   <vds-sidenav-item slot="category-items" icon="key" value="Roles & Permissions" has-children="true"></vds-sidenav-item>
+ *   <vds-sidenav-item slot="category-items" icon="history" value="Audit Logs"></vds-sidenav-item>
+ * </vds-sidenav-item-category>
+ *
+ * @slot action-slot - Slot for action buttons or icons on the right side of the category header (only visible when expanded and not static)
+ * @slot category-items - Slot for navigation items (vds-sidenav-item, vds-sidenav-item-app) that belong to this category
+ */
 export declare class VdsSidenavItemCategory {
     hostEl: HTMLElement;
     /**
      * Define text value. This component has the possibility of adding an element to the right of this value
      * using the slot called "action-slot". The display condition is when a value is defined in the value property,
      * the expanded property is equal to true, and the isStatic property is equal to false.
+     * @type {string}
      */
     value: string;
-    /** When true expands the nav item to show both text and icon. When false, only shows the icon */
+    /**
+     * When true expands the nav item to show both text and icon. When false, only shows the icon
+     * @type {boolean}
+     * @default false
+     */
     expanded: boolean;
-    /** Toggles static mode in nav-item */
+    /**
+     * Toggles static mode in nav-item
+     * @type {boolean}
+     * @default false
+     */
     isStatic: boolean;
-    /** Size of the group header when expanded */
+    /**
+     * Size of the group header when expanded
+     * @type {GroupHeaderSize}
+     * @default 'medium'
+     */
     size: GroupHeaderSize;
+    /**
+     * Get collapsed view with divider
+     * @private
+     * @returns {HTMLStencilElement} Collapsed divider element
+     */
     private getCollapsedView;
+    /**
+     * Get static view with divider
+     * @private
+     * @returns {HTMLStencilElement} Static divider element
+     */
     private getStaticView;
+    /**
+     * Get expanded view with group header
+     * @private
+     * @returns {HTMLStencilElement} Expanded group header element
+     */
     private getExpandedView;
+    /**
+     * Set the appropriate view based on expanded and isStatic props
+     * @private
+     * @returns {HTMLStencilElement} The appropriate view element
+     */
     private setView;
+    /**
+     * Set the action slot container if conditions are met
+     * @private
+     * @returns {HTMLStencilElement | undefined} Action slot element or undefined
+     */
     private setSlot;
+    /**
+     * Component lifecycle hook - propagate expanded and isStatic state to child sidenav items
+     * @private
+     */
     componentDidRender(): void;
+    /**
+     * Render the sidenav item category component
+     * @returns {HTMLStencilElement} The rendered sidenav category element
+     */
     render(): HTMLStencilElement;
 }

package/dist/types/components/sidenav-item-input/vds-sidenav-item-input.d.ts

@@ -1,92 +1,259 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @component vds-sidenav-item-input
+ * @description A search/filter input component designed for side navigation bars. Supports expanded/collapsed states, icons, form association, and dynamic action icons. Ideal for filtering navigation items or searching within sidebar content.
+ *
+ * @example
+ * <!-- Basic expanded search input -->
+ * <vds-sidenav-item-input
+ *   placeholder="Search..."
+ *   expanded="true">
+ * </vds-sidenav-item-input>
+ *
+ * @example
+ * <!-- Collapsed search icon -->
+ * <vds-sidenav-item-input
+ *   expanded="false"
+ *   action-icon="zoom">
+ * </vds-sidenav-item-input>
+ *
+ * @example
+ * <!-- Input with value -->
+ * <vds-sidenav-item-input
+ *   value="Project"
+ *   placeholder="Search projects"
+ *   expanded="true">
+ * </vds-sidenav-item-input>
+ *
+ * @example
+ * <!-- Input with custom action icon -->
+ * <vds-sidenav-item-input
+ *   placeholder="Filter items"
+ *   action-icon="filter"
+ *   expanded="true">
+ * </vds-sidenav-item-input>
+ *
+ * @example
+ * <!-- Input with informative icon -->
+ * <vds-sidenav-item-input
+ *   placeholder="Search"
+ *   informative-icon="magnify"
+ *   expanded="true">
+ * </vds-sidenav-item-input>
+ *
+ * @example
+ * <!-- Disabled input -->
+ * <vds-sidenav-item-input
+ *   placeholder="Search disabled"
+ *   disabled="true"
+ *   expanded="true">
+ * </vds-sidenav-item-input>
+ *
+ * @example
+ * <!-- Readonly input -->
+ * <vds-sidenav-item-input
+ *   value="Read only value"
+ *   is-readonly="true"
+ *   expanded="true">
+ * </vds-sidenav-item-input>
+ *
+ * @example
+ * <!-- Input in error state -->
+ * <vds-sidenav-item-input
+ *   value="Invalid"
+ *   error="true"
+ *   expanded="true">
+ * </vds-sidenav-item-input>
+ *
+ * @example
+ * <!-- Input with event handling -->
+ * <vds-sidenav-item-input
+ *   id="search-input"
+ *   placeholder="Search navigation"
+ *   expanded="true">
+ * </vds-sidenav-item-input>
+ * <script>
+ *   const input = document.getElementById('search-input');
+ *   input.addEventListener('changeInput', (e) => console.log('Search:', e.detail));
+ *   input.addEventListener('iconClick', () => console.log('Icon clicked'));
+ * </script>
+ *
+ * @example
+ * <!-- Complete sidebar with search -->
+ * <vds-sidenav style="width: 240px;">
+ *   <vds-sidenav-item-input
+ *     placeholder="Search menu..."
+ *     expanded="true">
+ *   </vds-sidenav-item-input>
+ *
+ *   <vds-sidenav-item-category value="Navigation" expanded="true">
+ *     <vds-sidenav-item slot="category-items" icon="home" value="Home"></vds-sidenav-item>
+ *     <vds-sidenav-item slot="category-items" icon="dashboard" value="Dashboard"></vds-sidenav-item>
+ *   </vds-sidenav-item-category>
+ * </vds-sidenav>
+ */
 export declare class VdsSidenavItemInput {
-    /** When true expands the nav item to show both text and icon. When false, only shows the icon */
+    /**
+     * When true expands the nav item to show both text and icon. When false, only shows the icon
+     * @type {boolean}
+     * @default true
+     */
     expanded: boolean;
-    /** Sets the input's value. */
+    /**
+     * Sets the input's value.
+     * @type {string}
+     * @default ""
+     */
     value: string;
-    /** Sets the input's placeholder. */
+    /**
+     * Sets the input's placeholder.
+     * @type {string}
+     */
     placeholder: string;
-    /** Sets the input in disabled state. */
+    /**
+     * Sets the input in disabled state.
+     * @type {boolean}
+     */
     disabled: boolean;
-    /** Sets the input in readonly state. */
+    /**
+     * Sets the input in readonly state.
+     * @type {boolean}
+     */
     isReadonly: boolean;
-    /** Sets the input in error state. */
+    /**
+     * Sets the input in error state.
+     * @type {boolean}
+     */
     error: boolean;
-    /** Allows user to define a information icon inside the input at its left . */
+    /**
+     * Allows user to define an information icon inside the input at its left.
+     * @type {string}
+     */
     informativeIcon: string;
-    /** Allows user to define a search icon inside the input at its right (zoom by default) . */
+    /**
+     * Allows user to define a search icon inside the input at its right (zoom by default).
+     * @type {string}
+     * @default "zoom"
+     */
     actionIcon: string;
-    /** Sets character formatting for user input. Useful for adding a mask to the input. */
+    /**
+     * Sets character formatting for user input. Useful for adding a mask to the input.
+     * @type {Function}
+     */
     formatter?: Function;
-    /** Emits an event when the user change the value */
+    /**
+     * Emits an event when the user changes the value
+     * @event changeInput
+     * @type {EventEmitter<string>}
+     */
     changeInput: EventEmitter<string>;
-    /** Emits an event when the user clicks on input's icon */
+    /**
+     * Emits an event when the user clicks on input's icon
+     * @event iconClick
+     * @type {EventEmitter<MouseEvent>}
+     */
     iconClick: EventEmitter<MouseEvent>;
-    /** Emits an event when the user clicks on icon when expanded is false */
+    /**
+     * Emits an event when the user clicks on icon when expanded is false
+     * @event collapseIconClick
+     * @type {EventEmitter<MouseEvent>}
+     */
     collapseIconClick: EventEmitter<MouseEvent>;
     hostEl: HTMLElement;
     internals: ElementInternals;
     inputIcon: string;
+    /**
+     * Reference to the input element
+     * @private
+     */
     private inputEl;
+    /**
+     * Cleanup function for attribute synchronization
+     * @private
+     */
+    private cleanupAttributeSync;
+    /**
+     * Component lifecycle hook - setup form value and attribute sync
+     * @private
+     */
     componentDidLoad(): void;
+    /**
+     * Component lifecycle hook - cleanup attribute sync
+     * @private
+     */
+    disconnectedCallback(): void;
+    /**
+     * Watch value changes and update form value
+     * @private
+     */
     setFormValue(): void;
+    /**
+     * Get safe value (empty string if undefined/null)
+     * @private
+     * @returns {string} Safe value
+     */
+    private getSafeValue;
     /**
        * Sets focus on the vds-input element.
-       *
-       * @returns Promise<void>
+       * @method
+       * @public
+       * @returns {Promise<void>}
        */
     setFocus(): Promise<void>;
     /**
        * Gets value prop from the vds-input element.
-       *
-       * @returns Promise<string>
+       * @method
+       * @public
+       * @returns {Promise<string>}
        */
     getValue(): Promise<string>;
     /**
        * Clears value prop from the vds-input element.
-       *
-       * @returns Promise<void>
+       * @method
+       * @public
+       * @returns {Promise<void>}
        */
     clear(): Promise<void>;
     /**
-       * Handles change input event from vds-basic-input
+       * Handles change input event from vds-basic-input.
      * Emits changeInput event.
-     * Sets icon to close when value is not blank otherwise zoom.
-       *
-     * @params evt - VdsBasicInputCustomEvent
-       * @returns void
+     * Sets icon to close when value is not blank otherwise to action icon.
+       * @private
+     * @param {VdsBasicInputCustomEvent<string>} evt - Input change event
        */
     private handleChangeInput;
     /**
        * Handles click event from vds-icon-button inside the input.
      * Emits iconClick event.
-     * When inputIcon equals close, vds-basic-input gets clear.
-     * When inputIcon equals zoom, vds-basic-input gets focus.
-       *
-     * @params evt - MouseEvent
-       * @returns void
+     * When inputIcon equals close, vds-basic-input gets cleared.
+     * When inputIcon equals action icon, vds-basic-input gets focus.
+       * @private
+     * @param {MouseEvent} evt - Click event
        */
     private handleIconClick;
     /**
-       * Handles click event from vds-icon-button when expanded is false
+       * Handles click event from vds-icon-button when expanded is false.
      * Emits collapseIconClick event.
-       *
-     * @params evt - MouseEvent
-       * @returns void
+       * @private
+     * @param {MouseEvent} evt - Click event
        */
     private handleCollapseIconClick;
     /**
-       * Renders input when expanded is to set true.
-       *
-       * @returns HTMLStencilElement
+       * Renders input when expanded is set to true.
+       * @private
+       * @returns {HTMLStencilElement} Input element
        */
     private renderInput;
     /**
-       * Renders sidenav-item icon when expanded is to set false.
-       *
-       * @returns HTMLStencilElement
+       * Renders sidenav-item icon when expanded is set to false.
+       * @private
+       * @returns {HTMLStencilElement} Icon element
        */
     private renderIcon;
+    /**
+     * Render the sidenav item input component
+     * @returns {HTMLStencilElement} The rendered sidenav item input element
+     */
     render(): HTMLStencilElement;
 }