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

package/dist/collection/components/icon/vds-icon.js

@@ -2,20 +2,195 @@ import { Host, h } from "@stencil/core";
 import * as svgs from "../../constants/icon-sprite";
 import { combineClasses } from "../../utils/combine-classes";
 import { GenerateVdsSvg } from "../../utils/icon-generation.utils";
+/**
+ * Displays an SVG icon from the Volt internal sprite library, an inline SVG string,
+ * an external `.svg` URL, or any image URL (PNG, JPG, etc.). Size and color are
+ * controlled via dedicated props using Volt design tokens.
+ *
+ * This component has **no events** and **no public methods** — it is purely declarative.
+ *
+ * ---
+ * ## Migration note (volt-icon → vds-icon)
+ *
+ * **`volt-icon` must be replaced with `vds-icon`.**
+ * The `svgIconSrc` property from `volt-icon` was renamed to `svgIcon` in `vds-icon`.
+ * This is the most common migration mistake — using the old property name silently
+ * renders nothing because the prop is simply ignored.
+ *
+ * ```html
+ * <!-- Before (old volt-icon) -->
+ * <volt-icon svg-icon-src="home" size="1.5rem"></volt-icon>
+ *
+ * <!-- After (new vds-icon) — property renamed to svg-icon -->
+ * <vds-icon svg-icon="home" size="1.5rem"></vds-icon>
+ * ```
+ *
+ * **Migration checklist:**
+ * - Replace tag `volt-icon` → `vds-icon`
+ * - Replace attribute `svg-icon-src` → `svg-icon`
+ * - Replace JS property `svgIconSrc` → `svgIcon`
+ *
+ * ---
+ * ## Mode 1 — Internal sprite icon (recommended)
+ *
+ * Pass the icon name as a plain string. The component resolves it against the
+ * built-in Volt icon sprite. Use the Storybook Icon Collection story to browse
+ * all available names.
+ *
+ * ```html
+ * <vds-icon svg-icon="home" size="1.5rem" color="color-icon-high"></vds-icon>
+ * <vds-icon svg-icon="star" size="2rem"   color="color-icon-warning"></vds-icon>
+ * <vds-icon svg-icon="calendar" size="20px" color="color-icon-brand"></vds-icon>
+ * ```
+ *
+ * ---
+ * ## Mode 2 — Inline SVG string
+ *
+ * Pass a raw `<svg>…</svg>` string directly to `svg-icon`. Useful for one-off
+ * custom icons or icons generated at runtime. The `color` prop still applies.
+ *
+ * ```html
+ * <vds-icon
+ *   svg-icon='<svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M15.4624 2.41407C17.2587 2.01855 18.6488 3.97488 17.6844 5.54106L11.2391 16.0079C10.2496 17.6149 7.80416 17.1834 7.42439 15.3348L6.5649 11.1512C6.54844 11.071 6.49972 11.0012 6.43018 10.9581L2.98664 8.82337C1.39738 7.83814 1.81021 5.42017 3.63634 5.01807L15.4624 2.41407Z" fill="white"/></svg>'
+ *   size="3rem"
+ *   color="color-icon-brand"
+ *   alt="Custom send icon"
+ * ></vds-icon>
+ * ```
+ *
+ * ---
+ * ## Mode 3 — External SVG URL
+ *
+ * Pass a URL ending in `.svg`. The component fetches the file at load time and
+ * inlines its content, so the `color` token is still applied via CSS.
+ *
+ * ```html
+ * <vds-icon
+ *   svg-icon="https://example.com/assets/send.svg"
+ *   size="2rem"
+ *   color="color-icon-brand"
+ *   alt="Send icon"
+ * ></vds-icon>
+ * ```
+ *
+ * ---
+ * ## Mode 4 — External image URL (PNG, JPG, etc.)
+ *
+ * Pass any non-SVG image URL. The component renders an `<img>` tag.
+ * The `color` token is **not** applied in this mode.
+ *
+ * ```html
+ * <vds-icon
+ *   svg-icon="https://cdn-icons-png.flaticon.com/128/1865/1865273.png"
+ *   size="3rem"
+ *   alt="Custom image icon"
+ * ></vds-icon>
+ * ```
+ *
+ * ---
+ * ## Size
+ *
+ * `size` accepts any CSS length value. For a square icon use a single value;
+ * for a rectangular icon use the `"width,height"` comma format.
+ *
+ * ```html
+ * <!-- Square -->
+ * <vds-icon svg-icon="home" size="1rem"></vds-icon>
+ * <vds-icon svg-icon="home" size="24px"></vds-icon>
+ * <vds-icon svg-icon="home" size="2em"></vds-icon>
+ *
+ * <!-- Rectangular (width,height) -->
+ * <vds-icon svg-icon="home" size="32px,24px"></vds-icon>
+ * ```
+ *
+ * ---
+ * ## Color tokens
+ *
+ * Use semantic Volt icon color tokens for the `color` prop. The token is applied
+ * via CSS `currentColor` so it works for both sprite icons and inlined SVGs.
+ *
+ * | Token | Usage |
+ * |---|---|
+ * | `color-icon-high` | Primary / high-emphasis icons |
+ * | `color-icon-medium` | Secondary / medium-emphasis icons |
+ * | `color-icon-low` | Tertiary / low-emphasis icons |
+ * | `color-icon-disabled` | Disabled state |
+ * | `color-icon-brand` | Brand-colored icons |
+ * | `color-icon-healthy` | Success / healthy state |
+ * | `color-icon-caution` | Caution / informational state |
+ * | `color-icon-warning` | Warning state |
+ * | `color-icon-danger` | Error / danger state |
+ * | `color-icon-white-low` | White icons on dark backgrounds |
+ *
+ * ```html
+ * <vds-icon svg-icon="check-circle" color="color-icon-healthy" size="1.5rem"></vds-icon>
+ * <vds-icon svg-icon="warning"      color="color-icon-warning" size="1.5rem"></vds-icon>
+ * <vds-icon svg-icon="error"        color="color-icon-danger"  size="1.5rem"></vds-icon>
+ * ```
+ *
+ * ---
+ * ## Accessibility
+ *
+ * Always provide `alt` text when the icon conveys meaning. Omit it for purely
+ * decorative icons (the attribute defaults to an empty string).
+ *
+ * ```html
+ * <!-- Meaningful icon — include alt -->
+ * <vds-icon svg-icon="warning" alt="Warning: action required" size="1.5rem"></vds-icon>
+ *
+ * <!-- Decorative icon — omit alt -->
+ * <vds-icon svg-icon="chevron-right" size="1rem"></vds-icon>
+ * ```
+ *
+ * ---
+ * ## Slots
+ *
+ * This component has no public slots. Rendering is fully controlled by props.
+ *
+ * @component vds-icon
+ */
 export class VdsIcon {
     constructor() {
-        /** Set icon color based in volt palette */
-        this.color = 'static-brand-main';
+        /**
+         * Sets the icon color using a Volt semantic icon color token.
+         * Applied via CSS `currentColor` — effective for sprite icons and inlined SVGs only.
+         * Has no effect when `svgIcon` resolves to an image URL (`<img>` mode).
+         *
+         * Available tokens: `color-icon-high`, `color-icon-medium`, `color-icon-low`,
+         * `color-icon-disabled`, `color-icon-brand`, `color-icon-healthy`,
+         * `color-icon-caution`, `color-icon-warning`, `color-icon-danger`, `color-icon-white-low`.
+         *
+         * @type {IconColors | Colors}
+         * @default "color-icon-brand-default"
+         */
+        this.color = "color-icon-brand-default";
     }
+    /**
+     * Lifecycle hook that runs before component loads
+     * Fetches SVG content if svgIcon is a valid SVG URL
+     * @returns {Promise<void>}
+     */
     async componentWillLoad() {
         if (this.isValidUrl(this.svgIcon) && this.isValidSvgUrl(this.svgIcon)) {
             this.svgContent = await this.setSvgContent(this.svgIcon);
         }
     }
+    /**
+     * Checks if the svgIcon prop is an inline SVG string
+     * @private
+     * @param {string} svgIcon - The icon identifier to check
+     * @returns {boolean} True if svgIcon starts with '<svg'
+     */
     isSvgString(svgIcon) {
         var _a;
         return (_a = svgIcon === null || svgIcon === void 0 ? void 0 : svgIcon.trim().startsWith('<svg')) !== null && _a !== void 0 ? _a : false;
     }
+    /**
+     * Checks if the svgIcon prop is a valid URL
+     * @private
+     * @param {string} svgIcon - The icon identifier to check
+     * @returns {boolean} True if svgIcon is a valid URL
+     */
     isValidUrl(svgIcon) {
         try {
             new URL(svgIcon);
@@ -25,16 +200,40 @@ export class VdsIcon {
             return false;
         }
     }
+    /**
+     * Checks if the svgIcon exists in the internal icon sprite
+     * @private
+     * @param {string} svgIcon - The icon name to check
+     * @returns {boolean} True if icon exists in internal sprite
+     */
     isInternalIcon(svgIcon) {
         const icons = Object.keys(svgs.default);
         return icons.some(icon => icon === svgIcon + '.svg');
     }
+    /**
+     * Checks if the URL has a .svg extension
+     * @private
+     * @param {string} svgIcon - The URL to check
+     * @returns {boolean} True if URL ends with .svg
+     */
     isValidSvgUrl(svgIcon) {
         return svgIcon === null || svgIcon === void 0 ? void 0 : svgIcon.endsWith('.svg');
     }
+    /**
+     * Sets the SVG content by fetching from URL
+     * @private
+     * @param {string} svgIcon - The SVG URL to fetch
+     * @returns {Promise<string | null>} The SVG content or null if fetch fails
+     */
     async setSvgContent(svgIcon) {
         return await this.fetchSvgContent(svgIcon);
     }
+    /**
+     * Fetches SVG content from a URL
+     * @private
+     * @param {string} url - The URL to fetch SVG content from
+     * @returns {Promise<string | null>} The SVG content or null if fetch fails
+     */
     async fetchSvgContent(url) {
         try {
             const response = await fetch(url);
@@ -44,6 +243,12 @@ export class VdsIcon {
             return null;
         }
     }
+    /**
+     * Gets the icon size from the size prop
+     * Supports single value or comma-separated width,height format
+     * @private
+     * @returns {{width: string, height: string}} The width and height values
+     */
     getSize() {
         if (this.size && this.size.indexOf(',') > -1) {
             const sizes = this.size.split(',');
@@ -54,6 +259,11 @@ export class VdsIcon {
         }
         return { width: this.size ? this.size : '1rem', height: this.size ? this.size : '1rem' };
     }
+    /**
+     * Gets the SVG content from inline string, external URL, or internal sprite
+     * @private
+     * @returns {string} The SVG content to display
+     */
     getSvgContent() {
         if (this.isSvgString(this.svgIcon)) {
             return GenerateVdsSvg(this.svgIcon);
@@ -63,8 +273,12 @@ export class VdsIcon {
         }
         return svgs.default[`${this.svgIcon}.svg`];
     }
+    /**
+     * Renders the component
+     * @returns {HostElement} The rendered component
+     */
     render() {
-        return (h(Host, { key: '5ddd9d6c96d27900dca1dcdd678e7c65ec4bd9f0', class: combineClasses('volt-icon', `color-${this.color}`) }, this.isInternalIcon(this.svgIcon) || this.isSvgString(this.svgIcon) ?
+        return (h(Host, { key: '8bdfc921ed8b36b9f037ce9cdaf8a690e6ab944b', class: combineClasses('volt-icon', `color-${this.color}`) }, this.isInternalIcon(this.svgIcon) || this.isSvgString(this.svgIcon) ?
             (h("div", { part: "svg-icon", style: this.getSize(), class: combineClasses('volt-icon-svg'), innerHTML: this.getSvgContent() }))
             :
                 (h("img", { style: this.getSize(), src: this.svgIcon, alt: `${this.alt} icon` }))));
@@ -94,8 +308,11 @@ export class VdsIcon {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Set svg icon name to display"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Defines the icon source. Accepts four forms (evaluated in this order):\n\n1. **Sprite name** \u2014 a plain string matching a Volt icon name (e.g. `\"home\"`, `\"star\"`).\n   Resolved against the built-in icon sprite. This is the standard usage.\n2. **Inline SVG** \u2014 a raw `<svg>\u2026</svg>` string. Rendered inline; `color` token applies.\n3. **External SVG URL** \u2014 a URL ending in `.svg`. Fetched at load time and inlined;\n   `color` token applies.\n4. **Image URL** \u2014 any other URL (PNG, JPG, etc.). Rendered as an `<img>`; `color` does NOT apply.\n\n**Migration:** this property was called `svgIconSrc` in `volt-icon`.\nAlways use `svgIcon` (HTML attribute: `svg-icon`) in `vds-icon`."
                 },
                 "getter": false,
                 "setter": false,
@@ -113,8 +330,11 @@ export class VdsIcon {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Set icon size in px or rem, IE: 1.25rem"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Sets the icon dimensions. Accepts any CSS length unit.\n- Single value sets both width and height equally: `\"1.5rem\"`, `\"24px\"`, `\"2em\"`.\n- Comma-separated pair sets width and height independently: `\"32px,24px\"`.\n\nDefaults to `1rem \u00D7 1rem` when not provided."
                 },
                 "getter": false,
                 "setter": false,
@@ -126,31 +346,39 @@ export class VdsIcon {
                 "mutable": true,
                 "complexType": {
                     "original": "IconColors | Colors",
-                    "resolved": "\"color-background-disabled\" | \"color-background-brand-default\" | \"color-background-brand-hover\" | \"color-background-brand-press\" | \"color-background-caution-default\" | \"color-background-caution-lowest-default\" | \"color-background-caution-lowest-hover\" | \"color-background-caution-lowest-press\" | \"color-background-danger-default\" | \"color-background-danger-high-default\" | \"color-background-danger-high-hover\" | \"color-background-danger-high-press\" | \"color-background-danger-lowest-default\" | \"color-background-danger-lowest-hover\" | \"color-background-danger-lowest-press\" | \"color-background-general-default\" | \"color-background-general-lowest-default\" | \"color-background-general-lowest-hover\" | \"color-background-general-lowest-press\" | \"color-background-healthy-default\" | \"color-background-healthy-lowest-default\" | \"color-background-healthy-lowest-hover\" | \"color-background-healthy-lowest-press\" | \"color-background-information-default\" | \"color-background-information-lowest-default\" | \"color-background-information-lowest-hover\" | \"color-background-information-lowest-press\" | \"color-background-neutral-default\" | \"color-background-neutral-hover\" | \"color-background-neutral-press\" | \"color-background-neutral-lowest-default\" | \"color-background-neutral-lowest-hover\" | \"color-background-neutral-lowest-press\" | \"color-background-warning-default\" | \"color-background-warning-lowest-default\" | \"color-background-warning-lowest-hover\" | \"color-background-warning-lowest-press\" | \"color-border-high\" | \"color-border-medium\" | \"color-border-low\" | \"color-border-lower\" | \"color-border-lowest\" | \"color-border-brand\" | \"color-border-brand-hover\" | \"color-border-disabled\" | \"color-border-danger\" | \"color-border-healthy\" | \"color-border-caution\" | \"color-border-warning\" | \"color-border-information\" | \"color-border-general\" | \"color-border-focus-1\" | \"color-border-focus-2\" | \"color-border-white-high\" | \"color-border-white-medium\" | \"color-border-white-low\" | \"color-border-white-lower\" | \"color-border-white-lowest\" | \"color-icon-high\" | \"color-icon-medium\" | \"color-icon-low\" | \"color-icon-disabled\" | \"color-icon-healthy\" | \"color-icon-caution\" | \"color-icon-warning\" | \"color-icon-danger\" | \"color-icon-information\" | \"color-icon-general\" | \"color-icon-brand-default\" | \"color-icon-brand-hover\" | \"color-icon-brand-press\" | \"color-icon-white-high\" | \"color-icon-white-medium\" | \"color-icon-white-low\" | \"color-interaction-black-medium\" | \"color-interaction-black-low\" | \"color-interaction-black-lower\" | \"color-interaction-black-lowest\" | \"color-interaction-brand-medium\" | \"color-interaction-brand-low\" | \"color-interaction-brand-lower\" | \"color-interaction-brand-lowest\" | \"color-interaction-danger-medium\" | \"color-interaction-danger-low\" | \"color-interaction-danger-lower\" | \"color-interaction-danger-lowest\" | \"color-interaction-white-medium\" | \"color-interaction-white-low\" | \"color-interaction-white-lower\" | \"color-interaction-white-lowest\" | \"color-interaction-backdrop\" | \"color-link-default\" | \"color-link-hover\" | \"color-link-press\" | \"color-text-high\" | \"color-text-medium\" | \"color-text-low\" | \"color-text-disabled\" | \"color-text-brand\" | \"color-text-caution-high\" | \"color-text-caution-medium\" | \"color-text-danger-high\" | \"color-text-danger-medium\" | \"color-text-general-high\" | \"color-text-general-medium\" | \"color-text-healthy-high\" | \"color-text-healthy-medium\" | \"color-text-information-high\" | \"color-text-information-medium\" | \"color-text-warning-high\" | \"color-text-warning-medium\" | \"color-text-white-high\" | \"color-text-white-medium\" | \"color-text-white-low\" | \"surface-higher\" | \"surface-high\" | \"surface-medium\" | \"surface-low\" | \"surface-lower\" | \"surface-neutral-default\" | \"surface-neutral-hover\" | \"surface-neutral-press\" | \"surface-overlay-default\" | \"surface-overlay-hover\" | \"surface-overlay-press\" | \"surface-elevation-01\" | \"surface-elevation-02\" | \"surface-elevation-03\" | \"surface-elevation-04\" | \"box-shadow-color-01\" | \"box-shadow-color-02\" | \"static-brand-50\" | \"static-brand-100\" | \"static-brand-200\" | \"static-brand-300\" | \"static-brand-400\" | \"static-brand-500\" | \"static-brand-main\" | \"static-brand-600\" | \"static-brand-700\" | \"static-brand-800\" | \"static-brand-900\" | \"static-brand-950\" | \"static-brand-1000\" | \"static-brand-1000-medium\" | \"static-brand-1000-low\" | \"static-brand-1000-lower\" | \"static-brand-1000-lowest\" | \"static-green-50\" | \"static-green-100\" | \"static-green-200\" | \"static-green-300\" | \"static-green-400\" | \"static-green-500\" | \"static-green-main\" | \"static-green-600\" | \"static-green-700\" | \"static-green-800\" | \"static-green-900\" | \"static-green-950\" | \"static-grey-50\" | \"static-grey-100\" | \"static-grey-200\" | \"static-grey-300\" | \"static-grey-400\" | \"static-grey-500\" | \"static-grey-main\" | \"static-grey-600\" | \"static-grey-700\" | \"static-grey-800\" | \"static-grey-900\" | \"static-grey-950\" | \"static-neutral-50\" | \"static-neutral-100\" | \"static-neutral-200\" | \"static-neutral-300\" | \"static-neutral-400\" | \"static-neutral-500\" | \"static-neutral-main\" | \"static-neutral-600\" | \"static-neutral-700\" | \"static-neutral-800\" | \"static-neutral-900\" | \"static-neutral-950\" | \"static-neutral-400-medium\" | \"static-neutral-400-low\" | \"static-neutral-400-lower\" | \"static-neutral-800-medium\" | \"static-neutral-800-low\" | \"static-orange-50\" | \"static-orange-100\" | \"static-orange-200\" | \"static-orange-300\" | \"static-orange-400\" | \"static-orange-500\" | \"static-orange-main\" | \"static-orange-600\" | \"static-orange-700\" | \"static-orange-800\" | \"static-orange-900\" | \"static-orange-950\" | \"static-red-50\" | \"static-red-100\" | \"static-red-200\" | \"static-red-300\" | \"static-red-400\" | \"static-red-500\" | \"static-red-main\" | \"static-red-600\" | \"static-red-700\" | \"static-red-800\" | \"static-red-900\" | \"static-red-950\" | \"static-yellow-50\" | \"static-yellow-100\" | \"static-yellow-200\" | \"static-yellow-300\" | \"static-yellow-400\" | \"static-yellow-500\" | \"static-yellow-main\" | \"static-yellow-600\" | \"static-yellow-700\" | \"static-yellow-800\" | \"static-yellow-900\" | \"static-yellow-950\" | \"static-white\" | \"static-white-medium\" | \"static-white-low\" | \"static-white-lower\" | \"static-white-lowest\" | \"static-black\" | \"static-black-medium\" | \"static-black-low\" | \"static-black-lower\" | \"static-black-lowest\"",
+                    "resolved": "\"box-shadow-color-01\" | \"box-shadow-color-02\" | \"color-background-brand-default\" | \"color-background-brand-hover\" | \"color-background-brand-press\" | \"color-background-caution-default\" | \"color-background-caution-lowest-default\" | \"color-background-caution-lowest-hover\" | \"color-background-caution-lowest-press\" | \"color-background-danger-default\" | \"color-background-danger-high-default\" | \"color-background-danger-high-hover\" | \"color-background-danger-high-press\" | \"color-background-danger-lowest-default\" | \"color-background-danger-lowest-hover\" | \"color-background-danger-lowest-press\" | \"color-background-disabled\" | \"color-background-general-default\" | \"color-background-general-lowest-default\" | \"color-background-general-lowest-hover\" | \"color-background-general-lowest-press\" | \"color-background-healthy-default\" | \"color-background-healthy-lowest-default\" | \"color-background-healthy-lowest-hover\" | \"color-background-healthy-lowest-press\" | \"color-background-information-default\" | \"color-background-information-lowest-default\" | \"color-background-information-lowest-hover\" | \"color-background-information-lowest-press\" | \"color-background-neutral-default\" | \"color-background-neutral-hover\" | \"color-background-neutral-lowest-default\" | \"color-background-neutral-lowest-hover\" | \"color-background-neutral-lowest-press\" | \"color-background-neutral-press\" | \"color-background-warning-default\" | \"color-background-warning-lowest-default\" | \"color-background-warning-lowest-hover\" | \"color-background-warning-lowest-press\" | \"color-border-brand\" | \"color-border-brand-hover\" | \"color-border-caution\" | \"color-border-danger\" | \"color-border-disabled\" | \"color-border-focus-1\" | \"color-border-focus-2\" | \"color-border-general\" | \"color-border-healthy\" | \"color-border-high\" | \"color-border-information\" | \"color-border-low\" | \"color-border-lower\" | \"color-border-lowest\" | \"color-border-medium\" | \"color-border-warning\" | \"color-border-white-high\" | \"color-border-white-low\" | \"color-border-white-lower\" | \"color-border-white-lowest\" | \"color-border-white-medium\" | \"color-icon-brand-default\" | \"color-icon-brand-hover\" | \"color-icon-brand-press\" | \"color-icon-caution\" | \"color-icon-danger\" | \"color-icon-disabled\" | \"color-icon-general\" | \"color-icon-healthy\" | \"color-icon-high\" | \"color-icon-information\" | \"color-icon-low\" | \"color-icon-medium\" | \"color-icon-warning\" | \"color-icon-white-high\" | \"color-icon-white-low\" | \"color-icon-white-medium\" | \"color-interaction-backdrop\" | \"color-interaction-black-low\" | \"color-interaction-black-lower\" | \"color-interaction-black-lowest\" | \"color-interaction-black-medium\" | \"color-interaction-brand-low\" | \"color-interaction-brand-lower\" | \"color-interaction-brand-lowest\" | \"color-interaction-brand-medium\" | \"color-interaction-danger-low\" | \"color-interaction-danger-lower\" | \"color-interaction-danger-lowest\" | \"color-interaction-danger-medium\" | \"color-interaction-white-low\" | \"color-interaction-white-lower\" | \"color-interaction-white-lowest\" | \"color-interaction-white-medium\" | \"color-link-default\" | \"color-link-hover\" | \"color-link-press\" | \"color-text-brand\" | \"color-text-caution-high\" | \"color-text-caution-medium\" | \"color-text-danger-high\" | \"color-text-danger-medium\" | \"color-text-disabled\" | \"color-text-general-high\" | \"color-text-general-medium\" | \"color-text-healthy-high\" | \"color-text-healthy-medium\" | \"color-text-high\" | \"color-text-information-high\" | \"color-text-information-medium\" | \"color-text-low\" | \"color-text-medium\" | \"color-text-warning-high\" | \"color-text-warning-medium\" | \"color-text-white-high\" | \"color-text-white-low\" | \"color-text-white-medium\" | \"static-black\" | \"static-black-low\" | \"static-black-lower\" | \"static-black-lowest\" | \"static-black-medium\" | \"static-brand-100\" | \"static-brand-1000\" | \"static-brand-1000-low\" | \"static-brand-1000-lower\" | \"static-brand-1000-lowest\" | \"static-brand-1000-medium\" | \"static-brand-200\" | \"static-brand-300\" | \"static-brand-400\" | \"static-brand-50\" | \"static-brand-500\" | \"static-brand-600\" | \"static-brand-700\" | \"static-brand-800\" | \"static-brand-900\" | \"static-brand-950\" | \"static-brand-main\" | \"static-green-100\" | \"static-green-200\" | \"static-green-300\" | \"static-green-400\" | \"static-green-50\" | \"static-green-500\" | \"static-green-600\" | \"static-green-700\" | \"static-green-800\" | \"static-green-900\" | \"static-green-950\" | \"static-green-main\" | \"static-grey-100\" | \"static-grey-200\" | \"static-grey-300\" | \"static-grey-400\" | \"static-grey-50\" | \"static-grey-500\" | \"static-grey-600\" | \"static-grey-700\" | \"static-grey-800\" | \"static-grey-900\" | \"static-grey-950\" | \"static-grey-main\" | \"static-neutral-100\" | \"static-neutral-200\" | \"static-neutral-300\" | \"static-neutral-400\" | \"static-neutral-400-low\" | \"static-neutral-400-lower\" | \"static-neutral-400-medium\" | \"static-neutral-50\" | \"static-neutral-500\" | \"static-neutral-600\" | \"static-neutral-700\" | \"static-neutral-800\" | \"static-neutral-800-low\" | \"static-neutral-800-medium\" | \"static-neutral-900\" | \"static-neutral-950\" | \"static-neutral-main\" | \"static-orange-100\" | \"static-orange-200\" | \"static-orange-300\" | \"static-orange-400\" | \"static-orange-50\" | \"static-orange-500\" | \"static-orange-600\" | \"static-orange-700\" | \"static-orange-800\" | \"static-orange-900\" | \"static-orange-950\" | \"static-orange-main\" | \"static-red-100\" | \"static-red-200\" | \"static-red-300\" | \"static-red-400\" | \"static-red-50\" | \"static-red-500\" | \"static-red-600\" | \"static-red-700\" | \"static-red-800\" | \"static-red-900\" | \"static-red-950\" | \"static-red-main\" | \"static-white\" | \"static-white-low\" | \"static-white-lower\" | \"static-white-lowest\" | \"static-white-medium\" | \"static-yellow-100\" | \"static-yellow-200\" | \"static-yellow-300\" | \"static-yellow-400\" | \"static-yellow-50\" | \"static-yellow-500\" | \"static-yellow-600\" | \"static-yellow-700\" | \"static-yellow-800\" | \"static-yellow-900\" | \"static-yellow-950\" | \"static-yellow-main\" | \"surface-elevation-01\" | \"surface-elevation-02\" | \"surface-elevation-03\" | \"surface-elevation-04\" | \"surface-high\" | \"surface-higher\" | \"surface-low\" | \"surface-lower\" | \"surface-medium\" | \"surface-neutral-default\" | \"surface-neutral-hover\" | \"surface-neutral-press\" | \"surface-overlay-default\" | \"surface-overlay-hover\" | \"surface-overlay-press\"",
                     "references": {
                         "IconColors": {
                             "location": "import",
                             "path": "../../definitions/colors",
-                            "id": "src/definitions/colors.ts::IconColors"
+                            "id": "src/definitions/colors.ts::IconColors",
+                            "referenceLocation": "IconColors"
                         },
                         "Colors": {
                             "location": "import",
                             "path": "../../definitions/colors",
-                            "id": "src/definitions/colors.ts::Colors"
+                            "id": "src/definitions/colors.ts::Colors",
+                            "referenceLocation": "Colors"
                         }
                     }
                 },
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Set icon color based in volt palette"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{IconColors | Colors}"
+                        }, {
+                            "name": "default",
+                            "text": "\"color-icon-brand-default\""
+                        }],
+                    "text": "Sets the icon color using a Volt semantic icon color token.\nApplied via CSS `currentColor` \u2014 effective for sprite icons and inlined SVGs only.\nHas no effect when `svgIcon` resolves to an image URL (`<img>` mode).\n\nAvailable tokens: `color-icon-high`, `color-icon-medium`, `color-icon-low`,\n`color-icon-disabled`, `color-icon-brand`, `color-icon-healthy`,\n`color-icon-caution`, `color-icon-warning`, `color-icon-danger`, `color-icon-white-low`."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": false,
                 "attribute": "color",
-                "defaultValue": "'static-brand-main'"
+                "defaultValue": "\"color-icon-brand-default\""
             },
             "alt": {
                 "type": "string",
@@ -163,8 +391,11 @@ export class VdsIcon {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Set alt text for accesibility"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Sets the accessible label for the icon.\nProvide a meaningful description when the icon conveys information.\nOmit for purely decorative icons."
                 },
                 "getter": false,
                 "setter": false,
@@ -175,4 +406,3 @@ export class VdsIcon {
     }
     static get elementRef() { return "host"; }
 }
-//# sourceMappingURL=vds-icon.js.map

package/dist/collection/components/icon/vds-icon.stories.js

@@ -212,4 +212,3 @@ IconList.args = {
     list: ICON_LIST,
     title: "Icon list",
 };
-//# sourceMappingURL=vds-icon.stories.js.map

package/dist/collection/components/icon-button/vds-icon-button.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: inline-block;
   width: fit-content;
@@ -932,11 +937,11 @@
 :host .vds-icon-button__variant--primary {
   background-color: transparent;
   border-color: transparent;
-  color: var(--color-text-brand);
+  color: var(--color-icon-brand-default);
 }
 :host .vds-icon-button__variant--primary vds-icon {
-  color: var(--color-text-brand);
-  fill: var(--color-text-brand);
+  color: var(--color-icon-brand-default);
+  fill: var(--color-icon-brand-default);
 }
 :host .vds-icon-button__variant--primary:hover {
   background: var(--color-interaction-brand-lowest);

package/dist/collection/components/icon-button/vds-icon-button.js

@@ -3,25 +3,80 @@ import { shadowSubmitForm } from "../../utils/form";
 import { combineClasses } from "../../utils/combine-classes";
 import { cloneAttributes } from "../../utils/clone-attributes";
 import { ICON_SIZE } from "./vds-icon-button.utils";
+/**
+ * @component vds-icon-button
+ * @description Icon button component that displays a clickable button with an icon, supporting multiple sizes and variants
+ * @example
+ * <!-- Primary icon button (default) -->
+ * <vds-icon-button icon="hamburger" set-aria-label="Open menu"></vds-icon-button>
+ *
+ * <!-- Secondary variant with small size -->
+ * <vds-icon-button
+ *   icon="close"
+ *   variant="secondary"
+ *   size="small"
+ *   set-aria-label="Close">
+ * </vds-icon-button>
+ *
+ * <!-- Disabled tertiary icon button -->
+ * <vds-icon-button
+ *   icon="module-settings"
+ *   variant="tertiary"
+ *   disabled
+ *   set-aria-label="Settings">
+ * </vds-icon-button>
+ *
+ * <!-- Large primary icon button -->
+ * <vds-icon-button
+ *   icon="magnify"
+ *   size="large"
+ *   set-aria-label="Search">
+ * </vds-icon-button>
+ */
 export class VdsIconButton {
     constructor() {
-        /** Set icon button's size */
+        /**
+         * Sets the icon button's size
+         * @type {"large" | "medium" | "small" | "extra-small"}
+         * @default "medium"
+         */
         this.size = "medium";
-        /** Set icon button's variant */
+        /**
+         * Sets the icon button's visual variant
+         * @type {"primary" | "secondary" | "tertiary"}
+         * @default "primary"
+         */
         this.variant = "primary";
-        /** Enable icon button's disable state */
+        /**
+         * Enables the icon button's disabled state
+         * @type {boolean}
+         * @default false
+         */
         this.disabled = false;
     }
+    /**
+     * Listens for click events to handle form submission
+     * @returns {void}
+     */
     handleSubmit() {
         if (this.hostEl.getAttribute("type") === "submit") {
             this.submitForm();
         }
     }
+    /**
+     * Submits the form if the button type is "submit"
+     * @private
+     * @returns {void}
+     */
     submitForm() {
         shadowSubmitForm(this.hostEl);
     }
+    /**
+     * Renders the component
+     * @returns {HTMLStencilElement} The rendered component
+     */
     render() {
-        return (h(Host, { key: '8ce2c379d57f2f4122451042b38c30dad6cca41a', class: combineClasses(`vds-icon-button`, this.disabled ? "vds-icon-button--disabled" : "") }, h("button", Object.assign({ key: 'bea8493fc9652c0799890f4256aa12d26a9b611c', class: combineClasses(`vds-icon-button__element`, `vds-icon-button__variant--${this.variant}`, `vds-icon-button__size--${this.size}`, this.disabled ? "vds-icon-button-disabled" : ""), "aria-label": this.setAriaLabel, type: "button", disabled: this.disabled || null }, cloneAttributes(this.hostEl, "disabled", "class", "style")), h("vds-icon", { key: '5ec08546a2a73ca3fe43f4da7342f1cbe83a81c9', "svg-icon": this.icon, size: ICON_SIZE[this.size] }))));
+        return (h(Host, { key: 'b079902fe9f47682c975520c877cc0a6197c814f', class: combineClasses(`vds-icon-button`, this.disabled ? "vds-icon-button--disabled" : "") }, h("button", Object.assign({ key: 'e08ab284df9a9da819020709d1cb44972947eaad', class: combineClasses(`vds-icon-button__element`, `vds-icon-button__variant--${this.variant}`, `vds-icon-button__size--${this.size}`, this.disabled ? "vds-icon-button-disabled" : ""), "aria-label": this.setAriaLabel, type: "button", disabled: this.disabled || null }, cloneAttributes(this.hostEl, "disabled", "class", "style")), h("vds-icon", { key: 'd872025e1ca51902ba756fa2920def2087a0e695', "svg-icon": this.icon, size: ICON_SIZE[this.size] }))));
     }
     static get is() { return "vds-icon-button"; }
     static get encapsulation() { return "shadow"; }
@@ -48,8 +103,14 @@ export class VdsIconButton {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Set icon button's size"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"large\" | \"medium\" | \"small\" | \"extra-small\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"medium\""
+                        }],
+                    "text": "Sets the icon button's size"
                 },
                 "getter": false,
                 "setter": false,
@@ -68,8 +129,14 @@ export class VdsIconButton {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Set icon button's variant"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"primary\" | \"secondary\" | \"tertiary\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"primary\""
+                        }],
+                    "text": "Sets the icon button's visual variant"
                 },
                 "getter": false,
                 "setter": false,
@@ -88,8 +155,14 @@ export class VdsIconButton {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Enable icon button's disable state"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Enables the icon button's disabled state"
                 },
                 "getter": false,
                 "setter": false,
@@ -108,8 +181,11 @@ export class VdsIconButton {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the icon inside icon button"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Sets the icon to display inside the button"
                 },
                 "getter": false,
                 "setter": false,
@@ -127,8 +203,11 @@ export class VdsIconButton {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the button icon arial-label"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Sets the button's aria-label for accessibility"
                 },
                 "getter": false,
                 "setter": false,
@@ -148,4 +227,3 @@ export class VdsIconButton {
             }];
     }
 }
-//# sourceMappingURL=vds-icon-button.js.map

package/dist/collection/components/icon-button/vds-icon-button.stories.js

@@ -95,4 +95,3 @@ Tertiary.args = {
     icon: "copy",
     disabled: false
 };
-//# sourceMappingURL=vds-icon-button.stories.js.map

package/dist/collection/components/icon-button/vds-icon-button.utils.js

@@ -4,4 +4,3 @@ export const ICON_SIZE = {
     "medium": "1.25rem",
     "large": "1.5rem",
 };
-//# sourceMappingURL=vds-icon-button.utils.js.map