@juspay/svelte-ui-components 2.62.1 → 2.63.0

package/dist/Tooltip/PortalContentRenderer.svelte

@@ -0,0 +1,14 @@
+<!--
+  @internal
+  Helper component that renders a Svelte snippet into an imperatively-created DOM element via
+  mount(). Used by Tooltip's portal mode to project rich `content` snippets into a bubble
+  that lives on document.body outside the normal component tree. Not intended for direct
+  consumer use.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  let { snippet }: { snippet: Snippet } = $props();
+</script>
+
+{@render snippet()}

package/dist/Tooltip/PortalContentRenderer.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    snippet: Snippet;
+};
+declare const PortalContentRenderer: import("svelte").Component<$$ComponentProps, {}, "">;
+type PortalContentRenderer = ReturnType<typeof PortalContentRenderer>;
+export default PortalContentRenderer;

package/dist/Tooltip/Tooltip.svelte

@@ -1,5 +1,7 @@
 <script lang="ts">
-  import type { TooltipProperties } from './properties';
+  import { mount, unmount, onDestroy } from 'svelte';
+  import type { TooltipProperties, TooltipPosition } from './properties';
+  import PortalContentRenderer from './PortalContentRenderer.svelte';
 
   let {
     text,
@@ -9,32 +11,199 @@
     classes,
     children,
     icon,
-    content
+    content,
+    usePortal = false
   }: TooltipProperties = $props();
 
   let visible = $state(false);
   let delayTimeout = $state<ReturnType<typeof setTimeout> | null>(null);
 
-  function showTooltip() {
-    if (delay > 0) {
-      delayTimeout = setTimeout(() => {
-        visible = true;
-      }, delay);
+  /** Reference to the trigger wrapper element, used for `getBoundingClientRect` in portal mode. */
+  let containerEl: HTMLDivElement | null = $state(null);
+
+  /**
+   * Imperatively managed portal bubble element.
+   * Created in `showTooltip` and removed in `hideTooltip` when `usePortal=true`.
+   * All styles are applied inline so the element is not subject to Svelte's CSS scoping.
+   */
+  let portalBubbleEl: HTMLDivElement | null = null;
+
+  /**
+   * Mounted Svelte component instance used to render the `content` snippet into the
+   * portal bubble. Stored so it can be unmounted when the bubble is removed.
+   */
+  let portalContentMount: Record<string, unknown> | null = null;
+
+  const computePortalCoords = (
+    rect: DOMRect,
+    pos: TooltipPosition
+  ): { top: number; left: number; transform: string } => {
+    const offset = 8; // matches --tooltip-offset default
+    if (pos === 'top') {
+      return {
+        top: rect.top - offset,
+        left: rect.left + rect.width / 2,
+        transform: 'translate(-50%, -100%)'
+      };
+    }
+    if (pos === 'bottom') {
+      return {
+        top: rect.bottom + offset,
+        left: rect.left + rect.width / 2,
+        transform: 'translate(-50%, 0)'
+      };
+    }
+    if (pos === 'left') {
+      return {
+        top: rect.top + rect.height / 2,
+        left: rect.left - offset,
+        transform: 'translate(-100%, -50%)'
+      };
+    }
+    // right
+    return {
+      top: rect.top + rect.height / 2,
+      left: rect.right + offset,
+      transform: 'translate(0, -50%)'
+    };
+  };
+
+  const computeArrowStyle = (pos: TooltipPosition): string => {
+    const arrowSize = 5; // matches --tooltip-arrow-size default
+    const bg = 'var(--tooltip-arrow-color,var(--tooltip-background,#333333))';
+    const t = 'transparent';
+    const base = 'position:absolute;width:0;height:0;border-style:solid;';
+    if (pos === 'top') {
+      return `${base}top:100%;left:50%;transform:translateX(-50%);border-width:${arrowSize}px ${arrowSize}px 0 ${arrowSize}px;border-color:${bg} ${t} ${t} ${t};`;
+    }
+    if (pos === 'bottom') {
+      return `${base}bottom:100%;left:50%;transform:translateX(-50%);border-width:0 ${arrowSize}px ${arrowSize}px ${arrowSize}px;border-color:${t} ${t} ${bg} ${t};`;
+    }
+    if (pos === 'left') {
+      return `${base}top:50%;left:100%;transform:translateY(-50%);border-width:${arrowSize}px 0 ${arrowSize}px ${arrowSize}px;border-color:${t} ${t} ${t} ${bg};`;
+    }
+    // right
+    return `${base}top:50%;right:100%;transform:translateY(-50%);border-width:${arrowSize}px ${arrowSize}px ${arrowSize}px 0;border-color:${t} ${bg} ${t} ${t};`;
+  };
+
+  const createPortalBubble = (rect: DOMRect, pos: TooltipPosition): HTMLDivElement | null => {
+    if (typeof document === 'undefined') {
+      return null;
+    }
+    const bubble = document.createElement('div');
+    bubble.setAttribute('role', 'tooltip');
+
+    const coords = computePortalCoords(rect, pos);
+    bubble.style.cssText = [
+      `position:fixed`,
+      `top:${coords.top}px`,
+      `left:${coords.left}px`,
+      `transform:${coords.transform}`,
+      `z-index:var(--tooltip-z-index,1000)`,
+      `max-width:var(--tooltip-max-width,200px)`,
+      `background:var(--tooltip-background,#333333)`,
+      `color:var(--tooltip-color,#ffffff)`,
+      `font-size:var(--tooltip-font-size,12px)`,
+      `font-weight:var(--tooltip-font-weight,400)`,
+      `font-family:var(--tooltip-font-family,inherit)`,
+      `padding:var(--tooltip-padding,6px 10px)`,
+      `border-radius:var(--tooltip-border-radius,4px)`,
+      `border:var(--tooltip-border,none)`,
+      `box-shadow:var(--tooltip-box-shadow,0 2px 6px rgba(0,0,0,0.15))`,
+      `white-space:normal`,
+      `word-wrap:break-word`,
+      `pointer-events:none`,
+      `transition:opacity var(--tooltip-opacity-duration,0.15s) ease-in-out`
+    ].join(';');
+
+    const arrowEl = document.createElement('div');
+    arrowEl.style.cssText = computeArrowStyle(pos);
+    bubble.appendChild(arrowEl);
+
+    // Render rich `content` snippet when provided; fall back to plain text.
+    if (typeof content === 'function') {
+      const contentContainer = document.createElement('span');
+      bubble.appendChild(contentContainer);
+      portalContentMount = mount(PortalContentRenderer, {
+        target: contentContainer,
+        props: { snippet: content }
+      });
     } else {
+      const textEl = document.createElement('span');
+      textEl.style.cssText = `color:var(--tooltip-color,#ffffff)`;
+      textEl.textContent = text;
+      bubble.appendChild(textEl);
+    }
+
+    return bubble;
+  };
+
+  const showTooltip = () => {
+    // Guard: if a delay timer is already pending, a second showTooltip() call (e.g. rapid
+    // mouseenter + focusin) would schedule another timer. Return early so only one timer
+    // is ever pending at a time, preventing stale callbacks from re-showing after hide.
+    if (delayTimeout !== null) {
+      return;
+    }
+
+    const doShow = () => {
+      delayTimeout = null;
       visible = true;
+      if (usePortal && containerEl !== null && typeof document !== 'undefined') {
+        const rect = containerEl.getBoundingClientRect();
+        const pos = position;
+        // Guard: only one portal bubble may exist at a time (overlapping events protection).
+        if (portalBubbleEl !== null) {
+          return;
+        }
+        portalBubbleEl = createPortalBubble(rect, pos);
+        if (portalBubbleEl !== null) {
+          document.body.appendChild(portalBubbleEl);
+        }
+      }
+    };
+
+    if (delay > 0) {
+      delayTimeout = setTimeout(doShow, delay);
+    } else {
+      doShow();
     }
-  }
+  };
 
-  function hideTooltip() {
+  const hideTooltip = () => {
     if (delayTimeout !== null) {
       clearTimeout(delayTimeout);
       delayTimeout = null;
     }
     visible = false;
-  }
+    if (portalContentMount !== null) {
+      unmount(portalContentMount);
+      portalContentMount = null;
+    }
+    if (portalBubbleEl !== null && typeof document !== 'undefined') {
+      portalBubbleEl.remove();
+      portalBubbleEl = null;
+    }
+  };
+
+  // Ensure the portal bubble and any pending delay timer are cleaned up when
+  // the component unmounts — prevents orphaned DOM nodes and memory leaks when
+  // Tooltip is used in dynamic lists or conditional rendering contexts.
+  onDestroy(() => {
+    if (delayTimeout !== null) {
+      clearTimeout(delayTimeout);
+    }
+    if (portalContentMount !== null) {
+      unmount(portalContentMount);
+    }
+    if (portalBubbleEl !== null && typeof document !== 'undefined') {
+      portalBubbleEl.remove();
+    }
+  });
 </script>
 
 <div
+  bind:this={containerEl}
   class="tooltip-container {classes ?? ''}"
   role="none"
   onmouseenter={showTooltip}
@@ -47,7 +216,7 @@
     <span class="tooltip-icon" aria-hidden="true">{@render icon()}</span>
   {/if}
   {@render children()}
-  {#if visible}
+  {#if visible && !usePortal}
     <div class="tooltip-bubble {position}" role="tooltip">
       <div class="tooltip-arrow"></div>
       {#if typeof content === 'function'}

package/dist/Tooltip/properties.d.ts

@@ -13,5 +13,23 @@ export type OptionalTooltipProperties = {
     icon?: Snippet;
     /** Snippet rendered as the bubble body. When provided, replaces the plain `text` string inside the tooltip bubble. */
     content?: Snippet;
+    /**
+     * When true, the tooltip bubble is mounted directly on `document.body` using
+     * `position: fixed` coordinates derived from `getBoundingClientRect`. This prevents
+     * clipping inside overflow-hidden or stacking-context ancestors (e.g. toolbar items).
+     */
+    usePortal?: boolean;
 };
 export type TooltipProperties = MandatoryTooltipProperties & OptionalTooltipProperties;
+/**
+ * Options accepted by the `tooltip` Svelte action.
+ * All fields mirror the corresponding Tooltip component props.
+ */
+export type TooltipActionOptions = {
+    /** Tooltip text shown in the bubble. */
+    text: string;
+    position?: TooltipPosition;
+    delay?: number;
+    /** Custom CSS classes forwarded to the bubble element. */
+    classes?: string;
+};

package/dist/Tooltip/tooltip-action.d.ts

@@ -0,0 +1,5 @@
+import type { TooltipActionOptions } from './properties';
+export declare const tooltip: (node: HTMLElement, options: TooltipActionOptions) => {
+    update: (nextOptions: TooltipActionOptions) => void;
+    destroy: () => void;
+};

package/dist/Tooltip/tooltip-action.js

@@ -0,0 +1,229 @@
+/**
+ * Svelte `use:tooltip` action — renderless alternative to the `<Tooltip>` component.
+ *
+ * Attaches hover and focus listeners to the host element without injecting any wrapper
+ * div, which prevents flex-child sizing breakage inside toolbars and icon rows.
+ * The tooltip bubble is mounted directly on `document.body` with `position:fixed`
+ * coordinates derived from `getBoundingClientRect`, so it is never clipped by
+ * `overflow:hidden` ancestors.
+ *
+ * Usage:
+ * ```svelte
+ * <script>
+ *   import { tooltip } from '@juspay/svelte-ui-components';
+ * </script>
+ * <button use:tooltip={{ text: 'Save', position: 'top' }}>💾</button>
+ * ```
+ */
+/** Monotonically-incrementing counter used to generate unique tooltip bubble IDs. */
+let tooltipIdCounter = 0;
+export const tooltip = (node, options) => {
+    let currentOptions = { ...options };
+    let bubbleEl = null;
+    let arrowEl = null;
+    let delayTimer = null;
+    const bubbleId = `sui-tooltip-${++tooltipIdCounter}`;
+    const OFFSET = 8; // px — matches --tooltip-offset default
+    const computeCoords = (rect, pos) => {
+        const arrowSize = 5; // px — matches --tooltip-arrow-size default
+        const bg = 'var(--tooltip-arrow-color,var(--tooltip-background,#333333))';
+        const t = 'transparent';
+        if (pos === 'top') {
+            return {
+                top: rect.top - OFFSET,
+                left: rect.left + rect.width / 2,
+                transform: 'translate(-50%, -100%)',
+                arrowTop: '100%',
+                arrowLeft: '50%',
+                arrowRight: '',
+                arrowTransform: 'translateX(-50%)',
+                arrowBorderWidth: `${arrowSize}px ${arrowSize}px 0 ${arrowSize}px`,
+                arrowBorderColor: `${bg} ${t} ${t} ${t}`
+            };
+        }
+        if (pos === 'bottom') {
+            return {
+                top: rect.bottom + OFFSET,
+                left: rect.left + rect.width / 2,
+                transform: 'translate(-50%, 0)',
+                arrowTop: `-${arrowSize}px`,
+                arrowLeft: '50%',
+                arrowRight: '',
+                arrowTransform: 'translateX(-50%)',
+                arrowBorderWidth: `0 ${arrowSize}px ${arrowSize}px ${arrowSize}px`,
+                arrowBorderColor: `${t} ${t} ${bg} ${t}`
+            };
+        }
+        if (pos === 'left') {
+            return {
+                top: rect.top + rect.height / 2,
+                left: rect.left - OFFSET,
+                transform: 'translate(-100%, -50%)',
+                arrowTop: '50%',
+                arrowLeft: '100%',
+                arrowRight: '',
+                arrowTransform: 'translateY(-50%)',
+                arrowBorderWidth: `${arrowSize}px 0 ${arrowSize}px ${arrowSize}px`,
+                arrowBorderColor: `${t} ${t} ${t} ${bg}`
+            };
+        }
+        // right
+        return {
+            top: rect.top + rect.height / 2,
+            left: rect.right + OFFSET,
+            transform: 'translate(0, -50%)',
+            arrowTop: '50%',
+            arrowLeft: '',
+            arrowRight: `${arrowSize}px`,
+            arrowTransform: 'translateY(-50%)',
+            arrowBorderWidth: `${arrowSize}px ${arrowSize}px ${arrowSize}px 0`,
+            arrowBorderColor: `${t} ${bg} ${t} ${t}`
+        };
+    };
+    /**
+     * Build the bubble and arrow elements and attach them to `document.body`.
+     * Inline styles are used to keep the action self-contained — no stylesheet injection.
+     * Sets `aria-describedby` on the host node to satisfy the ARIA tooltip pattern,
+     * which requires a programmatic association between the trigger and the bubble.
+     */
+    const createBubble = () => {
+        if (typeof document === 'undefined') {
+            return;
+        }
+        bubbleEl = document.createElement('div');
+        bubbleEl.setAttribute('role', 'tooltip');
+        bubbleEl.id = bubbleId;
+        node.setAttribute('aria-describedby', bubbleId);
+        bubbleEl.style.cssText = [
+            'position:fixed',
+            `z-index:var(--tooltip-z-index,1000)`,
+            `max-width:var(--tooltip-max-width,200px)`,
+            `background:var(--tooltip-background,#333333)`,
+            `color:var(--tooltip-color,#ffffff)`,
+            `font-size:var(--tooltip-font-size,12px)`,
+            `font-weight:var(--tooltip-font-weight,400)`,
+            `font-family:var(--tooltip-font-family,inherit)`,
+            `padding:var(--tooltip-padding,6px 10px)`,
+            `border-radius:var(--tooltip-border-radius,4px)`,
+            `border:var(--tooltip-border,none)`,
+            `box-shadow:var(--tooltip-box-shadow,0 2px 6px rgba(0,0,0,0.15))`,
+            'white-space:normal',
+            'word-wrap:break-word',
+            'pointer-events:none',
+            `transition:opacity var(--tooltip-opacity-duration,0.15s) ease-in-out`
+        ].join(';');
+        if (typeof currentOptions.classes === 'string' && currentOptions.classes.length > 0) {
+            bubbleEl.className = currentOptions.classes;
+        }
+        arrowEl = document.createElement('div');
+        arrowEl.style.cssText = 'position:absolute;width:0;height:0;border-style:solid;';
+        const textNode = document.createElement('span');
+        textNode.style.cssText = 'color:var(--tooltip-color,#ffffff)';
+        textNode.textContent = currentOptions.text;
+        bubbleEl.appendChild(arrowEl);
+        bubbleEl.appendChild(textNode);
+        document.body.appendChild(bubbleEl);
+    };
+    /**
+     * Compute and apply `top`/`left` fixed coordinates plus arrow styles based on the
+     * current bounding rect of the host element and the active `position` option.
+     */
+    const positionBubble = () => {
+        if (bubbleEl === null || arrowEl === null) {
+            return;
+        }
+        const rect = node.getBoundingClientRect();
+        const pos = currentOptions.position ?? 'top';
+        const coords = computeCoords(rect, pos);
+        bubbleEl.style.top = `${coords.top}px`;
+        bubbleEl.style.left = `${coords.left}px`;
+        bubbleEl.style.transform = coords.transform;
+        arrowEl.style.top = coords.arrowTop;
+        arrowEl.style.left = coords.arrowLeft;
+        if (coords.arrowRight !== '') {
+            arrowEl.style.right = coords.arrowRight;
+        }
+        arrowEl.style.transform = coords.arrowTransform;
+        arrowEl.style.borderWidth = coords.arrowBorderWidth;
+        arrowEl.style.borderColor = coords.arrowBorderColor;
+    };
+    const show = () => {
+        // Guard against overlapping events (e.g. mouseenter + focusin firing simultaneously,
+        // or two delayed timers both completing) — only one bubble may exist at a time.
+        // Also guard when a delay timer is already pending: a second show() call while the
+        // first is waiting would schedule a second timer; clearing it first prevents stale
+        // timers from re-opening the tooltip after hide() has already run.
+        if (bubbleEl !== null || delayTimer !== null) {
+            return;
+        }
+        const doShow = () => {
+            // Re-check after the delay: hide() may have been called while the timer was pending.
+            if (bubbleEl !== null) {
+                return;
+            }
+            delayTimer = null;
+            createBubble();
+            positionBubble();
+        };
+        const delayMs = currentOptions.delay ?? 0;
+        if (delayMs > 0) {
+            delayTimer = setTimeout(doShow, delayMs);
+        }
+        else {
+            doShow();
+        }
+    };
+    const hide = () => {
+        if (delayTimer !== null) {
+            clearTimeout(delayTimer);
+            delayTimer = null;
+        }
+        if (bubbleEl !== null) {
+            bubbleEl.remove();
+            bubbleEl = null;
+            arrowEl = null;
+            node.removeAttribute('aria-describedby');
+        }
+    };
+    /**
+     * Reposition the bubble when the viewport changes (scroll or resize) so the tooltip
+     * stays anchored to the trigger element while it is visible.
+     */
+    const handleReposition = () => {
+        if (bubbleEl !== null) {
+            positionBubble();
+        }
+    };
+    node.addEventListener('mouseenter', show);
+    node.addEventListener('mouseleave', hide);
+    node.addEventListener('focusin', show);
+    node.addEventListener('focusout', hide);
+    // Guard window access: Svelte actions run after mount (client-side only), but an
+    // explicit check keeps the action safe if it is somehow called during SSR.
+    const hasWindow = typeof window !== 'undefined';
+    if (hasWindow) {
+        window.addEventListener('resize', handleReposition);
+        window.addEventListener('scroll', handleReposition, true);
+    }
+    return {
+        update(nextOptions) {
+            currentOptions = { ...nextOptions };
+            // If bubble is currently visible, re-render it with new options.
+            if (bubbleEl !== null) {
+                hide();
+                show();
+            }
+        },
+        destroy() {
+            hide();
+            node.removeEventListener('mouseenter', show);
+            node.removeEventListener('mouseleave', hide);
+            node.removeEventListener('focusin', show);
+            node.removeEventListener('focusout', hide);
+            if (hasWindow) {
+                window.removeEventListener('resize', handleReposition);
+                window.removeEventListener('scroll', handleReposition, true);
+            }
+        }
+    };
+};

package/dist/index.d.ts

@@ -31,6 +31,7 @@ export { default as Tabs } from './Tabs/Tabs.svelte';
 export { default as Choicebox } from './Choicebox/Choicebox.svelte';
 export { default as Slider } from './Slider/Slider.svelte';
 export { default as Tooltip } from './Tooltip/Tooltip.svelte';
+export { tooltip } from './Tooltip/tooltip-action';
 export { default as Shimmer } from './Shimmer/Shimmer.svelte';
 export { default as Progress } from './Progress/Progress.svelte';
 export { default as Pill } from './Pill/Pill.svelte';

package/dist/index.js

@@ -31,6 +31,7 @@ export { default as Tabs } from './Tabs/Tabs.svelte';
 export { default as Choicebox } from './Choicebox/Choicebox.svelte';
 export { default as Slider } from './Slider/Slider.svelte';
 export { default as Tooltip } from './Tooltip/Tooltip.svelte';
+export { tooltip } from './Tooltip/tooltip-action';
 export { default as Shimmer } from './Shimmer/Shimmer.svelte';
 export { default as Progress } from './Progress/Progress.svelte';
 export { default as Pill } from './Pill/Pill.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/svelte-ui-components",
-  "version": "2.62.1",
+  "version": "2.63.0",
   "description": "A themeable Svelte 5 UI component library with CSS custom property driven styling",
   "keywords": [
     "svelte",