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

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

@@ -1,46 +1,229 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @component vds-popover
+ * @description A floating content container component that displays additional information or actions when triggered by user interaction. Supports both click and hover events with customizable positioning and sizing.
+ *
+ * @example
+ * <!-- Basic popover with click trigger -->
+ * <vds-popover position="bottom" event="click">
+ *   <button slot="popover-trigger">Click Me</button>
+ *   <div slot="popover-content">
+ *     <p>This is the popover content</p>
+ *   </div>
+ * </vds-popover>
+ *
+ * @example
+ * <!-- Popover with hover trigger -->
+ * <vds-popover position="top" event="hover">
+ *   <span slot="popover-trigger">Hover over me</span>
+ *   <div slot="popover-content">
+ *     <p>Additional information appears on hover</p>
+ *   </div>
+ * </vds-popover>
+ *
+ * @example
+ * <!-- Popover positioned to the right -->
+ * <vds-popover position="right" event="click">
+ *   <vds-icon-button slot="popover-trigger" icon="information" variant="secondary"></vds-icon-button>
+ *   <div slot="popover-content">
+ *     <h4>Help Information</h4>
+ *     <p>This is helpful context for the user.</p>
+ *   </div>
+ * </vds-popover>
+ *
+ * @example
+ * <!-- Popover with custom max width and height -->
+ * <vds-popover
+ *   position="bottom"
+ *   event="click"
+ *   max-width="400px"
+ *   max-height="300px">
+ *   <button slot="popover-trigger">Show Details</button>
+ *   <div slot="popover-content">
+ *     <p>Long content that needs scrolling...</p>
+ *   </div>
+ * </vds-popover>
+ *
+ * @example
+ * <!-- Popover without padding -->
+ * <vds-popover
+ *   position="bottom"
+ *   event="click"
+ *   padding="none">
+ *   <button slot="popover-trigger">Menu</button>
+ *   <vds-menu-list slot="popover-content">
+ *     <vds-menu-item value="Option 1"></vds-menu-item>
+ *     <vds-menu-item value="Option 2"></vds-menu-item>
+ *   </vds-menu-list>
+ * </vds-popover>
+ *
+ * @example
+ * <!-- Popover with auto-positioning -->
+ * <vds-popover
+ *   position="bottom"
+ *   event="click"
+ *   auto-position="true">
+ *   <button slot="popover-trigger">Smart Position</button>
+ *   <div slot="popover-content">
+ *     <p>This popover will reposition based on available space</p>
+ *   </div>
+ * </vds-popover>
+ *
+ * @example
+ * <!-- Popover with rich content -->
+ * <vds-popover position="bottom" event="click">
+ *   <vds-button slot="popover-trigger" variant="primary">User Profile</vds-button>
+ *   <div slot="popover-content">
+ *     <vds-avatar name="John Doe"></vds-avatar>
+ *     <h3>John Doe</h3>
+ *     <p>john.doe@example.com</p>
+ *     <vds-button variant="secondary" size="small">View Profile</vds-button>
+ *   </div>
+ * </vds-popover>
+ *
+ * @example
+ * <!-- Popover positioned to the left -->
+ * <vds-popover position="left" event="hover">
+ *   <vds-icon slot="popover-trigger" svg-icon="information"></vds-icon>
+ *   <div slot="popover-content">
+ *     <p>Tooltip-style help text</p>
+ *   </div>
+ * </vds-popover>
+ *
+ * @slot popover-trigger - The element that triggers the popover (button, icon, text, etc.)
+ * @slot popover-content - The content to display inside the popover
+ */
 export declare class VdsPopover {
     hostEl: HTMLElement;
-    /** Defines the position where the popover will be opened */
-    position: 'top' | 'bottom' | 'right' | 'left';
-    /** Sets the maximum width of the popover’s content */
+    /**
+     * Defines the position where the popover will be opened
+     * @type {'top' | 'bottom' | 'right' | 'left' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'}
+     * @default 'bottom'
+     */
+    position: 'top' | 'bottom' | 'right' | 'left' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+    /**
+     * Sets the maximum width of the popover's content
+     * @type {string}
+     */
     maxWidth: string;
-    /** Sets the maximum height of the popover’s content */
+    /**
+     * Sets the maximum height of the popover's content
+     * @type {string}
+     */
     maxHeight: string;
-    /** The type of event that will trigger the popover */
+    /**
+     * The type of event that will trigger the popover
+     * @type {'hover' | 'click'}
+     * @default 'click'
+     */
     event: 'hover' | 'click';
-    /** Toggles padding inside popover. */
+    /**
+     * Toggles padding inside popover.
+     * @type {'default' | 'none'}
+     * @default 'default'
+     */
     padding: 'default' | 'none';
-    /** Toggles the floating container auto-positioning based on available window space.
+    /**
+     * Toggles the floating container auto-positioning based on available window space.
      * False by default as it may cause positioning issues in some situations, use with caution
+     * @type {boolean}
+     * @default false
      */
     autoPosition: boolean;
     popupOpened: boolean;
-    /** Emits event when popover gets opens */
+    /**
+     * Emits event when popover gets opened
+     * @event opened
+     * @type {EventEmitter<void>}
+     */
     opened: EventEmitter<void>;
-    /** Emits event when popover gets closes */
+    /**
+     * Emits event when popover gets closed
+     * @event closed
+     * @type {EventEmitter<void>}
+     */
     closed: EventEmitter<void>;
     private floatingCleanUp;
     constructor();
+    /**
+     * Watch for popupOpened state changes and emit events, update positioning
+     * @private
+     */
     emitValue(): Promise<void>;
+    /**
+     * Close the popover when clicking outside
+     * @private
+     * @param {MouseEvent} evt - The mouse event
+     */
     private handleClickOut;
+    /**
+     * Open the popover with click on the trigger element
+     * @private
+     * @param {Event} event - The click event
+     */
     handleClick(event: Event): void;
+    /**
+     * Open the popover from other element
+     * @method
+     * @public
+     * @returns {Promise<void>}
+     */
     open(): Promise<void>;
+    /**
+     * Close the popover from other element
+     * @method
+     * @public
+     * @returns {Promise<void>}
+     */
     close(): Promise<void>;
     /**
-     *  Gets the target that will manage the popover
-     *  returns a promise with the target HTMLElement.
+     * Gets the target that will manage the popover
+     * @method
+     * @public
+     * @returns {Promise<HTMLElement | null>} A promise with the target HTMLElement
      */
     getTarget(): Promise<HTMLElement | null>;
+    /**
+     * Handle hover event to open popover
+     * @private
+     * @param {Event} event - The hover event
+     */
     private handleHover;
+    /**
+     * Handle hover out event to close popover
+     * @private
+     * @param {Event} event - The hover out event
+     */
     private handleHoverOut;
+    /**
+     * Set padding CSS variable based on padding prop
+     * @private
+     * @returns {{ [key: string]: string }} Style object with padding
+     */
     private setPadding;
+    /**
+     * Set max width and height CSS variables
+     * @private
+     * @returns {{ [key: string]: string }} Style object with max dimensions
+     */
     private setMaxWidthAndHeight;
     private actionElementRef;
     private arrowElementRef;
     private popoverElementRef;
+    /**
+     * Component lifecycle hook - setup event listeners and element references
+     * @private
+     */
     componentDidLoad(): void;
+    /**
+     * Component lifecycle hook - cleanup event listeners
+     * @private
+     */
     disconnectedCallback(): void;
+    /**
+     * Render the popover component
+     * @returns {HTMLStencilElement} The rendered popover element
+     */
     render(): HTMLStencilElement;
 }

package/dist/types/components/progress-circular/vds-progress-circular.d.ts

@@ -1,42 +1,315 @@
+/**
+ * A circular progress indicator rendered as an SVG ring. Supports determinate mode
+ * (a fixed percentage fill) and indeterminate mode (an infinite spinning animation).
+ * The mode is controlled implicitly by the `duration` prop — no separate `mode` attribute exists.
+ *
+ * This component has **no events** and **no public methods** — it is purely declarative.
+ *
+ * ---
+ * ## Migration note (volt-progress-indicator-circular → vds-progress-circular)
+ *
+ * **`volt-progress-indicator-circular` must be replaced with `vds-progress-circular`.**
+ * Every prop was either renamed, removed, or replaced with a different concept.
+ *
+ * ### 1. Tag rename
+ *
+ * ```html
+ * <!-- Before -->
+ * <volt-progress-indicator-circular progress="64" mode="determinate" size="md" color="secondary-blue">
+ * </volt-progress-indicator-circular>
+ *
+ * <!-- After -->
+ * <vds-progress-circular value="64" duration="0" scale="1" status="default">
+ * </vds-progress-circular>
+ * ```
+ *
+ * ### 2. `progress` → `value` (prop renamed)
+ *
+ * The percentage prop was renamed. `progress` is silently ignored on `vds-progress-circular`.
+ *
+ * ```html
+ * <!-- Before -->
+ * <volt-progress-indicator-circular progress="75"></volt-progress-indicator-circular>
+ *
+ * <!-- After -->
+ * <vds-progress-circular value="75"></vds-progress-circular>
+ * ```
+ *
+ * ### 3. `mode` prop removed — determinate vs indeterminate controlled by `duration`
+ *
+ * There is no `mode` prop in `vds-progress-circular`. The mode is determined implicitly:
+ * - **Determinate** (static fill): set `duration="0"` (or omit it — default is `500` but
+ *   setting it to `0` disables animation)
+ * - **Indeterminate** (infinite spin): set `duration` to any value **greater than 0** (ms)
+ *
+ * ```html
+ * <!-- Before: determinate -->
+ * <volt-progress-indicator-circular mode="determinate" progress="64"></volt-progress-indicator-circular>
+ * <!-- After: determinate (duration=0 disables animation) -->
+ * <vds-progress-circular value="64" duration="0"></vds-progress-circular>
+ *
+ * <!-- Before: indeterminate -->
+ * <volt-progress-indicator-circular mode="indeterminate" duration="1200"></volt-progress-indicator-circular>
+ * <!-- After: indeterminate (any duration > 0 enables animation) -->
+ * <vds-progress-circular duration="1000"></vds-progress-circular>
+ * ```
+ *
+ * ### 4. `color` prop removed — replaced by `status` and `colors`
+ *
+ * The `color` prop accepted BasePalette strings (e.g. `"secondary-blue"`, `"status-red"`).
+ * It no longer exists. Use:
+ * - `status` for semantic colors (`"default"`, `"success"`, `"error"`)
+ * - `colors` for fully custom Volt token overrides (JSON)
+ *
+ * ```html
+ * <!-- Before -->
+ * <volt-progress-indicator-circular color="secondary-blue" progress="50"></volt-progress-indicator-circular>
+ * <!-- After: closest semantic equivalent -->
+ * <vds-progress-circular value="50" status="default"></vds-progress-circular>
+ *
+ * <!-- Before -->
+ * <volt-progress-indicator-circular color="status-red" progress="30"></volt-progress-indicator-circular>
+ * <!-- After -->
+ * <vds-progress-circular value="30" status="error"></vds-progress-circular>
+ * ```
+ *
+ * ### 5. `size` prop removed — replaced by `scale` multiplier
+ *
+ * The fixed `size` tokens are replaced by a continuous `scale` multiplier (base: 52px / 3.5rem).
+ *
+ * | volt `size` | px | vds `scale` | px |
+ * |---|---|---|---|
+ * | `sm` | 20px | `0.5` | 26px |
+ * | `md` | 52px | `1` | 52px (exact) |
+ * | `lg` | 104px | `2` | 104px (exact) |
+ *
+ * ```html
+ * <!-- Before -->
+ * <volt-progress-indicator-circular size="md" progress="50"></volt-progress-indicator-circular>
+ * <!-- After -->
+ * <vds-progress-circular value="50" scale="1"></vds-progress-circular>
+ * ```
+ *
+ * **Full migration checklist:**
+ * - Replace tag `volt-progress-indicator-circular` → `vds-progress-circular`
+ * - Rename prop `progress` → `value`
+ * - Remove `mode` prop — use `duration="0"` for determinate, `duration > 0` for indeterminate
+ * - Remove `color` prop — use `status` for semantic colors or `colors` for custom tokens
+ * - Replace `size` with `scale` multiplier (`sm`→`0.5`, `md`→`1`, `lg`→`2`)
+ * - Add `set-aria-label` for accessibility
+ *
+ * ---
+ * ## Determinate usage (static fill)
+ *
+ * Set `duration="0"` to disable animation and show a fixed progress percentage.
+ * `value` is clamped to `[0, 100]`.
+ *
+ * ```html
+ * <vds-progress-circular value="0"   duration="0" set-aria-label="0% complete"></vds-progress-circular>
+ * <vds-progress-circular value="25"  duration="0" set-aria-label="25% complete"></vds-progress-circular>
+ * <vds-progress-circular value="59"  duration="0" set-aria-label="59% complete"></vds-progress-circular>
+ * <vds-progress-circular value="100" duration="0" set-aria-label="Complete"></vds-progress-circular>
+ * ```
+ *
+ * ---
+ * ## Indeterminate usage (animated spinner)
+ *
+ * Set `duration` to any value greater than `0` (milliseconds per full rotation).
+ * Lower values spin faster.
+ *
+ * ```html
+ * <!-- Fast spinner: 500ms per rotation -->
+ * <vds-progress-circular duration="500" set-aria-label="Loading..."></vds-progress-circular>
+ *
+ * <!-- Standard spinner: 1000ms per rotation -->
+ * <vds-progress-circular duration="1000" set-aria-label="Loading..."></vds-progress-circular>
+ *
+ * <!-- Slow spinner: 2000ms per rotation -->
+ * <vds-progress-circular duration="2000" set-aria-label="Loading..."></vds-progress-circular>
+ * ```
+ *
+ * ---
+ * ## Status colors
+ *
+ * ```html
+ * <!-- Default (brand blue) -->
+ * <vds-progress-circular value="60" duration="0" status="default"></vds-progress-circular>
+ *
+ * <!-- Success (green) -->
+ * <vds-progress-circular value="100" duration="0" status="success"></vds-progress-circular>
+ *
+ * <!-- Error (red) -->
+ * <vds-progress-circular value="30" duration="0" status="error"></vds-progress-circular>
+ * ```
+ *
+ * ---
+ * ## Custom colors
+ *
+ * Pass a JSON object (or a JSON string when used from HTML) with Volt theme token names —
+ * without the `var(--…)` wrapper. Both keys are optional.
+ *
+ * ```html
+ * <!-- HTML attribute: use single quotes outside, double inside -->
+ * <vds-progress-circular
+ *   value="30"
+ *   duration="500"
+ *   colors='{"backgroundTrack": "color-background-caution-default", "backgroundProgress": "color-background-healthy-default"}'
+ *   set-aria-label="Custom colors"
+ * ></vds-progress-circular>
+ * ```
+ *
+ * ```js
+ * // JavaScript: pass as an object
+ * const el = document.querySelector('vds-progress-circular');
+ * el.colors = {
+ *   backgroundTrack: 'color-background-caution-default',
+ *   backgroundProgress: 'color-background-healthy-default',
+ * };
+ * ```
+ *
+ * ---
+ * ## Scale (size)
+ *
+ * `scale` is a continuous multiplier. Base size is `52px` (3.5rem) at `scale=1`.
+ * Minimum enforced value is `0.25` (13px).
+ *
+ * ```html
+ * <vds-progress-circular value="50" duration="0" scale="0.25"></vds-progress-circular>  <!-- 13px -->
+ * <vds-progress-circular value="50" duration="0" scale="0.5"></vds-progress-circular>   <!-- 26px -->
+ * <vds-progress-circular value="50" duration="0" scale="1"></vds-progress-circular>     <!-- 52px (default) -->
+ * <vds-progress-circular value="50" duration="0" scale="1.5"></vds-progress-circular>   <!-- 78px -->
+ * <vds-progress-circular value="50" duration="0" scale="2"></vds-progress-circular>     <!-- 104px -->
+ * ```
+ *
+ * ---
+ * ## Accessibility
+ *
+ * Always set `set-aria-label` to describe the progress context for screen readers.
+ *
+ * ```html
+ * <vds-progress-circular
+ *   value="45"
+ *   duration="0"
+ *   set-aria-label="Upload progress: 45%"
+ * ></vds-progress-circular>
+ *
+ * <vds-progress-circular
+ *   duration="1000"
+ *   set-aria-label="Loading results, please wait"
+ * ></vds-progress-circular>
+ * ```
+ *
+ * ---
+ * ## Slots
+ *
+ * This component has no public slots. All rendering is driven by props.
+ *
+ * @component vds-progress-circular
+ */
 export declare class VdsProgressCircular {
-    /** Sets the percentage filled value from 0 to 100 */
+    /**
+     * The progress percentage to display in determinate mode. Clamped to `[0, 100]`.
+     * Has no visual effect when the indicator is in indeterminate mode (`duration > 0`).
+     *
+     * **Migration:** was `progress` in `volt-progress-indicator-circular`.
+     * Using the old prop name silently shows no fill.
+     *
+     * @type {number}
+     */
     value: number;
     /**
-     * Defines the color based on the status:
-     * error -> color-background-critical-default,
-     * success -> color-background-general-healthy-default,
-     * default -> color-background-brand-default
+     * Semantic color of the progress ring fill.
+     * - `"default"` — brand blue (`color-background-brand-default`)
+     * - `"success"` — green (`color-background-general-healthy-default`)
+     * - `"error"` — red (`color-background-critical-default`)
+     *
+     * **Migration:** replaces the `color` BasePalette prop from `volt-progress-indicator-circular`.
+     * Use `status` for semantic intent, or the `colors` prop for fully custom tokens.
+     *
+     * @type {'error' | 'success' | 'default'}
+     * @default 'default'
      */
     status: 'error' | 'success' | 'default';
     /**
-     * Sets the loop duration time for the indeterminate loop progress in miliseconds.
-     * Determinate and indeterminate state will be defined by adding or not the duration.
+     * Controls both **animation speed** and **mode** (determinate vs indeterminate):
+     * - `0` → **determinate**: no animation, the ring shows the `value` percentage as a static fill.
+     * - `> 0` → **indeterminate**: the ring spins continuously; the number is the milliseconds
+     *   per full rotation (lower = faster). The `value` prop is ignored in this mode.
+     *
+     * **Migration:** the old `mode="determinate|indeterminate"` prop is gone.
+     * Set `duration="0"` to replicate `mode="determinate"`.
+     * Set `duration > 0` to replicate `mode="indeterminate"`.
+     *
+     * @type {number}
+     * @default 500
      */
     duration: number;
-    /** Sets the aria label */
+    /**
+     * Accessible label announced by screen readers to describe the progress context.
+     * Always provide this — there is no visible text label on the component.
+     *
+     * HTML attribute: `set-aria-label`
+     *
+     * @type {string}
+     */
     setAriaLabel: string;
     /**
-     * Sets the progress indicator color from the Volt palette:
-     * backgroundProgress - ThemeColors,
-     * backgroundTrack - ThemeColors
+     * Overrides the ring colors with specific Volt theme tokens.
+     * Accepts a JSON object or a JSON string (required when set as an HTML attribute).
+     * Keys are optional — omit either to keep the default for that part.
+     *
+     * - `backgroundTrack` — the empty (unfilled) part of the ring
+     * - `backgroundProgress` — the filled (progress) part of the ring
+     *
+     * Token values must be Volt CSS variable names **without** the `var(--)` wrapper.
+     *
+     * **Migration:** replaces the `color` BasePalette prop from `volt-progress-indicator-circular`.
+     * Use this prop when you need a specific color that `status` does not cover.
+     *
+     * ```html
+     * <!-- HTML attribute (JSON string) -->
+     * <vds-progress-circular
+     *   colors='{"backgroundTrack": "color-background-caution-default", "backgroundProgress": "color-background-healthy-default"}'
+     * ></vds-progress-circular>
+     * ```
+     *
+     * ```js
+     * // JS property (object)
+     * el.colors = { backgroundTrack: 'color-background-caution-default' };
+     * ```
+     *
+     * @type {{ [key: string]: string } | string}
      */
     colors: {
         [key: string]: string;
     } | string;
     /**
-     * Set the size scale of the component based on 1 === 52px (3.5rem).
+     * Continuous size multiplier. Base size is `52px` (3.5rem) at `scale = 1`.
+     * The minimum enforced value is `0.25` (13px).
+     *
      * Common values:
-     * - 0.25 (extra small): 13px
-     * - 0.5 (small): 26px
-     * - 1 (medium): 52px
-     * - 1.5 (large): 78px
-     * Minimum scale is 0.25
+     * - `0.25` → 13px (extra small)
+     * - `0.5`  → 26px (small)
+     * - `1`    → 52px (medium, default)
+     * - `1.5`  → 78px (large)
+     * - `2`    → 104px (extra large)
+     *
+     * **Migration:** replaces the `size="sm|md|lg"` prop from `volt-progress-indicator-circular`.
+     * Equivalent mappings: `sm` → `0.5`, `md` → `1`, `lg` → `2`.
+     *
+     * @type {number}
+     * @default 1
      */
     scale: number;
     /**
-     * State variable to hold the progress value.
+     * State variable to hold the clamped progress value (0-100)
+     * @type {number}
      */
     progress: number;
+    /**
+     * Flag indicating whether custom colors are being used
+     * @private
+     */
     private customColors;
     /**
      * Calculates and returns the styling for the progress circle based on the current value.
@@ -51,33 +324,36 @@ export declare class VdsProgressCircular {
      * Returns the animation for the indeterminate slider.
      * Using the duration prop we return an animation effect in ms.
      * Going from top to bottom using the value as the progress.
-     *
      * @private
-     * @returns { animation: string }
+     * @returns {{ animation: string } | {}} Animation style object or empty object
      */
     private setDurationAnimation;
     /**
      * Ensures that the scale is clamped to a minimum value of 0.25.
-     *
      * @private
-     * @param {number} scale - The new scale value.
+     * @param {number} scale - The new scale value
      */
     private setScale;
     /**
      * Sets custom colors for the progress bar.
-     *
      * @private
-     * @returns {Object} An object containing the CSS styles for the custom colors.
+     * @returns {{ [key: string]: string }} An object containing the CSS styles for the custom colors
      */
     private setCustomColors;
     /**
      * Activates custom colors.
-     *
      * @private
-     * @param {Object} colors - The colors object.
-     * @returns {void}
+     * @param {{ [key: string]: string }} colors - The colors object
      */
     private activateCustomColors;
+    /**
+     * Component lifecycle hook - initialize scale on load
+     * @private
+     */
     componentWillLoad(): void;
+    /**
+     * Render the circular progress component
+     * @returns {HTMLElement} The rendered circular progress element
+     */
     render(): any;
 }