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

package/dist/collection/components/tabs-group/vds-tabs-group.js

@@ -1,48 +1,263 @@
 import { Host, h, forceUpdate } from "@stencil/core";
 import { combineClasses } from "../../utils/combine-classes";
+/**
+ * @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 class VdsTabsGroup {
     constructor() {
-        /** 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"
+         */
         this.type = 'default';
-        /** 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"
+         */
         this.tabAlignment = 'flex-start';
-        /** Shows the indicator track under the tab*/
+        /**
+         * Shows the indicator track under the active tab
+         * @type {boolean}
+         * @default false
+         */
         this.showTrack = false;
-        /** 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
          */
         this.activeTabIndex = 0;
-        /** Sets tab group to disable state */
+        /**
+         * Sets the entire tab group to disabled state. All tabs will be disabled.
+         * @type {boolean}
+         * @default false
+         */
         this.disabled = false;
+        /**
+         * Sets flex-grow to 1 for internal tabs to make them fit the full width
+         * @type {boolean}
+         * @default false
+         */
+        this.isFlexWidth = false;
+        /**
+         * Internal state for tracking the active tab index
+         * @private
+         * @type {number}
+         * @default 0
+         */
         this.internalActiveTabIndex = 0;
         this.tabs = [];
     }
+    /**
+     * Listens for tab selection events and updates the active tab
+     * @private
+     * @param {CustomEvent} evt - The custom event from tab selection
+     */
     handleTabSelection(evt) {
         const target = evt.target;
         this.internalActiveTabIndex = Number(target === null || target === void 0 ? void 0 : target.getAttribute('vds-tabindex')) || 0;
         this.activeTabIndex = this.internalActiveTabIndex;
         this.updateTabsState(this.tabs);
     }
+    /**
+     * Listens for value changes on tabs and updates the indicator position
+     * @private
+     */
     handleValueChanged() {
         this.updateIndicatorPosition();
         forceUpdate(this);
     }
+    /**
+     * Lifecycle method that runs before component loads
+     * @private
+     */
     componentWillLoad() {
         this.setTabs();
     }
+    /**
+     * Lifecycle method that runs before each render
+     * @private
+     */
     componentWillRender() {
         this.setTabs();
     }
+    /**
+     * Lifecycle method that runs after component renders
+     * @private
+     */
     componentDidRender() {
         if (this.tabs.length > 0) {
             this.observeActiveTabContent();
         }
     }
+    /**
+     * Lifecycle method that runs when component is removed from DOM
+     * @private
+     */
     disconnectedCallback() {
         if (this.resizeObserver) {
             this.resizeObserver.disconnect();
         }
     }
+    /**
+     * Sets up a ResizeObserver to monitor active tab content changes
+     * @private
+     */
     observeActiveTabContent() {
         var _a;
         if (this.resizeObserver) {
@@ -59,13 +274,15 @@ export class VdsTabsGroup {
             }
         }
     }
+    /**
+     * Initializes and updates the tabs array from the DOM
+     * @private
+     */
     setTabs() {
         try {
             this.tabs = Array.from(this.hostEl.querySelectorAll('vds-tab'));
             if (this.tabs.length > 0) {
-                this.internalActiveTabIndex = this.activeTabIndex >= 0 && this.activeTabIndex < this.tabs.length
-                    ? this.activeTabIndex
-                    : 0;
+                this.internalActiveTabIndex = this.activeTabIndex >= 0 && this.activeTabIndex < this.tabs.length ? this.activeTabIndex : 0;
                 this.updateTabsState(this.tabs);
             }
         }
@@ -73,9 +290,17 @@ export class VdsTabsGroup {
             console.error('componentWillLoad Error: ', e);
         }
     }
+    /**
+     * Watches for activeTabIndex property changes and updates tabs state
+     * @private
+     */
     handleActiveTabIndexChange() {
         this.updateTabsState(this.tabs);
     }
+    /**
+     * Watches for disabled property changes and propagates to all tabs
+     * @private
+     */
     setDisabledState() {
         (this.tabs || []).forEach(tab => {
             tab.disabled = this.disabled;
@@ -83,26 +308,37 @@ export class VdsTabsGroup {
     }
     /**
      * 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
      */
     async getActive() {
         return this.internalActiveTabIndex;
     }
     /**
-     * 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
      */
     async setActive(index) {
         this.setActiveTab(index);
     }
+    /**
+     * Internal method to set the active tab
+     * @private
+     * @param {number} index - The index of the tab to set as active
+     */
     setActiveTab(index) {
         if (this.tabs.length > 0) {
             this.internalActiveTabIndex = this.validateTabIndex(index);
             this.activeTabIndex = this.internalActiveTabIndex;
         }
     }
+    /**
+     * 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
+     */
     validateTabIndex(index) {
         var _a;
         const isValidIndex = index >= 0 && index < this.tabs.length;
@@ -113,15 +349,24 @@ export class VdsTabsGroup {
         const firstEnabledIndex = this.tabs.findIndex(tab => !tab.disabled);
         return firstEnabledIndex >= 0 ? firstEnabledIndex : 0;
     }
+    /**
+     * Defines component height based on active tab content
+     * @private
+     */
     defineAttributes() {
         var _a;
         if (this.activeTab && this.tabsGroupContainer) {
             const content = (_a = this.activeTab.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector('.vds__tab--content-active');
             if (content) {
-                this.hostEl.setAttribute('style', `height: ${this.tabsGroupContainer.offsetHeight + content.offsetHeight}px`);
+                const vdsTabsHeaderHeight = this.tabsGroupContainer.querySelector('.vds__tabs-group--header');
+                this.hostEl.setAttribute('style', `height: ${vdsTabsHeaderHeight.offsetHeight + content.offsetHeight}px`);
             }
         }
     }
+    /**
+     * Updates the visual indicator position to match the active tab
+     * @private
+     */
     updateIndicatorPosition() {
         if (this.activeTab && this.indicatorEl) {
             const tabLeft = this.activeTab.offsetLeft;
@@ -131,9 +376,19 @@ export class VdsTabsGroup {
             this.indicatorEl.style.width = `${tabWidth}px`;
         }
     }
+    /**
+     * Renders the active tab indicator element
+     * @private
+     * @returns {HTMLElement | void} The indicator element or undefined
+     */
     renderActiveTabIndicator() {
-        return this.activeTab && (h("div", { class: "vds__tabs-group--active-tab-indicator", ref: (el) => (this.indicatorEl = el) }));
+        return this.activeTab && h("div", { class: "vds__tabs-group--active-tab-indicator", ref: (el) => (this.indicatorEl = el) });
     }
+    /**
+     * Updates the state of all tabs based on current settings and active index
+     * @private
+     * @param {HTMLVdsTabElement[]} tabs - Array of tab elements to update
+     */
     updateTabsState(tabs) {
         this.internalActiveTabIndex = this.validateTabIndex(this.activeTabIndex);
         tabs.forEach((tab, tabIndex) => {
@@ -143,6 +398,9 @@ export class VdsTabsGroup {
                 this.activeTab = tab;
                 this.updateIndicatorPosition();
             }
+            if (this.isFlexWidth) {
+                tab.setAttribute('vds-flex-width', 'true');
+            }
             tab.setAttribute('vds-tabindex', `${tabIndex}`);
             tab.type = this.type;
             tab.width = this.width;
@@ -150,12 +408,16 @@ export class VdsTabsGroup {
         });
         this.defineAttributes();
     }
+    /**
+     * Renders the tabs group component
+     * @returns {HTMLStencilElement} The rendered tabs group element
+     */
     render() {
-        return (h(Host, { key: 'da27d20a6f0d2c6695e9b9b2e7984aa612355440', class: this.disabled ? 'vds__tabs-group--disabled' : '' }, h("div", { key: '0c7bceac3747ecd9cc658e5e1e55bad08803bb3a', ref: (el) => {
+        return (h(Host, { key: '8ffc4a6752a1af91e98c25be4dd0a90f6cbe2e18', class: this.disabled ? 'vds__tabs-group--disabled' : '' }, h("div", { key: '7a1faa257d4da119d8215316c867805547d11cd2', ref: (el) => {
                 if (!el)
                     return;
                 this.tabsGroupContainer = el;
-            }, class: "vds__tabs-group" }, h("div", { key: '12fd14a9b1779cdb5eec53c29b11bd32ede778c3', class: combineClasses('vds__tabs-group--header', 'vds__tabs-group--header-tabs-' + this.tabAlignment, this.showTrack ? 'vds__tabs-group--header-tabs-show-track' : '') }, h("div", { key: '86d3b8a9ee044a0a986abeed2e174e6685538a7d', class: "vds__tabs-group--header-content" }, h("slot", { key: 'e6d07580cd77e4df7f15cbc92033912ae35980d8', name: "header-content" })), h("div", { key: '4c6064d5318e091991eea4738361198f9394d243', class: "vds__tabs-group--header-tabs-nav", role: "tablist" }, h("slot", { key: '6ec027c38b6e31ccf4b8536437a1865cbaf428fe', name: "tab-list" })), this.renderActiveTabIndicator()))));
+            }, class: "vds__tabs-group" }, h("div", { key: '71f50c1d125df327806caa4043ee46cec80373ce', class: combineClasses('vds__tabs-group--header', 'vds__tabs-group--header-tabs-' + this.tabAlignment, this.showTrack ? 'vds__tabs-group--header-tabs-show-track' : '') }, h("div", { key: 'd68841bb82e51fa8c82e4abee790b06e821e6fa1', class: "vds__tabs-group--header-content" }, h("slot", { key: '5469eb193072b98bfdc28245a046d5570324b9b2', name: "header-content" })), h("div", { key: '42df23d09f95950e4072b1c5951a11520db88d9c', class: combineClasses('vds__tabs-group--header-tabs-nav', this.isFlexWidth ? 'vds__tabs-group--header-tabs-nav-automatic-width' : ''), role: "tablist" }, h("slot", { key: '477b7f891f6afa0568f80411c32c2b3f54e2609e', name: "tab-list" })), this.renderActiveTabIndicator()))));
     }
     static get is() { return "vds-tabs-group"; }
     static get encapsulation() { return "shadow"; }
@@ -182,8 +444,14 @@ export class VdsTabsGroup {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the type for the tabs group"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"default\" | \"icon\" | \"withAction\" | \"text\" | \"custom\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"default\""
+                        }],
+                    "text": "Sets the type for all tabs in the group. This will override individual tab type settings."
                 },
                 "getter": false,
                 "setter": false,
@@ -202,8 +470,11 @@ export class VdsTabsGroup {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the width for the tabs"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Sets the fixed width for all tabs in the group"
                 },
                 "getter": false,
                 "setter": false,
@@ -221,8 +492,11 @@ export class VdsTabsGroup {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the max width for the tabs"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Sets the maximum width for all tabs in the group"
                 },
                 "getter": false,
                 "setter": false,
@@ -240,8 +514,14 @@ export class VdsTabsGroup {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the alignment for the tabs"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"flex-start\" | \"flex-end\" | \"center\" | \"space-between\" | \"space-around\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"flex-start\""
+                        }],
+                    "text": "Sets the alignment for the tabs within the group"
                 },
                 "getter": false,
                 "setter": false,
@@ -260,8 +540,14 @@ export class VdsTabsGroup {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Shows the indicator track under the tab"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Shows the indicator track under the active tab"
                 },
                 "getter": false,
                 "setter": false,
@@ -280,8 +566,14 @@ export class VdsTabsGroup {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the index to select the active tab inside the group.\nIf not specified, loads the first tab."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{number}"
+                        }, {
+                            "name": "default",
+                            "text": "0"
+                        }],
+                    "text": "Sets the index to select the active tab inside the group. If not specified, loads the first tab."
                 },
                 "getter": false,
                 "setter": false,
@@ -300,14 +592,46 @@ export class VdsTabsGroup {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets tab group to disable state"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Sets the entire tab group to disabled state. All tabs will be disabled."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": true,
                 "attribute": "disabled",
                 "defaultValue": "false"
+            },
+            "isFlexWidth": {
+                "type": "boolean",
+                "mutable": true,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Sets flex-grow to 1 for internal tabs to make them fit the full width"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "is-flex-width",
+                "defaultValue": "false"
             }
         };
     }
@@ -333,8 +657,11 @@ export class VdsTabsGroup {
                 "docs": {
                     "text": "Gets the currently active tab index",
                     "tags": [{
+                            "name": "public",
+                            "text": undefined
+                        }, {
                             "name": "returns",
-                            "text": "A promise that resolves with the active tab index."
+                            "text": "A promise that resolves with the active tab index"
                         }]
                 }
             },
@@ -344,7 +671,7 @@ export class VdsTabsGroup {
                     "parameters": [{
                             "name": "index",
                             "type": "number",
-                            "docs": "- The index of the tab to set as active."
+                            "docs": "- The index of the tab to set as active"
                         }],
                     "references": {
                         "Promise": {
@@ -355,10 +682,13 @@ export class VdsTabsGroup {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Sets the active tab index",
+                    "text": "Sets the active tab index programmatically",
                     "tags": [{
+                            "name": "public",
+                            "text": undefined
+                        }, {
                             "name": "param",
-                            "text": "index - The index of the tab to set as active."
+                            "text": "index - The index of the tab to set as active"
                         }]
                 }
             }
@@ -390,4 +720,3 @@ export class VdsTabsGroup {
             }];
     }
 }
-//# sourceMappingURL=vds-tabs-group.js.map