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

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

@@ -1,28 +1,71 @@
 import { HTMLStencilElement, EventEmitter } from "../../stencil-public-runtime";
 import { CheckboxEvent } from "./vds-checkbox.utils";
+/**
+ * @component vds-checkbox
+ * @description A checkbox component that supports standard, indeterminate, and disabled states. Form-associated with support for native form submission and validation. Emits custom events with modifier key information.
+ * @slot - The default slot is not used; use the labelValue prop instead
+ */
 export declare class VdsBasicCheckbox {
-    /** Sets the text to be shown in the checkbox */
+    /**
+     * Sets the text to be shown in the checkbox label
+     * @type {string}
+     */
     labelValue: string;
-    /** Sets the checkbox in checked state */
+    /**
+     * Sets the checkbox in checked state
+     * @type {boolean}
+     * @default false
+     */
     checked: boolean;
-    /** Sets the checkbodx in indeterminate state */
+    /**
+     * Sets the checkbox in indeterminate state
+     * @type {boolean}
+     * @default false
+     */
     indeterminate: boolean;
-    /** Sets the checkbox in disabled state */
+    /**
+     * Sets the checkbox in disabled state
+     * @type {boolean}
+     * @default false
+     */
     disabled: boolean;
-    /** Sets the checkbox in error state */
+    /**
+     * Sets the checkbox in error state
+     * @type {boolean}
+     * @default false
+     */
     error: boolean;
-    /** Sets the checkbox's size */
+    /**
+     * Sets the checkbox's size
+     * @type {"medium" | "large"}
+     * @default "medium"
+     */
     size: "medium" | "large";
-    /** Toggles the required sign in the field */
+    /**
+     * Toggles the required sign in the field
+     * @type {boolean}
+     * @default false
+     */
     isRequired: boolean;
-    /** Sets the value in the input. Usually uses checked prop as string.
-     *  Used to manage Reactive forms and other native functionality */
+    /**
+     * Sets the value in the input. Usually uses checked prop as string.
+     * Used to manage Reactive forms and other native functionality
+     * @type {string}
+     */
     value: string;
+    /**
+     * Reference to the host element
+     * @type {HTMLElement}
+     */
     hostEl: HTMLElement;
+    /**
+     * ElementInternals API for form association
+     * @type {ElementInternals}
+     */
     internals: ElementInternals;
     /**
      * Event which is triggered when checkbox state changes. This event also captures if
-     * any of the special keys (shift, ctrl, meta or alt) where pressed when the checkbox state
+     * any of the special keys (shift, ctrl, meta or alt) were pressed when the checkbox state
      * changed. Use CheckboxEvent.isChecked() or
      * checkbox.on('checkboxEvent', (event : CustomEvent<CheckboxEvent>) => {
      *		if(event.detail == true) {
@@ -32,59 +75,80 @@ export declare class VdsBasicCheckbox {
      * console.log(event.detail.shiftKey);
      * console.log(event.detail.ctrlKey);
      * })
-     *
+     * @event checkboxChange
+     * @type {EventEmitter<CheckboxEvent>}
      */
     checkboxChange: EventEmitter<CheckboxEvent>;
-    /** Makes a custom change to target property using checked and indeterminate (use for React components) */
+    /**
+     * Makes a custom change to target property using checked and indeterminate (use for React components)
+     * @event check
+     * @type {EventEmitter<boolean>}
+     */
     check: EventEmitter<boolean>;
+    /**
+     * Internal state tracking for checkbox (checked, unchecked, or indeterminate)
+     * @private
+     * @type {"checked" | "unchecked" | "indeterminate"}
+     */
     private state;
+    /**
+     * Lifecycle hook that runs before component renders
+     * @returns {void}
+     */
     componentWillRender(): void;
+    /**
+     * Lifecycle hook that runs after component is loaded
+     * @returns {void}
+     */
     componentDidLoad(): void;
     /**
      * Executes every time checked value changes.
      * Sets indeterminate value to false in order to guarantee a change in value.
      * Sets form value in order to work properly with native forms
-     *
-     * @returns void
+     * @returns {void}
      */
     setCheckedStates(): void;
     /**
-     * Executes every time the checkbox is being click.
+     * Executes every time the checkbox is being clicked.
      * Executes toggleCheck method.
-     *
-     * @param event - MouseEvent
-     * @returns void
+     * @param {MouseEvent} event - The mouse event from the click
+     * @returns {void}
      */
     handleClick(event: MouseEvent): void;
     /**
-    * Toggles checkbox value.
-    * Emits checkboxChange event with CheckboxEvent value.
-    * Emits check event with checked value.
-    *
-    * @param evt - KeyboardEvent | MouseEvent
-    * @returns Promise<void>
-    */
+     * Toggles checkbox value.
+     * Emits checkboxChange event with CheckboxEvent value.
+     * Emits check event with checked value.
+     * @method
+     * @public
+     * @param {KeyboardEvent | MouseEvent} evt - The keyboard or mouse event (optional)
+     * @returns {Promise<void>}
+     */
     toggleCheck(evt?: KeyboardEvent | MouseEvent): Promise<void>;
     /**
-     * Determine state of the checkbox based on the indeterminate and checked properties.
-     * When indetermanate is true, state is indeterminate.
-     * When indetermanate is false and checked is true, state is checked.
-     * When indetermanate is false and checked is false, state is unchecked.
-     *
-     * @returns void
+     * Determines state of the checkbox based on the indeterminate and checked properties.
+     * When indeterminate is true, state is indeterminate.
+     * When indeterminate is false and checked is true, state is checked.
+     * When indeterminate is false and checked is false, state is unchecked.
+     * @private
+     * @returns {void}
      */
     private setCheckboxState;
     /**
-     * Returns the icon prop based on the state and calculate the size.
-     *
-     * @returns HTMLStencilElement
+     * Returns the icon element based on the state and calculates the size.
+     * @private
+     * @returns {HTMLStencilElement} The rendered checkbox icon
      */
     private renderCheckbox;
     /**
-    * Returns the vds-label for the checkbox when there is a label provided.
-    *
-    * @returns HTMLStencilElement
-    */
+     * Returns the vds-label for the checkbox when there is a label provided.
+     * @private
+     * @returns {HTMLStencilElement} The rendered label element
+     */
     private renderLabel;
+    /**
+     * Renders the checkbox component
+     * @returns {HTMLStencilElement} The rendered checkbox element
+     */
     render(): HTMLStencilElement;
 }

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

@@ -1,79 +1,407 @@
 import { HTMLStencilElement, EventEmitter } from '../../stencil-public-runtime';
+/**
+ * Compact interactive element used to display information, trigger actions, filter content,
+ * or make selections. Supports toggle (filter chip), close (input chip), menu, icon decoration,
+ * three sizes, and full CSS custom property theming.
+ *
+ * ---
+ * ## Migration note (volt-chip → vds-chip)
+ *
+ * **`volt-chip` must be replaced with `vds-chip`.** There are three breaking API changes
+ * that migration agents commonly miss — all three cause silent visual failures:
+ *
+ * ### 1. Label: slot → `value` prop
+ *
+ * In `volt-chip` the label was inner content (slot). In `vds-chip` it is the `value` prop.
+ *
+ * ```html
+ * <!-- Before (volt-chip) — label as slot content -->
+ * <volt-chip>Traveling</volt-chip>
+ *
+ * <!-- After (vds-chip) — label as value prop -->
+ * <vds-chip value="Traveling"></vds-chip>
+ * ```
+ *
+ * ### 2. Close button: `show-close` → `close`
+ *
+ * The prop was renamed. Using the old name shows no close button.
+ *
+ * ```html
+ * <!-- Before -->
+ * <volt-chip show-close="true">Tag</volt-chip>
+ *
+ * <!-- After -->
+ * <vds-chip value="Tag" close="true"></vds-chip>
+ * ```
+ *
+ * JS property: `showClose` → `close`
+ *
+ * ### 3. Active state: `is-active` → `active`
+ *
+ * ```html
+ * <!-- Before -->
+ * <volt-chip is-active="true">Selected</volt-chip>
+ *
+ * <!-- After -->
+ * <vds-chip value="Selected" active="true"></vds-chip>
+ * ```
+ *
+ * JS property: `isActive` → `active`
+ *
+ * ### 4. Color prop removed — use CSS custom properties
+ *
+ * `volt-chip` had a `color` prop. `vds-chip` removes it entirely.
+ * Theming is done via CSS custom properties (see **Custom styles** section below).
+ *
+ * ### 5. `element` prop removed
+ *
+ * `volt-chip` could render as `<button>` or `<a>`. `vds-chip` always renders as `<button>`.
+ *
+ * **Full migration checklist:**
+ * - Replace tag `volt-chip` → `vds-chip`
+ * - Move inner text (slot) → `value="..."` attribute
+ * - Replace `show-close` → `close`
+ * - Replace `is-active` → `active`
+ * - Remove `color` prop — use CSS custom properties instead
+ * - Remove `element` prop
+ *
+ * ---
+ * ## Basic usage
+ *
+ * ```html
+ * <vds-chip value="Traveling"></vds-chip>
+ * <vds-chip value="Traveling" size="small"></vds-chip>
+ * <vds-chip value="Traveling" size="large" active="true"></vds-chip>
+ * <vds-chip value="Traveling" disabled="true"></vds-chip>
+ * ```
+ *
+ * ---
+ * ## Input chips (close button)
+ *
+ * Use `close="true"` to show a dismiss button. By default clicking it removes the chip
+ * from the DOM (`remove-on-close="true"`). Set `remove-on-close="false"` to suppress
+ * DOM removal and handle cleanup via the `afterClosed` event instead.
+ *
+ * ```html
+ * <!-- Removed from DOM on close (default) -->
+ * <vds-chip value="Design" close="true" close-aria-label="Remove Design chip"></vds-chip>
+ *
+ * <!-- Keep in DOM, handle removal manually -->
+ * <vds-chip
+ *   id="my-chip"
+ *   value="Design"
+ *   close="true"
+ *   remove-on-close="false"
+ *   close-aria-label="Remove Design chip"
+ * ></vds-chip>
+ * <script>
+ *   document.querySelector('#my-chip').addEventListener('afterClosed', () => {
+ *     // handle removal manually
+ *   });
+ * </script>
+ * ```
+ *
+ * ---
+ * ## Filter chips (toggle)
+ *
+ * Use `toggle="true"` to make the chip behave as a selectable filter. Clicking it
+ * flips the `active` state and automatically shows a checkmark icon unless
+ * `hide-check-icon="true"` is set.
+ *
+ * ```html
+ * <vds-chip value="Docs"   toggle="true"></vds-chip>
+ * <vds-chip value="Sheets" toggle="true" active="true"></vds-chip>
+ * <vds-chip value="Slides" toggle="true"></vds-chip>
+ * <vds-chip value="Videos" toggle="true" active="true"></vds-chip>
+ * ```
+ *
+ * Listen for selections:
+ *
+ * ```js
+ * document.querySelectorAll('vds-chip').forEach(chip => {
+ *   chip.addEventListener('selected', () => {
+ *     console.log(chip.value, 'active:', chip.active);
+ *   });
+ * });
+ * ```
+ *
+ * ---
+ * ## With informative icon (left side)
+ *
+ * Use `informative-icon` to show a Volt sprite icon on the left of the label.
+ * When `toggle` is enabled and the chip is active, the icon defaults to `"good"`
+ * (checkmark) unless overridden by this prop or disabled with `hide-check-icon`.
+ *
+ * ```html
+ * <vds-chip value="Containers" informative-icon="local-containers" size="medium"></vds-chip>
+ * <vds-chip value="Filters"    informative-icon="filter" toggle="true" active="true"></vds-chip>
+ *
+ * <!-- Suppress checkmark on active toggle chip -->
+ * <vds-chip value="Selected" toggle="true" active="true" hide-check-icon="true"></vds-chip>
+ * ```
+ *
+ * ---
+ * ## With menu icon (right side)
+ *
+ * Use `menu="true"` to show a chevron icon on the right. It flips between
+ * `chevron-down` and `chevron-up` based on the `active` state.
+ *
+ * ```html
+ * <vds-chip value="Options" menu="true"></vds-chip>
+ * ```
+ *
+ * ```js
+ * document.querySelector('vds-chip').addEventListener('menuClick', () => {
+ *   console.log('menu chevron clicked');
+ * });
+ * ```
+ *
+ * ---
+ * ## Listening to events
+ *
+ * ```js
+ * const chip = document.querySelector('vds-chip');
+ *
+ * // Fired when the close button is clicked (before DOM removal)
+ * chip.addEventListener('afterClosed', () => {
+ *   console.log('chip closed');
+ * });
+ *
+ * // Fired on each click when toggle="true" — carries new active state on chip.active
+ * chip.addEventListener('selected', () => {
+ *   console.log('toggled, now active:', chip.active);
+ * });
+ *
+ * // Fired when the menu chevron icon is clicked
+ * chip.addEventListener('menuClick', () => {
+ *   console.log('menu icon clicked');
+ * });
+ * ```
+ *
+ * ---
+ * ## Programmatic control (methods)
+ *
+ * ```js
+ * const chip = document.querySelector('vds-chip');
+ *
+ * // Dismiss the chip — emits afterClosed and removes from DOM (if remove-on-close is true)
+ * await chip.dismiss();
+ * ```
+ *
+ * ---
+ * ## Custom styles (CSS custom properties)
+ *
+ * `volt-chip`'s `color` prop is replaced by CSS custom properties on `vds-chip`.
+ * Override them on the element or a parent selector:
+ *
+ * ```css
+ * vds-chip {
+ *   --vds-chip-background-color: transparent;
+ *   --vds-chip-background-hover-color: var(--color-interaction-white-lowest);
+ *   --vds-chip-background-press-color: var(--color-interaction-white-lower);
+ *   --vds-chip-border-color: var(--color-border-white-medium);
+ *   --vds-chip-content-color: var(--color-text-white-medium);
+ *   --vds-chip-icon-color: var(--color-icon-white-medium);
+ *
+ *   --vds-chip-active-background-color: var(--static-white);
+ *   --vds-chip-active-background-hover-color: var(--color-background-general-lowest-hover);
+ *   --vds-chip-active-background-press-color: var(--color-background-general-lowest-press);
+ *   --vds-chip-active-border-color: transparent;
+ *   --vds-chip-active-content-color: var(--static-black);
+ *   --vds-chip-active-icon-color: var(--static-black);
+ * }
+ * ```
+ *
+ * ---
+ * ## Slots
+ *
+ * This component has no public slots. The label content is set via the `value` prop.
+ * Using inner text (as in `volt-chip`) will not render anything.
+ *
+ * @component vds-chip
+ */
 export declare class VdsChip {
-    /** Sets chips content value */
+    /**
+     * Sets the visible label text of the chip.
+     *
+     * **Migration:** in `volt-chip` this was inner slot content (e.g. `<volt-chip>Label</volt-chip>`).
+     * In `vds-chip` it must be passed as this prop: `<vds-chip value="Label"></vds-chip>`.
+     * Inner text is ignored — the slot is not used.
+     *
+     * @type {string}
+     */
     value: string;
-    /** Displays close icon */
+    /**
+     * Shows a close (×) button on the right side of the chip.
+     * Clicking it calls `dismiss()`, emits `afterClosed`, and removes the chip from the DOM
+     * unless `remove-on-close="false"` is set.
+     *
+     * **Migration:** was `show-close` / `showClose` in `volt-chip`. Using the old name
+     * silently renders no close button.
+     *
+     * @type {boolean}
+     */
     close: boolean;
-    /** Displays menu (chevron-down) icon */
+    /**
+     * Shows a chevron icon (chevron-down / chevron-up) on the right side.
+     * Flips direction based on the `active` state. Emits `menuClick` when clicked.
+     *
+     * @type {boolean}
+     */
     menu: boolean;
-    /** Displays chip in active state */
+    /**
+     * Puts the chip in the active/selected visual state.
+     * When `toggle="true"`, this state is managed automatically on each click.
+     *
+     * **Migration:** was `is-active` / `isActive` in `volt-chip`.
+     *
+     * @type {boolean}
+     */
     active: boolean;
-    /** Sets chip to disabled */
+    /**
+     * Puts the chip in a non-interactive disabled state.
+     *
+     * @type {boolean}
+     */
     disabled: boolean;
-    /** Sets content size  */
+    /**
+     * Controls the visual size of the chip.
+     *
+     * @type {"small" | "medium" | "large"}
+     * @default "medium"
+     */
     size: "small" | "medium" | "large";
-    /** Defines the aria label on the close button  */
+    /**
+     * Accessible label for the close button. Always set this when `close="true"`
+     * so screen readers can announce the action.
+     *
+     * @type {string}
+     */
     closeAriaLabel: string;
-    /** They turn active on/off when clicking the chip */
+    /**
+     * Enables toggle (filter chip) behaviour. Each click flips `active` on/off,
+     * emits `selected`, and shows a checkmark icon when active (unless suppressed
+     * by `hide-check-icon` or overridden by `informative-icon`).
+     *
+     * @type {boolean}
+     * @default false
+     */
     toggle: boolean;
-    /** Receives the icon name to be shown in the left side */
+    /**
+     * Name of a Volt sprite icon to display on the left side of the label.
+     * When `toggle="true"` and the chip is active, defaults to `"good"` (checkmark)
+     * if this prop is not set and `hide-check-icon` is false.
+     *
+     * @type {string}
+     */
     informativeIcon: string;
-    /** When close button is clicked, the element is removed from the DOM */
+    /**
+     * When `true`, clicking the close button removes the chip element from the DOM.
+     * Set to `false` to keep the element and handle cleanup via the `afterClosed` event.
+     *
+     * @type {boolean}
+     * @default true
+     */
     removeOnClose: boolean;
-    /** Fires after chip dismiss and hide */
+    /**
+     * Suppresses the automatic checkmark icon that appears when `toggle="true"` and
+     * the chip is active. Has no effect when `informative-icon` is explicitly set.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    hideCheckIcon: boolean;
+    /**
+     * Fires after chip dismiss and hide
+     * @event afterClosed
+     * @type {EventEmitter<void>}
+     */
     afterClosed: EventEmitter<void>;
-    /** Fires when chip is selected (only works when toggle is enabled) */
+    /**
+     * Fires when chip is selected (only works when toggle is enabled)
+     * @event selected
+     * @type {EventEmitter<void>}
+     */
     selected: EventEmitter<void>;
-    /** Fires when menu-icon is clicked */
+    /**
+     * Fires when menu-icon is clicked
+     * @event menuClick
+     * @type {EventEmitter<void>}
+     */
     menuClick: EventEmitter<void>;
+    /**
+     * Reference to the host element
+     * @type {HTMLVdsChipElement}
+     */
     hostEl: HTMLVdsChipElement;
+    /**
+     * Internal state for the informative icon
+     * @type {string}
+     */
     _informativeIcon: string;
-    private iconColor;
+    /**
+     * Internal icon size state
+     * @private
+     * @type {string}
+     */
     private iconSize;
+    /**
+     * Internal divider color state
+     * @private
+     * @type {BorderColors | StaticGlobal}
+     */
     private dividerColor;
     /**
-     * Executes before every render cycle.
-     *
-     * @returns void
+     * Lifecycle hook that executes before every render cycle
+     * @returns {void}
      */
     componentWillRender(): void;
     /**
      * Dismiss/Hide the chip.
      * Emits afterClosed event
-     *
-     * @Returns Promise<void>
+     * @method
+     * @public
+     * @returns {Promise<void>}
      */
     dismiss(): Promise<void>;
     /**
      * Emits event when menu-icon is clicked
-     *
-     * @Returns void
+     * @private
+     * @returns {void}
      */
     private emitMenuClicked;
     /**
-     * Sets informative icon based on the following herarchy
+     * Sets informative icon based on the following hierarchy:
      * When informativeIcon prop is provided it will always display.
-     * When Chip is toggle and active it will set informativeIcon to checkMarck (good)
-     * Otherwise it'll not be display.
-     *
-     * @Returns void
+     * When Chip is toggle and active it will set informativeIcon to checkMark (good)
+     * When hideCheckIcon is true, it will not display the checkMark icon even when the chip is active and toggle is enabled.
+     * Otherwise it will not be displayed.
+     * @private
+     * @returns {void}
      */
     private setInformativeIcon;
     /**
-     * Sets the color for the icons inside the chip.
-     * Sets the chip's vds-icon colors
-     *
-     * @returns void
+     * Sets the icon size based on the chip size
+     * @private
+     * @returns {void}
      */
-    private setChipIconsColor;
     private setChipIconsSize;
     /**
      * Changes the chip active state when toggle option is enabled.
-     * Add checks icon when informativeIcon is not provided
-     *
-     * @returns void
+     * Adds check icon when informativeIcon is not provided
+     * @private
+     * @returns {void}
      */
     private handleChipClick;
+    /**
+     * Sets the divider color based on disabled and active states
+     * @private
+     * @returns {void}
+     */
     private setDividerColor;
+    /**
+     * Renders the chip component
+     * @returns {HTMLStencilElement} The rendered chip element
+     */
     render(): HTMLStencilElement;
 }

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

@@ -22,3 +22,4 @@ export default _default;
 export declare const BasicUsage: any;
 export declare const InputChips: any;
 export declare const FilterChips: any;
+export declare const CustomStyles: any;