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

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

@@ -1,21 +1,161 @@
 import { HTMLStencilElement } from '../../stencil-public-runtime';
 import { Colors } from '../../definitions/colors';
+/**
+ * @component vds-field
+ * @description A layout wrapper component for form controls. It composes a label (`vds-label`),
+ * a slotted form control (e.g. `vds-basic-input`, `vds-textarea`, a native `<select>`, etc.),
+ * an optional helper text, and an optional error message into a single consistently spaced column.
+ *
+ * The component is intentionally agnostic about its slotted content — any form control can be
+ * projected into the default slot. In practice it is consumed internally by higher-level
+ * components such as `vds-input` (volt-extended-components) and `vds-textarea`, which pass their
+ * own child element as the slotted control and forward their props to `vds-field`.
+ *
+ * @slot default - The form control to render inside the field (e.g. `vds-basic-input`, `<select>`, `<textarea>`).
+ *
+ * ---
+ *
+ * @example
+ * <!-- Basic usage with a native input -->
+ * <vds-field label="Username">
+ *   <input type="text" placeholder="Enter your username" />
+ * </vds-field>
+ *
+ * @example
+ * <!-- With helper text -->
+ * <vds-field label="Email" helper-text="We will never share your email address.">
+ *   <input type="email" placeholder="you@example.com" />
+ * </vds-field>
+ *
+ * @example
+ * <!-- With error message (replaces helper text visually) -->
+ * <vds-field label="Password" error-message="Password must be at least 8 characters.">
+ *   <input type="password" />
+ * </vds-field>
+ *
+ * @example
+ * <!-- Required field -->
+ * <vds-field label="Full name" is-required="true">
+ *   <input type="text" />
+ * </vds-field>
+ *
+ * @example
+ * <!-- Disabled state — disables pointer events on the whole field -->
+ * <vds-field label="Read-only value" is-disabled="true" helper-text="This field cannot be edited.">
+ *   <input type="text" value="John Doe" disabled />
+ * </vds-field>
+ *
+ * @example
+ * <!-- Size variants: "small" | "medium" (default) | "large" -->
+ * <vds-field label="Small field" size="small" helper-text="Small size helper text.">
+ *   <input type="text" />
+ * </vds-field>
+ * <vds-field label="Large field" size="large" helper-text="Large size helper text.">
+ *   <input type="text" />
+ * </vds-field>
+ *
+ * @example
+ * <!-- Colored helper text using a Volt color token -->
+ * <vds-field
+ *   label="Status"
+ *   helper-text="Everything looks good."
+ *   helper-text-color="healthy-main"
+ * >
+ *   <input type="text" value="Active" />
+ * </vds-field>
+ *
+ * @example
+ * <!-- Align helper text to the right via the CSS custom property -->
+ * <style>
+ *   vds-field.right-aligned {
+ *     --vds-field-helper-text-align: right;
+ *   }
+ * </style>
+ * <vds-field class="right-aligned" label="Character count" helper-text="42 / 100">
+ *   <input type="text" />
+ * </vds-field>
+ *
+ * @example
+ * <!-- Real-world pattern: used internally by vds-input (volt-extended-components).
+ *      vds-input renders vds-field and projects vds-basic-input into the default slot. -->
+ * <vds-field
+ *   label="Search"
+ *   helper-text="Enter a keyword to search."
+ *   is-required="true"
+ *   size="medium"
+ * >
+ *   <vds-basic-input type="text" placeholder="e.g. dashboard" size="medium"></vds-basic-input>
+ * </vds-field>
+ *
+ * @example
+ * <!-- Slotting any arbitrary control (native select) -->
+ * <vds-field label="Country" helper-text="Select your country of residence.">
+ *   <select>
+ *     <option value="us">United States</option>
+ *     <option value="mx">Mexico</option>
+ *     <option value="ca">Canada</option>
+ *   </select>
+ * </vds-field>
+ *
+ * ---
+ *
+ * @cssvar --vds-field-helper-text-align {string} Controls the `text-align` of the helper text.
+ *   Defaults to `start`. Override to `right`, `center`, or `end` as needed.
+ */
 export declare class VdsField {
-    /** Sets the field's label */
+    /**
+     * Sets the field's label text
+     * @type {string}
+     */
     label: string;
-    /** Toggles the required sign in the field */
+    /**
+     * Toggles the required indicator in the field label
+     * @type {boolean}
+     * @default false
+     */
     isRequired: boolean;
-    /** Sets the field in disabled state */
+    /**
+     * Sets the field in disabled state
+     * @type {boolean}
+     * @default false
+     */
     isDisabled: boolean;
-    /** Sets the field's helper text */
+    /**
+     * Sets the field's helper text displayed below the input
+     * @type {string}
+     */
     helperText: string;
-    /** Sets the field's helper text color */
+    /**
+     * Sets the helper text color
+     * @type {Colors}
+     */
     helperTextColor: Colors;
-    /** Sets the field's error message */
+    /**
+     * Sets the field's error message displayed below the input
+     * @type {string}
+     */
     errorMessage: string;
-    /** Sets the field's size */
+    /**
+     * Sets the field's size
+     * @type {"small" | "medium" | "large"}
+     * @default "medium"
+     */
     size: "small" | "medium" | "large";
+    /**
+     * Renders the field label if provided
+     * @private
+     * @returns {HTMLStencilElement | null} The label element or null
+     */
     private getLabel;
+    /**
+     * Renders the helper text if provided
+     * @private
+     * @returns {HTMLStencilElement | null} The helper text element or null
+     */
     private getHelperText;
+    /**
+     * Renders the component
+     * @returns {HTMLStencilElement} The rendered component
+     */
     render(): HTMLStencilElement;
 }

package/dist/types/components/field/vds-field.stories.d.ts

@@ -22,3 +22,4 @@ declare const _default: {
 };
 export default _default;
 export declare const BasicUsage: any;
+export declare const HelperTextAlignment: any;

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

@@ -1,32 +1,180 @@
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @component vds-footer
+ * @description Footer component that provides default, expandable, or custom footer layouts with app version, copyright, and powered by sections
+ * @slot default - Default slot for footer links (used in default and expandable types)
+ * @slot expandable-content - Content shown when footer is expanded (expandable type only)
+ * @slot start - Left section content (custom type only)
+ * @slot center - Center section content (custom type only)
+ * @slot end - Right section content (custom type only)
+ * @example
+ * <!-- Default footer with links -->
+ * <vds-footer
+ *   app-version="v1.2.3"
+ *   central-text="Wabtec Corporation. All rights reserved."
+ *   powered-by-text="Powered by">
+ *   <vds-link href="/privacy">Privacy Policy</vds-link>
+ *   <vds-link href="/terms">Terms of Service</vds-link>
+ *   <vds-link href="/contact">Contact</vds-link>
+ * </vds-footer>
+ *
+ * <!-- Expandable footer with bottom position -->
+ * <vds-footer
+ *   type="expandable"
+ *   app-version="v2.0.0"
+ *   expanded-content-position="bottom">
+ *   <vds-link href="/help">Help</vds-link>
+ *   <vds-link href="/support">Support</vds-link>
+ *   <div slot="expandable-content">
+ *     <p>Additional footer information here</p>
+ *   </div>
+ * </vds-footer>
+ *
+ * <!-- Expandable footer with top position -->
+ * <vds-footer
+ *   type="expandable"
+ *   expanded-content-position="top">
+ *   <div slot="expandable-content">
+ *     <vds-menu-list>
+ *       <vds-menu-item>Item 1</vds-menu-item>
+ *       <vds-menu-item>Item 2</vds-menu-item>
+ *     </vds-menu-list>
+ *   </div>
+ * </vds-footer>
+ *
+ * <!-- Custom footer with three sections -->
+ * <vds-footer type="custom">
+ *   <div slot="start">
+ *     <span>© 2026 Company</span>
+ *   </div>
+ *   <div slot="center">
+ *     <vds-link href="/about">About</vds-link>
+ *   </div>
+ *   <div slot="end">
+ *     <span>Version 1.0</span>
+ *   </div>
+ * </vds-footer>
+ */
 export declare class VdsFooter {
     /**
-     *  Sets the type for the footer, expandable shows an extra layer of the footer.
-     *  Default is only what is visible.
-     *  and custom allows to set the content of the footer.
+     * Sets the type for the footer
+     * - default: Shows standard footer layout
+     * - expandable: Includes expandable section with toggle button
+     * - custom: Allows custom content via slots
+     * @type {'default' | 'expandable' | 'custom'}
+     * @default 'default'
      */
     type: 'default' | 'expandable' | 'custom';
-    /** Sets the app version to be display in the footer */
+    /**
+     * Sets the app version to be displayed in the footer
+     * @type {string}
+     */
     appVersion: string;
-    /** Sets the expanded content position, default is bottom */
+    /**
+     * Sets the expanded content position relative to the footer
+     * @type {'top' | 'bottom'}
+     * @default 'bottom'
+     */
     expandedContentPosition: 'top' | 'bottom';
-    /** Defines the text in the central block of the footer */
+    /**
+     * Defines the text in the central block of the footer
+     * @type {string}
+     * @default 'Wabtec Corporation. All rights reserved.'
+     */
     centralText: string;
-    /** Modify the text in the "powered by" section of the footer */
+    /**
+     * Modifies the text in the "powered by" section of the footer
+     * @type {string}
+     * @default 'Powered by'
+     */
     poweredByText: string;
+    /**
+     * Reference to the host element
+     * @type {HTMLStencilElement}
+     */
     host: HTMLStencilElement;
+    /**
+     * Controls whether the expandable section is currently expanded
+     * @type {boolean}
+     * @default false
+     */
     isExpanded: boolean;
+    /**
+     * Stores the current year for copyright display
+     * @private
+     * @type {number}
+     */
     private currentYear;
+    /**
+     * MutationObserver for watching slot changes
+     * @private
+     * @type {MutationObserver}
+     */
     private observer;
+    /**
+     * Lifecycle hook that runs before component renders
+     * Sets up footer options and separators
+     * @returns {void}
+     */
     componentWillRender(): void;
+    /**
+     * Lifecycle hook that runs before component loads
+     * Initializes the current year
+     * @returns {void}
+     */
     componentWillLoad(): void;
+    /**
+     * Lifecycle hook that runs after component is loaded
+     * Sets up mutation observer for slot changes
+     * @returns {void}
+     */
     componentDidLoad(): void;
+    /**
+     * Lifecycle hook that runs when component is disconnected
+     * Cleans up mutation observer
+     * @returns {void}
+     */
     disconnectedCallback(): void;
+    /**
+     * Sets footer options based on type and manages slotted children
+     * Removes non-link children for default/expandable types and adds separators
+     * @private
+     * @returns {void}
+     */
     private setFooterOptions;
+    /**
+     * Adds divider elements between link elements in the footer
+     * @private
+     * @returns {void}
+     */
     private setSeparators;
+    /**
+     * Sets the current year for copyright display
+     * @private
+     * @returns {void}
+     */
     private setCurrentYear;
+    /**
+     * Toggles the expanded state of the footer
+     * @private
+     * @returns {void}
+     */
     private toggleExpand;
+    /**
+     * Renders the expandable toggle button for expandable footer type
+     * @private
+     * @returns {HTMLStencilElement} The expand/collapse button element
+     */
     private renderExpandableButton;
+    /**
+     * Renders the custom footer layout with start, center, and end slots
+     * @private
+     * @returns {HTMLElement} The custom footer container
+     */
     private renderCustomFooter;
+    /**
+     * Renders the component
+     * @returns {HTMLStencilElement} The rendered component
+     */
     render(): HTMLStencilElement;
 }

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

@@ -1,29 +1,149 @@
 import { Colors } from '../../components';
+/**
+ * @component vds-header
+ * @description Header component that displays app name, content section, and optional user section with avatar and dropdown menu
+ * @slot contentSection - Content section in the center of the header
+ * @slot profilePopupContent - Content for the user profile dropdown menu
+ * @example
+ * <!-- Basic header with app name and user section -->
+ * <vds-header
+ *   value="My Application"
+ *   username="John Doe"
+ *   avatar="JD">
+ *   <div slot="profilePopupContent">
+ *     <vds-menu-item>Profile</vds-menu-item>
+ *     <vds-menu-item>Settings</vds-menu-item>
+ *     <vds-menu-item>Logout</vds-menu-item>
+ *   </div>
+ * </vds-header>
+ *
+ * <!-- Header with notification badge -->
+ * <vds-header
+ *   value="Dashboard"
+ *   username="Jane Smith"
+ *   avatar="JS"
+ *   show-badge
+ *   badge-status-color="warning"
+ *   badge-aria-label="New notifications">
+ * </vds-header>
+ *
+ * <!-- Header with content section -->
+ * <vds-header value="My App" username="User" avatar="U">
+ *   <div slot="contentSection">
+ *     <vds-button>Actions</vds-button>
+ *   </div>
+ *   <div slot="profilePopupContent">
+ *     <vds-menu-item>Account</vds-menu-item>
+ *   </div>
+ * </vds-header>
+ *
+ * <!-- Header without user section -->
+ * <vds-header
+ *   value="Simple App"
+ *   show-user-section="false">
+ * </vds-header>
+ */
 export declare class VdsHeader {
-    /** Defines app name for header */
-    value: string;
-    /** Defines the value in the avatar component */
-    avatar: string;
-    /** Defines the username at the left of the avatar */
+    /**
+     * Defines the app name displayed in the header
+     * @type {string}
+     */
+    value?: string;
+    /**
+     * Defines the value for the avatar component
+     * @type {string}
+     */
+    avatar?: string;
+    /**
+     * Defines the username displayed to the left of the avatar
+     * @type {string}
+     */
     username: string;
-    /** Allow hide/show User-Section */
+    /**
+     * Controls visibility of the user section
+     * @type {boolean}
+     * @default true
+     */
     showUserSection: boolean;
-    /** Shows/hides badge dot to show notification or status */
+    /**
+     * Shows/hides badge dot to indicate notification or status
+     * @type {boolean}
+     * @default false
+     */
     showBadge: boolean;
-    /** Sets the status color for badge */
-    badgeStatusColor: "warning" | "danger" | "healthy" | "information" | "neutral" | Colors;
-    /** Sets the aria label in badge */
-    badgeAriaLabel: string;
-    hostEl: HTMLElement;
+    /**
+     * Sets the status color for the badge
+     * @type {"warning" | "danger" | "healthy" | "information" | "neutral" | Colors}
+     * @default "neutral"
+     */
+    badgeStatusColor: 'warning' | 'danger' | 'healthy' | 'information' | 'neutral' | Colors;
+    /**
+     * Sets the aria label for the badge
+     * @type {string}
+     */
+    badgeAriaLabel?: string;
+    /**
+     * Reference to the host element
+     * @type {HTMLElement}
+     */
+    hostEl?: HTMLElement;
+    /**
+     * Controls whether the user profile popup is opened
+     * @type {boolean}
+     * @default false
+     */
     popupOpened: boolean;
-    handleClickOut(evt: any): void;
-    private actionElementRef;
-    private arrowElementRef;
-    private floatingMenuElementRef;
-    private floatingCleanUp;
-    componentDidLoad(): void;
+    /**
+     * Listens for clicks outside the component to close the popup
+     * @param {Event} evt - The click event
+     * @returns {void}
+     */
+    handleClickOut(evt: MouseEvent): void;
+    /**
+     * Reference to the user section element
+     * @private
+     * @type {HTMLElement}
+     */
+    private userSectionElementRef?;
+    /**
+     * Reference to the arrow element
+     * @private
+     * @type {HTMLElement}
+     */
+    private arrowElementRef?;
+    /**
+     * Reference to the floating menu container element
+     * @private
+     * @type {HTMLElement}
+     */
+    private floatingMenuElementRef?;
+    /**
+     * Cleanup function for floating positioning
+     * @private
+     * @type {() => void}
+     */
+    private floatingCleanUp?;
+    /**
+     * Handles click on the user section to toggle popup
+     * @private
+     * @param {MouseEvent} _evt - The mouse click event
+     * @returns {void}
+     */
     private handleClick;
+    /**
+     * Watches for popup opened state changes and manages floating position
+     * @returns {Promise<void>}
+     */
     handlePopupOpened(): Promise<void>;
+    /**
+     * Renders the avatar with optional badge
+     * @private
+     * @returns {HTMLElement} The avatar element with or without badge
+     */
     private renderAvatar;
-    render(): any;
+    /**
+     * Renders the component
+     * @returns {HTMLElement} The rendered component
+     */
+    render(): HTMLElement;
 }

package/dist/types/components/header/vds-header.stories.d.ts

@@ -17,3 +17,4 @@ declare const _default: {
 export default _default;
 export declare const BasicUsage: any;
 export declare const WithAvatarImageUsage: any;
+export declare const CustomColorsUsage: any;