Skip to content

[SCAL-351755] Add DataAppEmbed host events, tile events and options - #745

Open
akshay-pandey-thoughtspot wants to merge 3 commits into
thoughtspot:mainfrom
akshay-pandey-thoughtspot:SCAL-351755-dataapp-embed-events
Open

akshay-pandey-thoughtspot wants to merge 3 commits into
thoughtspot:mainfrom
akshay-pandey-thoughtspot:SCAL-351755-dataapp-embed-events

Conversation

@akshay-pandey-thoughtspot

@akshay-pandey-thoughtspot akshay-pandey-thoughtspot commented Nov 12, 2026 •

Copy link
Copy Markdown

Summary

Host events, embed events and options for DataAppEmbed: load or switch Apps, refresh them, filter them, follow the host's theme, and hear about tile clicks, loads, errors and the App's own scheme switch.

Stacked on #734 (DataAppEmbed, enableDataApps): its two commits show here until it merges. Only the last commit is this PR. The branch is rebased on current main, which turns host events v2 on by default (#740), so the DataApp context matters for every host.

const embed = new DataAppEmbed('#tsEmbed', {
  dataAppId: '<app-id>',
  enableDataApps: true,
  runtimeFilters: [{ columnName: 'Region', operator: RuntimeFilterOp.EQ, values: ['West'] }],
  hideDataAppHeader: true,
});
embed.on(EmbedEvent.TileClick, ({ tileId }) => openDetails(tileId));
embed.render();

await embed.trigger(HostEvent.DataAppInit, { appId: '<other-app-id>' });
await embed.trigger(HostEvent.RefreshDataApp);
await embed.trigger(HostEvent.UpdateTheme, { isDarkMode: true });

Changes

  • New host events, typed in HostEventRequestMap:
    • HostEvent.DataAppInit (DataAppInitRequest { appId, runtimeFilters?, runtimeParameters? }): open an App or switch to another; its filters and parameters replace the earlier ones
    • HostEvent.RefreshDataApp (no payload): re-run the App's tiles, no frame reload
  • Reused host events, docs now cover DataAppEmbed: UpdateRuntimeFilters, UpdateParameters, UpdateTheme (a single-scheme App rejects)
  • New embed events, typed in EmbedEventDataExtension:
    • TileClick, TileLoad: DataAppTilePayload { appId, tileId }
    • TileError: DataAppTileErrorPayload { appId, tileId, errorCode?, message?, sourceName?, connectorName? }
    • Darkmode: DarkmodePayload { isDarkMode }, only from the App's own scheme button
  • ContextType.DataApp ('dataApp'), for host events v2
  • DataAppEmbedViewConfig:
    • runtimeFilters, runtimeParameters: sent in APP_INIT, never in the URL
    • hideDataAppHeader: hides the ThoughtSpot header above the App (hideDataAppHeader URL param)
  • New types exported from index.ts and react/all-types-export.ts; wire values added to the locks in contracts.spec.ts
  • @version SDK: <TBD> | ThoughtSpot Cloud: 26.12.0.cl on everything new

Testing

  • jest -c jest.config.sdk.js (full suite, rebased on current main): 56 suites, 2361 passed
  • New cases in data-app.spec.ts: hideDataAppHeader on the URL; filters and parameters in APP_INIT, not the URL
  • contracts.spec.ts: new wire values locked; DataAppInit and RefreshDataApp examples compile against TriggerData
  • tsc -p tsconfig.build.json --noEmit
  • eslint on the changed files (no new findings)
  • npm run lint-versions
  • Manual test against a cluster with the scaligent PRs deployed

Additional Notes

RefreshDataApp is a new event, not a reuse. The review comment asked to reuse the Liveboard one. The candidates:

  • HostEvent.RefreshLiveboardBrowserCache: named for the Liveboard and its browser data cache, documented as needing enableLiveboardDataCache, and typed with ScheduleEmailRequest. Apps have no browser cache; every load is a fresh stream.
  • HostEvent.Reload: reloads the whole iframe inside the SDK and never reaches ThoughtSpot, which is what RefreshDataApp must not do.

Reusing either would give a Liveboard-named event a different meaning for Apps. Easy to alias later if the reviewers still prefer it.

overrideFilters (in the design's DataAppInit payload) is left out of the type: the design does not define OverrideFilters, and narrowing a published field later is a breaking change. ThoughtSpot accepts and ignores it for now.

Port messages between the Apps page and the App frame (in the scaligent and apps-core PRs, listed here for reviewers):

Message Direction Payload When
host:refresh Apps page → App { requestId, force? } force: RefreshDataApp, every visible tile re-runs. Without: the usual refresh (steps: []) after the host's filters or parameters change
host:theme Apps page → App { requestId, isDarkMode } UpdateTheme, and the host's isDarkMode when the frame connects
dataapp:host-reply App → Apps page { requestId, error? } Answers one host:* request; error rejects it
dataapp:tile-click App → Apps page { tileId } Click inside a <Tile>
dataapp:tile-load App → Apps page { tileId } Every <StepData> in the tile settled, once per run
dataapp:tile-error App → Apps page { tileId, errorCode?, message?, sourceName?, connectorName? } A step feeding the tile failed
dataapp:scheme-change App → Apps page { isDarkMode } The App's own scheme button; never after host:theme

Names follow the existing port protocol: host:* goes into the frame, dataapp:* comes out of it.

Landing order

  1. [SCAL-349233] Add DataAppEmbed and enableDataApps #734, then this PR. Nothing here works without the scaligent PRs on the cluster.
  2. scaligent shell PR, then the scaligent dataapps PR.
  3. apps-core can land any time; it reaches Apps after its npm release and aurora's pin bump.

Older ThoughtSpot: the new host events get "no handler" validation errors (host events v2) or no reply; hideDataAppHeader and the filters are ignored.

Follow-ups, not in this PR

  • Every "To be added later" row: Share, Edit, ViewPublished, Rename, MakeACopy, Present, RestoreToPublished, Remove, and their actions
  • SourceData, UserInputs, style customizations (host:style), SpotterX, connectors
  • DataAppInit does not update the view config, so a pre-render show cycle re-sends the original filters
  • UpdateRuntimeFilters / UpdateParameters still get no reply, as in other embeds
  • overrideFilters type

Design doc: https://docs.google.com/document/d/1rBzPGZG3Y-IcZZQkUreTls93fK_WKZThXOlQjlxLZNQ/edit
Jira: SCAL-351755

Sibling PRs:

🤖 Generated with Claude Code

@akshay-pandey-thoughtspot
akshay-pandey-thoughtspot requested a review from a team as a code owner November 12, 2026 06:29

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces the DataAppEmbed component and its React wrapper to support embedding single ThoughtSpot Apps. It adds new host events (DataAppInit, RefreshDataApp), embed events (TileClick, TileLoad, TileError, Darkmode), associated payloads, and comprehensive unit tests. The review feedback suggests avoiding the reassignment of constructor parameter properties in DataAppEmbed, adding a defensive guard in getIframeSrc to handle missing dataAppId values, and correcting invalid JSX syntax in the JSDoc example for the React component.

Comment thread src/embed/data-app.ts
Comment on lines +127 to +141
constructor(container: HTMLElement, protected viewConfig: DataAppEmbedViewConfig) {
viewConfig = {
embedComponentType: 'dataApp',
...viewConfig,
// Filters and parameters go in the app init payload, never the URL.
excludeRuntimeFiltersfromURL: true,
excludeRuntimeParametersfromURL: true,
} as DataAppEmbedViewConfig;
// Not in the view config type, but a JS caller can still pass it.
if ((viewConfig as { fullHeight?: boolean }).fullHeight) {
logger.warn('DataAppEmbed does not support fullHeight; it is ignored.');
viewConfig = { ...viewConfig, fullHeight: false } as DataAppEmbedViewConfig;
}
super(container, viewConfig);
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Reassigning constructor parameter properties is highly discouraged and error-prone in TypeScript, especially when overriding a property from a base class. Instead, declare viewConfig as a class property and pass a regular parameter to the constructor, consistent with other embed components like AppEmbed.

    protected viewConfig: DataAppEmbedViewConfig;

    constructor(container: HTMLElement, viewConfig: DataAppEmbedViewConfig) {
        const config = {
            embedComponentType: 'dataApp',
            ...viewConfig,
            // Filters and parameters go in the app init payload, never the URL.
            excludeRuntimeFiltersfromURL: true,
            excludeRuntimeParametersfromURL: true,
        } as DataAppEmbedViewConfig;
        // Not in the view config type, but a JS caller can still pass it.
        if ((config as any).fullHeight) {
            logger.warn('DataAppEmbed does not support fullHeight; it is ignored.');
            (config as any).fullHeight = false;
        }
        super(container, config);
        this.viewConfig = config;
    }

Comment thread src/embed/data-app.ts
Comment on lines +158 to +161
public getIframeSrc(): string {
const path = `embed/insights/apps/${encodeURIComponent(this.viewConfig.dataAppId)}`;
return `${this.getRootIframeSrc()}/${path}${this.getThoughtSpotPostUrlParams()}`;
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Add a defensive guard for this.viewConfig.dataAppId to prevent encodeURIComponent from receiving undefined or generating a broken URL if the ID is missing or empty.

Suggested change
public getIframeSrc(): string {
const path = `embed/insights/apps/${encodeURIComponent(this.viewConfig.dataAppId)}`;
return `${this.getRootIframeSrc()}/${path}${this.getThoughtSpotPostUrlParams()}`;
}
public getIframeSrc(): string {
const appId = this.viewConfig.dataAppId || '';
const path = `embed/insights/apps/${encodeURIComponent(appId)}`;
return `${this.getRootIframeSrc()}/${path}${this.getThoughtSpotPostUrlParams()}`;
}

Comment thread src/react/index.tsx
Comment on lines +344 to +358
/**
* React component for embedding a single ThoughtSpot App.
* @version SDK: <TBD> | ThoughtSpot Cloud: 26.12.0.cl
* @example
* ```tsx
* function App() {
* return <DataAppEmbed
* dataAppId="<app-id>"
* enableDataApps={true}
* frameParams={{ height: '800px' }}
* ... other view config props or event listeners.
* />
* }
* ```
*/

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The JSDoc example contains ... other view config props or event listeners. which is invalid JSX syntax and will cause compilation/parsing errors in documentation tools. Remove this line to keep the example clean and syntactically valid.

/**
 * React component for embedding a single ThoughtSpot App.
 * @version SDK: <TBD> | ThoughtSpot Cloud: 26.12.0.cl
 * @example
 * ```tsx
 * function App() {
 *  return <DataAppEmbed
 *      dataAppId="<app-id>"
 *      enableDataApps={true}
 *      frameParams={{ height: '800px' }}
 *  />
 * }
 * ```
 */

DataAppEmbed embeds a single ThoughtSpot App, the way LiveboardEmbed
embeds one Liveboard. It loads the App embed route on the v2 shell,
/v2/?...#/embed/insights/apps/<dataAppId>, which renders the App page
inside ThoughtSpot.

- dataAppId is required: without it, a DATA_APP_ID_MISSING
  validation error and no frame
- fullHeight is not supported: it is dropped with a warning
- React <DataAppEmbed> wrapper and type exports
- embedComponentType 'dataApp'

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Embedded ThoughtSpot hides Apps unless the host opts in. The new
enableDataApps view config sends enableDataApps on the iframe URL; the
app shows Apps only when it is true and the instance has Apps on.

- AppViewConfig and DataAppEmbedViewConfig take enableDataApps
  (default false); DataAppEmbed now sends its own embed params
- Keep the param on the URL under excludeConfigFromURL, since the app
  reads it at boot for its route guards
- Specs for both embed types and the excludeConfigFromURL case

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Hosts embedding an App can now load or switch Apps, refresh them,
filter them and follow their tiles and color scheme.

- HostEvent.DataAppInit { appId, runtimeFilters?, runtimeParameters? }
  and HostEvent.RefreshDataApp, typed in HostEventRequestMap
- EmbedEvent.TileClick, TileLoad, TileError and Darkmode, typed in
  EmbedEventDataExtension
- ContextType.DataApp for host events v2
- DataAppEmbedViewConfig: runtimeFilters and runtimeParameters (sent in
  APP_INIT, never the URL) and hideDataAppHeader
- UpdateRuntimeFilters, UpdateParameters and UpdateTheme docs cover
  DataAppEmbed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@akshay-pandey-thoughtspot
akshay-pandey-thoughtspot force-pushed the SCAL-351755-dataapp-embed-events branch from dafd21a to 82acd37 Compare November 12, 2026 06:36
@pkg-pr-new

pkg-pr-new Bot commented Nov 12, 2026

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/@thoughtspot/visual-embed-sdk@745

commit: 82acd37

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant