@thoughtspot/visual-embed-sdk 1.52.1 → 1.52.2-beta.0

package/src/embed/ts-embed.ts

@@ -45,6 +45,7 @@ import {
     getHostEventsConfig,
     getValueFromWindow,
     deserializeParam,
+    getScrollableAncestors,
 } from '../utils';
 import { getCustomActions } from '../utils/custom-actions';
 import {
@@ -115,13 +116,17 @@ const TS_EMBED_ID = '_thoughtspot-embed';
  */
 const PRERENDER_CONTAINER_ORIGINAL_POSITION_KEY = 'tsEmbedOriginalPosition';
 const PRERENDER_WRAPPER_ID_PREFIX = 'tsEmbed-pre-render-wrapper-';
+const PRERENDER_PARKED_TRANSFORM = 'translateY(-100%)';
+/** The height createPreRenderWrapper() seeds before anything is measured. */
+const UNMEASURED_WRAPPER_HEIGHT = '100vh';
 
 // The container applies UpdateEmbedParams through React state, so a delivered
 // post is not the same as the params being in effect.
 const UPDATE_EMBED_PARAMS_SETTLE_MS = 200;
 
-// The container ignores runtimeFilterParams/runtimeParameterParams unless truthy, so
-// null or '' leaves the previous embed's values in place. '&' is truthy and parses to {}.
+// The container ignores runtimeFilterParams/runtimeParameterParams unless
+// truthy, so null or '' leaves the previous embed's values in place. '&' is
+// truthy and parses to {}.
 const NO_RUNTIME_PARAMS = '&';
 
 /**
@@ -229,8 +234,7 @@ export class TsEmbed {
 
     private preRenderContainerEl: HTMLElement = document.body;
 
-    private containerScrollListener: (() => void) | null = null;
-
+    /** Last height the embedded app reported, once fullHeight has measured one. */
     protected hostEventClient: HostEventClient;
 
     protected isReadyForRenderPromise;
@@ -740,8 +744,9 @@ export class TsEmbed {
             ...this.viewConfig,
             ...queryParams,
             ...appInitData,
-            // A show cycle has no URL to carry these, so the payload always states them
-            // — including "none", which is the case that leaks the previous filters.
+            // A show cycle has no URL to carry these, so the payload always
+            // states them — including "none", which is the case that leaks the
+            // previous filters.
             runtimeFilterParams:
                 getFilterQuery(this.viewConfig.runtimeFilters ?? []) || NO_RUNTIME_PARAMS,
             runtimeParameterParams:
@@ -1145,7 +1150,7 @@ export class TsEmbed {
             top: '0',
             left: '0',
             width: '100vw',
-            height: '100vh',
+            height: UNMEASURED_WRAPPER_HEIGHT,
         };
         setStyleProperties(preRenderWrapper, initialPreRenderWrapperStyle);
 
@@ -1231,10 +1236,26 @@ export class TsEmbed {
     }
 
     /**
-     * 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.
+     * Resolves the configured preRenderContainer to a live element. 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.
+     *
+     * With nothing configured the frame goes into the host element's nearest
+     * scrolling ancestor, falling back to `document.body`.
+     *
+     * The wrapper is absolutely positioned, so it follows the page for free —
+     * but only while it sits inside whatever scrolls. `document.body` is right
+     * only when the document itself is the scroller; an app that scrolls an
+     * inner element instead left the frame pinned to the viewport while the page
+     * moved under it (SCAL-338563). Being inside the scroller also lets wheel
+     * events chain out of the frame into it, which they cannot do from
+     * `document.body`.
+     *
+     * A scrolling ancestor is layout chrome rather than route content, so it
+     * outlives the embed in practice; and if it does go, the host element goes
+     * with it and this instance is remounting anyway.
+     * `reconcilePreRenderContainer` re-runs this on a detached container.
      */
     private resolvePreRenderContainerTarget(): HTMLElement {
         const containerConfig = this.getPreRenderConfig().containerSelector;
@@ -1251,7 +1272,13 @@ export class TsEmbed {
         } else if (containerConfig) {
             container = containerConfig;
         }
-        return (container as HTMLElement) ?? document.body;
+        if (container) {
+            return container as HTMLElement;
+        }
+        if (!this.hostElement) {
+            return document.body;
+        }
+        return getScrollableAncestors(this.hostElement)[0] ?? document.body;
     }
 
     private inheritPreRenderContainer(): void {
@@ -1305,8 +1332,9 @@ export class TsEmbed {
      * 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.
+     * reference and collapse the wrapper. Selectors and the auto-resolved
+     * scrolling ancestor are both re-resolved; a container passed as an element
+     * is left untouched, as there is nothing to re-query.
      */
     private reconcilePreRenderContainer(): void {
         const wrapper = this.preRenderWrapper;
@@ -1325,14 +1353,6 @@ export class TsEmbed {
         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.preRenderContainerEl = resolved;
         this.applyPreRenderContainerPositioning();
         if (wrapper.parentNode !== resolved) {
@@ -1401,10 +1421,11 @@ export class TsEmbed {
      */
     protected setIFrameHeight(height: number | string): void {
         if (this.isPreRendered) {
+            const next = getCssDimension(height);
             if (this.insertedDomEl) {
-                (this.insertedDomEl as HTMLElement).style.height = getCssDimension(height);
+                (this.insertedDomEl as HTMLElement).style.height = next;
             } else if (this.preRenderWrapper) {
-                this.preRenderWrapper.style.height = getCssDimension(height);
+                this.preRenderWrapper.style.height = next;
             }
         } else {
             // normal (non-preRender) mode: size the iframe directly
@@ -1615,8 +1636,9 @@ export class TsEmbed {
         (this.preRenderWrapper as any)[this.embedNodeKey] = this;
     }
 
-    // The flag lives on the wrapper because it describes the iframe: an instance
-    // hidden when the container announced itself would otherwise report false forever.
+    // The flag lives on the wrapper because it describes the iframe: an
+    // instance hidden when the container announced itself would otherwise
+    // report false forever.
     private markEmbedContainerLoaded() {
         this.isEmbedContainerLoaded = true;
         if (this.preRenderWrapper) {
@@ -1672,7 +1694,8 @@ export class TsEmbed {
                 const AUTH_INIT_FALLBACK_DELAY = 1000;
                 // Wait for 1 second to ensure the embed container is loaded
                 // This is a workaround to ensure the embed container is loaded
-                // this is needed until all clusters have EmbedListenerReady event
+                // this is needed until all clusters have EmbedListenerReady
+                // event
                 setTimeout(processEmbedContainerReady, AUTH_INIT_FALLBACK_DELAY);
             } else if (source === EmbedEvent.EmbedListenerReady) {
                 processEmbedContainerReady();
@@ -1967,15 +1990,27 @@ export class TsEmbed {
     }
 
     /**
-     * Detaches and clears the container scroll listener, if one is attached.
-     */
-    private removeContainerScrollListener(): void {
-        if (!this.containerScrollListener) {
+     * Re-sizes the wrapper when its placeholder changes size.
+     *
+     * Position deliberately has no equivalent. An absolutely positioned wrapper
+     * follows its containing block for free, so a correctly placed frame is the
+     * browser's job and costs nothing; repositioning it on scroll would mean a
+     * layout read and a style write per frame to compensate for placing it in
+     * the wrong box. Size is the one thing the browser will not do for us: the
+     * placeholder grows when the embedded app reports a new height, and the
+     * wrapper has to be told.
+     */
+    private observePreRenderSize(): void {
+        if (this.getPreRenderConfig().doNotTrackSize || typeof ResizeObserver === 'undefined') {
+            return;
+        }
+        const placeholder = this.getPreRenderPlaceHolderElement();
+        if (!placeholder) {
             return;
         }
-        const customContainer = this.getCustomPreRenderContainer();
-        customContainer?.removeEventListener('scroll', this.containerScrollListener);
-        this.containerScrollListener = null;
+        this.resizeObserver?.disconnect();
+        this.resizeObserver = new ResizeObserver(() => this.syncPreRenderStyle());
+        this.resizeObserver.observe(placeholder);
     }
 
     /**
@@ -1985,7 +2020,7 @@ export class TsEmbed {
     public destroy(): void {
         try {
             this.removeFullscreenChangeHandler();
-            this.removeContainerScrollListener();
+            this.resizeObserver?.disconnect();
             this.unsubscribeToEvents();
             this.preRenderWrapper?.remove();
             this.restorePreRenderContainerPosition();
@@ -2040,7 +2075,8 @@ export class TsEmbed {
     }
 
     // Subclasses that navigate the pre-render on show must await this before
-    // triggering Navigate. Resolves even on failure, so navigation is never blocked.
+    // triggering Navigate. Resolves even on failure, so navigation is never
+    // blocked.
     protected preRenderParamsApplied: Promise<void> = Promise.resolve();
 
     protected beforePrerenderVisible(): void {
@@ -2098,54 +2134,48 @@ export class TsEmbed {
 
         if (this.hostElement) {
             this.insertedDomEl = this.createPreRenderPlaceholder();
-            if ((this.viewConfig as { fullHeight: boolean }).fullHeight) {
-                // If fullHeight has already sized the wrapper, seed the placeholder
-                // with the same height so syncPreRenderStyle gets an accurate rect.
-                const existingHeight = this.preRenderWrapper.style.height;
-                if (existingHeight) {
-                    (this.insertedDomEl as HTMLDivElement).style.height = existingHeight;
-                }
+            // Carry a height fullHeight has already measured onto the fresh
+            // placeholder, so a re-show does not flash at frameParams height.
+            // UNMEASURED_WRAPPER_HEIGHT is what createPreRenderWrapper() seeds
+            // before anything has been measured; treating that as a measurement
+            // is what made a first reveal overshoot to a full viewport.
+            const wrapperHeight = this.preRenderWrapper.style.height;
+            if (
+                (this.viewConfig as { fullHeight: boolean }).fullHeight
+                && wrapperHeight
+                && wrapperHeight !== UNMEASURED_WRAPPER_HEIGHT
+            ) {
+                (this.insertedDomEl as HTMLDivElement).style.height = wrapperHeight;
             }
 
             const placeHolderId = this.getPreRenderIds().placeHolder;
             // Remove any stale placeholder from a previous cycle. It is located
-            // via a subtree-wide querySelector, so it may be nested deeper than a
-            // direct child (E.g.: with fullHeight the host app can wrap it). Use
-            // Element.remove() — which detaches from whatever the real parent is —
-            // rather than hostElement.removeChild(), which throws NotFoundError
-            // when the match is not a direct child. Mirrors the wrapper/child
-            // cleanup in createPreRenderWrapper()/createPreRenderChild().
+            // via a subtree-wide querySelector, so it may be nested deeper
+            // than a direct child (E.g.: with fullHeight the host app can wrap
+            // it). Use Element.remove() — which detaches from whatever the real
+            // parent is — rather than hostElement.removeChild(), which throws
+            // NotFoundError when the match is not a direct child. Mirrors the
+            // wrapper/child cleanup in
+            // createPreRenderWrapper()/createPreRenderChild().
             this.hostElement.querySelector(`#${placeHolderId}`)?.remove();
 
             this.hostElement.appendChild(this.insertedDomEl);
 
             this.syncPreRenderStyle();
-
-            const customContainer = this.getCustomPreRenderContainer();
-            if (customContainer && !this.containerScrollListener) {
-                this.containerScrollListener = () => this.syncPreRenderStyle();
-                customContainer.addEventListener('scroll', this.containerScrollListener);
-            }
-
-            if (!this.getPreRenderConfig().doNotTrackSize) {
-                const observeTarget = (this.insertedDomEl as HTMLElement) ?? this.hostElement;
-                this.resizeObserver = new ResizeObserver((entries) => {
-                    entries.forEach((entry) => {
-                        if (entry.target === observeTarget) {
-                            this.syncPreRenderStyle();
-                        }
-                    });
-                });
-                this.resizeObserver.observe(observeTarget);
-            }
+            this.observePreRenderSize();
         }
 
         removeStyleProperties(this.preRenderWrapper, [
             'z-index',
             'opacity',
-            'pointer-events',
             'overflow',
+            'transform',
         ]);
+        // Set rather than removed: a container that carries `pointer-events:
+        // none` — the usual styling for a parking root that must not swallow
+        // clicks — passes it down, and dropping the property here would leave
+        // the inherited `none` in force and the frame dead to input.
+        setStyleProperties(this.preRenderWrapper, { pointerEvents: 'auto' });
         this.subscribeToEvents();
 
         // Setup fullscreen change handler for prerendered components
@@ -2153,7 +2183,8 @@ export class TsEmbed {
             this.setupFullscreenChangeHandler();
         }
 
-        // Last, so everything above still sees the instance being taken over from.
+        // Last, so everything above still sees the instance being taken over
+        // from.
         this.takeOverPreRender();
 
         return this;
@@ -2224,14 +2255,16 @@ export class TsEmbed {
             top: '0',
             left: '0',
             overflow: 'hidden',
+            // Keeps the measured size — so the next show needs no resize, which
+            // is the point of pre-rendering — while lifting the box out of
+            // the container's scrollable area. Overflow only extends
+            // downwards, so a hidden frame parked above the top edge adds
+            // none, where one left at full height shows as blank scroll space.
+            transform: PRERENDER_PARKED_TRANSFORM,
         };
         setStyleProperties(this.preRenderWrapper, preRenderHideStyles);
 
-        this.removeContainerScrollListener();
-
-        if (this.resizeObserver) {
-            this.resizeObserver.disconnect();
-        }
+        this.resizeObserver?.disconnect();
 
         const placeHolderEle = this.getPreRenderPlaceHolderElement();
         if (placeHolderEle) {

package/src/errors.ts

@@ -29,7 +29,7 @@ export const ERROR_MESSAGE = {
     SSR_ENVIRONMENT_ERROR: 'SSR environment detected. This function cannot be called in SSR environment.',
     UPDATE_PARAMS_FAILED: 'Failed to update embed parameters',
     INVALID_SPOTTER_DOCUMENTATION_URL: 'Invalid spotterDocumentationUrl. Please provide a valid http or https URL.',
-    UPDATEFILTERS_INVALID_PAYLOAD: 'UpdateFilters requires a valid filter or filters array. Expected: { filter: { column, oper, values } } or { filters: [{ column, oper, values }, ...] }',
+    UPDATEFILTERS_INVALID_PAYLOAD: 'UpdateFilters requires a valid filter or filters array. Expected: { filter: { columnName, operator, values } } or { filters: [{ columnName, operator, values }, ...] }',
     DRILLDOWN_INVALID_PAYLOAD: 'DrillDown requires a valid points object. Expected: { points: { clickedPoint?, selectedPoints? }, autoDrillDown?, vizId? }',
     UPDATEPARAMETERS_INVALID_PAYLOAD: 'UpdateParameters received an invalid applicability. Expected: { level: LIVEBOARD | TAB | GROUP, targetId } where targetId is required for TAB and GROUP levels',
 };

package/src/index.ts

@@ -151,6 +151,12 @@ import {
     NavigateRequest,
     SetActiveTabRequest,
 } from './contracts/host-event-contracts';
+import {
+    convertFilterChangedToUpdateFiltersPayload,
+    FilterChangedPayload,
+    UpdateFiltersFilterParam,
+    UpdateFiltersPayload,
+} from './utils/filterConverter';
 
 export {
     init,
@@ -318,6 +324,10 @@ export {
     DataLabelFilterOperator,
     TableTheme,
     TableContentDensity,
+    convertFilterChangedToUpdateFiltersPayload,
+    FilterChangedPayload,
+    UpdateFiltersFilterParam,
+    UpdateFiltersPayload,
 };
 
 export { resetCachedAuthToken } from './authToken';

package/src/react/all-types-export.ts

@@ -128,4 +128,8 @@ export {
     StarterPromptCategory,
     StarterPreviewDataCategory,
     StarterPromptQuestion,
+    convertFilterChangedToUpdateFiltersPayload,
+    FilterChangedPayload,
+    UpdateFiltersFilterParam,
+    UpdateFiltersPayload,
 } from '../index';

package/src/types.ts

@@ -5918,6 +5918,12 @@ export enum HostEvent {
      * ```js
      * const data = await liveboardEmbed.trigger(HostEvent.GetFilters);
      *     console.log('data', data);
+     * // {
+     * //   liveboardFilters: [ ... ],
+     * //   runtimeFilters: [
+     * //     { columnName: "Region", operator: "IN", values: ["West"] }
+     * //   ]
+     * // }
      * ```
      * @example
      * ```js
@@ -5942,9 +5948,9 @@ export enum HostEvent {
      *
      * Each filter object must include the following attributes:
      *
-     * `column` - Name of the column to filter on.
+     * `columnName` - Name of the column to filter on.
      *
-     * `oper`  - Filter operator, for example, EQ, IN, CONTAINS.
+     * `operator`  - Filter operator, for example, EQ, IN, CONTAINS.
      *  For information about the supported filter operators,
      *  see link:https://developers.thoughtspot.com/docs/runtime-filters#rtOperator[Developer Documentation].
      *
@@ -5971,8 +5977,8 @@ export enum HostEvent {
      *
      * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
      *     filter: {
-     *         column: "item type",
-     *         oper: "IN",
+     *         columnName: "item type",
+     *         operator: "IN",
      *         values: ["bags","shirts"]
      *        }
      *    });
@@ -5982,8 +5988,8 @@ export enum HostEvent {
      *
      * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
      *     filter: {
-     *         column: "date",
-     *         oper: "EQ",
+     *         columnName: "date",
+     *         operator: "EQ",
      *         values: ["JULY","2023"],
      *         type: "MONTH_YEAR"
      *        }
@@ -5994,18 +6000,18 @@ export enum HostEvent {
      * ```js
      * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
      *  filters: [{
-     *      column: "Item Type",
-     *      oper: 'IN',
+     *      columnName: "Item Type",
+     *      operator: 'IN',
      *      values: ["bags","shirts"]
      *  },
      *    {
-     *      column: "Region",
-     *      oper: 'IN',
+     *      columnName: "Region",
+     *      operator: 'IN',
      *      values: ["West","Midwest"]
      *  },
      *    {
-     *      column: "Date",
-     *      oper: 'EQ',
+     *      columnName: "Date",
+     *      operator: 'EQ',
      *      values: ["2023-07-31"],
      *      type: "EXACT_DATE"
      *    }]
@@ -6019,13 +6025,13 @@ export enum HostEvent {
      * ```js
      * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
      *  filters: [{
-     *      column: "(Sample) Retail - Apparel::city",
-     *      oper: 'IN',
+     *      columnName: "(Sample) Retail - Apparel::city",
+     *      operator: 'IN',
      *      values: ["atlanta"]
      *  },
      *  {
-     *      column: "(Sample) Retail - Apparel::Region",
-     *      oper: 'IN',
+     *      columnName: "(Sample) Retail - Apparel::Region",
+     *      operator: 'IN',
      *      values: ["West","Midwest"]
      *  }]
      * });
@@ -6036,8 +6042,8 @@ export enum HostEvent {
      * import { ContextType } from '@thoughtspot/visual-embed-sdk';
      * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
      *     filter: {
-     *         column: "item type",
-     *         oper: "IN",
+     *         columnName: "item type",
+     *         operator: "IN",
      *         values: ["shoes", "boots"]
      *     }
      * }, ContextType.Liveboard);
@@ -6047,8 +6053,8 @@ export enum HostEvent {
      * // Scope the filter to a specific Liveboard tab
      * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
      *     filter: {
-     *         column: "item type",
-     *         oper: "IN",
+     *         columnName: "item type",
+     *         operator: "IN",
      *         values: ["bags", "shirts"],
      *         applicability: {
      *             level: "TAB",
@@ -6057,6 +6063,12 @@ export enum HostEvent {
      *     }
      * });
      * ```
+     * Use `columnName` and `operator` - the same spelling as
+     * {@link RuntimeFilter}. The older `column` and `oper` spellings are
+     * deprecated; they are still accepted, but pass only one spelling of each
+     * field, never both. To reapply the filter state captured from
+     * {@link EmbedEvent.FilterChanged}, use `convertFilterChangedToUpdateFiltersPayload`
+     * to convert its payload into the shape expected here.
      * @version SDK: 1.23.0 | ThoughtSpot: 9.4.0.cl
      */
     UpdateFilters = 'updateFilters',
@@ -7053,7 +7065,6 @@ export enum Param {
     IsStarterPromptsEnabled = 'enableStarterPrompts',
     UpdatedSpotterExperience = 'updatedSpotterExperience',
     SpotterDataSources = 'spotterDataSources',
-    AnalystId = 'analystId',
     OpenSpotterOnLiveboardByDefault = 'openSpotterOnLiveboardByDefault',
     ShowAnswerEditPanel = 'showAnswerEditPanel',
 }
@@ -9311,6 +9322,18 @@ export enum Action {
      * ```
      */
     DeleteCollection = 'deleteCollection',
+    /**
+     * Controls the visibility of the "Customize homepage" button on the
+     * embedded home page.
+     * @version SDK: 1.55.0 | ThoughtSpot Cloud: 26.12.0.cl
+     * @example
+     * ```js
+     * {
+     *     hiddenActions: [Action.CustomizeHomepage],
+     * }
+     * ```
+     */
+    CustomizeHomepage = 'customizeHomepage',
 }
 export interface AnswerServiceType {
     getAnswer?: (offset: number, batchSize: number) => any;

package/src/utils/authService/tokenizedAuthService.spec.ts

@@ -79,7 +79,8 @@ describe('fetchPreauthInfoService', () => {
     });
     it('fetchPreauthInfoService if fetch fails', async () => {
         const mockFetch = jest.spyOn(tokenizedFetchModule, 'tokenizedFetch');
-        // Prevent logger.error from reaching console.error (which throws in test env)
+        // Prevent logger.error from reaching console.error (which throws in
+        // test env)
         jest.spyOn(logger, 'error').mockImplementation(() => {});
 
         mockFetch.mockResolvedValueOnce({

package/src/utils/custom-actions.spec.ts

@@ -439,7 +439,8 @@ describe('getCustomActions function', () => {
                 metadataIds: { liveboardIds: ['lb-1'] },
             } as any;
             const result = getCustomActions([action]);
-            // Expect an error containing 'none' for unsupported metadataIds on SPOTTER
+            // Expect an error containing 'none' for unsupported metadataIds on
+            // SPOTTER
             expect(result.errors.some((e) => e.includes('none'))).toBe(true);
         });
 
@@ -452,7 +453,8 @@ describe('getCustomActions function', () => {
                 dataModelIds: { modelIds: ['model-1'] },
             } as any;
             const result = getCustomActions([action]);
-            // Expect an error containing 'none' for unsupported dataModelIds on LIVEBOARD
+            // Expect an error containing 'none' for unsupported dataModelIds
+            // on LIVEBOARD
             expect(result.errors.some((e) => e.includes('none'))).toBe(true);
         });
     });