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

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

@@ -1,23 +1,369 @@
 import { Host, h } from "@stencil/core";
 import { updateFloatingBoxPosition } from "../../utils/floating-engine-utils";
 import { queryElementFromShadowRoot } from "../../utils/node-utils";
+/**
+ * @component vds-tooltip
+ *
+ * @description
+ * A small floating label that appears near a trigger element to surface non-essential, contextual
+ * information without interrupting the user's flow. Use it for icon-button labels, field hints,
+ * truncated-text previews, and similar lightweight disclosures.
+ *
+ * **When NOT to use a tooltip:** if you need formatted, interactive, or critical content (links,
+ * form controls, error messages), use `vds-popover` instead.
+ *
+ * ---
+ *
+ * ## Type modes — the most important decision
+ *
+ * The `type` prop governs which slot is rendered and how the tooltip is triggered:
+ *
+ * | `type`       | Content source       | Trigger behaviour                                   |
+ * |--------------|----------------------|-----------------------------------------------------|
+ * | `"standard"` | `text` prop          | Responds to `event` prop (`hover` or `click`)       |
+ * | `"custom"`   | `tooltip-content` slot | Responds to `event` prop (`hover` or `click`)     |
+ * | `"manual"`   | `text` prop          | Ignores hover/click — only `open()` / `close()` work |
+ *
+ * > **Important:** the `tooltip-content` slot is **only rendered** when `type="custom"`.
+ * > Providing it on a `type="standard"` tooltip has no effect.
+ *
+ * ---
+ *
+ * ## Slots
+ *
+ * | Slot                | Required | Description                                                                 |
+ * |---------------------|----------|-----------------------------------------------------------------------------|
+ * | `tooltip-trigger`   | Yes      | The element the tooltip anchors to and that the user interacts with.        |
+ * | `tooltip-content`   | No       | Rich HTML content for the floating panel. **Only used when `type="custom"`.**|
+ *
+ * ---
+ *
+ * ## CSS Custom Properties
+ *
+ * | Property               | Description                                                        |
+ * |------------------------|--------------------------------------------------------------------|
+ * | `--tooltip-max-width`  | Maximum width of the tooltip bubble. Set via the `max-width` prop. |
+ *
+ * ---
+ *
+ * ## Position values
+ *
+ * | Value           | Description                                          |
+ * |-----------------|------------------------------------------------------|
+ * | `"top"`         | Centered above the trigger (default)                 |
+ * | `"bottom"`      | Centered below the trigger                           |
+ * | `"left"`        | To the left of the trigger                           |
+ * | `"right"`       | To the right of the trigger                          |
+ * | `"top-start"`   | Above the trigger, aligned to its start (left) edge  |
+ * | `"top-end"`     | Above the trigger, aligned to its end (right) edge   |
+ * | `"bottom-start"`| Below the trigger, aligned to its start (left) edge  |
+ * | `"bottom-end"`  | Below the trigger, aligned to its end (right) edge   |
+ *
+ * ---
+ *
+ * ## Examples
+ *
+ * ### Standard tooltip — hover trigger (most common pattern)
+ * Uses the `text` prop for content. Always put the interactive element in `slot="tooltip-trigger"`.
+ * ```html
+ * <vds-tooltip text="Save your changes" position="top" event="hover">
+ *   <vds-icon-button slot="tooltip-trigger" icon="save" aria-label="Save"></vds-icon-button>
+ * </vds-tooltip>
+ * ```
+ *
+ * ### Standard tooltip — click trigger
+ * The tooltip opens on click and closes when the user clicks anywhere outside the component.
+ * ```html
+ * <vds-tooltip text="Must be at least 8 characters" position="right" event="click">
+ *   <vds-icon-button
+ *     slot="tooltip-trigger"
+ *     icon="information"
+ *     variant="secondary"
+ *     aria-label="Password requirements"
+ *   ></vds-icon-button>
+ * </vds-tooltip>
+ * ```
+ *
+ * ### All eight position values
+ * ```html
+ * <!-- Above, centered (default) -->
+ * <vds-tooltip text="top" position="top">
+ *   <span slot="tooltip-trigger">top</span>
+ * </vds-tooltip>
+ *
+ * <!-- Below, centered -->
+ * <vds-tooltip text="bottom" position="bottom">
+ *   <span slot="tooltip-trigger">bottom</span>
+ * </vds-tooltip>
+ *
+ * <!-- Left of trigger -->
+ * <vds-tooltip text="left" position="left">
+ *   <span slot="tooltip-trigger">left</span>
+ * </vds-tooltip>
+ *
+ * <!-- Right of trigger -->
+ * <vds-tooltip text="right" position="right">
+ *   <span slot="tooltip-trigger">right</span>
+ * </vds-tooltip>
+ *
+ * <!-- Above, start-aligned -->
+ * <vds-tooltip text="top-start" position="top-start">
+ *   <span slot="tooltip-trigger">top-start</span>
+ * </vds-tooltip>
+ *
+ * <!-- Above, end-aligned -->
+ * <vds-tooltip text="top-end" position="top-end">
+ *   <span slot="tooltip-trigger">top-end</span>
+ * </vds-tooltip>
+ *
+ * <!-- Below, start-aligned -->
+ * <vds-tooltip text="bottom-start" position="bottom-start">
+ *   <span slot="tooltip-trigger">bottom-start</span>
+ * </vds-tooltip>
+ *
+ * <!-- Below, end-aligned -->
+ * <vds-tooltip text="bottom-end" position="bottom-end">
+ *   <span slot="tooltip-trigger">bottom-end</span>
+ * </vds-tooltip>
+ * ```
+ *
+ * ### Custom type — rich HTML content via `tooltip-content` slot
+ * Set `type="custom"` and provide content in `slot="tooltip-content"`.
+ * The `text` prop is ignored in this mode.
+ * ```html
+ * <vds-tooltip type="custom" position="bottom" event="click" max-width="200px">
+ *   <span slot="tooltip-trigger" style="color: var(--color-text-general-medium);">
+ *     Show details
+ *   </span>
+ *   <div slot="tooltip-content" style="padding: var(--spacing-02);">
+ *     <span style="display:block; margin-bottom: var(--spacing-01);">Learn more:</span>
+ *     <vds-link value="Documentation" target="_blank"></vds-link>
+ *   </div>
+ * </vds-tooltip>
+ * ```
+ *
+ * ### Custom type — user profile card
+ * ```html
+ * <vds-tooltip type="custom" position="right" event="hover" max-width="220px">
+ *   <vds-avatar slot="tooltip-trigger" name="Jane Smith"></vds-avatar>
+ *   <div slot="tooltip-content" style="padding: var(--spacing-03);">
+ *     <p style="margin: 0 0 var(--spacing-01) 0; font-weight: bold;">Jane Smith</p>
+ *     <p style="margin: 0 0 var(--spacing-02) 0; color: var(--color-text-general-medium);">
+ *       Senior Engineer
+ *     </p>
+ *     <vds-chip>Platform</vds-chip>
+ *   </div>
+ * </vds-tooltip>
+ * ```
+ *
+ * ### Manual type — full programmatic control
+ * Set `type="manual"` to disable all automatic hover/click triggering.
+ * The tooltip only opens and closes through calls to `open()` / `close()`.
+ * The `text` prop is still used for content; combine with `type="custom"` if you need a slot.
+ * ```html
+ * <vds-tooltip
+ *   id="manualTip"
+ *   type="manual"
+ *   text="This tooltip is fully controlled by JavaScript"
+ *   position="bottom"
+ * >
+ *   <span slot="tooltip-trigger" style="color: var(--color-text-general-medium);">
+ *     Reference element
+ *   </span>
+ * </vds-tooltip>
+ *
+ * <vds-button id="tipOpenBtn">Open tooltip</vds-button>
+ * <vds-button id="tipCloseBtn" variant="secondary">Close tooltip</vds-button>
+ *
+ * <script>
+ *   const tip = document.getElementById('manualTip');
+ *   document.getElementById('tipOpenBtn').addEventListener('click', () => tip.open());
+ *   document.getElementById('tipCloseBtn').addEventListener('click', () => tip.close());
+ * </script>
+ * ```
+ *
+ * ### Listening to `opened` and `closed` events
+ * Both events fire for all three `type` modes.
+ * ```html
+ * <vds-tooltip id="evtTip" text="Tracked tooltip" position="top" event="hover">
+ *   <span slot="tooltip-trigger" style="color: var(--color-text-general-medium);">
+ *     Hover me
+ *   </span>
+ * </vds-tooltip>
+ *
+ * <script>
+ *   const tip = document.getElementById('evtTip');
+ *   tip.addEventListener('opened', () => console.log('Tooltip became visible'));
+ *   tip.addEventListener('closed', () => console.log('Tooltip became hidden'));
+ * </script>
+ * ```
+ *
+ * ### Custom max-width for longer text
+ * By default the bubble is capped at `10rem`. Increase it when your text would otherwise wrap too aggressively.
+ * ```html
+ * <vds-tooltip
+ *   text="Required format: DD/MM/YYYY — future dates are not allowed"
+ *   position="bottom"
+ *   max-width="18rem"
+ * >
+ *   <vds-icon-button
+ *     slot="tooltip-trigger"
+ *     icon="information"
+ *     aria-label="Date format help"
+ *   ></vds-icon-button>
+ * </vds-tooltip>
+ * ```
+ *
+ * ### Auto-position — let the floating engine pick the best placement
+ * Enable `auto-position` when the trigger element is near a viewport edge and the preferred
+ * `position` might cause the bubble to clip. The engine flips or shifts the bubble automatically.
+ * ```html
+ * <vds-tooltip
+ *   text="I stay within the viewport"
+ *   position="top"
+ *   auto-position="true"
+ * >
+ *   <vds-button slot="tooltip-trigger">Near-edge button</vds-button>
+ * </vds-tooltip>
+ * ```
+ *
+ * ### Tooltip on a toolbar of icon buttons
+ * A common pattern — each action button gets a descriptive label via a hover tooltip.
+ * ```html
+ * <div style="display: flex; gap: var(--spacing-02);">
+ *   <vds-tooltip text="Bold" position="bottom">
+ *     <vds-icon-button slot="tooltip-trigger" icon="bold" aria-label="Bold"></vds-icon-button>
+ *   </vds-tooltip>
+ *
+ *   <vds-tooltip text="Italic" position="bottom">
+ *     <vds-icon-button slot="tooltip-trigger" icon="italic" aria-label="Italic"></vds-icon-button>
+ *   </vds-tooltip>
+ *
+ *   <vds-tooltip text="Underline" position="bottom">
+ *     <vds-icon-button slot="tooltip-trigger" icon="underline" aria-label="Underline"></vds-icon-button>
+ *   </vds-tooltip>
+ * </div>
+ * ```
+ *
+ * ### Inline field hint using click trigger
+ * Place a tooltip next to a form label to surface helper text on demand.
+ * ```html
+ * <div style="display: flex; align-items: center; gap: var(--spacing-02);">
+ *   <vds-label value="API Key"></vds-label>
+ *   <vds-tooltip
+ *     text="Found in Settings → Developer → API Keys"
+ *     position="right"
+ *     event="click"
+ *     max-width="14rem"
+ *   >
+ *     <vds-icon-button
+ *       slot="tooltip-trigger"
+ *       icon="information"
+ *       variant="secondary"
+ *       size="small"
+ *       aria-label="Where to find the API key"
+ *     ></vds-icon-button>
+ *   </vds-tooltip>
+ * </div>
+ * <vds-input placeholder="Paste your API key here"></vds-input>
+ * ```
+ *
+ * @slot tooltip-trigger  - The element that anchors the tooltip and that the user hovers or clicks. Always required.
+ * @slot tooltip-content  - Rich HTML content rendered inside the tooltip bubble. **Only active when `type="custom"`.**
+ */
 export class VdsTooltip {
     constructor() {
-        /** standard type receives the text in the "text" property, "custom" is an slot to include any html element inside the tooltip, "manual" allow open and close the tooltip only with the public methods  */
+        /**
+         * Determines how the tooltip is triggered and which content source is used.
+         *
+         * - `"standard"` — content comes from the `text` prop; opens/closes via `event` (hover or click).
+         *   This is the correct choice for plain-text labels on icon buttons, status badges, etc.
+         * - `"custom"` — content comes from `slot="tooltip-content"`; opens/closes via `event`.
+         *   Use this when the bubble needs formatted HTML, links, or other rich content.
+         * - `"manual"` — content comes from the `text` prop; hover and click listeners are disabled.
+         *   The tooltip only responds to calls to `open()` and `close()`. Use this for tour flows,
+         *   validation highlights, or any case where JavaScript controls visibility.
+         *
+         * > **Note:** providing `slot="tooltip-content"` on a `"standard"` or `"manual"` tooltip has
+         * > no effect — the slot is only rendered when `type="custom"`.
+         *
+         * @type {"standard" | "custom" | "manual"}
+         * @default "standard"
+         * @example <vds-tooltip type="standard" text="Save changes"><vds-icon-button slot="tooltip-trigger" icon="save"></vds-icon-button></vds-tooltip>
+         * @example <vds-tooltip type="custom"><span slot="tooltip-trigger">Hover</span><div slot="tooltip-content"><vds-link value="Docs"></vds-link></div></vds-tooltip>
+         * @example <vds-tooltip type="manual" text="Step 1 of 3" id="tourTip"><span slot="tooltip-trigger">Field</span></vds-tooltip>
+         */
         this.type = "standard";
-        /** Defines the position where the tooltip will be opened */
+        /**
+         * Preferred placement of the tooltip bubble relative to the trigger element.
+         * If `auto-position="true"` is also set, the engine may override this when the bubble
+         * would overflow the viewport.
+         *
+         * Accepted values: `"top"` (default), `"bottom"`, `"left"`, `"right"`,
+         * `"top-start"`, `"top-end"`, `"bottom-start"`, `"bottom-end"`.
+         *
+         * - `"top"` / `"bottom"` / `"left"` / `"right"` — centered on the respective side
+         * - `"*-start"` — aligned to the start (left) edge of the trigger
+         * - `"*-end"` — aligned to the end (right) edge of the trigger
+         *
+         * @type {"top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end"}
+         * @default "top"
+         * @example <vds-tooltip text="Below" position="bottom"><span slot="tooltip-trigger">element</span></vds-tooltip>
+         * @example <vds-tooltip text="Right side" position="right"><span slot="tooltip-trigger">element</span></vds-tooltip>
+         * @example <vds-tooltip text="Start-aligned" position="bottom-start"><span slot="tooltip-trigger">element</span></vds-tooltip>
+         */
         this.position = 'top';
-        /** Sets the maximum width of the tooltip's content */
+        /**
+         * Maximum width of the tooltip bubble. Accepts any valid CSS length value (`rem`, `px`, `%`, etc.).
+         * The default (`10rem`) suits short single-line labels. Increase it for longer descriptive text
+         * to reduce excessive line-wrapping.
+         * Internally sets the `--tooltip-max-width` CSS custom property on the host element.
+         * @type {string}
+         * @default "10rem"
+         * @example <vds-tooltip text="Detailed explanation of this field" max-width="18rem"><span slot="tooltip-trigger">Field</span></vds-tooltip>
+         */
         this.maxWidth = "10rem";
-        /** The type of event that will trigger the tooltip */
+        /**
+         * The DOM event on the trigger element that opens (and closes) the tooltip.
+         *
+         * - `"hover"` — tooltip appears on `mouseenter` and disappears on `mouseleave`. Best for
+         *   desktop-only icon labels and non-critical hints.
+         * - `"click"` — tooltip toggles on click and closes when the user clicks anywhere outside
+         *   the component. Better for touch devices or when the content requires deliberate intent
+         *   (e.g. password-rules hints, field-format guidance).
+         *
+         * This prop has no effect when `type="manual"`.
+         *
+         * @type {"hover" | "click"}
+         * @default "hover"
+         * @example <vds-tooltip text="Shown on hover" event="hover"><span slot="tooltip-trigger">element</span></vds-tooltip>
+         * @example <vds-tooltip text="Shown on click" event="click"><span slot="tooltip-trigger">element</span></vds-tooltip>
+         */
         this.event = 'hover';
-        /** Toggles the floating container auto-positioning based on available window space.
-         * False by default as it may cause positioning issues in some situations, use with caution
-         * */
+        /**
+         * When `true`, the floating positioning engine automatically flips or shifts the bubble to keep
+         * it within the visible viewport, overriding the `position` value when necessary.
+         * Enable this when the trigger element can appear near screen edges (e.g. in scrollable tables,
+         * sidebars, or responsive layouts). Leave it `false` when you need a strictly fixed placement.
+         * @type {boolean}
+         * @default false
+         * @example <vds-tooltip text="Stays in viewport" position="top" auto-position="true"><span slot="tooltip-trigger">element</span></vds-tooltip>
+         */
         this.autoPosition = false;
+        /**
+         * Internal state tracking whether the tooltip is currently visible
+         * @private
+         * @type {boolean}
+         * @default false
+         */
         this.popupOpened = false;
         this.floatingCleanup = () => { };
     }
+    /**
+     * Watches popup state changes and emits corresponding events, updates positioning
+     * @private
+     * @returns {Promise<void>}
+     */
     async emitValue() {
         if (this.popupOpened) {
             this.opened.emit();
@@ -30,14 +376,22 @@ export class VdsTooltip {
             this.floatingCleanup();
         }
     }
-    /* Close the tooltip when click outside */
+    /**
+     * Closes the tooltip when clicking outside the component
+     * @private
+     * @param {MouseEvent} evt - The click event
+     */
     handleClickOut(evt) {
         const isClickInside = this.hostEl.contains(evt.target);
         if (!isClickInside && this.type !== 'manual') {
             this.popupOpened = false;
         }
     }
-    /* Open the tooltip with click on the trigger element  */
+    /**
+     * Opens the tooltip when the trigger element is clicked (if event is 'click')
+     * @private
+     * @param {Event} event - The click event
+     */
     handleClick(event) {
         if (this.event === 'click' && this.type !== 'manual') {
             const clickedElement = event.target;
@@ -46,21 +400,77 @@ export class VdsTooltip {
             }
         }
     }
-    /* Open the tooltip from other element  */
+    /**
+     * Programmatically makes the tooltip visible by setting the internal `popupOpened` state to
+     * `true`. Triggers the floating-engine positioning update and emits the `opened` event.
+     *
+     * This is the **only** way to show the tooltip when `type="manual"`. For `type="standard"` and
+     * `type="custom"` it can supplement the automatic hover/click behaviour (e.g. show the tooltip
+     * when a related field receives focus).
+     *
+     * @method
+     * @public
+     * @returns {Promise<void>} Resolves once the visible state has been set.
+     * @example
+     * const tip = document.querySelector('vds-tooltip');
+     * await tip.open();
+     * @example
+     * // Show a tour step tooltip when the user reaches a particular step
+     * async function showStep(stepIndex) {
+     *   const tooltips = document.querySelectorAll('vds-tooltip[type="manual"]');
+     *   await tooltips[stepIndex].open();
+     * }
+     */
     async open() {
         this.popupOpened = true;
     }
-    /* Close the tooltip from other element  */
+    /**
+     * Programmatically hides the tooltip by setting the internal `popupOpened` state to `false`.
+     * Cleans up the floating-engine listeners and emits the `closed` event.
+     *
+     * When `type="manual"` this is the **only** way to hide the tooltip — clicking outside or
+     * moving the mouse away has no effect. For other types it can be used to close the tooltip
+     * imperatively (e.g. close it when a form is submitted).
+     *
+     * @method
+     * @public
+     * @returns {Promise<void>} Resolves once the hidden state has been set.
+     * @example
+     * const tip = document.querySelector('vds-tooltip');
+     * await tip.close();
+     * @example
+     * // Close all open tooltips on route change
+     * document.querySelectorAll('vds-tooltip').forEach(tip => tip.close());
+     */
     async close() {
         this.popupOpened = false;
     }
     /**
-     *  Gets the target that will manage the tooltip
-     *  returns a promise with the target HTMLElement.
+     * Returns a reference to the internal `.vds__tooltip-container` DOM element.
+     * Useful when you need to inspect the bubble's bounding box, apply additional inline styles,
+     * or observe its visibility with an `IntersectionObserver`.
+     *
+     * > **Note:** prefer `open()` / `close()` for controlling visibility. Only use `getTarget()`
+     * > when you genuinely need access to the underlying DOM node.
+     *
+     * @method
+     * @public
+     * @returns {Promise<HTMLElement | null>} The tooltip container element, or `null` if not found.
+     * @example
+     * const tip = document.querySelector('vds-tooltip');
+     * const container = await tip.getTarget();
+     * if (container) {
+     *   console.log('Bubble bounding rect:', container.getBoundingClientRect());
+     * }
      */
     async getTarget() {
         return document.querySelector('.vds__tooltip-container');
     }
+    /**
+     * Handles mouse enter event to show tooltip on hover
+     * @private
+     * @param {Event} event - The mouse enter event
+     */
     handleHover(event) {
         if (this.event === 'hover') {
             const hoveredElement = event.target;
@@ -69,6 +479,11 @@ export class VdsTooltip {
             }
         }
     }
+    /**
+     * Handles mouse leave event to hide tooltip on hover out
+     * @private
+     * @param {Event} event - The mouse leave event
+     */
     handleHoverOut(event) {
         if (this.event === 'hover') {
             const hoveredElement = event.target;
@@ -77,9 +492,18 @@ export class VdsTooltip {
             }
         }
     }
+    /**
+     * Sets the max width CSS custom property
+     * @private
+     * @returns {{[key: string]: string}} CSS custom property object
+     */
     setMaxWidth() {
         return { '--tooltip-max-width': this.maxWidth };
     }
+    /**
+     * Lifecycle method that runs after component loads
+     * @private
+     */
     componentDidLoad() {
         this.actionElementRef = queryElementFromShadowRoot(this.hostEl, '.vds__tooltip-trigger');
         this.arrowElementRef = queryElementFromShadowRoot(this.hostEl, '.vds__tooltip-arrow');
@@ -93,6 +517,10 @@ export class VdsTooltip {
             this.actionElementRef.addEventListener('mouseleave', this.handleHoverOut.bind(this));
         }
     }
+    /**
+     * Lifecycle method that runs when component is removed from DOM
+     * @private
+     */
     disconnectedCallback() {
         window.removeEventListener('click', this.handleClickOut.bind(this));
         if (this.event === 'click') {
@@ -103,19 +531,23 @@ export class VdsTooltip {
             this.actionElementRef.removeEventListener('mouseleave', this.handleHoverOut.bind(this));
         }
     }
+    /**
+     * Renders the tooltip component
+     * @returns {HTMLStencilElement} The rendered tooltip element
+     */
     render() {
-        return (h(Host, { key: 'd936c55e708f6572909b283ac46e7910a6844416', style: this.setMaxWidth() }, h("div", { key: '24bf56c54cc650c4df53c8ddd6d2d4138c008ce7', class: "vds__tooltip-trigger", onClick: (evt) => {
+        return (h(Host, { key: '1601aac864be622161abdf758d96cc6a7e80db97', style: this.setMaxWidth() }, h("div", { key: 'f5340b0f8bb452883b8a3e0f83447b1730ca73dc', class: "vds__tooltip-trigger", onClick: (evt) => {
                 this.handleClick(evt);
             }, ref: (triggerEl) => {
                 if (triggerEl)
                     this.actionElementRef = triggerEl;
-            } }, h("slot", { key: 'fdfe92e9bb1f6da214685e29e25f1d9e3bf9e785', name: "tooltip-trigger" })), h("div", { key: 'c31103d1b8ac82e96afc017c05d5ab3c688d5fe7', class: "vds__tooltip-container", ref: (tooltipEl) => {
+            } }, h("slot", { key: 'a27744861e4e984c9986eb378c974a58bee2af4e', name: "tooltip-trigger" })), h("div", { key: 'b2bf8e344eff8e9435155d4aa5ad415130a66496', class: "vds__tooltip-container", ref: (tooltipEl) => {
                 if (tooltipEl)
                     this.tooltipElementRef = tooltipEl;
-            } }, h("div", { key: '7806307702329619fd8a2ba3f53936b503f9ddaf' }, this.type === 'standard' || this.type === 'manual' ? h("span", { class: "vds__tooltip-container-text" }, this.text) : h("slot", { name: "tooltip-content" })), h("div", { key: '8fb5bc210cc969a2722ed297cc5e539b9e6d6a70', class: "vds__tooltip-arrow", ref: (tooltipArrowEl) => {
+            } }, h("div", { key: 'af17f559ff344903bb1394742d8c72417b23041b' }, this.type === 'standard' || this.type === 'manual' ? h("span", { class: "vds__tooltip-container-text" }, this.text) : h("slot", { name: "tooltip-content" })), h("div", { key: '20ad3fbeeb8bbf12f122e6e45ff58e87ea2c44e7', class: "vds__tooltip-arrow", ref: (tooltipArrowEl) => {
                 if (tooltipArrowEl)
                     this.arrowElementRef = tooltipArrowEl;
-            } }, h("svg", { key: '0df738281da38846dc0c51089622ca1aba70d994', class: "vds__tooltip-arrow-img", width: "8", height: "4", viewBox: "0 0 8 4", fill: "none", xmlns: "http://www.w3.org/2000/svg" }, h("path", { key: '3640cf38e897faad29d8a424a3efbeab292cf68f', id: "tooltip-caret-filled-small", d: "M0 0L4 4L8 0H0Z", fill: "var(--surface-overlay-default)" }))))));
+            } }, h("svg", { key: '4737dfe0d52408d50c59d6fd16e8004a1d9cfbeb', class: "vds__tooltip-arrow-img", width: "8", height: "4", viewBox: "0 0 8 4", fill: "none", xmlns: "http://www.w3.org/2000/svg" }, h("path", { key: '7b4d508ff62c2273a24506eae7c97828351ce0ab', id: "tooltip-caret-filled-small", d: "M0 0L4 4L8 0H0Z", fill: "var(--surface-overlay-default)" }))))));
     }
     static get is() { return "vds-tooltip"; }
     static get encapsulation() { return "shadow"; }
@@ -142,8 +574,23 @@ export class VdsTooltip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "standard type receives the text in the \"text\" property, \"custom\" is an slot to include any html element inside the tooltip, \"manual\" allow open and close the tooltip only with the public methods"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"standard\" | \"custom\" | \"manual\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"standard\""
+                        }, {
+                            "name": "example",
+                            "text": "<vds-tooltip type=\"standard\" text=\"Save changes\"><vds-icon-button slot=\"tooltip-trigger\" icon=\"save\"></vds-icon-button></vds-tooltip>"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-tooltip type=\"custom\"><span slot=\"tooltip-trigger\">Hover</span><div slot=\"tooltip-content\"><vds-link value=\"Docs\"></vds-link></div></vds-tooltip>"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-tooltip type=\"manual\" text=\"Step 1 of 3\" id=\"tourTip\"><span slot=\"tooltip-trigger\">Field</span></vds-tooltip>"
+                        }],
+                    "text": "Determines how the tooltip is triggered and which content source is used.\n\n- `\"standard\"` \u2014 content comes from the `text` prop; opens/closes via `event` (hover or click).\n  This is the correct choice for plain-text labels on icon buttons, status badges, etc.\n- `\"custom\"` \u2014 content comes from `slot=\"tooltip-content\"`; opens/closes via `event`.\n  Use this when the bubble needs formatted HTML, links, or other rich content.\n- `\"manual\"` \u2014 content comes from the `text` prop; hover and click listeners are disabled.\n  The tooltip only responds to calls to `open()` and `close()`. Use this for tour flows,\n  validation highlights, or any case where JavaScript controls visibility.\n\n> **Note:** providing `slot=\"tooltip-content\"` on a `\"standard\"` or `\"manual\"` tooltip has\n> no effect \u2014 the slot is only rendered when `type=\"custom\"`."
                 },
                 "getter": false,
                 "setter": false,
@@ -162,8 +609,17 @@ export class VdsTooltip {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the tooltip text, does not apply for custom tooltip"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }, {
+                            "name": "default",
+                            "text": "undefined"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-tooltip text=\"Copy to clipboard\"><vds-icon-button slot=\"tooltip-trigger\" icon=\"copy\"></vds-icon-button></vds-tooltip>"
+                        }],
+                    "text": "Plain-text content rendered inside the tooltip bubble.\nUsed when `type=\"standard\"` (default) or `type=\"manual\"`.\nIgnored when `type=\"custom\"` \u2014 use `slot=\"tooltip-content\"` instead."
                 },
                 "getter": false,
                 "setter": false,
@@ -174,15 +630,30 @@ export class VdsTooltip {
                 "type": "string",
                 "mutable": true,
                 "complexType": {
-                    "original": "'top' | 'bottom' | 'right' | 'left'",
-                    "resolved": "\"bottom\" | \"left\" | \"right\" | \"top\"",
+                    "original": "'top' | 'bottom' | 'right' | 'left' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'",
+                    "resolved": "\"bottom\" | \"bottom-end\" | \"bottom-start\" | \"left\" | \"right\" | \"top\" | \"top-end\" | \"top-start\"",
                     "references": {}
                 },
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Defines the position where the tooltip will be opened"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"top\" | \"bottom\" | \"right\" | \"left\" | \"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"top\""
+                        }, {
+                            "name": "example",
+                            "text": "<vds-tooltip text=\"Below\" position=\"bottom\"><span slot=\"tooltip-trigger\">element</span></vds-tooltip>"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-tooltip text=\"Right side\" position=\"right\"><span slot=\"tooltip-trigger\">element</span></vds-tooltip>"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-tooltip text=\"Start-aligned\" position=\"bottom-start\"><span slot=\"tooltip-trigger\">element</span></vds-tooltip>"
+                        }],
+                    "text": "Preferred placement of the tooltip bubble relative to the trigger element.\nIf `auto-position=\"true\"` is also set, the engine may override this when the bubble\nwould overflow the viewport.\n\nAccepted values: `\"top\"` (default), `\"bottom\"`, `\"left\"`, `\"right\"`,\n`\"top-start\"`, `\"top-end\"`, `\"bottom-start\"`, `\"bottom-end\"`.\n\n- `\"top\"` / `\"bottom\"` / `\"left\"` / `\"right\"` \u2014 centered on the respective side\n- `\"*-start\"` \u2014 aligned to the start (left) edge of the trigger\n- `\"*-end\"` \u2014 aligned to the end (right) edge of the trigger"
                 },
                 "getter": false,
                 "setter": false,
@@ -201,8 +672,17 @@ export class VdsTooltip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the maximum width of the tooltip's content"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{string}"
+                        }, {
+                            "name": "default",
+                            "text": "\"10rem\""
+                        }, {
+                            "name": "example",
+                            "text": "<vds-tooltip text=\"Detailed explanation of this field\" max-width=\"18rem\"><span slot=\"tooltip-trigger\">Field</span></vds-tooltip>"
+                        }],
+                    "text": "Maximum width of the tooltip bubble. Accepts any valid CSS length value (`rem`, `px`, `%`, etc.).\nThe default (`10rem`) suits short single-line labels. Increase it for longer descriptive text\nto reduce excessive line-wrapping.\nInternally sets the `--tooltip-max-width` CSS custom property on the host element."
                 },
                 "getter": false,
                 "setter": false,
@@ -221,8 +701,20 @@ export class VdsTooltip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "The type of event that will trigger the tooltip"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"hover\" | \"click\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"hover\""
+                        }, {
+                            "name": "example",
+                            "text": "<vds-tooltip text=\"Shown on hover\" event=\"hover\"><span slot=\"tooltip-trigger\">element</span></vds-tooltip>"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-tooltip text=\"Shown on click\" event=\"click\"><span slot=\"tooltip-trigger\">element</span></vds-tooltip>"
+                        }],
+                    "text": "The DOM event on the trigger element that opens (and closes) the tooltip.\n\n- `\"hover\"` \u2014 tooltip appears on `mouseenter` and disappears on `mouseleave`. Best for\n  desktop-only icon labels and non-critical hints.\n- `\"click\"` \u2014 tooltip toggles on click and closes when the user clicks anywhere outside\n  the component. Better for touch devices or when the content requires deliberate intent\n  (e.g. password-rules hints, field-format guidance).\n\nThis prop has no effect when `type=\"manual\"`."
                 },
                 "getter": false,
                 "setter": false,
@@ -241,8 +733,17 @@ export class VdsTooltip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Toggles the floating container auto-positioning based on available window space. \nFalse by default as it may cause positioning issues in some situations, use with caution"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-tooltip text=\"Stays in viewport\" position=\"top\" auto-position=\"true\"><span slot=\"tooltip-trigger\">element</span></vds-tooltip>"
+                        }],
+                    "text": "When `true`, the floating positioning engine automatically flips or shifts the bubble to keep\nit within the visible viewport, overriding the `position` value when necessary.\nEnable this when the trigger element can appear near screen edges (e.g. in scrollable tables,\nsidebars, or responsive layouts). Leave it `false` when you need a strictly fixed placement."
                 },
                 "getter": false,
                 "setter": false,
@@ -265,8 +766,17 @@ export class VdsTooltip {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emits event when tooltip gets opens"
+                    "tags": [{
+                            "name": "event",
+                            "text": "opened"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<void>}"
+                        }, {
+                            "name": "example",
+                            "text": "const tip = document.querySelector('vds-tooltip');\ntip.addEventListener('opened', () => {\n  console.log('Tooltip is now visible');\n});"
+                        }],
+                    "text": "Fired every time the tooltip transitions from hidden to visible \u2014 regardless of whether the\ntrigger was hover, click, or a programmatic call to `open()`.\nUse this to lazy-load tooltip content, log analytics, or synchronise other UI state."
                 },
                 "complexType": {
                     "original": "void",
@@ -280,8 +790,17 @@ export class VdsTooltip {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emits event when tooltip gets closes"
+                    "tags": [{
+                            "name": "event",
+                            "text": "closed"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<void>}"
+                        }, {
+                            "name": "example",
+                            "text": "const tip = document.querySelector('vds-tooltip');\ntip.addEventListener('closed', () => {\n  console.log('Tooltip is now hidden');\n});"
+                        }],
+                    "text": "Fired every time the tooltip transitions from visible to hidden \u2014 regardless of whether it was\ncaused by mouse-leave, an outside click, or a programmatic call to `close()`.\nUse this to restore focus, clear temporary state, or chain follow-up actions."
                 },
                 "complexType": {
                     "original": "void",
@@ -305,8 +824,23 @@ export class VdsTooltip {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "",
-                    "tags": []
+                    "text": "Programmatically makes the tooltip visible by setting the internal `popupOpened` state to\n`true`. Triggers the floating-engine positioning update and emits the `opened` event.\n\nThis is the **only** way to show the tooltip when `type=\"manual\"`. For `type=\"standard\"` and\n`type=\"custom\"` it can supplement the automatic hover/click behaviour (e.g. show the tooltip\nwhen a related field receives focus).",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": "Resolves once the visible state has been set."
+                        }, {
+                            "name": "example",
+                            "text": "const tip = document.querySelector('vds-tooltip');\nawait tip.open();"
+                        }, {
+                            "name": "example",
+                            "text": "// Show a tour step tooltip when the user reaches a particular step\nasync function showStep(stepIndex) {\n  const tooltips = document.querySelectorAll('vds-tooltip[type=\"manual\"]');\n  await tooltips[stepIndex].open();\n}"
+                        }]
                 }
             },
             "close": {
@@ -322,8 +856,23 @@ export class VdsTooltip {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "",
-                    "tags": []
+                    "text": "Programmatically hides the tooltip by setting the internal `popupOpened` state to `false`.\nCleans up the floating-engine listeners and emits the `closed` event.\n\nWhen `type=\"manual\"` this is the **only** way to hide the tooltip \u2014 clicking outside or\nmoving the mouse away has no effect. For other types it can be used to close the tooltip\nimperatively (e.g. close it when a form is submitted).",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": "Resolves once the hidden state has been set."
+                        }, {
+                            "name": "example",
+                            "text": "const tip = document.querySelector('vds-tooltip');\nawait tip.close();"
+                        }, {
+                            "name": "example",
+                            "text": "// Close all open tooltips on route change\ndocument.querySelectorAll('vds-tooltip').forEach(tip => tip.close());"
+                        }]
                 }
             },
             "getTarget": {
@@ -343,8 +892,20 @@ export class VdsTooltip {
                     "return": "Promise<HTMLElement>"
                 },
                 "docs": {
-                    "text": "Gets the target that will manage the tooltip\nreturns a promise with the target HTMLElement.",
-                    "tags": []
+                    "text": "Returns a reference to the internal `.vds__tooltip-container` DOM element.\nUseful when you need to inspect the bubble's bounding box, apply additional inline styles,\nor observe its visibility with an `IntersectionObserver`.\n\n> **Note:** prefer `open()` / `close()` for controlling visibility. Only use `getTarget()`\n> when you genuinely need access to the underlying DOM node.",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": "The tooltip container element, or `null` if not found."
+                        }, {
+                            "name": "example",
+                            "text": "const tip = document.querySelector('vds-tooltip');\nconst container = await tip.getTarget();\nif (container) {\n  console.log('Bubble bounding rect:', container.getBoundingClientRect());\n}"
+                        }]
                 }
             }
         };
@@ -372,4 +933,3 @@ export class VdsTooltip {
             }];
     }
 }
-//# sourceMappingURL=vds-tooltip.js.map