@thoughtspot/visual-embed-sdk 1.51.0 → 1.51.2

package/src/embed/liveboard.ts

@@ -26,12 +26,14 @@ import {
     DefaultAppInitData,
 } from '../types';
 import { calculateVisibleElementData, getEffectiveClippingAncestors, getQueryParamString, getScrollableAncestors, isUndefined, isValidCssMargin, setParamIfDefined } from '../utils';
+import { DEFAULT_LAZY_LOADING_MARGIN } from '../config';
 import { getAuthPromise } from './base';
 import { TsEmbed, V1Embed } from './ts-embed';
 import { addPreviewStylesIfNotPresent } from '../utils/global-styles';
-import { TriggerPayload, TriggerResponse } from './hostEventClient/contracts';
+import { HostEventRequest, TriggerPayload, TriggerResponse } from './hostEventClient/contracts';
 import { logger } from '../utils/logger';
-import { SpotterChatViewConfig } from './conversation';
+import { SpotterChatViewConfig, StarterPromptsConfig } from './conversation';
+import { buildStarterPromptsAppInitData } from './spotter-utils';
 import { SpotterVizConfig, buildSpotterVizAppInitData } from './spotter-viz-utils';
 
 /**
@@ -41,6 +43,7 @@ import { SpotterVizConfig, buildSpotterVizAppInitData } from './spotter-viz-util
 export interface LiveboardEmbedAppInitData extends DefaultAppInitData {
     embedParams?: {
         spotterVizConfig?: SpotterVizConfig;
+        starterPrompts?: StarterPromptsConfig;
     };
 }
 
@@ -61,6 +64,11 @@ export interface LiveboardViewConfig extends BaseViewConfig, LiveboardOtherViewC
      * Setting `fullHeight` to `false` fetches visualizations
      * incrementally as users scroll the page to view the charts and tables.
      *
+     * From SDK 1.52.0, enabling `fullHeight` also turns on
+     * {@link lazyLoadingForFullHeight} and
+     * {@link enableScrollableContainerLazyLoading}, so visualizations load as
+     * they scroll into view. Set either flag to `false` to opt out.
+     *
      *
      * Supported embed types: `LiveboardEmbed`
      * @version SDK: 1.1.0 | ThoughtSpot: ts7.may.cl, 7.2.1
@@ -455,11 +463,17 @@ export interface LiveboardViewConfig extends BaseViewConfig, LiveboardOtherViewC
      */
     isGranularXLSXCSVSchedulesEnabled?: boolean;
     /**
-     * This flag is used to enable the full height lazy load data.
+     * Loads visualizations only as they scroll into the viewport, instead of
+     * loading the whole full-height Liveboard at once.
+     *
+     * From SDK 1.52.0 this is enabled automatically whenever `fullHeight` is
+     * `true`. On SDK 1.51.0 and earlier it defaulted to `false` and had to be
+     * set explicitly. Set it to `false` to load every visualization upfront.
+     * The flag has no effect unless `fullHeight` is enabled.
      *
      * @type {boolean}
      * @version SDK: 1.40.0 | ThoughtSpot: 10.12.0.cl
-     * @default false
+     * @default true when `fullHeight` is enabled, from SDK 1.52.0
      * @example
      * ```js
      * const embed = new LiveboardEmbed('#embed-container', {
@@ -471,26 +485,42 @@ export interface LiveboardViewConfig extends BaseViewConfig, LiveboardOtherViewC
      */
     lazyLoadingForFullHeight?: boolean;
     /**
-     * This flag is used to enable container-aware full height lazy loading.
+     * Computes the visible region of the embed against its scrollable and
+     * clipping ancestors, instead of treating the browser window as the only
+     * viewport, and tracks scroll and resize on those ancestors.
      *
-     * Use this when the embed is rendered inside a scrollable or clipping
-     * container instead of relying on the browser window as the only viewport.
+     * From SDK 1.52.0 this is enabled automatically whenever `fullHeight` is
+     * `true`. On SDK 1.51.0 and earlier it defaulted to `false` and had to be
+     * set explicitly. Set it to `false` when the page scrolls with the window
+     * and the embed has no clipping ancestor, to skip the extra ancestor
+     * tracking.
      *
      * @type {boolean}
-     * @default false
+     * @default true when `fullHeight` is enabled, from SDK 1.52.0
      */
     enableScrollableContainerLazyLoading?: boolean;
     /**
-     * The margin to be used for lazy loading.
+     * How far outside the viewport a visualization starts loading, when
+     * {@link lazyLoadingForFullHeight} is enabled.
      *
      * For example, if the margin is set to '10px',
      * the visualization will be loaded 10px before its top edge is visible in the
      * viewport.
      *
-     * The format is similar to CSS margin.
+     * The format is similar to CSS margin, so `'500px 0px'` extends the
+     * prefetch 500px above and below the viewport and not sideways. Accepted
+     * units are `px`, `em`, `rem`, `%`, `vh` and `vw`, plus bare `0` and
+     * `auto`; an invalid value is logged and ignored.
+     *
+     * From SDK 1.52.0 this defaults to `'500px 0px'` — roughly one
+     * visualization ahead of the scroll position, so a chart has usually
+     * finished loading by the time it scrolls into view. Use a smaller margin
+     * to cut warehouse queries further, or `'0px'` to load a visualization
+     * only once it is actually visible.
      *
      * @type {string}
      * @version SDK: 1.40.0 | ThoughtSpot: 10.12.0.cl
+     * @default '500px 0px' when `fullHeight` is enabled, from SDK 1.52.0
      * @example
      * ```js
      * const embed = new LiveboardEmbed('#embed-container', {
@@ -594,13 +624,12 @@ export interface LiveboardViewConfig extends BaseViewConfig, LiveboardOtherViewC
      *        inputChatPlaceholder: 'Ask a question...',
      *        hideStarterPrompts: false,
      *        customStarterPrompts: [{ id: '1', displayText: 'Top products', fullPrompt: 'What are the top products by revenue?' }],
-     *        // loaderHeadline and loaderTips require SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl
+     *        // The options below require SDK: 1.51.0
      *        loaderHeadline: 'Crunching the numbers...',
      *        loaderTips: [
      *            { label: 'Tip', text: 'try asking about revenue by region' },
      *            { label: 'Tip', text: 'use natural language' },
      *        ],
-     *        // liveboardBrandName, spotterBrandName, insightTileBrandName, insightTileViewPlanLabel and insightTileLoaderText require SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
      *        liveboardBrandName: 'Reports',
      *        spotterBrandName: 'Analyst',
      *        insightTileBrandName: 'Insight card',
@@ -675,6 +704,16 @@ export class LiveboardEmbed extends V1Embed {
                     'Using full height with vizId might lead to unexpected behavior.');
             }
 
+            if (this.viewConfig.lazyLoadingForFullHeight === undefined) {
+                this.viewConfig.lazyLoadingForFullHeight = true;
+            }
+            if (this.viewConfig.enableScrollableContainerLazyLoading === undefined) {
+                this.viewConfig.enableScrollableContainerLazyLoading = true;
+            }
+            if (this.viewConfig.lazyLoadingMargin === undefined) {
+                this.viewConfig.lazyLoadingMargin = DEFAULT_LAZY_LOADING_MARGIN;
+            }
+
             this.on(EmbedEvent.RouteChange, this.setIframeHeightForNonEmbedLiveboard);
             this.on(EmbedEvent.EmbedHeight, this.updateIFrameHeight);
             this.on(EmbedEvent.EmbedIframeCenter, this.embedIframeCenter);
@@ -684,7 +723,8 @@ export class LiveboardEmbed extends V1Embed {
 
     protected async getAppInitData(): Promise<LiveboardEmbedAppInitData> {
         const defaultAppInitData = await super.getAppInitData();
-        return buildSpotterVizAppInitData(defaultAppInitData, this.viewConfig);
+        const vizInitData = buildSpotterVizAppInitData(defaultAppInitData, this.viewConfig);
+        return buildStarterPromptsAppInitData(vizInitData, this.viewConfig);
     }
 
     /**
@@ -724,6 +764,7 @@ export class LiveboardEmbed extends V1Embed {
             isEnhancedFilterInteractivityEnabled,
             enableAskSage,
             enable2ColumnLayout,
+            isLiveboardAlwaysOn12ColLayout,
             dataPanelV2 = true,
             updatedSpotterExperience,
             enableCustomColumnGroups = false,
@@ -732,6 +773,7 @@ export class LiveboardEmbed extends V1Embed {
             dataSourceId,
             coverAndFilterOptionInPDF,
             isLiveboardStylingAndGroupingEnabled,
+            liveboardGutter,
             isPNGInScheduledEmailsEnabled = false,
             isLiveboardXLSXCSVDownloadEnabled,
             isGranularXLSXCSVSchedulesEnabled,
@@ -789,6 +831,9 @@ export class LiveboardEmbed extends V1Embed {
         if (enable2ColumnLayout !== undefined) {
             params[Param.Enable2ColumnLayout] = enable2ColumnLayout;
         }
+        if (isLiveboardAlwaysOn12ColLayout !== undefined) {
+            params[Param.IsLiveboardAlwaysOn12ColLayout] = isLiveboardAlwaysOn12ColLayout;
+        }
         if (hideTabPanel) {
             params[Param.HideTabPanel] = hideTabPanel;
         }
@@ -821,6 +866,10 @@ export class LiveboardEmbed extends V1Embed {
             params[Param.IsLiveboardStylingAndGroupingEnabled] = isLiveboardStylingAndGroupingEnabled;
         }
 
+        if (liveboardGutter !== undefined) {
+            params[Param.LiveboardGutter] = liveboardGutter;
+        }
+
         if (isPNGInScheduledEmailsEnabled !== undefined) {
             params[Param.isPNGInScheduledEmailsEnabled] = isPNGInScheduledEmailsEnabled;
         }
@@ -849,6 +898,7 @@ export class LiveboardEmbed extends V1Embed {
                 spotterFileUploadEnabled,
                 spotterFileUploadFileTypes,
                 enableStarterPrompts,
+                openSpotterOnLiveboardByDefault,
             } = spotterChatConfig;
 
             setParamIfDefined(params, Param.HideToolResponseCardBranding, hideToolResponseCardBranding, true);
@@ -859,6 +909,9 @@ export class LiveboardEmbed extends V1Embed {
             if (enableStarterPrompts !== undefined) {
                 params[Param.IsStarterPromptsEnabled] = enableStarterPrompts;
             }
+            if (openSpotterOnLiveboardByDefault !== undefined) {
+                params[Param.OpenSpotterOnLiveboardByDefault] = openSpotterOnLiveboardByDefault;
+            }
             if (spotterFileUploadFileTypes !== undefined) {
                 params[Param.SpotterFileUploadFileTypes] = JSON.stringify(spotterFileUploadFileTypes);
             }
@@ -1141,7 +1194,13 @@ export class LiveboardEmbed extends V1Embed {
      * @param {any} data The payload to send with the message
      * @returns A promise that resolves with the response from the embedded app
      */
-    public trigger<HostEventT extends HostEvent, PayloadT, ContextT extends ContextType>(
+    public trigger<
+        HostEventT extends HostEvent,
+        // Must mirror TsEmbed.trigger: without the default, no-payload calls
+        // through LiveboardEmbed lose the typed response and collapse to `any`.
+        PayloadT = HostEventRequest<HostEventT>,
+        ContextT extends ContextType = ContextType,
+    >(
         messageType: HostEventT,
         data: TriggerPayload<PayloadT, HostEventT> = ({} as any),
         context?: ContextT,
@@ -1240,7 +1299,7 @@ export class LiveboardEmbed extends V1Embed {
         this.viewConfig.personalizedViewId = personalizedViewId;
         if (this.isRendered) {
             this.trigger(HostEvent.Navigate, path.substring(1));
-        } else if (this.viewConfig.preRenderId) {
+        } else if (this.getPreRenderConfig().preRenderId) {
             this.preRender(true);
         } else {
             this.render();

package/src/embed/search.spec.ts

@@ -77,6 +77,37 @@ describe('Search embed tests', () => {
         });
     });
 
+    test('getUpdateEmbedParamsObject sends dataSources as a real ARRAY, not the URL-encoded string', async () => {
+        // The iframe URL correctly carries dataSources as a JSON-encoded
+        // string (asserted above), but the UpdateEmbedParams postMessage
+        // payload is spread into app state unparsed — a string there reaches
+        // the $sources GraphQL variable ([GUID!]) and fails GUID coercion
+        // (SCAL-334713, fired from beforePrerenderVisible on prerender-show).
+        const dataSources = ['4dd30af7-9ed7-4847-8f28-b65b44a841d8'];
+        const searchEmbed = new SearchEmbed(getRootEl(), {
+            ...defaultViewConfig,
+            dataSources,
+        });
+        const params = await (searchEmbed as any).getUpdateEmbedParamsObject();
+        expect(params.dataSources).toEqual(dataSources);
+
+        // Single-GUID `dataSource` prop (the customer's shape) normalizes to
+        // a one-element array the same way the app's URL parser would.
+        const singleSourceEmbed = new SearchEmbed(getRootEl(), {
+            ...defaultViewConfig,
+            dataSource: '4dd30af7-9ed7-4847-8f28-b65b44a841d8',
+        });
+        const singleParams = await (singleSourceEmbed as any).getUpdateEmbedParamsObject();
+        expect(singleParams.dataSources).toEqual([
+            '4dd30af7-9ed7-4847-8f28-b65b44a841d8',
+        ]);
+
+        // The normalization only reverses JSON serialization: non-JSON
+        // strings and already-structured values pass through untouched.
+        expect(singleParams.embedApp).toBe(true);
+        expect(singleParams.authType).toBe('None');
+    });
+
     test('should pass in search query', async () => {
         const dataSources = ['data-source-1'];
         const searchOptions = {

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

@@ -2,6 +2,7 @@ import {
     resolveEnablePastConversationsSidebar,
     buildSpotterSidebarAppInitData,
     buildSpotterShareConversationAppInitData,
+    buildStarterPromptsAppInitData,
 } from './spotter-utils';
 import { ErrorDetailsTypes, EmbedErrorCodes } from '../types';
 import { ERROR_MESSAGE } from '../errors';
@@ -173,3 +174,74 @@ describe('buildSpotterShareConversationAppInitData', () => {
         expect(result.embedParams?.spotterShareConversationConfig?.enableShareConversation).toBe(true);
     });
 });
+
+describe('buildStarterPromptsAppInitData', () => {
+    const base = { type: 'APP_INIT' } as any;
+
+    it('returns the payload unchanged when starterPrompts is absent', () => {
+        expect(buildStarterPromptsAppInitData(base, {})).toBe(base);
+        expect(buildStarterPromptsAppInitData(base, { spotterChatConfig: {} })).toBe(base);
+    });
+
+    it('nests starterPrompts under embedParams', () => {
+        const result = buildStarterPromptsAppInitData(base, {
+            spotterChatConfig: { starterPrompts: { quick: { label: 'Quick' } } },
+        });
+        expect(result.embedParams?.starterPrompts).toEqual({ quick: { label: 'Quick' } });
+    });
+
+    it('forwards the enable feature flag', () => {
+        const enabled = buildStarterPromptsAppInitData(base, {
+            spotterChatConfig: { starterPrompts: { enable: true, quick: { label: 'Quick' } } },
+        });
+        expect(enabled.embedParams?.starterPrompts).toEqual({ enable: true, quick: { label: 'Quick' } });
+
+        const disabled = buildStarterPromptsAppInitData(base, {
+            spotterChatConfig: { starterPrompts: { enable: false } },
+        });
+        expect(disabled.embedParams?.starterPrompts).toEqual({ enable: false });
+    });
+
+    it('preserves existing embedParams keys', () => {
+        const withExisting = {
+            ...base,
+            embedParams: { spotterSidebarConfig: { enablePastConversationsSidebar: true } },
+        } as any;
+        const result = buildStarterPromptsAppInitData(withExisting, {
+            spotterChatConfig: { starterPrompts: { quick: { label: 'Quick' } } },
+        });
+        expect(result.embedParams?.spotterSidebarConfig).toEqual({ enablePastConversationsSidebar: true });
+        expect(result.embedParams?.starterPrompts).toEqual({ quick: { label: 'Quick' } });
+    });
+
+    it('forwards every category as configured', () => {
+        const starterPrompts = {
+            enable: true,
+            quick: {
+                label: 'Quick',
+                questions: Array.from({ length: 6 }, (_, i) => ({
+                    label: `q${i}`,
+                    prompt: `prompt ${i}`,
+                })),
+            },
+            research: { label: 'Research', questions: [{ prompt: 'Why did revenue drop?' }] },
+            previewData: { label: 'Explore' },
+            liveboard: [
+                { label: 'Top products', prompt: 'What are the top products by revenue?' },
+                { prompt: 'How did revenue trend last quarter?' },
+            ],
+        };
+        const result = buildStarterPromptsAppInitData(base, {
+            spotterChatConfig: { starterPrompts },
+        });
+        expect(result.embedParams?.starterPrompts).toEqual(starterPrompts);
+    });
+
+    it('forwards the liveboard questions on their own', () => {
+        const liveboard = [{ label: 'Top products', prompt: 'What are the top products by revenue?' }];
+        const result = buildStarterPromptsAppInitData(base, {
+            spotterChatConfig: { starterPrompts: { enable: true, liveboard } },
+        });
+        expect(result.embedParams?.starterPrompts).toEqual({ enable: true, liveboard });
+    });
+});

package/src/embed/spotter-utils.ts

@@ -1,7 +1,12 @@
 import { DefaultAppInitData, ErrorDetailsTypes, EmbedErrorCodes } from '../types';
 import { validateHttpUrl } from '../utils';
 import { ERROR_MESSAGE } from '../errors';
-import type { SpotterSidebarViewConfig, SpotterShareConversationConfig } from './conversation';
+import type {
+    SpotterSidebarViewConfig,
+    SpotterShareConversationConfig,
+    SpotterChatViewConfig,
+    StarterPromptsConfig,
+} from './conversation';
 import type { VisualizationOverrides } from '../types';
 
 /**
@@ -94,3 +99,18 @@ export function buildSpotterShareConversationAppInitData<T extends DefaultAppIni
         },
     };
 }
+
+export function buildStarterPromptsAppInitData<T extends DefaultAppInitData>(
+    initData: T,
+    viewConfig: { spotterChatConfig?: SpotterChatViewConfig },
+): T & { embedParams?: { starterPrompts?: StarterPromptsConfig } } {
+    const starterPrompts = viewConfig.spotterChatConfig?.starterPrompts;
+    if (!starterPrompts) return initData;
+    return {
+        ...initData,
+        embedParams: {
+            ...((initData as T & { embedParams?: Record<string, unknown> }).embedParams || {}),
+            starterPrompts,
+        },
+    };
+}

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

@@ -32,13 +32,12 @@ export interface SpotterVizStarterPrompt {
  *        customStarterPrompts: [
  *            { id: '1', displayText: 'Top products', fullPrompt: 'What are the top products by revenue?' }
  *        ],
- *        // loaderHeadline and loaderTips require SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl
+ *        // The options below require SDK: 1.51.0
  *        loaderHeadline: 'Crunching the numbers...',
  *        loaderTips: [
  *            { label: 'Tip', text: 'try asking about revenue by region' },
  *            { label: 'Tip', text: 'use natural language' },
  *        ],
- *        // liveboardBrandName, spotterBrandName, insightTileBrandName, insightTileViewPlanLabel and insightTileLoaderText require SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
  *        liveboardBrandName: 'Reports',
  *        spotterBrandName: 'Analyst',
  *        insightTileBrandName: 'Insight card',
@@ -91,48 +90,48 @@ export interface SpotterVizConfig {
     /**
      * Custom headline text shown in the SpotterViz loading state.
      * Replaces the default loading headline.
-     * @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl
+     * @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.7.0.cl
      */
     loaderHeadline?: string;
     /**
      * Custom tips shown in the SpotterViz loading state.
      * Replaces the default loading tips with the provided list.
-     * @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl
+     * @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.7.0.cl
      */
     loaderTips?: SpotterVizLoaderTip[];
     /**
      * Custom term used to replace "Liveboard" in the agent's responses.
-     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.7.0.cl
      * @default ''
      */
     liveboardBrandName?: string;
     /**
      * Custom term used to replace "Spotter" in the agent's responses.
-     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.7.0.cl
      * @default ''
      */
     spotterBrandName?: string;
     /**
      * Custom term used to replace "Insight tile" in the UI and in the agent's responses.
-     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.7.0.cl
      * @default ''
      */
     insightTileBrandName?: string;
     /**
      * Custom term used to replace "View plan" in the insight tile menu.
-     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.7.0.cl
      */
     insightTileViewPlanLabel?: string;
     /**
      * Custom loader text shown on the insight tile.
-     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.7.0.cl
      */
     insightTileLoaderText?: string;
 }
 
 /**
  * A single tip shown in the SpotterViz loading state.
- * @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl
+ * @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.7.0.cl
  * @group Embed components
  */
 export interface SpotterVizLoaderTip {