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

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

@@ -1,18 +1,231 @@
+/**
+ * @component vds-button
+ * @description A button component that supports various sizes, variants, and states. Handles form submission and provides flexible layout options with icon slots.
+ * @example
+ * <!-- Primary button (default) -->
+ * <vds-button>Click Me</vds-button>
+ *
+ * @example
+ * <!-- Secondary variant button -->
+ * <vds-button variant="secondary">Secondary Action</vds-button>
+ *
+ * @example
+ * <!-- Tertiary variant button -->
+ * <vds-button variant="tertiary">Tertiary Action</vds-button>
+ *
+ * @example
+ * <!-- Ghost variant button -->
+ * <vds-button variant="ghost">Ghost Action</vds-button>
+ *
+ * @example
+ * <!-- Ghost alt variant button -->
+ * <vds-button variant="ghost-alt">Ghost Alt Action</vds-button>
+ *
+ * @example
+ * <!-- Large size button -->
+ * <vds-button size="large">Large Button</vds-button>
+ *
+ * @example
+ * <!-- Small size button -->
+ * <vds-button size="small">Small Button</vds-button>
+ *
+ * @example
+ * <!-- Button with left icon -->
+ * <vds-button>
+ *   <vds-icon slot="icon-left" svg-icon="add"></vds-icon>
+ *   Create New
+ * </vds-button>
+ *
+ * @example
+ * <!-- Button with right icon -->
+ * <vds-button variant="secondary">
+ *   Download
+ *   <vds-icon slot="icon-right" svg-icon="download"></vds-icon>
+ * </vds-button>
+ *
+ * @example
+ * <!-- Button with both icons -->
+ * <vds-button>
+ *   <vds-icon slot="icon-left" svg-icon="upload"></vds-icon>
+ *   Upload File
+ *   <vds-icon slot="icon-right" svg-icon="chevron-right"></vds-icon>
+ * </vds-button>
+ *
+ * @example
+ * <!-- Disabled button -->
+ * <vds-button disabled="true">Disabled Button</vds-button>
+ *
+ * @example
+ * <!-- Danger button -->
+ * <vds-button danger="true">Delete</vds-button>
+ *
+ * @example
+ * <!-- Danger secondary button -->
+ * <vds-button variant="secondary" danger="true">
+ *   <vds-icon slot="icon-left" svg-icon="trash"></vds-icon>
+ *   Remove Item
+ * </vds-button>
+ *
+ * @example
+ * <!-- Full width button -->
+ * <vds-button is-full-width="true">Full Width Button</vds-button>
+ *
+ * @example
+ * <!-- Button with left text alignment -->
+ * <vds-button text-alignment="left" is-full-width="true">
+ *   <vds-icon slot="icon-left" svg-icon="home"></vds-icon>
+ *   Go to Dashboard
+ * </vds-button>
+ *
+ * @example
+ * <!-- Button with right text alignment -->
+ * <vds-button text-alignment="right" is-full-width="true">
+ *   Next Step
+ *   <vds-icon slot="icon-right" svg-icon="arrow-right"></vds-icon>
+ * </vds-button>
+ *
+ * @example
+ * <!-- Submit button in form -->
+ * <form id="myForm">
+ *   <vds-basic-input placeholder="Enter text"></vds-basic-input>
+ *   <vds-button type="submit">Submit</vds-button>
+ * </form>
+ *
+ * @example
+ * <!-- Button group with different variants -->
+ * <div style="display: flex; gap: 8px;">
+ *   <vds-button variant="primary">Save</vds-button>
+ *   <vds-button variant="secondary">Cancel</vds-button>
+ * </div>
+ *
+ * @example
+ * <!-- Action buttons with icons -->
+ * <div style="display: flex; gap: 8px;">
+ *   <vds-button size="small">
+ *     <vds-icon slot="icon-left" svg-icon="edit"></vds-icon>
+ *     Edit
+ *   </vds-button>
+ *   <vds-button size="small" variant="secondary">
+ *     <vds-icon slot="icon-left" svg-icon="copy"></vds-icon>
+ *     Copy
+ *   </vds-button>
+ *   <vds-button size="small" variant="secondary" danger="true">
+ *     <vds-icon slot="icon-left" svg-icon="trash"></vds-icon>
+ *     Delete
+ *   </vds-button>
+ * </div>
+ *
+ * @example
+ * <!-- Confirmation dialog buttons -->
+ * <div style="display: flex; gap: 12px; justify-content: flex-end;">
+ *   <vds-button variant="ghost">Cancel</vds-button>
+ *   <vds-button>Confirm</vds-button>
+ * </div>
+ *
+ * @example
+ * <!-- Loading state button -->
+ * <vds-button disabled="true">
+ *   <vds-progress-circular slot="icon-left" size="small"></vds-progress-circular>
+ *   Processing...
+ * </vds-button>
+ *
+ * @example
+ * <!-- Navigation buttons -->
+ * <div style="display: flex; justify-content: space-between;">
+ *   <vds-button variant="secondary">
+ *     <vds-icon slot="icon-left" svg-icon="arrow-left"></vds-icon>
+ *     Previous
+ *   </vds-button>
+ *   <vds-button>
+ *     Next
+ *     <vds-icon slot="icon-right" svg-icon="arrow-right"></vds-icon>
+ *   </vds-button>
+ * </div>
+ *
+ * @example
+ * <!-- Call-to-action button -->
+ * <vds-button size="large" is-full-width="true">
+ *   Get Started
+ *   <vds-icon slot="icon-right" svg-icon="chevron-right"></vds-icon>
+ * </vds-button>
+ *
+ * @example
+ * <!-- Toolbar buttons -->
+ * <div style="display: flex; gap: 4px; align-items: center;">
+ *   <vds-button variant="ghost" size="small">
+ *     <vds-icon slot="icon-left" svg-icon="save"></vds-icon>
+ *     Save
+ *   </vds-button>
+ *   <vds-button variant="ghost" size="small">
+ *     <vds-icon slot="icon-left" svg-icon="print"></vds-icon>
+ *     Print
+ *   </vds-button>
+ *   <vds-button variant="ghost" size="small">
+ *     <vds-icon slot="icon-left" svg-icon="share"></vds-icon>
+ *     Share
+ *   </vds-button>
+ * </div>
+ *
+ * @slot - The default slot for button text content
+ * @slot icon-left - Slot for icon positioned at the left side of the button text
+ * @slot icon-right - Slot for icon positioned at the right side of the button text
+ */
 export declare class VdsButton {
-    /** Set button's size */
+    /**
+     * Set button's size
+     * @type {"large" | "medium" | "small"}
+     * @default "medium"
+     */
     size: "large" | "medium" | "small";
-    /** Set button's variant */
+    /**
+     * Set button's variant
+     * @type {"primary" | "secondary" | "tertiary" | "ghost" | "ghost-alt"}
+     * @default "primary"
+     */
     variant: "primary" | "secondary" | "tertiary" | "ghost" | "ghost-alt";
-    /** Allow to change the button's text alignment */
+    /**
+     * Allow to change the button's text alignment
+     * @type {"right" | "left" | "center"}
+     * @default "center"
+     */
     textAlignment: "right" | "left" | "center";
-    /** Enable button's danger/error state */
+    /**
+     * Enable button's danger/error state
+     * @type {boolean}
+     * @default false
+     */
     danger: boolean;
-    /** Enable button's disable state */
+    /**
+     * Enable button's disable state
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Enable button's full width. This prop permits to the component will be adaptable to the container available horizontal space. */
+    /**
+     * Enable button's full width. This prop permits the component to be adaptable to the container's available horizontal space.
+     * @type {boolean}
+     * @default false
+     */
     isFullWidth: boolean;
+    /**
+     * Reference to the host element
+     * @type {HTMLButtonElement}
+     */
     hostEl: HTMLButtonElement;
-    handleSubmit(event: Event): void;
+    /**
+     * Handles button click events and form submission
+     * @param {Event} event - The click event
+     * @returns {void}
+     */ handleSubmit(event: Event): void;
+    /**
+     * Submits the form associated with the button
+     * @private
+     * @returns {void}
+     */
     private submitForm;
+    /**
+     * Renders the button component
+     * @returns {JSX.Element} The rendered button element
+     */
     render(): any;
 }

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

@@ -111,3 +111,5 @@ export declare const Danger: {
         isFullWidth: boolean;
     };
 };
+export declare const CustomColorsUsage: any;
+export declare const CustomLayoutOverride: any;

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

@@ -2,48 +2,372 @@ import { HTMLStencilElement, EventEmitter } from '../../stencil-public-runtime';
 import { Colors } from '../../definitions/colors';
 import { Spacing } from '../../definitions/spacing';
 import { ShadowBox } from '../../definitions/shadows';
+/**
+ * A versatile content container that can function as a static surface, a selectable item
+ * (like a checkbox), or a clickable button. Supports four visual variants, configurable
+ * spacing tokens, elevation shadows, and full CSS custom property theming.
+ *
+ * All content — including headers and titles — is placed in the **default slot**.
+ *
+ * ---
+ * ## Migration note (volt-card / volt-card-header / volt-card-title → vds-card)
+ *
+ * **`volt-card` must be replaced with `vds-card`.**
+ * `volt-card-header` and `volt-card-title` **no longer exist** as components in the new system.
+ * Migrating to `vds-card-header` or `vds-card-title` will fail silently — those tags are
+ * unknown and render nothing.
+ *
+ * ### 1. volt-card-header is removed
+ *
+ * There is no `vds-card-header`. Use a native `<header>` or `<div>` element inside
+ * the `vds-card` slot to replicate the visual grouping.
+ *
+ * ```html
+ * <!-- Before -->
+ * <volt-card padding="md">
+ *   <volt-card-header>
+ *     Header content here
+ *   </volt-card-header>
+ * </volt-card>
+ *
+ * <!-- After — use a native element in the slot -->
+ * <vds-card padding="spacing-05">
+ *   <header>Header content here</header>
+ * </vds-card>
+ * ```
+ *
+ * ### 2. volt-card-title is removed
+ *
+ * There is no `vds-card-title`. Use a native heading element (`<h1>`–`<h6>`) with a
+ * Volt typography utility class inside the slot. Pick the heading level that is semantically
+ * correct for the page hierarchy (accessibility requirement).
+ *
+ * ```html
+ * <!-- Before — element prop controlled heading tag -->
+ * <volt-card padding="md">
+ *   <volt-card-header>
+ *     <volt-card-title element="h2">Card Title</volt-card-title>
+ *   </volt-card-header>
+ *   Body content here.
+ * </volt-card>
+ *
+ * <!-- After — native heading with Volt typography class -->
+ * <vds-card padding="spacing-05">
+ *   <h2 class="vds-font-title-medium">Card Title</h2>
+ *   <p>Body content here.</p>
+ * </vds-card>
+ * ```
+ *
+ * ### 3. padding token system changed
+ *
+ * Old named tokens map to new numeric spacing tokens:
+ *
+ * | volt-card (`padding`) | vds-card (`padding`) | Value |
+ * |---|---|---|
+ * | `xs` | `spacing-02` | 0.25rem |
+ * | `sm` | `spacing-03` | 0.5rem |
+ * | `md` | `spacing-05` | 1rem |
+ * | `lg` | `spacing-07` | 1.5rem |
+ * | `lg2` | `spacing-08` | 1.75rem |
+ * | `xl` | `spacing-09` | 2rem |
+ * | `xxl` | `spacing-11` | 2.5rem |
+ *
+ * **Full migration checklist:**
+ * - Replace tag `volt-card` → `vds-card`
+ * - Remove `volt-card-header` — replace with a native `<header>` or `<div>`
+ * - Remove `volt-card-title` — replace with a native `<h1>`–`<h6>` and a Volt typography class
+ * - Update `padding` value to the new `spacing-XX` token
+ *
+ * ---
+ * ## Basic usage
+ *
+ * ```html
+ * <!-- Static content card -->
+ * <vds-card padding="spacing-05">
+ *   <p>Card content goes here.</p>
+ * </vds-card>
+ *
+ * <!-- Card with title and body (replaces volt-card-header + volt-card-title) -->
+ * <vds-card padding="spacing-05">
+ *   <h2 class="vds-font-title-medium">Card Title</h2>
+ *   <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
+ * </vds-card>
+ *
+ * <!-- Card with header section and actions -->
+ * <vds-card padding="spacing-07">
+ *   <header style="display:flex; justify-content:space-between; align-items:center; margin-bottom:1rem;">
+ *     <h3 class="vds-font-title-small">Settings</h3>
+ *     <vds-button size="small">Edit</vds-button>
+ *   </header>
+ *   <p>Body content here.</p>
+ * </vds-card>
+ * ```
+ *
+ * ---
+ * ## Variants
+ *
+ * ```html
+ * <vds-card variant="default"   padding="spacing-05"><p>Default</p></vds-card>
+ * <vds-card variant="primary"   padding="spacing-05"><p>Primary</p></vds-card>
+ * <vds-card variant="secondary" padding="spacing-05"><p>Secondary</p></vds-card>
+ * <vds-card variant="danger"    padding="spacing-05"><p>Danger</p></vds-card>
+ * ```
+ *
+ * ---
+ * ## Shadow levels
+ *
+ * ```html
+ * <vds-card shadow-box="elevation-shadow-0"  padding="spacing-05"><p>No shadow</p></vds-card>
+ * <vds-card shadow-box="elevation-shadow-1"  padding="spacing-05"><p>Level 1 (default)</p></vds-card>
+ * <vds-card shadow-box="elevation-shadow-2"  padding="spacing-05"><p>Level 2</p></vds-card>
+ * <vds-card shadow-box="elevation-shadow-3"  padding="spacing-05"><p>Level 3</p></vds-card>
+ * <vds-card shadow-box="elevation-shadow-5"  padding="spacing-05"><p>Level 5</p></vds-card>
+ * <vds-card shadow-box="elevation-shadow-8"  padding="spacing-05"><p>Level 8</p></vds-card>
+ * <vds-card shadow-box="elevation-shadow-17" padding="spacing-05"><p>Level 17</p></vds-card>
+ * ```
+ *
+ * ---
+ * ## Selectable card
+ *
+ * Use `selectable="true"` to let users toggle the card between selected and unselected.
+ * Read or set the state via the `selected` prop. Emits `select` with the new boolean value
+ * on every toggle. **Cannot be combined with `button`.**
+ *
+ * ```html
+ * <vds-card selectable="true" padding="spacing-05">
+ *   <p>Click to select</p>
+ * </vds-card>
+ *
+ * <!-- Pre-selected -->
+ * <vds-card selectable="true" selected="true" padding="spacing-05">
+ *   <p>Already selected</p>
+ * </vds-card>
+ * ```
+ *
+ * ```js
+ * document.querySelector('vds-card').addEventListener('select', (e) => {
+ *   console.log('selected:', e.detail); // true | false
+ * });
+ * ```
+ *
+ * ---
+ * ## Button card (entire surface is clickable)
+ *
+ * Use `button="true"` when the whole card should act as a single action. Emits `click`
+ * with the native `MouseEvent`. **Cannot be combined with `selectable`.**
+ *
+ * ```html
+ * <vds-card button="true" padding="spacing-05">
+ *   <p>Click anywhere on the card</p>
+ * </vds-card>
+ * ```
+ *
+ * ```js
+ * document.querySelector('vds-card').addEventListener('click', (e) => {
+ *   console.log('card clicked', e.detail);
+ * });
+ * ```
+ *
+ * ---
+ * ## Disabled state
+ *
+ * ```html
+ * <vds-card disabled="true" selectable="true" padding="spacing-05">
+ *   <p>Not interactive</p>
+ * </vds-card>
+ * ```
+ *
+ * ---
+ * ## Cards side by side
+ *
+ * ```html
+ * <div style="display:flex; gap:1rem;">
+ *   <vds-card padding="spacing-05" style="flex:1;">
+ *     <h3 class="vds-font-title-small">Card A</h3>
+ *     <p>Short content.</p>
+ *   </vds-card>
+ *   <vds-card padding="spacing-05" style="flex:1;">
+ *     <h3 class="vds-font-title-small">Card B</h3>
+ *     <p>Longer content that makes this card taller.</p>
+ *   </vds-card>
+ * </div>
+ * ```
+ *
+ * ---
+ * ## Custom styles (CSS custom properties)
+ *
+ * Override per-variant tokens on the element or a parent selector.
+ * All values must be CSS color values or references to Volt design tokens.
+ *
+ * ```css
+ * vds-card {
+ *   /​* Default variant *​/
+ *   --vds-card-default-border-color: var(--color-background-healthy-lowest-press);
+ *   --vds-card-default-border-hover-color: var(--color-border-healthy);
+ *   --vds-card-default-border-press-color: var(--color-border-healthy);
+ *   --vds-card-default-background-color: var(--color-background-healthy-lowest-default);
+ *   --vds-card-default-background-hover-color: var(--color-background-healthy-lowest-hover);
+ *   --vds-card-default-background-press-color: var(--color-background-healthy-lowest-press);
+ *   --vds-card-default-selected-border-color: var(--color-border-healthy);
+ *   --vds-card-default-selected-background-color: var(--color-background-healthy-lowest-hover);
+ *
+ *   /​* Primary variant *​/
+ *   --vds-card-primary-border-hover-color: var(--color-interaction-brand-low);
+ *   --vds-card-primary-background-color: var(--color-background-information-lowest-default);
+ *   --vds-card-primary-background-hover-color: var(--color-background-information-lowest-hover);
+ *   --vds-card-primary-background-press-color: var(--color-background-information-lowest-press);
+ *   --vds-card-primary-selected-border-color: var(--color-interaction-brand-lower);
+ *   --vds-card-primary-selected-background-color: var(--color-background-information-lowest-hover);
+ * }
+ * ```
+ *
+ * ---
+ * ## Slots
+ *
+ * | Slot | Description |
+ * |---|---|
+ * | *(default)* | All card content — titles, body text, actions, nested components. There are no named slots. |
+ *
+ * Since `volt-card-header` and `volt-card-title` are removed, place titles and header
+ * sections directly in this slot using native HTML elements.
+ *
+ * @component vds-card
+ */
 export declare class VdsCard {
-    /** Padding of component based on volt-spacing tokens */
+    /**
+     * Internal padding of the card using Volt spacing tokens (`spacing-00` – `spacing-21`).
+     *
+     * **Migration:** the old `volt-card` used named tokens (`xs`, `sm`, `md`, `lg`, `xl`, `xxl`).
+     * These no longer exist. Use the numeric equivalents:
+     * `xs` → `spacing-02`, `sm` → `spacing-03`, `md` → `spacing-05`,
+     * `lg` → `spacing-07`, `lg2` → `spacing-08`, `xl` → `spacing-09`, `xxl` → `spacing-11`.
+     *
+     * @type {Spacing}
+     * @default "spacing-05"
+     */
     padding: Spacing;
-    /** Selectable property allow the card to toggle between selected and unselected state.
-     * This property can't be used with the button property at the same time */
+    /**
+     * Makes the card toggleable between selected and unselected on click.
+     * Emits the `select` event with the new boolean value on each toggle.
+     *
+     * **Mutually exclusive with `button`** — if both are set, `selectable` is disabled automatically.
+     *
+     * @type {boolean}
+     * @default false
+     */
     selectable: boolean;
-    /** Sets the selected state for the card (only works when selectable property is true).
-     * This property can't be used with the button property at the same time */
+    /**
+     * Reflects the current selected state of the card.
+     * Only meaningful when `selectable="true"`. Can be set initially to pre-select the card.
+     * Automatically reset to `false` when `selectable` is disabled.
+     *
+     * @type {boolean}
+     * @default false
+     */
     selected: boolean;
-    /** Button property allows the card to behave like a button.
-     * This property can't be used with the selectable property at the same time */
+    /**
+     * Makes the entire card surface act as a single clickable button.
+     * Emits the `click` event with the native `MouseEvent` on each click.
+     *
+     * **Mutually exclusive with `selectable`** — if both are set, `selectable` is disabled automatically.
+     *
+     * @type {boolean}
+     * @default false
+     */
     button: boolean;
-    /** Sets the card in disabled state */
+    /**
+     * Puts the card in a non-interactive disabled visual state.
+     * Prevents `select` and `click` events from being emitted.
+     *
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Allows changing the default card variant */
+    /**
+     * Controls the card's color scheme.
+     * - `"default"` — neutral surface (most common)
+     * - `"primary"` — brand/information emphasis
+     * - `"secondary"` — secondary emphasis
+     * - `"danger"` — destructive or error context
+     *
+     * @type {"primary" | "secondary" | "danger" | "default"}
+     * @default "default"
+     */
     variant: 'primary' | 'secondary' | 'danger' | 'default';
-    /** Sets the shadow for the card */
+    /**
+     * Sets the card's drop shadow using a Volt elevation token.
+     * Available values: `elevation-shadow-0` (none), `elevation-shadow-1` through
+     * `elevation-shadow-3`, `elevation-shadow-5`, `elevation-shadow-8`, `elevation-shadow-17`.
+     *
+     * @type {ShadowBox}
+     * @default "elevation-shadow-1"
+     */
     shadowBox: ShadowBox;
     /**
-     * Allows changing the default border color.
-     * @deprecated This property is deprecated and will be removed from the code in the future.
+     * Overrides the default border color with a Volt color token.
+     *
+     * @type {Colors}
+     * @deprecated Use the `--vds-card-default-border-color` CSS custom property instead.
+     * This prop will be removed in a future release.
      */
     borderColor: Colors;
     /**
-     * Allows changing the border color when hovering.
-     * @deprecated This property is deprecated and will be removed from the code in the future.
+     * Overrides the border color on hover with a Volt color token.
+     *
+     * @type {Colors}
+     * @deprecated Use the `--vds-card-default-border-hover-color` CSS custom property instead.
+     * This prop will be removed in a future release.
      */
     borderHoverColor: Colors;
-    /** Emits event when card have been selected (only works when selectable property is true) */
+    /**
+     * Emits event when card has been selected (only works when selectable property is true)
+     * @event select
+     * @type {EventEmitter<boolean>}
+     */
     select: EventEmitter<boolean>;
-    /** Emits event when card have been clicked on (only works when button property is true) */
+    /**
+     * Emits event when card has been clicked on (only works when button property is true)
+     * @event click
+     * @type {EventEmitter<MouseEvent>}
+     */
     click: EventEmitter<MouseEvent>;
+    /**
+     * Emits the selected state when the selected property changes
+     * @returns {void}
+     */
     emitSelected(): void;
+    /**
+     * Validates and handles behavior conflicts between selectable and button properties
+     * @returns {void}
+     */
     handleBehaviorValidation(): void;
     /**
-     * Sets card's custom border colors
-     *
-     * @returns { [key: string]: string }
+     * Sets card's custom border colors based on borderColor and borderHoverColor props
+     * @private
+     * @returns {{ [key: string]: string }} Object containing CSS custom properties for border colors
      */
     private setCustomBorderColors;
+    /**
+     * Toggles the selected state of the card
+     * @private
+     * @returns {void}
+     */
     private handleSelectable;
+    /**
+     * Handles click events on the card and emits appropriate events
+     * @private
+     * @param {MouseEvent} evt - The mouse event from the click
+     * @returns {void}
+     */
     private handleClick;
+    /**
+     * Lifecycle hook that runs before component is loaded
+     * @returns {void}
+     */
     componentWillLoad(): void;
+    /**
+     * Renders the card component
+     * @returns {HTMLStencilElement} The rendered card element
+     */
     render(): HTMLStencilElement;
 }