@thoughtspot/visual-embed-sdk 1.47.3 → 1.49.0

package/src/embed/liveboard.ts

@@ -23,14 +23,26 @@ import {
     ErrorDetailsTypes,
     EmbedErrorCodes,
     ContextType,
+    DefaultAppInitData,
 } from '../types';
-import { calculateVisibleElementData, getQueryParamString, isUndefined, isValidCssMargin, setParamIfDefined } from '../utils';
+import { calculateVisibleElementData, getEffectiveClippingAncestors, getQueryParamString, getScrollableAncestors, isUndefined, isValidCssMargin, setParamIfDefined } from '../utils';
 import { getAuthPromise } from './base';
 import { TsEmbed, V1Embed } from './ts-embed';
 import { addPreviewStylesIfNotPresent } from '../utils/global-styles';
 import { TriggerPayload, TriggerResponse } from './hostEventClient/contracts';
 import { logger } from '../utils/logger';
 import { SpotterChatViewConfig } from './conversation';
+import { SpotterVizConfig, buildSpotterVizAppInitData } from './spotter-viz-utils';
+
+/**
+ * APP_INIT data shape for LiveboardEmbed.
+ * @internal
+ */
+export interface LiveboardEmbedAppInitData extends DefaultAppInitData {
+    embedParams?: {
+        spotterVizConfig?: SpotterVizConfig;
+    };
+}
 
 
 /**
@@ -388,9 +400,9 @@ export interface LiveboardViewConfig extends BaseViewConfig, LiveboardOtherViewC
      */
     isPNGInScheduledEmailsEnabled?: boolean;
     /**
-     * Enables the 'what you see is what you get' PDF export for Liveboards. Each tab is rendered on a single page 
-     * following the exact UI layout, instead of splitting visualizations across multiple A4 pages. 
-     * This feature is GA from version 26.5.0.cl and is enabled by default on embed deployments.
+     * Enables the 'what you see is what you get' PDF export for Liveboards. Each tab is rendered on a single page
+     * following the exact UI layout, instead of splitting visualizations across multiple A4 pages.
+     * This feature is GA from version 26.5.0.cl. It is disabled by default in embed deployments.
      *
      * Supported embed types: `AppEmbed`, `LiveboardEmbed`
      * @type {boolean}
@@ -453,6 +465,16 @@ export interface LiveboardViewConfig extends BaseViewConfig, LiveboardOtherViewC
      * ```
      */
     lazyLoadingForFullHeight?: boolean;
+    /**
+     * This flag is used to enable container-aware full height lazy loading.
+     *
+     * Use this when the embed is rendered inside a scrollable or clipping
+     * container instead of relying on the browser window as the only viewport.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    enableScrollableContainerLazyLoading?: boolean;
     /**
      * The margin to be used for lazy loading.
      *
@@ -534,6 +556,29 @@ export interface LiveboardViewConfig extends BaseViewConfig, LiveboardOtherViewC
      * ```
      */
     spotterChatConfig?: SpotterChatViewConfig;
+    /**
+     * Configuration for the SpotterViz interface shown on the Liveboard.
+     * Customize the brand name, description, chat input placeholder,
+     * starter prompts, and visibility of starter prompts in the SpotterViz panel.
+     *
+     * Supported embed types: `AppEmbed`, `LiveboardEmbed`
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @example
+     * ```js
+     * const embed = new LiveboardEmbed('#embed-container', {
+     *    ... // other options
+     *    spotterViz: {
+     *        brandName: 'MyBrand',
+     *        brandHeadline: 'Hi, there! I\'m',
+     *        description: 'Ask questions about your data',
+     *        inputChatPlaceholder: 'Ask a question...',
+     *        hideStarterPrompts: false,
+     *        customStarterPrompts: [{ id: '1', displayText: 'Top products', fullPrompt: 'What are the top products by revenue?' }],
+     *    },
+     * })
+     * ```
+     */
+    spotterViz?: SpotterVizConfig;
     /**
      * If set to true, enables visualization data caching on the Liveboard.
      * @type {boolean}
@@ -569,6 +614,10 @@ export class LiveboardEmbed extends V1Embed {
 
     private defaultHeight = 500;
 
+    private lazyLoadScrollContainers: HTMLElement[] = [];
+
+    private lazyLoadResizeObserver: ResizeObserver | undefined;
+
 
     constructor(domSelector: DOMSelector, viewConfig: LiveboardViewConfig) {
         viewConfig.embedComponentType = 'LiveboardEmbed';
@@ -586,6 +635,11 @@ export class LiveboardEmbed extends V1Embed {
         }
     }
 
+    protected async getAppInitData(): Promise<LiveboardEmbedAppInitData> {
+        const defaultAppInitData = await super.getAppInitData();
+        return buildSpotterVizAppInitData(defaultAppInitData, this.viewConfig);
+    }
+
     /**
      * Construct a map of params to be passed on to the
      * embedded Liveboard or visualization.
@@ -640,7 +694,7 @@ export class LiveboardEmbed extends V1Embed {
             enableStopAnswerGenerationEmbed,
             spotterChatConfig,
             isThisPeriodInDateFiltersEnabled,
-            isContinuousLiveboardPDFEnabled,
+            isContinuousLiveboardPDFEnabled = false,
             enableLiveboardDataCache,
         } = this.viewConfig;
 
@@ -735,10 +789,18 @@ export class LiveboardEmbed extends V1Embed {
             const {
                 hideToolResponseCardBranding,
                 toolResponseCardBrandingLabel,
+                spotterFileUploadEnabled,
+                spotterFileUploadFileTypes,
             } = spotterChatConfig;
 
             setParamIfDefined(params, Param.HideToolResponseCardBranding, hideToolResponseCardBranding, true);
             setParamIfDefined(params, Param.ToolResponseCardBrandingLabel, toolResponseCardBrandingLabel);
+            if (spotterFileUploadEnabled !== undefined) {
+                params[Param.SpotterFileUploadEnabled] = spotterFileUploadEnabled;
+            }
+            if (spotterFileUploadFileTypes !== undefined) {
+                params[Param.SpotterFileUploadFileTypes] = JSON.stringify(spotterFileUploadFileTypes);
+            }
         }
 
         if (isLinkParametersEnabled !== undefined) {
@@ -825,7 +887,10 @@ export class LiveboardEmbed extends V1Embed {
     }
 
     private sendFullHeightLazyLoadData = () => {
-        const data = calculateVisibleElementData(this.iFrame);
+        const data = calculateVisibleElementData(
+            this.iFrame,
+            this.viewConfig.enableScrollableContainerLazyLoading,
+        );
         // this should be fired only if the lazyLoadingForFullHeight and fullHeight are true
         if(this.viewConfig.lazyLoadingForFullHeight && this.viewConfig.fullHeight){
             this.trigger(HostEvent.VisibleEmbedCoordinates, data);
@@ -840,7 +905,10 @@ export class LiveboardEmbed extends V1Embed {
      */
     private requestVisibleEmbedCoordinatesHandler = (data: MessagePayload, responder: any) => {
         logger.info('Sending RequestVisibleEmbedCoordinates', data);
-        const visibleCoordinatesData = calculateVisibleElementData(this.iFrame);
+        const visibleCoordinatesData = calculateVisibleElementData(
+            this.iFrame,
+            this.viewConfig.enableScrollableContainerLazyLoading,
+        );
         responder({ type: EmbedEvent.RequestVisibleEmbedCoordinates, data: visibleCoordinatesData });
     }
 
@@ -938,8 +1006,8 @@ export class LiveboardEmbed extends V1Embed {
                 </div>
                 `;
             const previewDiv = div.firstElementChild as HTMLElement;
-            this.el.appendChild(previewDiv);
-            this.el.style.position = 'relative';
+            this.hostElement.appendChild(previewDiv);
+            this.hostElement.style.position = 'relative';
             this.on(EmbedEvent.Data, () => {
                 previewDiv.remove();
             });
@@ -961,6 +1029,7 @@ export class LiveboardEmbed extends V1Embed {
     };
 
     protected beforePrerenderVisible(): void {
+        super.beforePrerenderVisible();
         const embedObj = this.getPreRenderObj<LiveboardEmbed>();
 
         this.executeAfterEmbedContainerLoaded(() => {
@@ -1023,17 +1092,44 @@ export class LiveboardEmbed extends V1Embed {
     }
 
     private registerLazyLoadEvents() {
+        if(!this.iFrame) {
+            return;
+        }
         if (this.viewConfig.fullHeight && this.viewConfig.lazyLoadingForFullHeight) {
+            this.unregisterLazyLoadEvents();
             // TODO: Use passive: true, install modernizr to check for passive
             window.addEventListener('resize', this.sendFullHeightLazyLoadData);
             window.addEventListener('scroll', this.sendFullHeightLazyLoadData, true);
+            if (!this.viewConfig.enableScrollableContainerLazyLoading) {
+                return;
+            }
+            this.lazyLoadScrollContainers = getScrollableAncestors(this.iFrame);
+            this.lazyLoadScrollContainers.forEach((scrollContainer) => {
+                scrollContainer.addEventListener('scroll', this.sendFullHeightLazyLoadData);
+            });
+            if (typeof ResizeObserver !== 'undefined') {
+                const resizeTargets = new Set([
+                    this.iFrame.parentElement,
+                    ...getEffectiveClippingAncestors(this.iFrame),
+                ].filter(Boolean) as HTMLElement[]);
+                this.lazyLoadResizeObserver = new ResizeObserver(this.sendFullHeightLazyLoadData);
+                resizeTargets.forEach((resizeTarget) => {
+                    this.lazyLoadResizeObserver.observe(resizeTarget);
+                });
+            }
         }
     }
 
     private unregisterLazyLoadEvents() {
         if (this.viewConfig.fullHeight && this.viewConfig.lazyLoadingForFullHeight) {
             window.removeEventListener('resize', this.sendFullHeightLazyLoadData);
-            window.removeEventListener('scroll', this.sendFullHeightLazyLoadData);
+            window.removeEventListener('scroll', this.sendFullHeightLazyLoadData, true);
+            this.lazyLoadResizeObserver?.disconnect();
+            this.lazyLoadResizeObserver = undefined;
+            this.lazyLoadScrollContainers.forEach((scrollContainer) => {
+                scrollContainer.removeEventListener('scroll', this.sendFullHeightLazyLoadData);
+            });
+            this.lazyLoadScrollContainers = [];
         }
     }
 

package/src/embed/spotter-viz-utils.spec.ts

@@ -0,0 +1,30 @@
+import { buildSpotterVizAppInitData } from './spotter-viz-utils';
+
+describe('buildSpotterVizAppInitData', () => {
+    const base = { type: 'APP_INIT' } as any;
+
+    it('returns initData unchanged when spotterViz is not provided', () => {
+        const result = buildSpotterVizAppInitData(base, {});
+        expect(result).toBe(base);
+    });
+
+    it('nests spotterViz under embedParams.spotterVizConfig', () => {
+        const spotterViz = { brandName: 'MyBrand', description: 'Desc', inputChatPlaceholder: 'Ask...' };
+        const result = buildSpotterVizAppInitData(base, { spotterViz });
+        expect(result.embedParams?.spotterVizConfig).toEqual(spotterViz);
+    });
+
+    it('passes brandHeadline through spotterVizConfig', () => {
+        const spotterViz = { brandName: 'MyBrand', brandHeadline: "Hi, there! I'm" };
+        const result = buildSpotterVizAppInitData(base, { spotterViz });
+        expect(result.embedParams?.spotterVizConfig?.brandHeadline).toBe("Hi, there! I'm");
+    });
+
+    it('preserves existing embedParams when adding spotterVizConfig', () => {
+        const existing = { ...base, embedParams: { spotterSidebarConfig: { enablePastConversationsSidebar: true } } };
+        const spotterViz = { brandName: 'MyBrand' };
+        const result = buildSpotterVizAppInitData(existing, { spotterViz });
+        expect(result.embedParams?.spotterVizConfig).toEqual(spotterViz);
+        expect(result.embedParams?.spotterSidebarConfig?.enablePastConversationsSidebar).toBe(true);
+    });
+});

package/src/embed/spotter-viz-utils.ts

@@ -0,0 +1,94 @@
+import { DefaultAppInitData } from '../types';
+
+/**
+ * Defines starter prompts displayed in the SpotterViz interface.
+ * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+ * @group Embed components
+ */
+export interface SpotterVizStarterPrompt {
+    /** Identifier for the prompt. */
+    id: string;
+    /** Short label shown to the user as a clickable suggestion. */
+    displayText: string;
+    /** Full prompt text sent to Spotter when the user clicks the suggestion. */
+    fullPrompt: string;
+}
+
+/**
+ * Configuration for the SpotterViz interface shown on the Liveboard.
+ * Supported embed types: `AppEmbed`, `LiveboardEmbed`
+ * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+ * @group Embed components
+ * @example
+ * ```js
+ * const embed = new AppEmbed('#embed-container', {
+ *    ... // other options,
+ *    spotterViz: {
+ *        brandName: 'MyBrand',
+ *        brandHeadline: 'Hi, there! I\'m',
+ *        description: 'Ask questions about your data',
+ *        inputChatPlaceholder: 'Ask a question...',
+ *        hideStarterPrompts: false,
+ *        customStarterPrompts: [
+ *            { id: '1', displayText: 'Top products', fullPrompt: 'What are the top products by revenue?' }
+ *        ],
+ *    },
+ * })
+ * ```
+ */
+export interface SpotterVizConfig {
+    /**
+     * Rename the default "SpotterViz" label shown in the SpotterViz interface with a custom brand name.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @default ''
+     */
+    brandName?: string;
+    /**
+     * Custom headline text shown before the brand name in the SpotterViz interface.
+     * Replaces the default greeting prefix (e.g. "Hi, there! I'm").
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @default ''
+     */
+    brandHeadline?: string;
+    /**
+     * Hides the starter prompts section entirely in the SpotterViz interface.
+     * When set to `true`, the starter prompts are not displayed.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @default false
+     */
+    hideStarterPrompts?: boolean;
+    /**
+     * Overrides the starter prompts with a custom list.
+     * Each entry must match the {@link SpotterVizStarterPrompt} shape.
+     * Has no effect when `hideStarterPrompts` is `true`.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     */
+    customStarterPrompts?: SpotterVizStarterPrompt[];
+    /**
+     * Custom description text shown in the SpotterViz interface.
+     * Replaces the default SpotterViz description.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     */
+    description?: string;
+    /**
+     * Custom placeholder text for the chat input in the SpotterViz interface.
+     * Replaces the default chat input placeholder text.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     */
+    inputChatPlaceholder?: string;
+}
+
+export function buildSpotterVizAppInitData<T extends DefaultAppInitData>(
+    initData: T,
+    viewConfig: { spotterViz?: SpotterVizConfig },
+): T & { embedParams?: { spotterVizConfig?: SpotterVizConfig } } {
+    const { spotterViz } = viewConfig;
+    if (!spotterViz) return initData;
+    return {
+        ...initData,
+        embedParams: {
+            ...((initData as T & { embedParams?: Record<string, unknown> }).embedParams || {}),
+            spotterVizConfig: spotterViz,
+        },
+    };
+}