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

package/dist/collection/components/progress-circular/vds-progress-circular.js

@@ -1,29 +1,264 @@
 import { Host, h } from "@stencil/core";
 import { combineClasses } from "../../utils/combine-classes";
+/**
+ * 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 class VdsProgressCircular {
     constructor() {
         /**
-         * 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'
          */
         this.status = '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
          */
         this.duration = 500;
         /**
-         * 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
          */
         this.scale = 1;
+        /**
+         * Flag indicating whether custom colors are being used
+         * @private
+         */
         this.customColors = false;
     }
     /**
@@ -48,27 +283,24 @@ export 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
      */
     setDurationAnimation() {
         return this.duration > 0 ? { animation: `rotate ${this.duration}ms linear infinite` } : {};
     }
     /**
      * 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
      */
     setScale(scale) {
         this.scale = Math.max(0.25, scale);
     }
     /**
      * 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
      */
     setCustomColors() {
         const colors = typeof this.colors === 'string' ? JSON.parse(this.colors) : this.colors;
@@ -78,19 +310,25 @@ export class VdsProgressCircular {
     }
     /**
      * Activates custom colors.
-     *
      * @private
-     * @param {Object} colors - The colors object.
-     * @returns {void}
+     * @param {{ [key: string]: string }} colors - The colors object
      */
     activateCustomColors(colors) {
         this.customColors = !!colors && (!!colors['backgroundTrack'] || !!colors['backgroundProgress']);
     }
+    /**
+     * Component lifecycle hook - initialize scale on load
+     * @private
+     */
     componentWillLoad() {
         this.setScale(this.scale);
     }
+    /**
+     * Render the circular progress component
+     * @returns {HTMLElement} The rendered circular progress element
+     */
     render() {
-        return (h(Host, { key: '5ead07229ac2b7ae9a2a94f01778d4382456f5c5', style: this.setCustomColors() }, h("div", { key: 'a7eb859248c6f997f9ef3a8f974ccfb92cb62dc6', class: combineClasses('vds-progress-circular__container', this.customColors ? 'vds-progress-circular__container--custom-colors' : 'vds-progress-circular__container--default-colors'), style: { '--size': `calc(3.5rem * ${this.scale})` } }, h("svg", { key: 'fec503b19a454e49475084a3fd6a9b9f6a746185', class: combineClasses('vds-progress-circular__track', `vds-progress-circular__track--${this.status}`), viewBox: "0 0 52 52" }, h("circle", { key: '8ad9dcd88148fa393e6328ecccb5643800aeeb39', cx: "26", cy: "26", r: "24", fill: "none" })), h("svg", { key: '89097d77ca783cd46ef0b3fbdc8d4e41f70548f7', class: combineClasses('vds-progress-circular__track-fill', `vds-progress-circular__track-fill--${this.status}`), style: this.setDurationAnimation(), viewBox: "0 0 52 52" }, h("circle", { key: '4180a218d83650d3174c7aabe76ff56e8931874f', cx: "26", cy: "26", r: "24", fill: "none", style: this.setProgress() })))));
+        return (h(Host, { key: '9779d8f18b3a160d5f98b519d47e0d3eb1cdbd85', style: this.setCustomColors() }, h("div", { key: '4b9d3fff6e8a791897dfd94fb94ab478aa96cf1e', class: combineClasses('vds-progress-circular__container', this.customColors ? 'vds-progress-circular__container--custom-colors' : 'vds-progress-circular__container--default-colors'), style: { '--size': `calc(3.5rem * ${this.scale})` } }, h("svg", { key: '7f6c4b4f963a9ffd7ad8a9ab93018d59fb7c6da3', class: combineClasses('vds-progress-circular__track', `vds-progress-circular__track--${this.status}`), viewBox: "0 0 52 52" }, h("circle", { key: 'eb35b07a1a05e00801a659377f86343421de6946', cx: "26", cy: "26", r: "24", fill: "none" })), h("svg", { key: '68b31c3177ce4d4731f1565f793363cd333240bd', class: combineClasses('vds-progress-circular__track-fill', `vds-progress-circular__track-fill--${this.status}`), style: this.setDurationAnimation(), viewBox: "0 0 52 52" }, h("circle", { key: '7864aad0822738aa1495c599e23852c51862a7b5', cx: "26", cy: "26", r: "24", fill: "none", style: this.setProgress() })))));
     }
     static get is() { return "vds-progress-circular"; }
     static get encapsulation() { return "shadow"; }
@@ -117,8 +355,11 @@ export class VdsProgressCircular {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the percentage filled value from 0 to 100"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{number}"
+                        }],
+                    "text": "The progress percentage to display in determinate mode. Clamped to `[0, 100]`.\nHas no visual effect when the indicator is in indeterminate mode (`duration > 0`).\n\n**Migration:** was `progress` in `volt-progress-indicator-circular`.\nUsing the old prop name silently shows no fill."
                 },
                 "getter": false,
                 "setter": false,
@@ -136,8 +377,14 @@ export class VdsProgressCircular {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Defines the color based on the status:\nerror -> color-background-critical-default,\nsuccess -> color-background-general-healthy-default,\ndefault -> color-background-brand-default"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{'error' | 'success' | 'default'}"
+                        }, {
+                            "name": "default",
+                            "text": "'default'"
+                        }],
+                    "text": "Semantic color of the progress ring fill.\n- `\"default\"` \u2014 brand blue (`color-background-brand-default`)\n- `\"success\"` \u2014 green (`color-background-general-healthy-default`)\n- `\"error\"` \u2014 red (`color-background-critical-default`)\n\n**Migration:** replaces the `color` BasePalette prop from `volt-progress-indicator-circular`.\nUse `status` for semantic intent, or the `colors` prop for fully custom tokens."
                 },
                 "getter": false,
                 "setter": false,
@@ -156,8 +403,14 @@ export class VdsProgressCircular {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the loop duration time for the indeterminate loop progress in miliseconds.\nDeterminate and indeterminate state will be defined by adding or not the duration."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{number}"
+                        }, {
+                            "name": "default",
+                            "text": "500"
+                        }],
+                    "text": "Controls both **animation speed** and **mode** (determinate vs indeterminate):\n- `0` \u2192 **determinate**: no animation, the ring shows the `value` percentage as a static fill.\n- `> 0` \u2192 **indeterminate**: the ring spins continuously; the number is the milliseconds\n  per full rotation (lower = faster). The `value` prop is ignored in this mode.\n\n**Migration:** the old `mode=\"determinate|indeterminate\"` prop is gone.\nSet `duration=\"0\"` to replicate `mode=\"determinate\"`.\nSet `duration > 0` to replicate `mode=\"indeterminate\"`."
                 },
                 "getter": false,
                 "setter": false,
@@ -176,8 +429,11 @@ export class VdsProgressCircular {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the aria label"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Accessible label announced by screen readers to describe the progress context.\nAlways provide this \u2014 there is no visible text label on the component.\n\nHTML attribute: `set-aria-label`"
                 },
                 "getter": false,
                 "setter": false,
@@ -195,8 +451,11 @@ export class VdsProgressCircular {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the progress indicator color from the Volt palette:\nbackgroundProgress - ThemeColors,\nbackgroundTrack - ThemeColors"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{{ [key: string]: string } | string}"
+                        }],
+                    "text": "Overrides the ring colors with specific Volt theme tokens.\nAccepts a JSON object or a JSON string (required when set as an HTML attribute).\nKeys are optional \u2014 omit either to keep the default for that part.\n\n- `backgroundTrack` \u2014 the empty (unfilled) part of the ring\n- `backgroundProgress` \u2014 the filled (progress) part of the ring\n\nToken values must be Volt CSS variable names **without** the `var(--)` wrapper.\n\n**Migration:** replaces the `color` BasePalette prop from `volt-progress-indicator-circular`.\nUse this prop when you need a specific color that `status` does not cover.\n\n```html\n<!-- HTML attribute (JSON string) -->\n<vds-progress-circular\n  colors='{\"backgroundTrack\": \"color-background-caution-default\", \"backgroundProgress\": \"color-background-healthy-default\"}'\n></vds-progress-circular>\n```\n\n```js\n// JS property (object)\nel.colors = { backgroundTrack: 'color-background-caution-default' };\n```"
                 },
                 "getter": false,
                 "setter": false,
@@ -214,8 +473,14 @@ export class VdsProgressCircular {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Set the size scale of the component based on 1 === 52px (3.5rem).\nCommon values:\n- 0.25 (extra small): 13px\n- 0.5 (small): 26px\n- 1 (medium): 52px\n- 1.5 (large): 78px\nMinimum scale is 0.25"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{number}"
+                        }, {
+                            "name": "default",
+                            "text": "1"
+                        }],
+                    "text": "Continuous size multiplier. Base size is `52px` (3.5rem) at `scale = 1`.\nThe minimum enforced value is `0.25` (13px).\n\nCommon values:\n- `0.25` \u2192 13px (extra small)\n- `0.5`  \u2192 26px (small)\n- `1`    \u2192 52px (medium, default)\n- `1.5`  \u2192 78px (large)\n- `2`    \u2192 104px (extra large)\n\n**Migration:** replaces the `size=\"sm|md|lg\"` prop from `volt-progress-indicator-circular`.\nEquivalent mappings: `sm` \u2192 `0.5`, `md` \u2192 `1`, `lg` \u2192 `2`."
                 },
                 "getter": false,
                 "setter": false,
@@ -240,4 +505,3 @@ export class VdsProgressCircular {
             }];
     }
 }
-//# sourceMappingURL=vds-progress-circular.js.map

package/dist/collection/components/progress-circular/vds-progress-circular.stories.js

@@ -93,4 +93,3 @@ customColorsUsage.args = {
     duration: 500,
     scale: 1,
 };
-//# sourceMappingURL=vds-progress-circular.stories.js.map

package/dist/collection/components/progress-linear/vds-progress-linear.css

@@ -509,6 +509,7 @@
   --spacing-18:4.25rem;
   --spacing-19:4.5rem;
   --spacing-20:4.75rem;
+  --spacing-21:5rem;
   --opacity-64:0.64;
   --opacity-32:0.32;
   --opacity-16:0.16;
@@ -761,6 +762,11 @@
   --elevation-layer-3:6;
   --elevation-layer-4:8;
   --elevation-layer-5:12;
+  --elevation-layer-6:16;
+  --elevation-layer-7:20;
+  --elevation-layer-8:24;
+  --elevation-layer-9:28;
+  --elevation-layer-10:32;
   --border-thickness-01:0.0625rem;
   --border-thickness-02:0.078125rem;
   --border-thickness-03:0.09375rem;
@@ -770,6 +776,16 @@
   --border-thickness-07:0.15625rem;
   --border-thickness-08:0.171875rem;
   --border-thickness-09:0.1875rem;
+  --duration-instant:0ms;
+  --duration-short:100ms;
+  --duration-medium:200ms;
+  --duration-long:300ms;
+  --duration-extra-long:500ms;
+  --easing-standard:cubic-bezier(0.2, 0, 0, 1);
+  --easing-emphasized:cubic-bezier(0.2, 0, 0, 1);
+  --easing-decelerate:cubic-bezier(0, 0, 0, 1);
+  --easing-accelerate:cubic-bezier(0.3, 0, 1, 1);
+  --easing-linear:linear;
 }
 
 :root body .vds-font-display-large {
@@ -893,17 +909,6 @@
   gap: var(--spacing-03);
 }
 
-.vds__menu--backdrop {
-  position: fixed;
-  top: 0;
-  left: 0;
-  width: 100%;
-  height: 100%;
-  background-color: rgba(0, 0, 0, 0.5);
-  backdrop-filter: grayscale(100%) opacity(0.5);
-  pointer-events: auto;
-}
-
 :host {
   display: block;
   z-index: var(--elevation-layer-5);