@thoughtspot/visual-embed-sdk 1.52.0 → 1.52.1

package/src/full-height.ts

@@ -0,0 +1,361 @@
+/**
+ * Copyright (c) 2025
+ *
+ * Full-height support for the Liveboard and app embeds.
+ * @summary Full height
+ */
+
+import {
+    BaseViewConfig,
+    EmbedEvent,
+    FullHeightViewConfig,
+    HostEvent,
+    MessageCallback,
+    MessagePayload,
+    Param,
+    QueryParams,
+} from './types';
+import {
+    calculateElementCenter,
+    calculateVisibleElementData,
+    getEffectiveClippingAncestors,
+    getScrollableAncestors,
+    isValidCssMargin,
+} from './utils';
+import { logger } from './utils/logger';
+import { DEFAULT_LAZY_LOADING_MARGIN } from './config';
+
+/**
+ * The height the embed falls back to when the host app has not configured
+ * `minimumHeight` or `defaultHeight`.
+ */
+const DEFAULT_MINIMUM_HEIGHT = 500;
+
+/**
+ * Routes that are part of the Liveboard experience itself. Navigating between
+ * these does not reset the frame height, because the ThoughtSpot app keeps
+ * reporting a height of its own for them.
+ */
+const LIVEBOARD_RELATED_ROUTES = [
+    '/pinboard/',
+    '/insights/pinboard/',
+    '/schedules/',
+    '/embed/viz/',
+    '/embed/insights/viz/',
+    '/liveboard/',
+    '/insights/liveboard/',
+    '/tsl-editor/PINBOARD_ANSWER_BOOK/',
+    '/import-tsl/PINBOARD_ANSWER_BOOK/',
+];
+
+/**
+ * The slice of an embed's view config the full-height controller reads.
+ */
+export type FullHeightControllerViewConfig = FullHeightViewConfig &
+    Pick<BaseViewConfig, 'frameParams'>;
+
+/**
+ * The subset of the embed the full-height controller drives. Keeping this
+ * narrow lets the controller stay independent of the embed class hierarchy.
+ */
+export interface FullHeightEmbedHost {
+    /**
+     * Returns the embedded iframe. The iframe only exists once the embed has
+     * rendered, so this is a callback rather than a value.
+     */
+    getIframe: () => HTMLIFrameElement;
+    /**
+     * Sets the height of the embed container.
+     */
+    setFrameHeight: (height: number | string) => void;
+    /**
+     * Registers an SDK-owned handler for an embed event.
+     */
+    on: (eventType: EmbedEvent, callback: MessageCallback) => void;
+    /**
+     * Sends a host event to the embedded ThoughtSpot app.
+     */
+    trigger: (hostEvent: HostEvent, data: unknown) => void;
+}
+
+/**
+ * Owns every piece of full-height behavior for an embed: the height
+ * negotiation with the ThoughtSpot app, the query parameters that switch the
+ * feature on, and the viewport listeners that drive lazy loading.
+ *
+ * The controller is inert unless `fullHeight` is enabled, so embeds can create
+ * one unconditionally.
+ */
+export class FullHeightController {
+    private scrollContainers: HTMLElement[] = [];
+
+    private resizeObserver: ResizeObserver | undefined;
+
+    private config: FullHeightControllerViewConfig;
+
+    constructor(
+        viewConfig: FullHeightControllerViewConfig,
+        private readonly host: FullHeightEmbedHost,
+    ) {
+        this.config = FullHeightController.withLazyLoadingDefaults(viewConfig);
+        this.registerEventHandlers();
+    }
+
+    /**
+     * The view config the controller runs on: the host app's own config with
+     * the lazy-loading defaults filled in. Read-only, so the only way to change
+     * it is through the setter, which re-resolves the defaults.
+     */
+    public get viewConfig(): Readonly<FullHeightControllerViewConfig> {
+        return this.config;
+    }
+
+    /**
+     * Replaces the view config the controller runs on and re-resolves the
+     * lazy-loading defaults against it. The config the caller passes is never
+     * written to; the controller keeps a copy of its own.
+     */
+    public set viewConfig(viewConfig: Readonly<FullHeightControllerViewConfig>) {
+        this.config = FullHeightController.withLazyLoadingDefaults(viewConfig);
+    }
+
+    /**
+     * The view config with the lazy-loading settings the embed falls back to
+     * when the host app has not chosen its own.
+     *
+     * Pure by design: it returns a new config rather than writing to the one it
+     * is given, so the host app's object is left untouched.
+     * @param viewConfig The embed's view config
+     * @returns A copy with the defaults filled in, host app choices preserved
+     */
+    private static withLazyLoadingDefaults(
+        viewConfig: Readonly<FullHeightControllerViewConfig>,
+    ): FullHeightControllerViewConfig {
+        return {
+            ...viewConfig,
+            lazyLoadingForFullHeight:
+                viewConfig.lazyLoadingForFullHeight === undefined
+                    ? true
+                    : viewConfig.lazyLoadingForFullHeight,
+            enableScrollableContainerLazyLoading:
+                viewConfig.enableScrollableContainerLazyLoading === undefined
+                    ? true
+                    : viewConfig.enableScrollableContainerLazyLoading,
+            lazyLoadingMargin:
+                viewConfig.lazyLoadingMargin === undefined
+                    ? DEFAULT_LAZY_LOADING_MARGIN
+                    : viewConfig.lazyLoadingMargin,
+        };
+    }
+
+    /**
+     * Whether the host app asked for a full-height embed.
+     */
+    private get isEnabled(): boolean {
+        return this.config.fullHeight === true;
+    }
+
+    /**
+     * Whether visualizations should load as they scroll into view, which
+     * requires the SDK to report the visible region of the embed.
+     */
+    private get isLazyLoadEnabled(): boolean {
+        return this.isEnabled && !!this.config.lazyLoadingForFullHeight;
+    }
+
+    /**
+     * The floor for the frame height. `defaultHeight` is the deprecated
+     * spelling of `minimumHeight` and is still honored for compatibility.
+     */
+    public get minimumHeight(): number {
+        const { minimumHeight, defaultHeight } = this.config;
+        return minimumHeight || defaultHeight || DEFAULT_MINIMUM_HEIGHT;
+    }
+
+    /**
+     * Registers the embed event handlers the feature depends on. Called from
+     * the constructor, so the handlers are in place before `render`.
+     */
+    private registerEventHandlers(): void {
+        if (!this.isEnabled) {
+            return;
+        }
+        this.host.on(EmbedEvent.RouteChange, this.handleRouteChange);
+        this.host.on(EmbedEvent.EmbedHeight, this.handleEmbedHeight);
+        this.host.on(EmbedEvent.EmbedIframeCenter, this.handleEmbedIframeCenter);
+        this.host.on(
+            EmbedEvent.RequestVisibleEmbedCoordinates,
+            this.handleRequestVisibleCoordinates,
+        );
+    }
+
+    /**
+     * Adds the full-height query parameters to the embed URL params.
+     * @param params The query parameters being built by the embed
+     */
+    public addQueryParams(params: QueryParams): void {
+        if (!this.isEnabled) {
+            return;
+        }
+        params[Param.fullHeight] = true;
+        if (!this.config.lazyLoadingForFullHeight) {
+            return;
+        }
+        params[Param.IsLazyLoadingForEmbedEnabled] = true;
+        if (isValidCssMargin(this.config.lazyLoadingMargin)) {
+            params[Param.RootMarginForLazyLoad] = this.config.lazyLoadingMargin;
+        }
+    }
+
+    /**
+     * Attaches the viewport listeners that keep lazy loading in sync. Call this
+     * once the embed has rendered and the iframe exists.
+     */
+    public onRender(): void {
+        this.registerLazyLoadListeners();
+    }
+
+    /**
+     * Detaches every listener and observer owned by the controller.
+     */
+    public destroy(): void {
+        this.unregisterLazyLoadListeners();
+    }
+
+    /**
+     * Sets the frame height to the height reported by the ThoughtSpot app,
+     * never going below the configured minimum.
+     */
+    private handleEmbedHeight = (payload: MessagePayload): void => {
+        const height = Number(payload?.data);
+        if (!isNaN(height)) {
+            this.host.setFrameHeight(Math.max(height, this.minimumHeight));
+        }
+        this.sendVisibleCoordinates();
+    };
+
+    /**
+     * Answers the app's request for the center of the visible embed region.
+     */
+    private handleEmbedIframeCenter = (
+        payload: MessagePayload,
+        responder?: (data: any) => void,
+    ): void => {
+        const iframe = this.host.getIframe();
+        if (!iframe) {
+            return;
+        }
+        responder?.({
+            type: EmbedEvent.EmbedIframeCenter,
+            data: calculateElementCenter(iframe),
+        });
+    };
+
+    /**
+     * Answers the app's request for the currently visible embed coordinates.
+     */
+    private handleRequestVisibleCoordinates = (
+        payload: MessagePayload,
+        responder?: (data: any) => void,
+    ): void => {
+        logger.info('Sending RequestVisibleEmbedCoordinates', payload);
+        responder?.({
+            type: EmbedEvent.RequestVisibleEmbedCoordinates,
+            data: this.getVisibleCoordinates(),
+        });
+    };
+
+    /**
+     * Resets the frame height when the app navigates away from a Liveboard,
+     * since only Liveboard routes report a height of their own.
+     */
+    private handleRouteChange = (payload: MessagePayload): void => {
+        const currentPath: string = payload?.data?.currentPath;
+        if (!currentPath) {
+            return;
+        }
+        if (LIVEBOARD_RELATED_ROUTES.some((route) => currentPath.startsWith(route))) {
+            return;
+        }
+        this.host.setFrameHeight(this.config.frameParams?.height || this.minimumHeight);
+    };
+
+    /**
+     * Pushes the visible embed region to the app so it can decide which
+     * visualizations to load.
+     */
+    private sendVisibleCoordinates = (): void => {
+        if (!this.isLazyLoadEnabled) {
+            return;
+        }
+        const coordinates = this.getVisibleCoordinates();
+        if (coordinates) {
+            this.host.trigger(HostEvent.VisibleEmbedCoordinates, coordinates);
+        }
+    };
+
+    private getVisibleCoordinates() {
+        const iframe = this.host.getIframe();
+        if (!iframe) {
+            return null;
+        }
+        return calculateVisibleElementData(
+            iframe,
+            this.config.enableScrollableContainerLazyLoading,
+        );
+    }
+
+    private registerLazyLoadListeners(): void {
+        if (!this.isLazyLoadEnabled || !this.host.getIframe()) {
+            return;
+        }
+        // Re-registering is safe: drop whatever a previous render attached.
+        this.unregisterLazyLoadListeners();
+        // TODO: Use passive: true, install modernizr to check for passive
+        window.addEventListener('resize', this.sendVisibleCoordinates);
+        window.addEventListener('scroll', this.sendVisibleCoordinates, true);
+        if (!this.config.enableScrollableContainerLazyLoading) {
+            return;
+        }
+        this.observeScrollableContainers();
+    }
+
+    /**
+     * Tracks the ancestors that can scroll or clip the embed, so the visible
+     * region stays correct when the embed lives inside its own scroll
+     * container rather than the page.
+     */
+    private observeScrollableContainers(): void {
+        const iFrame = this.host.getIframe();
+        this.scrollContainers = getScrollableAncestors(iFrame);
+        this.scrollContainers.forEach((scrollContainer) => {
+            scrollContainer.addEventListener('scroll', this.sendVisibleCoordinates);
+        });
+        if (typeof ResizeObserver === 'undefined') {
+            return;
+        }
+        const resizeTargets = new Set(
+            [iFrame.parentElement, ...getEffectiveClippingAncestors(iFrame)].filter(
+                Boolean,
+            ) as HTMLElement[],
+        );
+        this.resizeObserver = new ResizeObserver(this.sendVisibleCoordinates);
+        resizeTargets.forEach((resizeTarget) => {
+            this.resizeObserver.observe(resizeTarget);
+        });
+    }
+
+    private unregisterLazyLoadListeners(): void {
+        if (!this.isLazyLoadEnabled) {
+            return;
+        }
+        window.removeEventListener('resize', this.sendVisibleCoordinates);
+        window.removeEventListener('scroll', this.sendVisibleCoordinates, true);
+        this.resizeObserver?.disconnect();
+        this.resizeObserver = undefined;
+        this.scrollContainers.forEach((scrollContainer) => {
+            scrollContainer.removeEventListener('scroll', this.sendVisibleCoordinates);
+        });
+        this.scrollContainers = [];
+    }
+}

package/src/index.ts

@@ -64,6 +64,7 @@ import {
     VizPoint,
     CustomActionPayload,
     ListPageColumns,
+    CustomAction,
     CustomActionsPosition,
     CustomActionTarget,
     InterceptedApiType,
@@ -95,10 +96,6 @@ import {
     UIPassthroughRequest,
     UIPassthroughResponse,
     UIPassthroughArrayResponse,
-    HostEventRequest,
-    HostEventResponse,
-    TriggerPayload,
-    TriggerResponse,
     LiveboardTab,
     LiveboardGroup,
     ApplicabilityLevel,
@@ -106,7 +103,54 @@ import {
     FilterUpdate,
     LiveboardFilter,
     LiveboardParameter,
-} from './embed/hostEventClient/contracts';
+    PinAnswerToLiveboardRequest,
+    PinAnswerToLiveboardResponse,
+    SaveAnswerRequest,
+    SaveAnswerResponse,
+    GetDiscoverabilityStatusResponse,
+    GetAvailableUIPassthroughsResponse,
+    GetAnswerConfigRequest,
+    GetUnsavedAnswerTMLRequest,
+    GetUnsavedAnswerTMLResponse,
+    GetAnswerSessionRequest,
+    GetAnswerSessionResponse,
+    GetFiltersRequest,
+    GetFiltersResponse,
+    GetIframeUrlResponse,
+    GetParametersResponse,
+    GetTMLRequest,
+    GetTabsResponse,
+    GetGroupsResponse,
+    GetExportRequestForCurrentPinboardResponse,
+    UpdateFiltersPassthroughRequest,
+    DrilldownRequest,
+} from './contracts/ui-passthrough-contracts';
+import {
+    HostEventRequest,
+    HostEventResponse,
+    TriggerPayload,
+    TriggerResponse,
+    TriggerData,
+    VizScopedRequest,
+    RequiredVizRequest,
+    ConversationScopedRequest,
+    OpenFilterRequest,
+    OpenFilterLiveboardRequest,
+    OpenFilterSpotterRequest,
+    OpenFilterSearchRequest,
+    DrillDownRequest,
+    OpenParameterRequest,
+    SearchRequest,
+    SpotterSearchRequest,
+    CrossFilterCondition,
+    UpdateCrossFilterRequest,
+    HostFilterUpdate,
+    UpdateFiltersRequest,
+    PersonalisedViewRequest,
+    ScheduleEmailRequest,
+    NavigateRequest,
+    SetActiveTabRequest,
+} from './contracts/host-event-contracts';
 
 export {
     init,
@@ -191,6 +235,7 @@ export {
     HomePage,
     ListPage,
     VizPoint,
+    CustomAction,
     CustomActionPayload,
     UIPassthroughEvent,
     // Host event payload / response contracts. These describe what to send with
@@ -205,12 +250,55 @@ export {
     HostEventResponse,
     TriggerPayload,
     TriggerResponse,
+    // Host event contract shapes, map and trigger() data type — see /contracts.
+    TriggerData,
+    VizScopedRequest,
+    RequiredVizRequest,
+    ConversationScopedRequest,
+    OpenFilterRequest,
+    OpenFilterLiveboardRequest,
+    OpenFilterSpotterRequest,
+    OpenFilterSearchRequest,
+    DrillDownRequest,
+    OpenParameterRequest,
+    SearchRequest,
+    SpotterSearchRequest,
+    CrossFilterCondition,
+    UpdateCrossFilterRequest,
+    HostFilterUpdate,
+    UpdateFiltersRequest,
+    PersonalisedViewRequest,
+    ScheduleEmailRequest,
+    NavigateRequest,
+    SetActiveTabRequest,
     LiveboardTab,
     LiveboardGroup,
     ApplicabilityLevel,
     Applicability,
     FilterUpdate,
     LiveboardFilter,
+    // UI passthrough request/response shapes (see UIPassthroughContractBase).
+    PinAnswerToLiveboardRequest,
+    PinAnswerToLiveboardResponse,
+    SaveAnswerRequest,
+    SaveAnswerResponse,
+    GetDiscoverabilityStatusResponse,
+    GetAvailableUIPassthroughsResponse,
+    GetAnswerConfigRequest,
+    GetUnsavedAnswerTMLRequest,
+    GetUnsavedAnswerTMLResponse,
+    GetAnswerSessionRequest,
+    GetAnswerSessionResponse,
+    GetFiltersRequest,
+    GetFiltersResponse,
+    GetIframeUrlResponse,
+    GetParametersResponse,
+    GetTMLRequest,
+    GetTabsResponse,
+    GetGroupsResponse,
+    GetExportRequestForCurrentPinboardResponse,
+    UpdateFiltersPassthroughRequest,
+    DrilldownRequest,
     LiveboardParameter,
     ListPageColumns,
     DataPanelCustomColumnGroupsAccordionState,

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

@@ -16,6 +16,39 @@ import * as path from 'path';
 
 const INDEX_PATH = path.join(__dirname, '..', 'index.ts');
 const REACT_EXPORT_PATH = path.join(__dirname, 'all-types-export.ts');
+const TYPES_PATH = path.join(__dirname, '..', 'types.ts');
+const HOST_EVENT_CONTRACTS_PATH = path.join(
+    __dirname, '..', 'contracts', 'host-event-contracts.ts',
+);
+
+// Payload/request/response types named by `{@link X}` in a doc comment that a
+// customer is meant to import. Enums and internal resolver/map mechanics are
+// referenced by docs too but are not part of this exported-payload contract.
+const NON_PAYLOAD_LINK_TARGETS = new Set([
+    'HostEvent', 'EmbedEvent', 'ContextType', 'RuntimeFilterOp',
+    'HostEventRequest', 'HostEventResponse', 'HostEventRequestMap',
+    'HostEventContextRequestMap', 'DefaultHostEventRequest',
+    'EmbedApiHostEventMapping', 'TriggerData', 'TriggerResponse',
+    'TriggerPayload', 'DeepPartial', 'UIPassthroughRequest',
+    'UIPassthroughResponse', 'HostEventName',
+]);
+
+// Extract the payload types named by `{@link X}` (bare identifier, not a member
+// access like `HostEvent.Foo`) inside the `*Request`/`*Response` docs and
+// the HostEvent enum docs — the links a customer follows to a payload type.
+const extractPayloadLinkTargets = (source: string): Set<string> => {
+    const targets = new Set<string>();
+    const linkRe = /\{@link\s+([A-Za-z_$][\w$]*)(?:\.[\w$]+)?\s*\}/g;
+    let m = linkRe.exec(source);
+    while (m !== null) {
+        const name = m[1];
+        // Member access (`HostEvent.OpenFilter`) captured `HostEvent` — that is
+        // an enum, filtered below. A payload type ends in Request/Response.
+        if (/(?:Request|Response)$/.test(name)) targets.add(name);
+        m = linkRe.exec(source);
+    }
+    return targets;
+};
 
 /**
  * Symbols intentionally absent from the React surface.
@@ -45,8 +78,8 @@ const REACT_EXEMPT = new Set<string>([
 /**
  * PRE-EXISTING gaps, discovered when this spec was introduced. These are
  * symbols React consumers cannot import today — most look like oversights
- * rather than deliberate omissions (e.g. `ContextType`, `CustomActionPayload`,
- * `VizPoint`, the Spotter view configs).
+ * rather than deliberate omissions (e.g. `ContextType`, `VizPoint`,
+ * the Spotter view configs).
  *
  * This list may only ever SHRINK. Do not add to it — a new entry means a
  * symbol was added to `src/index.ts` without adding it to the React surface,
@@ -64,7 +97,6 @@ const KNOWN_REACT_GAPS = new Set<string>([
     'ContextMenuTriggerOptions',
     'ContextType',
     'ConversationViewConfig',
-    'CustomActionPayload',
     'DataLabelFilterOperator',
     'EmbedErrorCodes',
     'EmbedErrorDetailsEvent',
@@ -203,6 +235,34 @@ describe('react/all-types-export parity with index', () => {
             'HostEventResponse',
             'TriggerPayload',
             'TriggerResponse',
+            'TriggerData',
+            'UpdateFiltersRequest',
+            'NavigateRequest',
         ].forEach((name) => expect(reactNames.has(name)).toBe(true));
     });
+
+    // Docs and types must not diverge: a `{@link SomethingRequest}` in a doc
+    // comment promises the reader can reach that type. If generation renames
+    // or drops a payload type, or an export is removed, the link dangles. This
+    // or drops a payload type, or an export is removed, the link dangles. It
+    it('every payload type linked from docs is exported from both entry points', () => {
+        const indexNames = extractExportedNames(fs.readFileSync(INDEX_PATH, 'utf8'));
+        const reactNames = extractExportedNames(fs.readFileSync(REACT_EXPORT_PATH, 'utf8'));
+        const linked = new Set<string>([
+            ...extractPayloadLinkTargets(fs.readFileSync(TYPES_PATH, 'utf8')),
+            ...extractPayloadLinkTargets(
+                fs.readFileSync(HOST_EVENT_CONTRACTS_PATH, 'utf8'),
+            ),
+        ]);
+
+        // Sanity: the doc scan found the payload links we added.
+        expect(linked.has('OpenFilterLiveboardRequest')).toBe(true);
+        expect(linked.has('DrillDownRequest')).toBe(true);
+        expect(linked.size).toBeGreaterThan(5);
+
+        const dangling = [...linked]
+            .filter((name) => !NON_PAYLOAD_LINK_TARGETS.has(name))
+            .filter((name) => !indexNames.has(name) || !reactNames.has(name));
+        expect(dangling).toEqual([]);
+    });
 });

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

@@ -66,16 +66,61 @@ export {
     HostEventResponse,
     TriggerPayload,
     TriggerResponse,
+    // Host event contract shapes, map and trigger() data type — see /contracts.
+    TriggerData,
+    VizScopedRequest,
+    RequiredVizRequest,
+    ConversationScopedRequest,
+    OpenFilterRequest,
+    OpenFilterLiveboardRequest,
+    OpenFilterSpotterRequest,
+    OpenFilterSearchRequest,
+    DrillDownRequest,
+    OpenParameterRequest,
+    SearchRequest,
+    SpotterSearchRequest,
+    CrossFilterCondition,
+    UpdateCrossFilterRequest,
+    HostFilterUpdate,
+    UpdateFiltersRequest,
+    PersonalisedViewRequest,
+    ScheduleEmailRequest,
+    NavigateRequest,
+    SetActiveTabRequest,
     LiveboardTab,
     LiveboardGroup,
     ApplicabilityLevel,
     Applicability,
     FilterUpdate,
     LiveboardFilter,
+    // UI passthrough request/response shapes (see UIPassthroughContractBase).
+    PinAnswerToLiveboardRequest,
+    PinAnswerToLiveboardResponse,
+    SaveAnswerRequest,
+    SaveAnswerResponse,
+    GetDiscoverabilityStatusResponse,
+    GetAvailableUIPassthroughsResponse,
+    GetAnswerConfigRequest,
+    GetUnsavedAnswerTMLRequest,
+    GetUnsavedAnswerTMLResponse,
+    GetAnswerSessionRequest,
+    GetAnswerSessionResponse,
+    GetFiltersRequest,
+    GetFiltersResponse,
+    GetIframeUrlResponse,
+    GetParametersResponse,
+    GetTMLRequest,
+    GetTabsResponse,
+    GetGroupsResponse,
+    GetExportRequestForCurrentPinboardResponse,
+    UpdateFiltersPassthroughRequest,
+    DrilldownRequest,
     LiveboardParameter,
     DataPanelCustomColumnGroupsAccordionState,
     InterceptedApiType,
     EmbedErrorSeverity,
+    CustomAction,
+    CustomActionPayload,
     CustomActionsPosition,
     CustomActionTarget,
     SpotterAnalystConfig,