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

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

@@ -1,48 +1,221 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @component vds-sheet
+ * @description A bottom sheet component that slides up from the bottom of the viewport to display content. Supports backdrop, drag-to-close interactions, custom heights, and keyboard accessibility. Ideal for mobile-first interfaces, forms, menus, and contextual information.
+ *
+ * @example
+ * <!-- Basic bottom sheet -->
+ * <vds-sheet id="mySheet">
+ *   <h2>Bottom Sheet Content</h2>
+ *   <p>This is a simple bottom sheet.</p>
+ * </vds-sheet>
+ *
+ * @example
+ * <!-- Bottom sheet with backdrop -->
+ * <vds-sheet backdrop="true" opened="true">
+ *   <h3>Sheet with Backdrop</h3>
+ *   <p>Click outside to close this sheet.</p>
+ * </vds-sheet>
+ *
+ * @example
+ * <!-- Bottom sheet with custom height (50% of viewport) -->
+ * <vds-sheet height="50%" backdrop="true">
+ *   <h3>Half Screen Sheet</h3>
+ *   <p>This sheet takes up 50% of the viewport height.</p>
+ * </vds-sheet>
+ *
+ * @example
+ * <!-- Bottom sheet with fixed pixel height -->
+ * <vds-sheet height="400px" backdrop="true">
+ *   <h3>Fixed Height Sheet</h3>
+ *   <p>This sheet has a fixed height of 400px.</p>
+ * </vds-sheet>
+ *
+ * @example
+ * <!-- Bottom sheet without drag handle -->
+ * <vds-sheet hide-drag-handle="true" backdrop="true">
+ *   <h3>No Drag Handle</h3>
+ *   <p>This sheet cannot be dragged to close.</p>
+ * </vds-sheet>
+ *
+ * @example
+ * <!-- Bottom sheet with form -->
+ * <vds-sheet height="60%" backdrop="true">
+ *   <h3>Contact Form</h3>
+ *   <form>
+ *     <vds-input label="Name" placeholder="Enter your name"></vds-input>
+ *     <vds-input label="Email" placeholder="Enter your email"></vds-input>
+ *     <vds-textarea label="Message" placeholder="Your message"></vds-textarea>
+ *     <vds-button variant="primary">Submit</vds-button>
+ *   </form>
+ * </vds-sheet>
+ *
+ * @example
+ * <!-- Bottom sheet for menu options -->
+ * <vds-sheet height="auto" backdrop="true">
+ *   <vds-menu-list>
+ *     <vds-menu-item icon="share" value="Share"></vds-menu-item>
+ *     <vds-menu-item icon="edit" value="Edit"></vds-menu-item>
+ *     <vds-menu-item icon="trash" value="Delete" danger="true"></vds-menu-item>
+ *   </vds-menu-list>
+ * </vds-sheet>
+ *
+ * @example
+ * <!-- Bottom sheet with programmatic control -->
+ * <vds-button onclick="document.getElementById('controlledSheet').open()">Open Sheet</vds-button>
+ * <vds-sheet id="controlledSheet" backdrop="true">
+ *   <h3>Controlled Sheet</h3>
+ *   <p>Opened programmatically via JavaScript.</p>
+ *   <vds-button onclick="document.getElementById('controlledSheet').close()">Close</vds-button>
+ * </vds-sheet>
+ *
+ * @example
+ * <!-- Full height bottom sheet -->
+ * <vds-sheet height="100%" backdrop="true">
+ *   <div style="padding: 20px;">
+ *     <h2>Full Screen Sheet</h2>
+ *     <p>This sheet covers the entire viewport.</p>
+ *   </div>
+ * </vds-sheet>
+ *
+ * @example
+ * <!-- Bottom sheet with auto height (content-based) -->
+ * <vds-sheet height="auto" backdrop="true" opened="true">
+ *   <div style="padding: 20px;">
+ *     <h3>Auto Height</h3>
+ *     <p>This sheet adjusts to its content height.</p>
+ *     <vds-button variant="secondary">Action</vds-button>
+ *   </div>
+ * </vds-sheet>
+ *
+ * @slot - Default slot for the bottom sheet content
+ */
 export declare class VdsSheet {
-    /** Create a backdrop that allow's to close the bottom sheet by clicking outside. */
+    /**
+     * Create a backdrop that allows closing the bottom sheet by clicking outside.
+     * @type {boolean}
+     * @default false
+     */
     backdrop: boolean;
-    /** Open / Close the bottom sheet. */
+    /**
+     * Open / Close the bottom sheet.
+     * @type {boolean}
+     * @default false
+     */
     opened: boolean;
-    /** Sets the height of the bottom sheet (any CSS height value: auto, 50%, 400px, etc.) */
+    /**
+     * Sets the height of the bottom sheet (any CSS height value: auto, 50%, 400px, etc.)
+     * @type {string}
+     * @default 'auto'
+     */
     height: string;
-    /** Allow drag handle interaction to close the bottom sheet. */
+    /**
+     * Allow drag handle interaction to close the bottom sheet.
+     * @type {boolean}
+     * @default false
+     */
     hideDragHandle: boolean;
-    /** Emits event when bottom-sheet is opened */
+    /**
+     * Emits event when bottom-sheet is opened
+     * @event bottomsheetOpened
+     * @type {EventEmitter<void>}
+     */
     bottomsheetOpened: EventEmitter<void>;
-    /** Emits event when bottom-sheet is closed */
+    /**
+     * Emits event when bottom-sheet is closed
+     * @event bottomsheetClosed
+     * @type {EventEmitter<void>}
+     */
     bottomsheetClosed: EventEmitter<void>;
     el: HTMLElement;
+    /**
+     * Y-coordinate where drag started
+     * @private
+     */
     private dragStartY;
+    /**
+     * Flag indicating if dragging is in progress
+     * @private
+     */
     private isDragging;
+    /**
+     * Pixel threshold to close bottom sheet when dragging
+     * @private
+     */
     private dragThreshold;
+    /**
+     * Watch for opened state changes and emit events
+     * @private
+     */
     emitValue(): void;
-    /** Listen for Escape key to close the bottom sheet */
+    /**
+     * Listen for Escape key to close the bottom sheet
+     * @private
+     * @param {KeyboardEvent} event - The keyboard event
+     */
     handleKeyDown(event: KeyboardEvent): void;
     /**
      * Trigger open the bottomsheet
-     * @returns Promise that resolves when the bottomsheet is opened
+     * @method
+     * @public
+     * @returns {Promise<void>} Promise that resolves when the bottomsheet is opened
      */
     open(): Promise<void>;
     /**
      * Trigger closes the bottomsheet
-     * @returns Promise that resolves when the bottomsheet is closed
+     * @method
+     * @public
+     * @returns {Promise<void>} Promise that resolves when the bottomsheet is closed
      */
     close(): Promise<void>;
     /**
      * Handle drag interactions to close the bottom sheet.
+     * @private
+     * @param {TouchEvent | MouseEvent} event - The touch or mouse event
      */
     private handleDragStart;
+    /**
+     * Handle drag move events during bottom sheet dragging
+     * @private
+     * @param {TouchEvent | MouseEvent} event - The touch or mouse event
+     */
     private handleDragMove;
+    /**
+     * Handle drag end events and close sheet if threshold is met
+     * @private
+     * @param {TouchEvent | MouseEvent} event - The touch or mouse event
+     */
     private handleDragEnd;
+    /**
+     * Get the Y-coordinate from touch or mouse event
+     * @private
+     * @param {TouchEvent | MouseEvent} event - The touch or mouse event
+     * @returns {number} The Y-coordinate
+     */
     private getClientY;
     /**
-     * Get the style for the container based on the height prop
+     * Get the style for the container based on the height prop.
      * If the height is a percentage, it converts it to viewport height.
+     * @private
+     * @returns {{ [key: string]: string }} Style object with height property
      */
     private getContainerStyle;
+    /**
+     * Render backdrop element if enabled
+     * @private
+     * @returns {HTMLStencilElement} Backdrop element
+     */
     private renderBackdrop;
+    /**
+     * Render drag handle element if not hidden
+     * @private
+     * @returns {HTMLStencilElement | null} Drag handle element or null
+     */
     private renderDragHandle;
+    /**
+     * Render the bottom sheet component
+     * @returns {HTMLStencilElement} The rendered bottom sheet element
+     */
     render(): HTMLStencilElement;
 }

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

@@ -1,31 +1,199 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @component vds-sidenav-item
+ * @description A navigation item component for side navigation menus. Supports expanded/collapsed states, icons, links, active states, and nested children. Designed for application navigation and hierarchical menu structures.
+ *
+ * @example
+ * <!-- Basic sidenav item (collapsed) -->
+ * <vds-sidenav-item icon="home" value="Home"></vds-sidenav-item>
+ *
+ * @example
+ * <!-- Expanded sidenav item -->
+ * <vds-sidenav-item
+ *   icon="dashboard"
+ *   value="Dashboard"
+ *   expanded="true">
+ * </vds-sidenav-item>
+ *
+ * @example
+ * <!-- Active sidenav item -->
+ * <vds-sidenav-item
+ *   icon="module-settings"
+ *   value="Settings"
+ *   expanded="true"
+ *   is-active="true">
+ * </vds-sidenav-item>
+ *
+ * @example
+ * <!-- Sidenav item as link -->
+ * <vds-sidenav-item
+ *   icon="information"
+ *   value="Documentation"
+ *   expanded="true"
+ *   link_href="https://example.com/docs"
+ *   link_target="_blank"
+ *   link_rel="noopener noreferrer">
+ * </vds-sidenav-item>
+ *
+ * @example
+ * <!-- Sidenav item with children indicator -->
+ * <vds-sidenav-item
+ *   icon="folder-closed"
+ *   value="Projects"
+ *   expanded="true"
+ *   has-children="true">
+ * </vds-sidenav-item>
+ *
+ * @example
+ * <!-- Static sidenav item (always visible, no collapse) -->
+ * <vds-sidenav-item
+ *   icon="star"
+ *   value="Favorites"
+ *   is-static="true">
+ * </vds-sidenav-item>
+ *
+ * @example
+ * <!-- Disabled sidenav item -->
+ * <vds-sidenav-item
+ *   icon="lock-closed"
+ *   value="Premium Feature"
+ *   expanded="true"
+ *   disabled="true">
+ * </vds-sidenav-item>
+ *
+ * @example
+ * <!-- Sidenav item with right slot (badge, counter) -->
+ * <vds-sidenav-item
+ *   icon="bell"
+ *   value="Notifications"
+ *   expanded="true">
+ *   <vds-badge-pill slot="rightSlot" value="5"></vds-badge-pill>
+ * </vds-sidenav-item>
+ *
+ * @example
+ * <!-- Collapsed navigation with icons only -->
+ * <nav>
+ *   <vds-sidenav-item icon="home" value="Home"></vds-sidenav-item>
+ *   <vds-sidenav-item icon="user" value="Profile"></vds-sidenav-item>
+ *   <vds-sidenav-item icon="module-settings" value="Settings"></vds-sidenav-item>
+ * </nav>
+ *
+ * @example
+ * <!-- Complete side navigation example -->
+ * <nav style="width: 240px;">
+ *   <vds-sidenav-item icon="home" value="Home" expanded="true" is-active="true"></vds-sidenav-item>
+ *   <vds-sidenav-item icon="folder-closed" value="Projects" expanded="true" has-children="true"></vds-sidenav-item>
+ *   <vds-sidenav-item icon="user-group" value="Team" expanded="true"></vds-sidenav-item>
+ *   <vds-sidenav-item icon="module-settings" value="Settings" expanded="true"></vds-sidenav-item>
+ * </nav>
+ *
+ * @slot rightSlot - Slot for additional content on the right side (badges, counters, indicators)
+ */
 export declare class VdsSidenavItem {
-    /** Puts the navItem in disabled state */
+    /**
+     * Set sidenav-item's size
+     * @type {"large" | "medium" }
+     * @default "medium"
+     */
+    size: "large" | "medium";
+    /**
+     * 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;
-    /** Define item as active when is true */
+    /**
+     * Define item as active when is true
+     * @type {boolean}
+     * @default false
+     */
     isActive: boolean;
-    /** Toggles static mode in nav-item */
+    /**
+     * Toggles static mode in nav-item
+     * @type {boolean}
+     * @default false
+     */
     isStatic: 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
+     */
     link_href: string;
-    /** Sets the target value */
+    /**
+     * Sets the target value
+     * @type {'_self' | '_blank' | '_parent' | '_top'}
+     * @default '_self'
+     */
     link_target: '_self' | '_blank' | '_parent' | '_top';
-    /** Sets the link rel value */
+    /**
+     * Sets the link rel value
+     * @type {string}
+     * @default null
+     */
     link_rel: string;
-    /** Define text value */
+    /**
+     * Define text value
+     * @type {string}
+     */
     value: string;
-    /** 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 item
+     * @private
+     * @param {MouseEvent} evt - The mouse event
+     */
     private handleClick;
+    /**
+     * Generate right slot container for badges and additional content
+     * @private
+     * @returns {HTMLStencilElement | null} Right slot element or null
+     */
     private generateRightSlot;
+    /**
+     * Get icon size based on the sidenav item size
+     * @private
+     * @returns {string} Icon size
+     */
+    private get iconSize();
+    /**
+     * Generate children indicator icon (chevron) when item has children
+     * @private
+     * @returns {HTMLStencilElement | null} Children icon element or null
+     */
     private generateChildrenIcon;
+    /**
+     * Generate informative icon for the sidenav item
+     * @private
+     * @returns {HTMLStencilElement | null} Informative icon element or null
+     */
     private generateInformativeIcon;
+    /**
+     * Render the sidenav item component
+     * @returns {HTMLStencilElement} The rendered sidenav item element
+     */
     render(): HTMLStencilElement;
 }

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

@@ -5,6 +5,14 @@ declare const _default: {
             toc: boolean;
         };
     };
+    argTypes: {
+        size: {
+            options: string[];
+            control: {
+                type: string;
+            };
+        };
+    };
 };
 export default _default;
 export declare const ExpandableUsage: any;
@@ -12,4 +20,5 @@ export declare const ExpandableWithChildrenUsage: any;
 export declare const StaticUsage: any;
 export declare const ExpandableAsLinkUsage: any;
 export declare const ExpandableWithRightSlotUsage: any;
+export declare const LargeStaticUsage: any;
 export declare const CustomWidthUsage: any;

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

@@ -1,18 +1,144 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @component vds-sidenav-item-app
+ * @description A specialized side navigation item for displaying application launchers or app switchers. Features an image/icon slot with optional expansion to show app name and menu actions. Ideal for app selector panels or workspace switchers.
+ *
+ * @example
+ * <!-- Basic app item (expanded) -->
+ * <vds-sidenav-item-app value="Workspace">
+ *   <img slot="img" src="workspace-icon.png" alt="Workspace" />
+ * </vds-sidenav-item-app>
+ *
+ * @example
+ * <!-- Collapsed app item (icon only) -->
+ * <vds-sidenav-item-app value="Dashboard" expanded="false">
+ *   <vds-avatar slot="img" name="Dashboard" size="small"></vds-avatar>
+ * </vds-sidenav-item-app>
+ *
+ * @example
+ * <!-- Active app item -->
+ * <vds-sidenav-item-app
+ *   value="My App"
+ *   is-active="true">
+ *   <img slot="img" src="app-icon.png" alt="My App" />
+ * </vds-sidenav-item-app>
+ *
+ * @example
+ * <!-- App item with menu icon -->
+ * <vds-sidenav-item-app
+ *   value="Project Alpha"
+ *   menu-icon="true">
+ *   <img slot="img" src="project-icon.png" alt="Project" />
+ * </vds-sidenav-item-app>
+ *
+ * @example
+ * <!-- App switcher with multiple apps -->
+ * <nav>
+ *   <vds-sidenav-item-app value="Main Workspace" is-active="true" menu-icon="true">
+ *     <vds-avatar slot="img" name="Main" size="small"></vds-avatar>
+ *   </vds-sidenav-item-app>
+ *   <vds-sidenav-item-app value="Personal" menu-icon="true">
+ *     <vds-avatar slot="img" name="Personal" size="small"></vds-avatar>
+ *   </vds-sidenav-item-app>
+ *   <vds-sidenav-item-app value="Team Project" menu-icon="true">
+ *     <vds-avatar slot="img" name="Team" size="small"></vds-avatar>
+ *   </vds-sidenav-item-app>
+ * </nav>
+ *
+ * @example
+ * <!-- App item with custom icon -->
+ * <vds-sidenav-item-app value="Analytics">
+ *   <div slot="img" style="width: 32px; height: 32px; background: #4CAF50; border-radius: 4px;"></div>
+ * </vds-sidenav-item-app>
+ *
+ * @example
+ * <!-- Collapsed navigation (icons only) -->
+ * <nav style="width: 60px;">
+ *   <vds-sidenav-item-app value="App 1" expanded="false">
+ *     <img slot="img" src="app1.png" alt="App 1" />
+ *   </vds-sidenav-item-app>
+ *   <vds-sidenav-item-app value="App 2" expanded="false" is-active="true">
+ *     <img slot="img" src="app2.png" alt="App 2" />
+ *   </vds-sidenav-item-app>
+ * </nav>
+ *
+ * @example
+ * <!-- App item with event handling -->
+ * <vds-sidenav-item-app
+ *   id="workspace-item"
+ *   value="Workspace"
+ *   menu-icon="true">
+ *   <img slot="img" src="workspace.png" alt="Workspace" />
+ * </vds-sidenav-item-app>
+ * <script>
+ *   const item = document.getElementById('workspace-item');
+ *   item.addEventListener('clicked', () => console.log('App clicked'));
+ *   item.addEventListener('viewMoreClick', () => console.log('Menu clicked'));
+ * </script>
+ *
+ * @example
+ * <!-- Organization switcher -->
+ * <vds-sidenav-item-app value="Acme Corp" menu-icon="true" is-active="true">
+ *   <vds-avatar slot="img" name="Acme Corp" size="small" color="color-background-brand-default"></vds-avatar>
+ * </vds-sidenav-item-app>
+ *
+ * @example
+ * <!-- Multi-tenant app selector -->
+ * <div style="display: flex; flex-direction: column; gap: 8px;">
+ *   <vds-sidenav-item-app value="Production" is-active="true">
+ *     <vds-badge-dot slot="img" color="green"></vds-badge-dot>
+ *   </vds-sidenav-item-app>
+ *   <vds-sidenav-item-app value="Staging">
+ *     <vds-badge-dot slot="img" color="yellow"></vds-badge-dot>
+ *   </vds-sidenav-item-app>
+ * </div>
+ *
+ * @slot img - Slot for the app icon, image, avatar, or custom visual identifier
+ */
 export declare class VdsSidenavItemApp {
-    /** Define text value */
+    /**
+     * Define text value (app name)
+     * @type {string}
+     */
     value: string;
-    /** Shows arrow when there are children */
+    /**
+     * Shows menu icon button when true
+     * @type {boolean}
+     */
     menuIcon: 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 true
+     */
     expanded: boolean;
-    /** Puts the navItem in active state */
+    /**
+     * Puts the navItem in active state
+     * @type {boolean}
+     */
     isActive: boolean;
-    /** Emits event when item gets clicked */
+    /**
+     * Emits event when item gets clicked
+     * @event clicked
+     * @type {EventEmitter<MouseEvent>}
+     */
     clicked: EventEmitter<MouseEvent>;
-    /** Emits event when the user clicks on menu icon*/
+    /**
+     * Emits event when the user clicks on menu icon
+     * @event viewMoreClick
+     * @type {EventEmitter<MouseEvent>}
+     */
     viewMoreClick: EventEmitter<MouseEvent>;
+    /**
+     * Get expanded sidenav item app content (text and menu icon)
+     * @private
+     * @returns {HTMLStencilElement} Expanded content element
+     */
     private getExpandedSidenavItemApp;
+    /**
+     * Render the sidenav item app component
+     * @returns {HTMLStencilElement} The rendered sidenav item app element
+     */
     render(): HTMLStencilElement;
 }