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

package/dist/types/components/autocomplete/vds-basic-autocomplete.stories.d.ts

@@ -34,6 +34,18 @@ declare const _default: {
                 type: string;
             };
         };
+        displayValue: {
+            options: string[];
+            control: {
+                type: string;
+            };
+        };
+        position: {
+            options: string[];
+            control: {
+                type: string;
+            };
+        };
     };
 };
 export default _default;
@@ -41,3 +53,4 @@ export declare const BasicUsage: any;
 export declare const DropdownUsage: any;
 export declare const BasicMultipleUsage: any;
 export declare const BasicMultipleSlotHeaderUsage: any;
+export declare const DynamicInformativeIcon: any;

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

@@ -1,49 +1,346 @@
 import { EventEmitter } from "../../stencil-public-runtime";
 import { HTMLStencilElement } from "../../stencil-public-runtime";
+/**
+ * @component vds-autocomplete-item
+ * @description An autocomplete item component used within vds-basic-autocomplete.
+ * Provides selectable items with optional checkmarks, icons, and danger states.
+ * Supports different sizes, alignment options, and accessibility features.
+ *
+ * @example
+ * <!-- Basic autocomplete item -->
+ * <vds-autocomplete-item value="option1">Option 1</vds-autocomplete-item>
+ *
+ * @example
+ * <!-- Autocomplete item with label -->
+ * <vds-autocomplete-item
+ *   value="opt-1"
+ *   label="First Option">
+ * </vds-autocomplete-item>
+ *
+ * @example
+ * <!-- Disabled autocomplete item -->
+ * <vds-autocomplete-item
+ *   value="disabled-option"
+ *   disabled>
+ *   Disabled Option
+ * </vds-autocomplete-item>
+ *
+ * @example
+ * <!-- Active/selected autocomplete item -->
+ * <vds-autocomplete-item
+ *   value="active-option"
+ *   is-active>
+ *   Active Option
+ * </vds-autocomplete-item>
+ *
+ * @example
+ * <!-- Autocomplete item with informative icon -->
+ * <vds-autocomplete-item
+ *   value="document.pdf"
+ *   informative-icon="document">
+ *   Document File
+ * </vds-autocomplete-item>
+ *
+ * @example
+ * <!-- Large size autocomplete item -->
+ * <vds-autocomplete-item
+ *   value="large-item"
+ *   size="large">
+ *   Large Size Item
+ * </vds-autocomplete-item>
+ *
+ * @example
+ * <!-- Autocomplete item with checkmark (start aligned) -->
+ * <vds-autocomplete-item
+ *   value="checked-item"
+ *   has-checkmark
+ *   is-selected>
+ *   Selected Item
+ * </vds-autocomplete-item>
+ *
+ * @example
+ * <!-- Autocomplete item with checkbox (end aligned) -->
+ * <vds-autocomplete-item
+ *   value="checkbox-item"
+ *   has-checkmark
+ *   checkmark-variant="checkbox"
+ *   checkmark-alignment="end"
+ *   is-selected>
+ *   Checkbox Item
+ * </vds-autocomplete-item>
+ *
+ * @example
+ * <!-- Danger state autocomplete item -->
+ * <vds-autocomplete-item
+ *   value="delete-option"
+ *   danger>
+ *   Delete Item
+ * </vds-autocomplete-item>
+ *
+ * @example
+ * <!-- ⚠️ Avoid listening to autocompleteClicked directly – it is an internal event.
+ *      Instead, listen to selectedValueChanged on the parent vds-basic-autocomplete / vds-autocomplete.
+ *      See the autocompleteClicked event JSDoc for the full migration guide. -->
+ * <vds-basic-autocomplete id="my-auto" placeholder="Select an option">
+ *   <vds-autocomplete-item value="click-me">Click Me</vds-autocomplete-item>
+ * </vds-basic-autocomplete>
+ * <script>
+ *   document.getElementById('my-auto')
+ *     .addEventListener('selectedValueChanged', (e) => {
+ *       console.log('label:', e.detail.label);
+ *       console.log('value:', e.detail.value);
+ *     });
+ * </script>
+ *
+ * @example
+ * <!-- Multiple autocomplete items in a list -->
+ * <div style="display: flex; flex-direction: column; gap: 4px;">
+ *   <vds-autocomplete-item value="item1" informative-icon="star">Favorite</vds-autocomplete-item>
+ *   <vds-autocomplete-item value="item2" informative-icon="folder-closed">Documents</vds-autocomplete-item>
+ *   <vds-autocomplete-item value="item3" informative-icon="image">Images</vds-autocomplete-item>
+ *   <vds-autocomplete-item value="item4" danger>Delete All</vds-autocomplete-item>
+ * </div>
+ *
+ * @example
+ * <!-- Autocomplete items with different sizes -->
+ * <div style="display: flex; flex-direction: column; gap: 8px;">
+ *   <vds-autocomplete-item value="small" size="small">Small Item</vds-autocomplete-item>
+ *   <vds-autocomplete-item value="medium" size="medium">Medium Item</vds-autocomplete-item>
+ *   <vds-autocomplete-item value="large" size="large">Large Item</vds-autocomplete-item>
+ * </div>
+ *
+ * @example
+ * <!-- Autocomplete items within vds-basic-autocomplete -->
+ * <vds-basic-autocomplete placeholder="Select a fruit">
+ *   <vds-autocomplete-item value="apple" informative-icon="radio-unchecked">Apple</vds-autocomplete-item>
+ *   <vds-autocomplete-item value="banana" informative-icon="radio-unchecked">Banana</vds-autocomplete-item>
+ *   <vds-autocomplete-item value="orange" informative-icon="radio-unchecked">Orange</vds-autocomplete-item>
+ *   <vds-autocomplete-item value="grape" informative-icon="radio-unchecked">Grape</vds-autocomplete-item>
+ * </vds-basic-autocomplete>
+ *
+ * @example
+ * <!-- Autocomplete items with checkmarks in multiple mode -->
+ * <vds-basic-autocomplete id="multi-autocomplete" multiple placeholder="Select multiple">
+ *   <vds-autocomplete-item value="opt1" has-checkmark checkmark-variant="checkbox">Option 1</vds-autocomplete-item>
+ *   <vds-autocomplete-item value="opt2" has-checkmark checkmark-variant="checkbox">Option 2</vds-autocomplete-item>
+ *   <vds-autocomplete-item value="opt3" has-checkmark checkmark-variant="checkbox">Option 3</vds-autocomplete-item>
+ * </vds-basic-autocomplete>
+ * <script>
+ *   const multiAuto = document.getElementById('multi-autocomplete');
+ *   multiAuto.multipleValues = ['opt1', 'opt3'];
+ * </script>
+ *
+ * @slot (default) - Default slot for custom content (overridden by label or value if present)
+ */
 export declare class VdsAutocompleteItem {
-    /** Sets the autocomplete in disabled state */
+    /**
+     * Sets the autocomplete item in disabled state, preventing user interaction.
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Sets the icon value */
+    /**
+     * Sets the informative icon value displayed in the item.
+     * @type {string}
+     * @default undefined
+     */
     informativeIcon: string;
-    /** Sets item in active state */
+    /**
+     * Sets the item in active state for visual feedback.
+     * @type {boolean}
+     * @default false
+     */
     isActive: boolean;
-    /** Sets item's value; This will be display as the text in the item when label is not present.
-     *  When value is present as text to be display, it will override children content. */
+    /**
+     * Sets the item's value; this will be displayed as text when label is not present.
+     * When value is present as text to display, it will override children content.
+     * @type {string}
+     * @default undefined
+     */
     value: string;
-    /** Sets item's label; This will be display as the text in the item.
-     *  When label is present, it will override children content and value when present. */
+    /**
+     * Sets the item's label; this will be displayed as text in the item.
+     * When label is present, it will override children content and value.
+     * @type {string}
+     * @default undefined
+     */
     label: string;
-    /** Sets aria-label */
+    /**
+     * Sets the aria-label for accessibility.
+     * @type {string}
+     * @default undefined
+     */
     setAriaLabel: string;
-    /** Set size of menu item */
+    /**
+     * Sets the size of the autocomplete item.
+     * @type {("small" | "medium" | "large")}
+     * @default "medium"
+     */
     size: "small" | "medium" | "large";
-    /** Shows checkmark */
+    /**
+     * Controls whether to show a checkmark or checkbox indicator.
+     * @type {boolean}
+     * @default false
+     */
     hasCheckmark: boolean;
-    /** Set state of checkmark */
+    /**
+     * Sets the selected state of the checkmark or checkbox.
+     * @type {boolean}
+     * @default false
+     */
     isSelected: boolean;
-    /** When has-checkmark is true, sets the checks element as checkmark or checkbox.  */
+    /**
+     * When hasCheckmark is true, sets the check element as checkmark or checkbox.
+     * @type {("checkbox" | "checkmark")}
+     * @default "checkmark"
+     */
     checkmarkVariant: "checkbox" | "checkmark";
-    /** When has-checkmark is true, sets the checks element at the beginning or end.  */
+    /**
+     * When hasCheckmark is true, sets the check element position at the beginning or end.
+     * @type {("start" | "end")}
+     * @default "start"
+     */
     checkmarkAlignment: "start" | "end";
-    /** Sets the autocomplete item to danger state.  */
+    /**
+     * Sets the autocomplete item to danger state for destructive actions.
+     * @type {boolean}
+     * @default false
+     */
     danger: boolean;
-    /** Emits event when item gets clicked */
+    /**
+     * Sets the text to be highlighted in the item when highlightText is provided.
+     * @type {string}
+     * @default undefined
+     */
+    highlightText: string;
+    /**
+     * Emitted when the item is clicked.
+     * Contains the item's value (label, value, or textContent) and selected state.
+     * @event autocompleteClicked
+     * @type {EventEmitter<{value: string, selected: boolean}>}
+     *
+     * @internal
+     * @warning **Do not listen to this event directly.** This event is intended for
+     * internal communication between `vds-autocomplete-item` and its parent
+     * `vds-basic-autocomplete` / `vds-autocomplete`. Listening to it externally
+     * may produce unexpected behaviour or break in future versions.
+     *
+     * **Migration:** Replace any `autocompleteClicked` listener on `vds-autocomplete-item`
+     * with the `selectedValueChanged` event on the parent `vds-basic-autocomplete` /
+     * `vds-autocomplete` instead:
+     *
+     * @example
+     * <!-- ❌ Avoid – internal event, do not use externally -->
+     * <script>
+     *   document.querySelector('vds-autocomplete-item')
+     *     .addEventListener('autocompleteClicked', (e) => {
+     *       console.log(e.detail.value, e.detail.selected);
+     *     });
+     * </script>
+     *
+     * @example
+     * <!-- ✅ Recommended – listen on the parent autocomplete -->
+     * <vds-basic-autocomplete id="my-autocomplete" placeholder="Select an option">
+     *   <vds-autocomplete-item value="opt1">Option 1</vds-autocomplete-item>
+     *   <vds-autocomplete-item value="opt2">Option 2</vds-autocomplete-item>
+     * </vds-basic-autocomplete>
+     * <script>
+     *   // selectedValueChanged emits { label, value, target } for single selection,
+     *   // and valueChanged emits string[] for multiple selection.
+     *   document.getElementById('my-autocomplete')
+     *     .addEventListener('selectedValueChanged', (e) => {
+     *       console.log('label:', e.detail.label);
+     *       console.log('value:', e.detail.value);
+     *       console.log('target element:', e.detail.target);
+     *     });
+     * </script>
+     */
     autocompleteClicked: EventEmitter<{
         value: string;
         selected: boolean;
     }>;
-    /** Emits event when item is selected */
+    /**
+     * Emitted when the item is selected.
+     * @event selected
+     * @type {EventEmitter<MouseEvent>}
+     *
+     * @internal
+     * @warning **Do not listen to this event directly.** This event is for internal
+     * use by the parent `vds-basic-autocomplete` / `vds-autocomplete` component.
+     * Use the `selectedValueChanged` event on the parent autocomplete component
+     * to react to selection changes. See the `autocompleteClicked` JSDoc for a
+     * full migration example.
+     */
     selected: EventEmitter<MouseEvent>;
-    /** Emits event when item is deselected */
+    /**
+     * Emitted when the item is deselected.
+     * @event deselected
+     * @type {EventEmitter<MouseEvent>}
+     *
+     * @internal
+     * @warning **Do not listen to this event directly.** This event is for internal
+     * use by the parent `vds-basic-autocomplete` / `vds-autocomplete` component.
+     * Use the `valueChanged` event on the parent autocomplete component (which
+     * emits the updated `string[]` of selected values) to react to deselection.
+     * See the `autocompleteClicked` JSDoc for a full migration example.
+     */
     deselected: EventEmitter<MouseEvent>;
     hostEl: HTMLElement;
+    /**
+     * Watches the isSelected property and updates the active state accordingly.
+     * @private
+     * @returns {void}
+     */
     updateItemState(): void;
+    /**
+     * Handles click events on the autocomplete item.
+     * @private
+     * @param {MouseEvent} evt - The mouse click event
+     * @returns {void}
+     */
     private handleClick;
+    /**
+     * Handles the selection/deselection logic and emits appropriate events.
+     * Emits selected or deselected event based on current state.
+     * Emits autocompleteClicked event with item value and selection state.
+     * @private
+     * @param {MouseEvent} evt - The mouse click event
+     * @returns {void}
+     */
     private handleSelected;
+    /**
+     * Generates a checkmark icon button element.
+     * @private
+     * @returns {HTMLStencilElement} The checkmark icon button element
+     */
     private generateCheckmarkIconButton;
+    /**
+     * Generates a checkbox element.
+     * @private
+     * @returns {HTMLStencilElement} The checkbox element
+     */
     private generateCheckbox;
+    /**
+     * Generates an informative icon element.
+     * @private
+     * @returns {HTMLStencilElement} The informative icon element
+     */
     private generateInformativeIcon;
+    /**
+     * Generates the label text element for the item.
+     * @private
+     * @returns {HTMLStencilElement} The label element
+     */
     private generateLabel;
+    /**
+     * Determines the aria-label text based on setAriaLabel, label, or value priority.
+     * @private
+     * @returns {string} The aria-label text
+     */
     private setAriaLabelText;
+    /**
+     * Renders the autocomplete item component.
+     * @returns {HTMLStencilElement} The root autocomplete item element
+     */
     render(): HTMLStencilElement;
 }

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

@@ -1,34 +1,116 @@
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @component vds-avatar
+ * @description An avatar component that displays user images, initials, or counts.
+ * Supports image URLs, full names (showing initials), and +XX format for additional users.
+ * Includes optional hover overlay with icon for interactive states.
+ * Avatar size is customizable in px or rem units.
+ */
 export declare class VdsAvatar {
     /**
-     * This property can receive:
-     * - Fullname to show the first letters inside the avatar.
-     * - Url of image.
-     * - +XX format for showing the number of additional users. Caps at +99.
+     * The value to display in the avatar. Can receive:
+     * - Full name to show the first letters inside the avatar (e.g., "John Doe" becomes "JD")
+     * - URL of an image (must start with "http")
+     * - +XX format for showing the number of additional users (caps at +99)
+     * @type {string}
+     * @default undefined
+     * @example "John Doe"
+     * @example "https://example.com/avatar.jpg"
+     * @example "+5"
      */
     value: string;
-    /** Set icon size in px or rem, IE: 32px or 1.25rem */
+    /**
+     * Sets the avatar size in px or rem.
+     * @type {string}
+     * @default "20px"
+     * @example "32px"
+     * @example "1.25rem"
+     */
     size: string;
     /**
-     * Name of the icon to show as overlay on hover. If not set, no overlay is shown.
+     * Name of the icon to show as overlay on hover.
+     * If not set, no overlay is shown.
+     * @type {string}
+     * @default undefined
+     * @example "edit"
      */
     overlayIcon?: string;
     setBackground: boolean;
+    /**
+     * Formats a number string to show additional users count.
+     * Caps the display at +99 for numbers greater than 99.
+     * @private
+     * @param {string} number - The number string in +XX format
+     * @returns {string} The formatted number string (e.g., "+5" or "+99")
+     */
     private getNumberFormat;
+    /**
+     * Extracts initials from a full name.
+     * Takes the first character of the first word and the first character of the last word.
+     * @private
+     * @param {string} name - The full name to extract initials from
+     * @returns {string} The uppercase initials (e.g., "JD" from "John Doe")
+     */
     private getNameInitials;
+    /**
+     * Determines the appropriate avatar value based on the input.
+     * Returns formatted number if value matches +XX pattern, otherwise returns initials.
+     * @private
+     * @param {string} value - The value to process
+     * @returns {string} The formatted avatar value
+     */
     getAvatarValue(value: string): string;
+    /**
+     * Calculates the appropriate font size based on the avatar size.
+     * Font size is half of the avatar size.
+     * @private
+     * @param {string} size - The avatar size in px or rem
+     * @returns {string} The calculated font size
+     * @throws {Error} If size format is invalid
+     */
     calcFontSize(size: string): string;
+    /**
+     * Calculates the line height based on the avatar size.
+     * Line height is calculated as (size * 1.25) / 2.
+     * @private
+     * @param {string} size - The avatar size in px or rem
+     * @returns {string} The calculated line height
+     */
     calcLineHeight(size: string): string;
+    /**
+     * Gets the CSS styles for the avatar value display.
+     * @private
+     * @returns {{ 'width': string; 'height': string; 'font-size': string }} Object containing CSS properties
+     */
     getValueStyles(): {
         'width': string;
         'height': string;
         'font-size': string;
     };
+    /**
+     * Generates the avatar content based on the value type.
+     * Returns an image element if value is a URL, otherwise returns initials or count.
+     * @private
+     * @returns {HTMLStencilElement} The avatar content element
+     */
     getAvatarContent(): any;
+    /**
+     * Determines the background color based on whether an image or text is displayed.
+     * @private
+     * @returns {string} The background color CSS value
+     */
     setBackgroundColor(): string;
     /**
-     * Calculates the overlay icon size so that a 100px avatar = 20px icon (1.25rem), scaling proportionally for px or rem.
+     * Calculates the overlay icon size proportionally based on avatar size.
+     * A 100px avatar yields a 20px (1.25rem) icon, scaling proportionally for px or rem.
+     * @private
+     * @returns {string} The calculated icon size in rem
      */
     getOverlayIconSize(): string;
+    /**
+     * Renders the avatar component.
+     * Renders as a button with overlay if overlayIcon is set, otherwise renders as a div.
+     * @returns {HTMLStencilElement} The root avatar element
+     */
     render(): HTMLStencilElement;
 }

package/dist/types/components/badge-dot/vds-badge-dot.d.ts

@@ -1,18 +1,64 @@
 import { Colors } from '../../definitions/colors';
+/**
+ * @component vds-badge-dot
+ * @description A badge dot component that displays a small colored indicator.
+ * Used to show status, notifications, or presence indicators.
+ * Supports predefined status colors and custom theme colors.
+ * Can be positioned at different corners and optionally overlap content.
+ * @slot (default) - Content to display alongside the badge dot
+ */
 export declare class VdsBadgeDot {
-    /** Sets the badge's size */
+    /**
+     * Sets the badge's size.
+     * @type {("small" | "medium")}
+     * @default "medium"
+     */
     size: "small" | "medium";
-    /** Sets the color of the badge, it provides special colors such as warning, danger, healthy, information, neutral
-     *  If you pass a color from out pallete it will consider as custom. The color will be applied as background color. */
+    /**
+     * Sets the color of the badge.
+     * Provides special status colors: warning, danger, healthy, information, neutral.
+     * Can also accept custom colors from the theme palette.
+     * Custom colors are applied as background color using CSS variables.
+     * @type {("warning" | "danger" | "healthy" | "information" | "neutral" | Colors)}
+     * @default "neutral"
+     */
     statusColor: "warning" | "danger" | "healthy" | "information" | "neutral" | Colors;
-    /** Sets the aria label in badge */
+    /**
+     * Sets the aria-label for accessibility.
+     * @type {string}
+     * @default undefined
+     */
     setAriaLabel: string;
-    /** Sets to overlap component content */
+    /**
+     * Controls whether the badge overlaps the content.
+     * When true, the badge is positioned to overlap the content.
+     * @type {boolean}
+     * @default false
+     */
     overlap: boolean;
-    /** Sets the position of the badge */
+    /**
+     * Sets the position of the badge relative to the content.
+     * @type {("top-right" | "top-left" | "bottom-right" | "bottom-left")}
+     * @default "top-right"
+     */
     position: "top-right" | "top-left" | "bottom-right" | "bottom-left";
     private isCustom;
+    /**
+     * Component lifecycle method called before each render.
+     * Determines if the statusColor is a custom color or a predefined variant.
+     * @returns {void}
+     */
     componentWillRender(): void;
+    /**
+     * Sets the custom color style for the badge dot.
+     * Applies the custom color as a CSS variable if it's not a predefined variant.
+     * @private
+     * @returns {{ backgroundColor?: string }} Object containing CSS properties or empty object
+     */
     setCustomColorStyle(): {};
+    /**
+     * Renders the badge dot component.
+     * @returns {HTMLElement} The root badge dot element
+     */
     render(): any;
 }