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

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

@@ -1,24 +1,275 @@
 import { HostElement } from '../../stencil-public-runtime';
 import { Colors, IconColors } from '../../definitions/colors';
+/**
+ * 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 declare class VdsIcon {
-    /** Set svg icon name to display */
+    /**
+     * Defines the icon source. Accepts four forms (evaluated in this order):
+     *
+     * 1. **Sprite name** — a plain string matching a Volt icon name (e.g. `"home"`, `"star"`).
+     *    Resolved against the built-in icon sprite. This is the standard usage.
+     * 2. **Inline SVG** — a raw `<svg>…</svg>` string. Rendered inline; `color` token applies.
+     * 3. **External SVG URL** — a URL ending in `.svg`. Fetched at load time and inlined;
+     *    `color` token applies.
+     * 4. **Image URL** — any other URL (PNG, JPG, etc.). Rendered as an `<img>`; `color` does NOT apply.
+     *
+     * **Migration:** this property was called `svgIconSrc` in `volt-icon`.
+     * Always use `svgIcon` (HTML attribute: `svg-icon`) in `vds-icon`.
+     *
+     * @type {string}
+     */
     svgIcon: string;
-    /** Set icon size in px or rem, IE: 1.25rem */
+    /**
+     * Sets the icon dimensions. Accepts any CSS length unit.
+     * - Single value sets both width and height equally: `"1.5rem"`, `"24px"`, `"2em"`.
+     * - Comma-separated pair sets width and height independently: `"32px,24px"`.
+     *
+     * Defaults to `1rem × 1rem` when not provided.
+     *
+     * @type {string}
+     */
     size: string;
-    /** Set icon color based in volt palette */
+    /**
+     * 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"
+     */
     color: IconColors | Colors;
-    /** Set alt text for accesibility */
+    /**
+     * Sets the accessible label for the icon.
+     * Provide a meaningful description when the icon conveys information.
+     * Omit for purely decorative icons.
+     *
+     * @type {string}
+     */
     alt: string;
+    /**
+     * Reference to the host element
+     * @type {HTMLDivElement}
+     */
     host: HTMLDivElement;
+    /**
+     * Stores the SVG content fetched from external URL
+     * @private
+     * @type {string}
+     */
     private svgContent;
+    /**
+     * Lifecycle hook that runs before component loads
+     * Fetches SVG content if svgIcon is a valid SVG URL
+     * @returns {Promise<void>}
+     */
     componentWillLoad(): Promise<void>;
+    /**
+     * 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'
+     */
     private isSvgString;
+    /**
+     * 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
+     */
     private isValidUrl;
+    /**
+     * 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
+     */
     private isInternalIcon;
+    /**
+     * Checks if the URL has a .svg extension
+     * @private
+     * @param {string} svgIcon - The URL to check
+     * @returns {boolean} True if URL ends with .svg
+     */
     private isValidSvgUrl;
+    /**
+     * 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
+     */
     private setSvgContent;
+    /**
+     * 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
+     */
     private fetchSvgContent;
+    /**
+     * 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
+     */
     private getSize;
+    /**
+     * Gets the SVG content from inline string, external URL, or internal sprite
+     * @private
+     * @returns {string} The SVG content to display
+     */
     private getSvgContent;
+    /**
+     * Renders the component
+     * @returns {HostElement} The rendered component
+     */
     render(): HostElement;
 }

package/dist/types/components/icon-button/vds-icon-button.d.ts

@@ -1,17 +1,82 @@
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @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 declare class VdsIconButton {
-    /** Set icon button's size */
+    /**
+     * Sets the icon button's size
+     * @type {"large" | "medium" | "small" | "extra-small"}
+     * @default "medium"
+     */
     size: "large" | "medium" | "small" | "extra-small";
-    /** Set icon button's variant */
+    /**
+     * Sets the icon button's visual variant
+     * @type {"primary" | "secondary" | "tertiary"}
+     * @default "primary"
+     */
     variant: "primary" | "secondary" | "tertiary";
-    /** Enable icon button's disable state */
+    /**
+     * Enables the icon button's disabled state
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Sets the icon inside icon button */
+    /**
+     * Sets the icon to display inside the button
+     * @type {string}
+     */
     icon: string;
-    /** Sets the button icon arial-label */
+    /**
+     * Sets the button's aria-label for accessibility
+     * @type {string}
+     */
     setAriaLabel: string;
+    /**
+     * Reference to the host element
+     * @type {HTMLVdsButtonElement}
+     */
     hostEl: HTMLVdsButtonElement;
+    /**
+     * Listens for click events to handle form submission
+     * @returns {void}
+     */
     handleSubmit(): void;
+    /**
+     * Submits the form if the button type is "submit"
+     * @private
+     * @returns {void}
+     */
     private submitForm;
+    /**
+     * Renders the component
+     * @returns {HTMLStencilElement} The rendered component
+     */
     render(): HTMLStencilElement;
 }