@thoughtspot/visual-embed-sdk 1.49.0 → 1.49.2

package/src/embed/ts-embed.ts

@@ -28,6 +28,7 @@ import {
     getCustomisations,
     getRuntimeFilters,
     getDOMNode,
+    querySelectorAcrossShadowRoot,
     getFilterQuery,
     getQueryParamString,
     getRuntimeParameters,
@@ -68,7 +69,7 @@ import {
 } from '../types';
 import { uploadMixpanelEvent, MIXPANEL_EVENT } from '../mixpanel-service';
 import { processEventData, processAuthFailure } from '../utils/processData';
-import { version } from '../../package.json';
+import { version } from '../utils/sdk-version';
 import {
     getAuthPromise,
     renderInQueue,
@@ -95,6 +96,14 @@ import {
  */
 export const THOUGHTSPOT_PARAM_PREFIX = 'ts-';
 const TS_EMBED_ID = '_thoughtspot-embed';
+/**
+ * dataset key used to stash a custom preRenderContainer's original inline
+ * `position` while we override it to `relative`. Stored on the container (not
+ * per-instance) so the override can be reverted on destroy even when multiple
+ * pre-rendered embeds share the same container.
+ */
+const PRERENDER_CONTAINER_ORIGINAL_POSITION_KEY = 'tsEmbedOriginalPosition';
+const PRERENDER_WRAPPER_ID_PREFIX = 'tsEmbed-pre-render-wrapper-';
 
 /**
  * The event id map from v2 event names to v1 event id
@@ -197,6 +206,10 @@ export class TsEmbed {
 
     private resizeObserver: ResizeObserver;
 
+    private preRenderContainerEl: HTMLElement | null = null;
+
+    private containerScrollListener: (() => void) | null = null;
+
     protected hostEventClient: HostEventClient;
 
     protected isReadyForRenderPromise;
@@ -1152,6 +1165,91 @@ export class TsEmbed {
         return placeholder;
     }
 
+    /**
+     * Resolves the configured preRenderContainer to a live element, falling
+     * back to `document.body`. A string selector is re-queried on every call so
+     * a remounted container (E.g.: React replacing the node) resolves to the
+     * fresh element; an element passed directly cannot be re-resolved.
+     */
+    private resolvePreRenderContainerTarget(): HTMLElement {
+        const containerConfig = this.viewConfig.preRenderContainer;
+        let container: Element | null = null;
+        if (typeof containerConfig === 'string') {
+            try {
+                // Resolve against the host's shadow root too, so a selector can
+                // target a container inside the same shadow DOM as the embed —
+                // document.querySelector alone cannot pierce shadow boundaries.
+                container = querySelectorAcrossShadowRoot(containerConfig, this.hostElement);
+            } catch (e) {
+                logger.error(`Invalid CSS selector for preRenderContainer: ${containerConfig}`, e);
+            }
+        } else if (containerConfig) {
+            container = containerConfig;
+        }
+        return (container as HTMLElement) ?? document.body;
+    }
+
+    /**
+     * Makes the container a positioning context for the absolutely positioned
+     * wrapper, stashing the original inline `position` on the element (once) so
+     * destroy() can restore it exactly, leaving no trace. Recording it on the
+     * element rather than per-instance lets the override be reverted even when
+     * embeds share the same container.
+     */
+    private applyPreRenderContainerPositioning(container: HTMLElement): void {
+        if (container === document.body) {
+            return;
+        }
+        const pos = window.getComputedStyle(container).position;
+        if (pos === 'static') {
+            if (container.dataset[PRERENDER_CONTAINER_ORIGINAL_POSITION_KEY] === undefined) {
+                container.dataset[
+                    PRERENDER_CONTAINER_ORIGINAL_POSITION_KEY
+                ] = container.style.position;
+            }
+            container.style.position = 'relative';
+        }
+    }
+
+    /**
+     * Re-attaches the wrapper to a live container when the previously resolved
+     * one has been detached or no longer holds the wrapper — e.g. the host app
+     * remounted a custom preRenderContainer, which would otherwise leave a stale
+     * reference and collapse the wrapper. Only string selectors can be
+     * re-resolved; a container passed as an element is left untouched.
+     */
+    private reconcilePreRenderContainer(): void {
+        const wrapper = this.preRenderWrapper;
+        const stored = this.preRenderContainerEl;
+        // Nothing to reconcile until this instance resolved its container.
+        if (!wrapper || !stored) {
+            return;
+        }
+        const storedIsLive = stored === document.body || document.contains(stored);
+        if (storedIsLive && stored.contains(wrapper)) {
+            return;
+        }
+        const resolved = this.resolvePreRenderContainerTarget();
+        // Re-resolution yielded the same (still stale) element — nothing we can
+        // do, e.g. a detached container passed as an HTMLElement.
+        if (resolved === stored && stored.contains(wrapper)) {
+            return;
+        }
+        if (this.containerScrollListener && stored !== resolved) {
+            if (stored !== document.body) {
+                stored.removeEventListener('scroll', this.containerScrollListener);
+            }
+            if (resolved !== document.body) {
+                resolved.addEventListener('scroll', this.containerScrollListener);
+            }
+        }
+        this.applyPreRenderContainerPositioning(resolved);
+        if (wrapper.parentNode !== resolved) {
+            resolved.appendChild(wrapper);
+        }
+        this.preRenderContainerEl = resolved;
+    }
+
     protected insertIntoDOMForPreRender(child: string | Node): void {
         const preRenderChild = this.createPreRenderChild(child);
         const preRenderWrapper = this.createPreRenderWrapper();
@@ -1175,7 +1273,10 @@ export class TsEmbed {
             this.hidePreRender();
         }
 
-        document.body.appendChild(preRenderWrapper);
+        const targetContainer = this.resolvePreRenderContainerTarget();
+        this.preRenderContainerEl = targetContainer;
+        this.applyPreRenderContainerPositioning(targetContainer);
+        targetContainer.appendChild(preRenderWrapper);
     }
 
     private showPreRenderByDefault = false;
@@ -1735,6 +1836,55 @@ export class TsEmbed {
         return tsParams;
     }
 
+    /**
+     * Reverts the custom preRenderContainer's `position` to the value it had
+     * before we overrode it to `relative` (see insertIntoDOMForPreRender).
+     *
+     * We restore the original inline value rather than forcing `static`, and we
+     * skip the restore if another preRender wrapper is still mounted inside the
+     * same container — a shared container still needs the positioning context.
+     */
+    private restorePreRenderContainerPosition(): void {
+        const container = this.preRenderContainerEl as HTMLElement | null;
+        if (!container || container === document.body) {
+            return;
+        }
+        // Drop our reference up front so a destroyed embed never pins a
+        // detached container in memory; restoration uses the local handle.
+        this.preRenderContainerEl = null;
+        const originalPosition = container.dataset[PRERENDER_CONTAINER_ORIGINAL_POSITION_KEY];
+        if (originalPosition === undefined) {
+            // We never overrode this container's position; nothing to restore.
+            return;
+        }
+        // This instance's own wrapper has already been removed by now, so any
+        // match here belongs to another embed still sharing the container — it
+        // continues to rely on the positioning context, so leave it in place.
+        const hasOtherWrapper = container.querySelector(
+            `[id^="${PRERENDER_WRAPPER_ID_PREFIX}"]`,
+        );
+        if (hasOtherWrapper) {
+            return;
+        }
+        container.style.position = originalPosition;
+        delete container.dataset[PRERENDER_CONTAINER_ORIGINAL_POSITION_KEY];
+    }
+
+    /**
+     * Detaches and clears the container scroll listener, if one is attached.
+     */
+    private removeContainerScrollListener(): void {
+        if (!this.containerScrollListener) {
+            return;
+        }
+        const customContainer = 
+            this.preRenderContainerEl && this.preRenderContainerEl !== document.body
+                ? this.preRenderContainerEl
+                : null;
+        customContainer?.removeEventListener('scroll', this.containerScrollListener);
+        this.containerScrollListener = null;
+    }
+
     /**
      * Destroys the ThoughtSpot embed, and remove any nodes from the DOM.
      * @version SDK: 1.19.1 | ThoughtSpot: *
@@ -1742,8 +1892,10 @@ export class TsEmbed {
     public destroy(): void {
         try {
             this.removeFullscreenChangeHandler();
+            this.removeContainerScrollListener();
             this.unsubscribeToEvents();
             this.preRenderWrapper?.remove();
+            this.restorePreRenderContainerPosition();
             if (!this.isRendered) {
                 return;
             }
@@ -1856,15 +2008,21 @@ export class TsEmbed {
 
             this.syncPreRenderStyle();
 
+            const customContainer =
+                this.preRenderContainerEl && this.preRenderContainerEl !== document.body
+                    ? this.preRenderContainerEl
+                    : null;
+            if (customContainer && !this.containerScrollListener) {
+                this.containerScrollListener = () => this.syncPreRenderStyle();
+                customContainer.addEventListener('scroll', this.containerScrollListener);
+            }
+
             if (!this.viewConfig.doNotTrackPreRenderSize) {
                 const observeTarget = (this.insertedDomEl as HTMLElement) ?? this.hostElement;
                 this.resizeObserver = new ResizeObserver((entries) => {
                     entries.forEach((entry) => {
-                        if (entry.contentRect && entry.target === observeTarget) {
-                            setStyleProperties(this.preRenderWrapper, {
-                                width: `${entry.contentRect.width}px`,
-                                height: `${entry.contentRect.height}px`,
-                            });
+                        if (entry.target === observeTarget) {
+                            this.syncPreRenderStyle();
                         }
                     });
                 });
@@ -1905,11 +2063,22 @@ export class TsEmbed {
             logger.error(ERROR_MESSAGE.SYNC_STYLE_CALLED_BEFORE_RENDER);
             return;
         }
+        // Self-heal if the resolved container was remounted/detached, so we
+        // never measure a stale node (which would collapse the wrapper).
+        this.reconcilePreRenderContainer();
         const elBoundingClient = this.getPreRenderPlaceHolderElement().getBoundingClientRect();
 
+        const containerEl =
+            this.preRenderContainerEl && this.preRenderContainerEl !== document.body
+                ? this.preRenderContainerEl
+                : null;
+        const containerRect = containerEl?.getBoundingClientRect() ?? { x: 0, y: 0 };
+        const scrollX = containerEl ? containerEl.scrollLeft : window.scrollX;
+        const scrollY = containerEl ? containerEl.scrollTop : window.scrollY;
+
         setStyleProperties(this.preRenderWrapper, {
-            top: `${elBoundingClient.y + window.scrollY}px`,
-            left: `${elBoundingClient.x + window.scrollX}px`,
+            top: `${elBoundingClient.y - containerRect.y + scrollY}px`,
+            left: `${elBoundingClient.x - containerRect.x + scrollX}px`,
             width: `${elBoundingClient.width}px`,
             height: `${elBoundingClient.height}px`,
             position: 'absolute',
@@ -1938,6 +2107,8 @@ export class TsEmbed {
         };
         setStyleProperties(this.preRenderWrapper, preRenderHideStyles);
 
+        this.removeContainerScrollListener();
+
         if (this.resizeObserver) {
             this.resizeObserver.disconnect();
         }
@@ -1959,7 +2130,7 @@ export class TsEmbed {
      */
     public getPreRenderIds() {
         return {
-            wrapper: `tsEmbed-pre-render-wrapper-${this.viewConfig.preRenderId}`,
+            wrapper: `${PRERENDER_WRAPPER_ID_PREFIX}${this.viewConfig.preRenderId}`,
             child: `tsEmbed-pre-render-child-${this.viewConfig.preRenderId}`,
             placeHolder: `tsEmbed-pre-render-placeholder-${this.viewConfig.preRenderId}`,
         };

package/src/mixpanel-service.ts

@@ -2,7 +2,7 @@ import * as mixpanel from 'mixpanel-browser';
 import { logger } from './utils/logger';
 import { SessionInfo } from './utils/sessionInfoService';
 import { ERROR_MESSAGE } from './errors';
-import { version } from '../package.json';
+import { version } from './utils/sdk-version';
 
 export const EndPoints = {
     CONFIG: '/callosum/v1/system/config',

package/src/types.ts

@@ -1108,6 +1108,45 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      * ```
      */
     doNotTrackPreRenderSize?: boolean;
+    /**
+     * The DOM element or CSS selector string specifying the container into which
+     * the pre-rendered wrapper is inserted. Defaults to `document.body` when not
+     * specified.
+     *
+     * **When to use a target container:** set this when the pre-render should
+     * live somewhere other than `document.body` — for example when `<body>` has
+     * `overflow: hidden` and scrolling is handled by an inner element, or when
+     * you need the wrapper to sit inside a specific stacking/positioning context.
+     * The wrapper is positioned to track the embedding element within this
+     * container, so choose the scrollable/positioned ancestor you want it
+     * aligned to.
+     *
+     * **Pass a stable container:** the wrapper is mounted into the resolved
+     * container once, during `preRender()`. The container must stay mounted for
+     * the lifetime of the pre-render — if the host app unmounts and remounts it
+     * (for example React replacing the node), the wrapper is orphaned on the
+     * detached node. Mount the container above the part of the tree that
+     * re-renders so its identity is stable. Prefer a CSS selector string over a
+     * raw element: a selector can be re-resolved to the fresh node on the next
+     * reposition, whereas an element reference cannot be recovered once detached.
+     *
+     * When the embed host lives inside a Shadow DOM, a selector string is
+     * resolved against that shadow root as well (since `document.querySelector`
+     * cannot pierce shadow boundaries); pass the element directly if the
+     * container lives in a different root.
+     *
+     * @type {string | HTMLElement}
+     * @version SDK: 1.49.2 | ThoughtSpot: *
+     * @example
+     * ```js
+     * const embed = new LiveboardEmbed('#tsEmbed', {
+     *   preRenderId: 'my-liveboard',
+     *   // Prefer a selector for a stable, scrollable container.
+     *   preRenderContainer: '#my-scroll-container',
+     * });
+     * ```
+     */
+    preRenderContainer?: string | HTMLElement;
     /**
      * Enable the V2 shell. This can provide performance benefits
      * due to a lighter-weight shell.
@@ -4150,11 +4189,30 @@ export enum HostEvent {
     /**
      * Navigate to a specific page in the embedded ThoughtSpot application.
      * This is the same as calling `appEmbed.navigateToPage(path, true)`.
-     * @param - `path` - the path to navigate to go forward or back. The path value can
-     * be a number; for example, `1`, `-1`.
+     *
+     * Accepts either a plain value or an object with `path`
+     * and an optional `replace` flag.
+     *
+     * @param data - A string path, a numeric history delta, or an object
+     *   `{ path: string | number, replace?: boolean }`.
+     *   - `path` — the route to navigate to, or a history delta such as `1`
+     *     or `-1` (calls `window.history.go()`).
+     *   - `replace` — when `true`, replaces the current history entry instead
+     *     of pushing a new one (uses `window.location.replace`).
+     *
      * @example
      * ```js
-     * appEmbed.navigateToPage(-1)
+     * // Preferred: use navigateToPage directly
+     * appEmbed.navigateToPage(-1);
+     * 
+     * // Numeric delta — go back one step
+     * appEmbed.trigger(HostEvent.Navigate, -1);
+     *
+     * // String path — push a new history entry
+     * appEmbed.trigger(HostEvent.Navigate, 'home');
+     *
+     * // Object format — replace current history entry
+     * appEmbed.trigger(HostEvent.Navigate, { path: 'home', replace: true }); // SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl
      * ```
      * @version SDK: 1.12.0 | ThoughtSpot: 8.4.0.cl, 8.4.1.sw
      */
@@ -6149,6 +6207,7 @@ export enum Param {
     EnableLiveboardDataCache = 'enableLiveboardDataCache',
     SpotterFileUploadEnabled = 'spotterFileUploadEnabled',
     SpotterFileUploadFileTypes = 'spotterFileUploadFileTypes',
+    IsStarterPromptsEnabled = 'enableStarterPrompts',
 }
 
 /**
@@ -6801,6 +6860,16 @@ export enum Action {
      * @version SDK: 1.9.0 | ThoughtSpot: 8.1.0.cl, 8.4.1.sw
      */
     AddToFavorites = 'addToFavorites',
+    /**
+     * Remove from Favorites option in home page v3 sidebar.
+     * Allows removing an object from the user's favorites list from home-page v3 sidebar.
+     * @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl
+     * @example
+     * ```js
+     * disabledActions: [Action.RemoveFromFavorites]
+     * ```
+     */
+    RemoveFromFavorites = 'removeFromFavorites',
     /**
      * The edit icon on Liveboards (Classic experience).
      * @example
@@ -7879,6 +7948,20 @@ export enum Action {
      * ```
      */
     SpotterViz = 'spotterViz',
+    /**
+     * The reference-mode toggle button inside the SpotterViz chat input.
+     * When users enable reference mode, clicking tiles, filters, or
+     * parameters adds them as chat context. Hide this action to remove
+     * the reference-mode capability entirely.
+     * Visible by default.
+     * @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl
+     * @example
+     * ```js
+     * hiddenActions: [Action.SpotterVizReferenceMode]
+     * disabledActions: [Action.SpotterVizReferenceMode]
+     * ```
+     */
+    SpotterVizReferenceMode = 'spotterVizReferenceMode',
     /**
      * Clears browser cache and fetches new data for liveboard ChartViz Containers.
      * Requires `enableLiveboardDataCache` to be enabled.

package/src/utils/logger.ts

@@ -1,5 +1,5 @@
 import { LogLevel } from '../types';
-import { version } from '../../package.json';
+import { version } from './sdk-version';
 const logFunctions: {
     [key: string]: (...args: any[]) => void;
 } = {

package/src/utils/processTrigger.spec.ts

@@ -94,6 +94,29 @@ describe('Unit test for processTrigger', () => {
         await expect(triggerPromise).resolves.toEqual(null);
     });
 
+    test('should clear the timeout when response arrives before TRIGGER_TIMEOUT', async () => {
+        const messageType = HostEvent.Search;
+        const thoughtSpotHost = 'http://localhost:3000';
+        const data = {};
+        mockMessageChannel();
+        const clearTimeoutSpy = jest.spyOn(global, 'clearTimeout');
+
+        const triggerPromise = _processTriggerInstance.processTrigger(
+            iFrame,
+            messageType,
+            thoughtSpotHost,
+            data,
+        );
+
+        const res = { data: { test: '123' } };
+        messageChannelMock.port1.onmessage(res);
+
+        expect(clearTimeoutSpy).toHaveBeenCalled();
+        await expect(triggerPromise).resolves.toEqual(res.data);
+
+        clearTimeoutSpy.mockRestore();
+    });
+
     test('should close channel.port1 when timeout exceeds TRIGGER_TIMEOUT', async () => {
         const messageType = HostEvent.Search;
         const thoughtSpotHost = 'http://localhost:3000';

package/src/utils/processTrigger.ts

@@ -70,7 +70,15 @@ export function processTrigger(
         }
         
         const channel = new MessageChannel();
+
+        // Close the messageChannel and resolve the promise if timeout.
+        const timeoutId = setTimeout(() => {
+            channel.port1.close();
+            res(new Error(ERROR_MESSAGE.TRIGGER_TIMED_OUT));
+        }, TRIGGER_TIMEOUT);
+
         channel.port1.onmessage = ({ data: responseData }) => {
+            clearTimeout(timeoutId);
             channel.port1.close();
             const error = responseData?.error || responseData?.data?.error;
             if (error) {
@@ -80,12 +88,6 @@ export function processTrigger(
             }
         };
 
-        // Close the messageChannel and resolve the promise if timeout.
-        setTimeout(() => {
-            channel.port1.close();
-            res(new Error(ERROR_MESSAGE.TRIGGER_TIMED_OUT));
-        }, TRIGGER_TIMEOUT);
-
         return postIframeMessage(iFrame, { type: messageType, data, context }, thoughtSpotHost, channel);
     });
 }

package/src/utils/sdk-version.ts

@@ -0,0 +1,3 @@
+import pkg from '../../package.json';
+
+export const { version } = pkg;

package/src/utils.spec.ts

@@ -26,6 +26,7 @@ import {
     resetValueFromWindow,
     validateHttpUrl,
     setParamIfDefined,
+    querySelectorAcrossShadowRoot,
 } from './utils';
 import { RuntimeFilterOp } from './types';
 import { logger } from './utils/logger';
@@ -855,6 +856,68 @@ describe('getClippingAncestors', () => {
     });
 });
 
+describe('querySelectorAcrossShadowRoot', () => {
+    it('should resolve a selector from the light DOM document', () => {
+        const el = document.createElement('div');
+        el.id = 'light-dom-target';
+        document.body.appendChild(el);
+
+        expect(querySelectorAcrossShadowRoot('#light-dom-target')).toBe(el);
+
+        el.remove();
+    });
+
+    it('should resolve a selector inside the reference node shadow root when the document misses', () => {
+        const host = document.createElement('div');
+        document.body.appendChild(host);
+        const shadow = host.attachShadow({ mode: 'open' });
+        const container = document.createElement('div');
+        container.id = 'shadow-target';
+        const reference = document.createElement('div');
+        shadow.appendChild(container);
+        shadow.appendChild(reference);
+
+        // document.querySelector cannot see into the shadow root.
+        expect(document.querySelector('#shadow-target')).toBeNull();
+        expect(querySelectorAcrossShadowRoot('#shadow-target', reference)).toBe(container);
+
+        host.remove();
+    });
+
+    it('should prefer the document match over the shadow root', () => {
+        const lightEl = document.createElement('div');
+        lightEl.id = 'shared-id';
+        document.body.appendChild(lightEl);
+
+        const host = document.createElement('div');
+        document.body.appendChild(host);
+        const shadow = host.attachShadow({ mode: 'open' });
+        const shadowEl = document.createElement('div');
+        shadowEl.id = 'shared-id';
+        const reference = document.createElement('div');
+        shadow.appendChild(shadowEl);
+        shadow.appendChild(reference);
+
+        expect(querySelectorAcrossShadowRoot('#shared-id', reference)).toBe(lightEl);
+
+        lightEl.remove();
+        host.remove();
+    });
+
+    it('should return null when nothing matches and the reference node is in the light DOM', () => {
+        const reference = document.createElement('div');
+        document.body.appendChild(reference);
+
+        expect(querySelectorAcrossShadowRoot('#does-not-exist', reference)).toBeNull();
+
+        reference.remove();
+    });
+
+    it('should return null when no reference node is provided and the document misses', () => {
+        expect(querySelectorAcrossShadowRoot('#does-not-exist')).toBeNull();
+    });
+});
+
 describe('getEffectiveClippingAncestors', () => {
     it('should return an empty list when element is missing', () => {
         expect(getEffectiveClippingAncestors(null as unknown as HTMLElement)).toEqual([]);

package/src/utils.ts

@@ -291,6 +291,30 @@ export function getDOMNode(domSelector: DOMSelector): HTMLElement {
     return typeof domSelector === 'string' ? document.querySelector(domSelector) : domSelector;
 }
 
+/**
+ * Resolves a CSS selector to an element. `document.querySelector` cannot pierce
+ * shadow boundaries, so when the document lookup misses and a reference node is
+ * provided, this also searches the shadow root the reference node lives in —
+ * letting a selector target an element inside the same shadow root as the embed
+ * instead of silently falling back to the light DOM.
+ * @param selector CSS selector string.
+ * @param referenceNode Node whose shadow root is searched when the document lookup misses.
+ */
+export function querySelectorAcrossShadowRoot(
+    selector: string,
+    referenceNode?: Node | null,
+): Element | null {
+    const fromDocument = document.querySelector(selector);
+    if (fromDocument) {
+        return fromDocument;
+    }
+    const rootNode = referenceNode?.getRootNode?.();
+    if (typeof ShadowRoot !== 'undefined' && rootNode instanceof ShadowRoot) {
+        return rootNode.querySelector(selector);
+    }
+    return null;
+}
+
 export const deepMerge = (target: any, source: any) => merge(target, source);
 
 export const getOperationNameFromQuery = (query: string) => {