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

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

@@ -1,44 +1,509 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { HTMLStencilElement } from '../../stencil-public-runtime';
+/**
+ * @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 declare class VdsTooltip {
     hostEl: HTMLElement;
-    /** 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>
+     */
     type: "standard" | "custom" | "manual";
-    /** Sets the tooltip text, does not apply for custom tooltip */
+    /**
+     * Plain-text content rendered inside the tooltip bubble.
+     * Used when `type="standard"` (default) or `type="manual"`.
+     * Ignored when `type="custom"` — use `slot="tooltip-content"` instead.
+     * @type {string}
+     * @default undefined
+     * @example <vds-tooltip text="Copy to clipboard"><vds-icon-button slot="tooltip-trigger" icon="copy"></vds-icon-button></vds-tooltip>
+     */
     text?: string;
-    /** Defines the position where the tooltip will be opened */
-    position: 'top' | 'bottom' | 'right' | 'left';
-    /** Sets the maximum width of the tooltip's content */
+    /**
+     * 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>
+     */
+    position: 'top' | 'bottom' | 'right' | 'left' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+    /**
+     * 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>
+     */
     maxWidth: string;
-    /** 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>
+     */
     event: 'hover' | 'click';
-    /** 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>
+     */
     autoPosition: boolean;
+    /**
+     * Internal state tracking whether the tooltip is currently visible
+     * @private
+     * @type {boolean}
+     * @default false
+     */
     popupOpened: boolean;
-    /** Emits event when tooltip gets opens */
+    /**
+     * Fired every time the tooltip transitions from hidden to visible — regardless of whether the
+     * trigger was hover, click, or a programmatic call to `open()`.
+     * Use this to lazy-load tooltip content, log analytics, or synchronise other UI state.
+     * @event opened
+     * @type {EventEmitter<void>}
+     * @example
+     * const tip = document.querySelector('vds-tooltip');
+     * tip.addEventListener('opened', () => {
+     *   console.log('Tooltip is now visible');
+     * });
+     */
     opened: EventEmitter<void>;
-    /** Emits event when tooltip gets closes */
+    /**
+     * Fired every time the tooltip transitions from visible to hidden — regardless of whether it was
+     * caused by mouse-leave, an outside click, or a programmatic call to `close()`.
+     * Use this to restore focus, clear temporary state, or chain follow-up actions.
+     * @event closed
+     * @type {EventEmitter<void>}
+     * @example
+     * const tip = document.querySelector('vds-tooltip');
+     * tip.addEventListener('closed', () => {
+     *   console.log('Tooltip is now hidden');
+     * });
+     */
     closed: EventEmitter<void>;
-    floatingCleanup: () => void;
+    private floatingCleanup;
+    /**
+     * Watches popup state changes and emits corresponding events, updates positioning
+     * @private
+     * @returns {Promise<void>}
+     */
     emitValue(): Promise<void>;
+    /**
+     * Closes the tooltip when clicking outside the component
+     * @private
+     * @param {MouseEvent} evt - The click event
+     */
     private handleClickOut;
+    /**
+     * Opens the tooltip when the trigger element is clicked (if event is 'click')
+     * @private
+     * @param {Event} event - The click event
+     */
     private handleClick;
+    /**
+     * 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();
+     * }
+     */
     open(): Promise<void>;
+    /**
+     * 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());
+     */
     close(): Promise<void>;
     /**
-     *  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());
+     * }
      */
     getTarget(): Promise<HTMLElement | null>;
+    /**
+     * Handles mouse enter event to show tooltip on hover
+     * @private
+     * @param {Event} event - The mouse enter event
+     */
     private handleHover;
+    /**
+     * Handles mouse leave event to hide tooltip on hover out
+     * @private
+     * @param {Event} event - The mouse leave event
+     */
     private handleHoverOut;
+    /**
+     * Sets the max width CSS custom property
+     * @private
+     * @returns {{[key: string]: string}} CSS custom property object
+     */
     private setMaxWidth;
     private actionElementRef;
     private arrowElementRef;
     private tooltipElementRef;
+    /**
+     * Lifecycle method that runs after component loads
+     * @private
+     */
     componentDidLoad(): void;
+    /**
+     * Lifecycle method that runs when component is removed from DOM
+     * @private
+     */
     disconnectedCallback(): void;
+    /**
+     * Renders the tooltip component
+     * @returns {HTMLStencilElement} The rendered tooltip element
+     */
     render(): HTMLStencilElement;
 }