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

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

@@ -1,25 +1,278 @@
 import { Host, h } from "@stencil/core";
 import { combineClasses } from "../../utils/combine-classes";
 import { ICON_SIZE } from "../icon-button/vds-icon-button.utils";
+/**
+ * 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 class VdsChip {
     constructor() {
-        /** Sets content size  */
+        /**
+         * Controls the visual size of the chip.
+         *
+         * @type {"small" | "medium" | "large"}
+         * @default "medium"
+         */
         this.size = "medium";
-        /** 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
+         */
         this.toggle = false;
-        /** 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
+         */
         this.removeOnClose = true;
+        /**
+         * 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
+         */
+        this.hideCheckIcon = false;
+        /**
+         * Internal state for the informative icon
+         * @type {string}
+         */
         this._informativeIcon = undefined;
-        this.iconColor = "color-icon-brand-default";
+        /**
+         * Internal icon size state
+         * @private
+         * @type {string}
+         */
         this.iconSize = ICON_SIZE["small"];
     }
     /**
-     * Executes before every render cycle.
-     *
-     * @returns void
+     * Lifecycle hook that executes before every render cycle
+     * @returns {void}
      */
     componentWillRender() {
-        this.setChipIconsColor();
         this.setChipIconsSize();
         this.setInformativeIcon();
         this.setDividerColor();
@@ -27,8 +280,9 @@ export class VdsChip {
     /**
      * Dismiss/Hide the chip.
      * Emits afterClosed event
-     *
-     * @Returns Promise<void>
+     * @method
+     * @public
+     * @returns {Promise<void>}
      */
     dismiss() {
         return new Promise(resolve => {
@@ -41,46 +295,29 @@ export class VdsChip {
     }
     /**
      * Emits event when menu-icon is clicked
-     *
-     * @Returns void
+     * @private
+     * @returns {void}
      */
     emitMenuClicked() {
         this.menuClick.emit();
     }
     /**
-     * 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}
      */
     setInformativeIcon() {
-        this._informativeIcon = this.informativeIcon ? this.informativeIcon : this.active && this.toggle ? "good" : undefined;
+        this._informativeIcon = this.informativeIcon ? this.informativeIcon : (this.active && this.toggle && !this.hideCheckIcon) ? "good" : undefined;
     }
     /**
-     * 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}
      */
-    setChipIconsColor() {
-        const state = this.disabled && this.active ? "disabled-active" : this.disabled ? "disabled" : this.active ? "active" : "default";
-        switch (state) {
-            case "disabled-active":
-                this.iconColor = "color-icon-white-high";
-                break;
-            case "disabled":
-                this.iconColor = "color-icon-disabled";
-                break;
-            case "active":
-                this.iconColor = "static-white";
-                break;
-            default:
-                this.iconColor = "color-icon-brand-default";
-                break;
-        }
-    }
     setChipIconsSize() {
         switch (this.size) {
             case "small":
@@ -96,9 +333,9 @@ export class VdsChip {
     }
     /**
      * 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}
      */
     handleChipClick() {
         if (!this.toggle)
@@ -107,6 +344,11 @@ export class VdsChip {
         this.setInformativeIcon();
         this.selected.emit();
     }
+    /**
+     * Sets the divider color based on disabled and active states
+     * @private
+     * @returns {void}
+     */
     setDividerColor() {
         const state = this.disabled && this.active ? "disabled-active" : this.disabled ? "disabled" : this.active ? "active" : "default";
         switch (state) {
@@ -124,8 +366,12 @@ export class VdsChip {
                 break;
         }
     }
+    /**
+     * Renders the chip component
+     * @returns {HTMLStencilElement} The rendered chip element
+     */
     render() {
-        return (h(Host, { key: '5b401a1b9d16c9dc2dfd3cb00d74ba64de865bb1', class: this.disabled ? "vds-chip--disabled" : "" }, h("button", { key: 'd6c30dbbe03e3bb6df05218e9c2da6b02f36e558', onClick: () => this.handleChipClick(), class: combineClasses("vds__chip__container", `vds__chip__container--size-${this.size}`, this.toggle && "vds__chip__container--toggleable", this.disabled && "vds__chip__container--disabled", this.active && "vds__chip__container--active"), disabled: this.disabled }, this._informativeIcon && h("vds-icon", { key: 'c4b5a03f5c7d6d78398f1816511112a167918fdc', svgIcon: this._informativeIcon, color: this.iconColor, size: this.iconSize }), this.value, this.menu && h("vds-icon", { key: 'f5b9e3f665ce42c7100bfc9c24578652274c1455', class: "vds-chip__icon", onClick: () => this.emitMenuClicked(), svgIcon: this.active ? "chevron-up" : "chevron-down", color: this.iconColor, size: this.iconSize }), this.close && h("vds-divider", { key: '1dc431c960eb0c0d18d517fd645d76aa4c1afa7a', orientation: "vertical", padding: "spacing-00", color: this.dividerColor }), this.close && h("vds-icon", { key: '237c9890965cbbebe3a2d72df161a4ca0925557b', class: "vds-chip__icon", onClick: () => this.dismiss(), "aria-label": this.closeAriaLabel, svgIcon: "close", color: this.iconColor, size: this.iconSize }))));
+        return (h(Host, { key: 'c11ba27f905f570949f83a22afef1fed6a56a79c', class: this.disabled ? "vds-chip--disabled" : "" }, h("button", { key: '4f6528314777f0d45ca996a656b050a1f10c3f53', onClick: () => this.handleChipClick(), class: combineClasses("vds__chip__container", `vds__chip__container--size-${this.size}`, this.toggle && "vds__chip__container--toggleable", this.disabled && "vds__chip__container--disabled", this.active && "vds__chip__container--active"), disabled: this.disabled }, this._informativeIcon && h("vds-icon", { key: '8acaabd8acfb576ce61aba817d7ca517d63558bb', svgIcon: this._informativeIcon, size: this.iconSize }), this.value, this.menu && h("vds-icon", { key: '9e2863a71288038d600e1aaed4f29ea7712b9658', class: "vds-chip__icon", onClick: () => this.emitMenuClicked(), svgIcon: this.active ? "chevron-up" : "chevron-down", size: this.iconSize }), this.close && h("vds-divider", { key: 'bade8b2aff2a0f7081fecb162f22baaedbf9673b', orientation: "vertical", padding: "spacing-00", color: this.dividerColor }), this.close && h("vds-icon", { key: 'a28dfdbb494e12e7841a94c18c01da050c0e9b6f', class: "vds-chip__icon", onClick: () => this.dismiss(), "aria-label": this.closeAriaLabel, svgIcon: "close", size: this.iconSize }))));
     }
     static get is() { return "vds-chip"; }
     static get encapsulation() { return "shadow"; }
@@ -152,8 +398,11 @@ export class VdsChip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets chips content value"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Sets the visible label text of the chip.\n\n**Migration:** in `volt-chip` this was inner slot content (e.g. `<volt-chip>Label</volt-chip>`).\nIn `vds-chip` it must be passed as this prop: `<vds-chip value=\"Label\"></vds-chip>`.\nInner text is ignored \u2014 the slot is not used."
                 },
                 "getter": false,
                 "setter": false,
@@ -171,8 +420,11 @@ export class VdsChip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Displays close icon"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }],
+                    "text": "Shows a close (\u00D7) button on the right side of the chip.\nClicking it calls `dismiss()`, emits `afterClosed`, and removes the chip from the DOM\nunless `remove-on-close=\"false\"` is set.\n\n**Migration:** was `show-close` / `showClose` in `volt-chip`. Using the old name\nsilently renders no close button."
                 },
                 "getter": false,
                 "setter": false,
@@ -190,8 +442,11 @@ export class VdsChip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Displays menu (chevron-down) icon"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }],
+                    "text": "Shows a chevron icon (chevron-down / chevron-up) on the right side.\nFlips direction based on the `active` state. Emits `menuClick` when clicked."
                 },
                 "getter": false,
                 "setter": false,
@@ -209,8 +464,11 @@ export class VdsChip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Displays chip in active state"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }],
+                    "text": "Puts the chip in the active/selected visual state.\nWhen `toggle=\"true\"`, this state is managed automatically on each click.\n\n**Migration:** was `is-active` / `isActive` in `volt-chip`."
                 },
                 "getter": false,
                 "setter": false,
@@ -228,8 +486,11 @@ export class VdsChip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets chip to disabled"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }],
+                    "text": "Puts the chip in a non-interactive disabled state."
                 },
                 "getter": false,
                 "setter": false,
@@ -247,8 +508,14 @@ export class VdsChip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets content size"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"small\" | \"medium\" | \"large\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"medium\""
+                        }],
+                    "text": "Controls the visual size of the chip."
                 },
                 "getter": false,
                 "setter": false,
@@ -267,8 +534,11 @@ export class VdsChip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Defines the aria label on the close button"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Accessible label for the close button. Always set this when `close=\"true\"`\nso screen readers can announce the action."
                 },
                 "getter": false,
                 "setter": false,
@@ -286,8 +556,14 @@ export class VdsChip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "They turn active on/off when clicking the chip"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Enables toggle (filter chip) behaviour. Each click flips `active` on/off,\nemits `selected`, and shows a checkmark icon when active (unless suppressed\nby `hide-check-icon` or overridden by `informative-icon`)."
                 },
                 "getter": false,
                 "setter": false,
@@ -306,8 +582,11 @@ export class VdsChip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Receives the icon name to be shown in the left side"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }],
+                    "text": "Name of a Volt sprite icon to display on the left side of the label.\nWhen `toggle=\"true\"` and the chip is active, defaults to `\"good\"` (checkmark)\nif this prop is not set and `hide-check-icon` is false."
                 },
                 "getter": false,
                 "setter": false,
@@ -325,14 +604,46 @@ export class VdsChip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "When close button is clicked, the element is removed from the DOM"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "true"
+                        }],
+                    "text": "When `true`, clicking the close button removes the chip element from the DOM.\nSet to `false` to keep the element and handle cleanup via the `afterClosed` event."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": false,
                 "attribute": "remove-on-close",
                 "defaultValue": "true"
+            },
+            "hideCheckIcon": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Suppresses the automatic checkmark icon that appears when `toggle=\"true\"` and\nthe chip is active. Has no effect when `informative-icon` is explicitly set."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "hide-check-icon",
+                "defaultValue": "false"
             }
         };
     }
@@ -349,7 +660,13 @@ export class VdsChip {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "event",
+                            "text": "afterClosed"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<void>}"
+                        }],
                     "text": "Fires after chip dismiss and hide"
                 },
                 "complexType": {
@@ -364,7 +681,13 @@ export class VdsChip {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "event",
+                            "text": "selected"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<void>}"
+                        }],
                     "text": "Fires when chip is selected (only works when toggle is enabled)"
                 },
                 "complexType": {
@@ -379,7 +702,13 @@ export class VdsChip {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "event",
+                            "text": "menuClick"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<void>}"
+                        }],
                     "text": "Fires when menu-icon is clicked"
                 },
                 "complexType": {
@@ -406,8 +735,14 @@ export class VdsChip {
                 "docs": {
                     "text": "Dismiss/Hide the chip.\nEmits afterClosed event",
                     "tags": [{
-                            "name": "Returns",
-                            "text": "Promise<void>"
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": undefined
                         }]
                 }
             }
@@ -415,4 +750,3 @@ export class VdsChip {
     }
     static get elementRef() { return "hostEl"; }
 }
-//# sourceMappingURL=vds-chip.js.map