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

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

@@ -1,54 +1,295 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * @component vds-tab
+ * @description A tab component that represents a single tab within a tab group. Supports multiple types (default, icon, text, withAction, custom), icons, action buttons, and accessibility features. Designed to work with vds-tabs-group for creating tabbed interfaces.
+ *
+ * @example
+ * <!-- Basic tab with icon and label -->
+ * <vds-tab
+ *   value="Profile"
+ *   informative-icon="user">
+ * </vds-tab>
+ *
+ * @example
+ * <!-- Text-only tab -->
+ * <vds-tab
+ *   value="Settings"
+ *   type="text">
+ * </vds-tab>
+ *
+ * @example
+ * <!-- Icon-only tab -->
+ * <vds-tab
+ *   type="icon"
+ *   informative-icon="home"
+ *   set-aria-label="Home">
+ * </vds-tab>
+ *
+ * @example
+ * <!-- Tab with action button -->
+ * <vds-tab
+ *   value="Documents"
+ *   informative-icon="folder-closed"
+ *   type="withAction"
+ *   action-icon="close"
+ *   action-aria-label="Close tab">
+ * </vds-tab>
+ *
+ * @example
+ * <!-- Custom tab with slot content -->
+ * <vds-tab type="custom">
+ *   <div slot="tab-header-content">
+ *     <span>Custom Content</span>
+ *   </div>
+ * </vds-tab>
+ *
+ * @example
+ * <!-- Disabled tab -->
+ * <vds-tab
+ *   value="Premium"
+ *   informative-icon="star"
+ *   disabled="true">
+ * </vds-tab>
+ *
+ * @example
+ * <!-- Tab with fixed width -->
+ * <vds-tab
+ *   value="Dashboard"
+ *   informative-icon="dashboard"
+ *   width="200px">
+ * </vds-tab>
+ *
+ * @example
+ * <!-- Tab with max width -->
+ * <vds-tab
+ *   value="Very Long Tab Title"
+ *   type="text"
+ *   max-width="150px">
+ * </vds-tab>
+ *
+ * @example
+ * <!-- Tab group with multiple tabs -->
+ * <vds-tabs-group active-tab-index="0">
+ *   <vds-tab value="Home" informative-icon="home"></vds-tab>
+ *   <vds-tab value="Profile" informative-icon="user"></vds-tab>
+ *   <vds-tab value="Settings" informative-icon="module-settings"></vds-tab>
+ * </vds-tabs-group>
+ *
+ * @example
+ * <!-- Tab with content slot -->
+ * <vds-tab value="Overview" informative-icon="dashboard">
+ *   <div slot="tab-content">
+ *     <h3>Dashboard Overview</h3>
+ *     <p>Your dashboard content goes here</p>
+ *   </div>
+ * </vds-tab>
+ *
+ * @example
+ * <!-- Tab with event handling -->
+ * <vds-tab
+ *   id="notifications-tab"
+ *   value="Notifications"
+ *   informative-icon="bell"
+ *   type="withAction"
+ *   action-icon="close">
+ * </vds-tab>
+ * <script>
+ *   const tab = document.getElementById('notifications-tab');
+ *   tab.addEventListener('isSelected', () => console.log('Tab selected'));
+ *   tab.addEventListener('clicked', () => console.log('Action button clicked'));
+ * </script>
+ *
+ * @example
+ * <!-- Complete tabbed interface -->
+ * <vds-tabs-group active-tab-index="0">
+ *   <vds-tab value="Overview" informative-icon="dashboard">
+ *     <div slot="tab-content">
+ *       <h2>Overview</h2>
+ *       <p>Dashboard content</p>
+ *     </div>
+ *   </vds-tab>
+ *
+ *   <vds-tab value="Analytics" informative-icon="analytics">
+ *     <div slot="tab-content">
+ *       <h2>Analytics</h2>
+ *       <p>Analytics data</p>
+ *     </div>
+ *   </vds-tab>
+ *
+ *   <vds-tab value="Reports" informative-icon="document">
+ *     <div slot="tab-content">
+ *       <h2>Reports</h2>
+ *       <p>Your reports</p>
+ *     </div>
+ *   </vds-tab>
+ * </vds-tabs-group>
+ */
 export declare class VdsTab {
     hostEl: HTMLElement;
-    /** Sets tab title. The value of this property is used by default as an aria-label too. */
+    /**
+     * Sets tab title. The value of this property is used by default as an aria-label too.
+     * @type {string}
+     */
     value: string;
     /**
-     * @deprecated This property is now being overridden by the VdsTabsGroup,
-     * the activeTabIndex property is the new preferred way of setting the default tab.
-     * Sets tab to active state.
+     * Sets tab to active state
+     * @deprecated This property is now being overridden by the VdsTabsGroup, the activeTabIndex property is the new preferred way of setting the default tab.
+     * @type {boolean}
+     * @default false
      */
     isActive: boolean;
-    /** Sets tab to disable state */
+    /**
+     * Sets tab to disable state
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
     /**
-     * @deprecated This property is being replaced by informativeIcon.
      * Sets tab icon. The tab icon is only a visual representation.
+     * @deprecated This property is being replaced by informativeIcon.
+     * @type {string}
      */
     icon?: string;
-    /** Sets tab icon. The tab icon is only a visual representation. */
+    /**
+     * Sets tab icon. The tab icon is only a visual representation.
+     * @type {string}
+     */
     informativeIcon?: string;
-    /** Sets tab fixed width. This property can't be used at the same time with the property maxWidth */
+    /**
+     * Sets tab fixed width. This property can't be used at the same time with the property maxWidth
+     * @type {string}
+     */
     width: string;
-    /** Sets tab maxWidth. This property can't be used at the same time with the property width */
+    /**
+     * Sets tab maxWidth. This property can't be used at the same time with the property width
+     * @type {string}
+     */
     maxWidth: string;
-    /** Sets tab type. Default shows Icon+Label. Icon shows only the Icon. withAction shows the Icon+Label+ActionIconButton. Custom permits define content in a slot. */
+    /**
+     * Sets tab type. Default shows Icon+Label. Icon shows only the Icon. withAction shows the Icon+Label+ActionIconButton. Custom permits define content in a slot.
+     * @type {"default" | "icon" | "withAction" | "text" | "custom"}
+     * @default "default"
+     */
     type: 'default' | 'icon' | 'withAction' | 'text' | 'custom';
-    /** Sets tab action icon button. Only available selecting withAction type. */
+    /**
+     * Sets tab action icon button. Only available selecting withAction type.
+     * @type {string}
+     */
     actionIcon: string;
-    /** Sets tab action icon button aria-label*/
+    /**
+     * Sets tab action icon button aria-label
+     * @type {string}
+     */
     actionAriaLabel: string;
-    /** Set aria-label for the tab. This property will be used only if the aria-label is required to be different from the value property. */
+    /**
+     * Set aria-label for the tab. This property will be used only if the aria-label is required to be different from the value property.
+     * @type {string}
+     */
     setAriaLabel: string;
-    /** Emits event when the tab is selected (sets isActive prop to true) */
+    /**
+     * Emits event when the tab is selected (sets isActive prop to true)
+     * @event isSelected
+     * @type {EventEmitter<MouseEvent>}
+     */
     isSelected: EventEmitter<MouseEvent>;
-    /** Emits event when the action icon button is clicked */
+    /**
+     * Emits event when the action icon button is clicked
+     * @event clicked
+     * @type {EventEmitter<MouseEvent>}
+     */
     clicked: EventEmitter<MouseEvent>;
-    /** Emits event when the value is changed */
+    /**
+     * Emits event when the value is changed
+     * @event valueChanged
+     * @type {EventEmitter<string>}
+     */
     valueChanged: EventEmitter<string>;
+    /**
+     * Handles keyboard navigation (Enter and Space keys)
+     * @private
+     * @param {KeyboardEvent} event - The keyboard event
+     */
     handleKeyDown(event: KeyboardEvent): void;
+    /**
+     * Watches for value changes and emits valueChanged event
+     * @private
+     */
     handleValueChange(): void;
+    /**
+     * Generates the icon element for the tab
+     * @private
+     * @returns {HTMLElement | void} The icon element or undefined if no icon is set
+     */
     private generateIcon;
+    /**
+     * Generates the action icon button for withAction type tabs
+     * @private
+     * @returns {HTMLElement | void} The action icon button element or undefined if not configured
+     */
     private generateActionIconButton;
+    /**
+     * Generates the label element for the tab
+     * @private
+     * @returns {HTMLElement} The label element
+     */
     private generateLabel;
+    /**
+     * Generates the default type tab (icon + label)
+     * @private
+     * @returns {HTMLElement} The default tab element
+     */
     private generateTypeDefault;
+    /**
+     * Generates the icon-only type tab
+     * @private
+     * @returns {HTMLElement} The icon tab element
+     */
     private generateTypeIcon;
+    /**
+     * Generates the withAction type tab (icon + label + action button)
+     * @private
+     * @returns {HTMLElement} The withAction tab element
+     */
     private generateTypeWithAction;
+    /**
+     * Generates the custom type tab with slot content
+     * @private
+     * @returns {HTMLElement} The custom tab element
+     */
     private generateTypeCustom;
+    /**
+     * Generates the text-only type tab
+     * @private
+     * @returns {HTMLElement} The text tab element
+     */
     private generateTypeText;
+    /**
+     * Returns the formatted content based on the tab type
+     * @private
+     * @returns {HTMLElement} The tab content element
+     */
     private getType;
+    /**
+     * Handles click events on the tab
+     * @private
+     * @param {MouseEvent} evt - The mouse event
+     */
     private handleClick;
+    /**
+     * Handles click events on the action icon button
+     * @private
+     * @param {MouseEvent} evt - The mouse event
+     */
     private handleActionIconClick;
+    /**
+     * Sets the width style based on width or maxWidth properties
+     * @private
+     * @returns {Object} Style object with CSS custom properties
+     */
     private setStyle;
+    /**
+     * Render the tab component
+     * @returns {HTMLElement} The rendered tab element
+     */
     render(): any;
 }

package/dist/types/components/tabs-group/vds-tabs-group.d.ts

@@ -1,55 +1,321 @@
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @component vds-tabs-group
+ * @description A container component that manages and organizes multiple vds-tab components into a tabbed interface. Handles active tab state, tab alignment, indicators, and provides methods for programmatic tab control.
+ *
+ * @example
+ * <!-- Basic tabs group -->
+ * <vds-tabs-group active-tab-index="0">
+ *   <vds-tab slot="tab-list" value="Home" informative-icon="home"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Profile" informative-icon="user"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Settings" informative-icon="module-settings"></vds-tab>
+ * </vds-tabs-group>
+ *
+ * @example
+ * <!-- Tabs group with track indicator -->
+ * <vds-tabs-group
+ *   active-tab-index="0"
+ *   show-track="true">
+ *   <vds-tab slot="tab-list" value="Overview" informative-icon="dashboard"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Analytics" informative-icon="analytics"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Reports" informative-icon="document"></vds-tab>
+ * </vds-tabs-group>
+ *
+ * @example
+ * <!-- Icon-only tabs group -->
+ * <vds-tabs-group
+ *   type="icon"
+ *   active-tab-index="0">
+ *   <vds-tab slot="tab-list" informative-icon="home" set-aria-label="Home"></vds-tab>
+ *   <vds-tab slot="tab-list" informative-icon="user" set-aria-label="Profile"></vds-tab>
+ *   <vds-tab slot="tab-list" informative-icon="module-settings" set-aria-label="Settings"></vds-tab>
+ * </vds-tabs-group>
+ *
+ * @example
+ * <!-- Center-aligned tabs -->
+ * <vds-tabs-group
+ *   active-tab-index="0"
+ *   tab-alignment="center">
+ *   <vds-tab slot="tab-list" value="Tab 1" informative-icon="star"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Tab 2" informative-icon="favorite"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Tab 3" informative-icon="flag"></vds-tab>
+ * </vds-tabs-group>
+ *
+ * @example
+ * <!-- Tabs with action buttons -->
+ * <vds-tabs-group
+ *   type="withAction"
+ *   active-tab-index="0">
+ *   <vds-tab
+ *     slot="tab-list"
+ *     value="Document 1"
+ *     informative-icon="document"
+ *     action-icon="close"
+ *     action-aria-label="Close tab">
+ *   </vds-tab>
+ *   <vds-tab
+ *     slot="tab-list"
+ *     value="Document 2"
+ *     informative-icon="document"
+ *     action-icon="close"
+ *     action-aria-label="Close tab">
+ *   </vds-tab>
+ * </vds-tabs-group>
+ *
+ * @example
+ * <!-- Flexible width tabs -->
+ * <vds-tabs-group
+ *   active-tab-index="0"
+ *   is-flex-width="true">
+ *   <vds-tab slot="tab-list" value="Short"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Medium Tab"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Very Long Tab Title"></vds-tab>
+ * </vds-tabs-group>
+ *
+ * @example
+ * <!-- Tabs with fixed width -->
+ * <vds-tabs-group
+ *   active-tab-index="0"
+ *   width="200px">
+ *   <vds-tab slot="tab-list" value="Tab 1"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Tab 2"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Tab 3"></vds-tab>
+ * </vds-tabs-group>
+ *
+ * @example
+ * <!-- Disabled tabs group -->
+ * <vds-tabs-group
+ *   active-tab-index="0"
+ *   disabled="true">
+ *   <vds-tab slot="tab-list" value="Tab 1"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Tab 2"></vds-tab>
+ * </vds-tabs-group>
+ *
+ * @example
+ * <!-- Tabs with header content -->
+ * <vds-tabs-group active-tab-index="0">
+ *   <div slot="header-content">
+ *     <h2>Dashboard Navigation</h2>
+ *   </div>
+ *   <vds-tab slot="tab-list" value="Overview" informative-icon="dashboard"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Analytics" informative-icon="analytics"></vds-tab>
+ * </vds-tabs-group>
+ *
+ * @example
+ * <!-- Complete tabs with content -->
+ * <vds-tabs-group active-tab-index="0" show-track="true">
+ *   <vds-tab slot="tab-list" value="Overview" informative-icon="dashboard">
+ *     <div slot="tab-content">
+ *       <h2>Overview</h2>
+ *       <p>Dashboard overview content</p>
+ *     </div>
+ *   </vds-tab>
+ *
+ *   <vds-tab slot="tab-list" value="Analytics" informative-icon="analytics">
+ *     <div slot="tab-content">
+ *       <h2>Analytics</h2>
+ *       <p>Analytics data and charts</p>
+ *     </div>
+ *   </vds-tab>
+ *
+ *   <vds-tab slot="tab-list" value="Reports" informative-icon="document">
+ *     <div slot="tab-content">
+ *       <h2>Reports</h2>
+ *       <p>Your reports and exports</p>
+ *     </div>
+ *   </vds-tab>
+ * </vds-tabs-group>
+ *
+ * @example
+ * <!-- Space-between alignment with max width -->
+ * <vds-tabs-group
+ *   active-tab-index="0"
+ *   tab-alignment="space-between"
+ *   max-width="150px">
+ *   <vds-tab slot="tab-list" value="Home"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Profile"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Settings"></vds-tab>
+ * </vds-tabs-group>
+ *
+ * @example
+ * <!-- Programmatic tab control -->
+ * <vds-tabs-group id="my-tabs" active-tab-index="0">
+ *   <vds-tab slot="tab-list" value="Tab 1"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Tab 2"></vds-tab>
+ *   <vds-tab slot="tab-list" value="Tab 3"></vds-tab>
+ * </vds-tabs-group>
+ * <button id="next-tab">Next Tab</button>
+ * <script>
+ *   const tabsGroup = document.getElementById('my-tabs');
+ *   const nextBtn = document.getElementById('next-tab');
+ *
+ *   nextBtn.addEventListener('click', async () => {
+ *     const currentIndex = await tabsGroup.getActive();
+ *     await tabsGroup.setActive((currentIndex + 1) % 3);
+ *   });
+ * </script>
+ */
 export declare class VdsTabsGroup {
     hostEl: HTMLElement;
-    /** Sets the type for the tabs group */
+    /**
+     * Sets the type for all tabs in the group. This will override individual tab type settings.
+     * @type {"default" | "icon" | "withAction" | "text" | "custom"}
+     * @default "default"
+     */
     type: 'default' | 'icon' | 'withAction' | 'text' | 'custom';
-    /** Sets the width for the tabs */
+    /**
+     * Sets the fixed width for all tabs in the group
+     * @type {string}
+     */
     width?: string;
-    /** Sets the max width for the tabs */
+    /**
+     * Sets the maximum width for all tabs in the group
+     * @type {string}
+     */
     maxWidth?: string;
-    /** Sets the alignment for the tabs */
+    /**
+     * Sets the alignment for the tabs within the group
+     * @type {"flex-start" | "flex-end" | "center" | "space-between" | "space-around"}
+     * @default "flex-start"
+     */
     tabAlignment: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around';
-    /** Shows the indicator track under the tab*/
+    /**
+     * Shows the indicator track under the active tab
+     * @type {boolean}
+     * @default false
+     */
     showTrack: boolean;
-    /** Sets the index to select the active tab inside the group.
-     * If not specified, loads the first tab.
+    /**
+     * Sets the index to select the active tab inside the group. If not specified, loads the first tab.
+     * @type {number}
+     * @default 0
      */
     activeTabIndex: number;
-    /** Sets tab group to disable state */
+    /**
+     * Sets the entire tab group to disabled state. All tabs will be disabled.
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
+    /**
+     * Sets flex-grow to 1 for internal tabs to make them fit the full width
+     * @type {boolean}
+     * @default false
+     */
+    isFlexWidth: boolean;
+    /**
+     * Internal state for tracking the active tab index
+     * @private
+     * @type {number}
+     * @default 0
+     */
     internalActiveTabIndex: number;
     private activeTab;
     private tabsGroupContainer;
     private indicatorEl;
     private tabs;
     private resizeObserver;
+    /**
+     * Listens for tab selection events and updates the active tab
+     * @private
+     * @param {CustomEvent} evt - The custom event from tab selection
+     */
     handleTabSelection(evt: CustomEvent): void;
+    /**
+     * Listens for value changes on tabs and updates the indicator position
+     * @private
+     */
     handleValueChanged(): void;
+    /**
+     * Lifecycle method that runs before component loads
+     * @private
+     */
     componentWillLoad(): void;
+    /**
+     * Lifecycle method that runs before each render
+     * @private
+     */
     componentWillRender(): void;
+    /**
+     * Lifecycle method that runs after component renders
+     * @private
+     */
     componentDidRender(): void;
+    /**
+     * Lifecycle method that runs when component is removed from DOM
+     * @private
+     */
     disconnectedCallback(): void;
+    /**
+     * Sets up a ResizeObserver to monitor active tab content changes
+     * @private
+     */
     private observeActiveTabContent;
+    /**
+     * Initializes and updates the tabs array from the DOM
+     * @private
+     */
     private setTabs;
+    /**
+     * Watches for activeTabIndex property changes and updates tabs state
+     * @private
+     */
     handleActiveTabIndexChange(): void;
+    /**
+     * Watches for disabled property changes and propagates to all tabs
+     * @private
+     */
     setDisabledState(): void;
     /**
      * Gets the currently active tab index
-     *
-     * @returns {Promise<number>} A promise that resolves with the active tab index.
+     * @public
+     * @returns {Promise<number>} A promise that resolves with the active tab index
      */
     getActive(): Promise<number>;
     /**
-     * Sets the active tab index
-     *
-     * @param {number} index - The index of the tab to set as active.
+     * Sets the active tab index programmatically
+     * @public
+     * @param {number} index - The index of the tab to set as active
      */
     setActive(index: number): Promise<void>;
+    /**
+     * Internal method to set the active tab
+     * @private
+     * @param {number} index - The index of the tab to set as active
+     */
     private setActiveTab;
+    /**
+     * Validates and returns a valid tab index, accounting for disabled tabs
+     * @private
+     * @param {number} index - The index to validate
+     * @returns {number} A valid, enabled tab index
+     */
     private validateTabIndex;
+    /**
+     * Defines component height based on active tab content
+     * @private
+     */
     private defineAttributes;
+    /**
+     * Updates the visual indicator position to match the active tab
+     * @private
+     */
     private updateIndicatorPosition;
+    /**
+     * Renders the active tab indicator element
+     * @private
+     * @returns {HTMLElement | void} The indicator element or undefined
+     */
     private renderActiveTabIndicator;
+    /**
+     * Updates the state of all tabs based on current settings and active index
+     * @private
+     * @param {HTMLVdsTabElement[]} tabs - Array of tab elements to update
+     */
     private updateTabsState;
+    /**
+     * Renders the tabs group component
+     * @returns {HTMLStencilElement} The rendered tabs group element
+     */
     render(): HTMLStencilElement;
 }

package/dist/types/components/tabs-group/vds-tabs-group.stories.d.ts

@@ -26,3 +26,4 @@ declare const _default: {
 export default _default;
 export declare const BasicUsage: any;
 export declare const CustomUsage: any;
+export declare const CustomUsageFullWidth: any;