@thoughtspot/visual-embed-sdk 1.10.0-alpha.1 → 1.10.0-alpha.4

package/CHANGELOG.md

@@ -8,6 +8,22 @@ This project follows Semantic Versioning.
 ### New Features
 - Events for all actions on Search Embed
 
+## 1.9.5 (04-06-2022)
+
+### New Features
+- `locale` param to set Locale/language for the embedded view.
+
+
+## 1.9.4 (04-06-2022)
+
+### Fixed
+- [React] `className` should be forwarded to the iframe container div.
+
+
+## 1.9.3 (03-22-2022)
+
+### New Features 
+- `disableLoginRedirect` option in `EmbedConfig`
 
 ## 1.9.2 (03-17-2022)
 

package/README.md

@@ -25,6 +25,8 @@ The SDK is written in TypeScript and is also provided both as ES Module (ESM) an
 ```js
 // ESM via NPM
 import * as TsEmbedSDK from '@thoughtspot/visual-embed-sdk';
+// OR
+import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk';
 
 // NPM <script>
 <script src="https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.js"></script>;
@@ -41,7 +43,8 @@ import {
 
 ## Live Playground
 
-Visit our [code playground](https://try-everywhere.thoughtspot.cloud/v2/#/everywhere).
+Visit our [code playground](https://try-everywhere.thoughtspot.cloud/v2/#/everywhere). <br/><br/>
+Start a [free trial](https://www.thoughtspot.com/trial?tsref=trialtse) on your own data.
 
 <br/>
 
@@ -132,10 +135,26 @@ const appEmbed = new AppEmbed(document.getElementById('ts-embed'), {
 appEmbed.render();
 ```
 
+### Triggering and Listening to events
+```js
+// NPM
+import { LiveboardEmbed, Page, AuthType, init, EmbedEvent, HostEvent } from '@thoughtspot/visual-embed-sdk';
+
+// .. Do init and create a liveboardEmbed object as above.
+
+liveboardEmbed.render();
+
+liveboardEmbed.on(EmbedEvent.LiveboardRendered, () => {
+    liveboardEmbed.trigger(HostEvent.SetVisibleVizs, ['viz1', 'viz2']);
+});
+```
+
 ## React Components
 
 All the above flavors of embedding are also provided as React components for your convenience.
 The constructor options are passed as props and the event listeners can be attached using `on<EventName>` convention.
+<br/><br/>
+Checkout a comprehensive working demo [here](https://codesandbox.io/s/github/ashubham/big-react-demo)
 
 ### Search Component
 
@@ -166,7 +185,7 @@ const MyComponent = ({ dataSources }) => {
 };
 ```
 
-### Triggering events on React components
+### Triggering events on React components (> version 1.9.2)
 
 ```jsx
 import { HostEvent } from '@thoughtspot/visual-embed-sdk';

package/dist/src/embed/app.d.ts

@@ -37,7 +37,11 @@ export declare enum Page {
     /**
      * Data management page
      */
-    Data = "data"
+    Data = "data",
+    /**
+     * SpotIQ listing page
+     */
+    SpotIQ = "spotiq"
 }
 /**
  * The view configuration for full app embedding.
@@ -74,6 +78,14 @@ export interface AppViewConfig extends ViewConfig {
      * The array of GUIDs to be hidden
      */
     hideObjects?: string[];
+    /**
+     * Render liveboards using the new v2 rendering mode
+     * This is a transient flag which is primarily meant for internal use
+     * @default false
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     * @hidden
+     */
+    liveboardV2?: boolean;
 }
 /**
  * Embeds full ThoughtSpot experience in a host application.
@@ -106,10 +118,12 @@ export declare class AppEmbed extends V1Embed {
     /**
      * Navigate to particular page for app embed. eg:answers/pinboards/home
      * This is used for embedding answers, pinboards, visualizations and full application only.
-     * @param path The string, set to iframe src and navigate to new page
+     * @param path string | number The string, set to iframe src and navigate to new page
      * eg: appEmbed.navigateToPage('pinboards')
+     * When used with `noReload` this can also be a number like 1/-1 to go forward/back.
+     * @param noReload boolean Trigger the navigation without reloading the page (version: 1.12.0 | 8.4.0.cl)
      */
-    navigateToPage(path: string): void;
+    navigateToPage(path: string | number, noReload?: boolean): void;
     /**
      * Renders the embedded application pages in the ThoughtSpot app.
      * @param renderOptions An object containing the page ID

package/dist/src/embed/liveboard.d.ts

@@ -63,6 +63,14 @@ export interface LiveboardViewConfig extends ViewConfig {
      * @hidden
      */
     preventPinboardFilterRemoval?: boolean;
+    /**
+     * Render embedded liveboards and visualizations using the new v2 rendering mode
+     * This is a transient flag which is primarily meant for internal use
+     * @default false
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     * @hidden
+     */
+    liveboardV2?: boolean;
 }
 /**
  * Embed a ThoughtSpot Liveboard or visualization

package/dist/src/embed/pinboard.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Copyright (c) 2021
+ *
+ * Embed a ThoughtSpot pinboard or visualization
+ * https://developers.thoughtspot.com/docs/?pageid=embed-pinboard
+ * https://developers.thoughtspot.com/docs/?pageid=embed-a-viz
+ *
+ * @summary Pinboard & visualization embed
+ * @author Ayon Ghosh <ayon.ghosh@thoughtspot.com>
+ */
+import { DOMSelector } from '../types';
+import { V1Embed, ViewConfig } from './ts-embed';
+/**
+ * The configuration for the embedded pinboard or visualization page view.
+ * @Category Pinboards and Charts
+ */
+export interface PinboardViewConfig extends ViewConfig {
+    /**
+     * If set to true, the embedded object container dynamically resizes
+     * according to the height of the pinboard.
+     */
+    fullHeight?: boolean;
+    /**
+     * This is the minimum height(in pixels) for a full height pinboard.
+     * Setting this height helps resolves issues with empty pinboards and
+     * other screens navigable from a pinboard.
+     * @default 500
+     * * _since 1.5.0_
+     */
+    defaultHeight?: number;
+    /**
+     * If set to true, the context menu in visualizations will be enabled.
+     */
+    enableVizTransformations?: boolean;
+    /**
+     * The pinboard to display in the embedded view.
+     */
+    pinboardId: string;
+    /**
+     * The visualization within the pinboard to display.
+     */
+    vizId?: string;
+    /**
+     * If set to true, all filter chips from a
+     * pinboard page will be read-only (no X buttons)
+     */
+    preventPinboardFilterRemoval?: boolean;
+}
+/**
+ * Embed a ThoughtSpot pinboard or visualization
+ * @Category Pinboards and Charts
+ */
+export declare class PinboardEmbed extends V1Embed {
+    protected viewConfig: PinboardViewConfig;
+    private defaultHeight;
+    constructor(domSelector: DOMSelector, viewConfig: PinboardViewConfig);
+    /**
+     * Construct a map of params to be passed on to the
+     * embedded pinboard or visualization.
+     */
+    private getEmbedParams;
+    /**
+     * Construct the URL of the embedded ThoughtSpot pinboard or visualization
+     * to be loaded within the iframe.
+     * @param pinboardId The GUID of the pinboard.
+     * @param vizId The optional GUID of a visualization within the pinboard.
+     * @param runtimeFilters A list of runtime filters to be applied to
+     * the pinboard or visualization on load.
+     */
+    private getIFrameSrc;
+    /**
+     * Set the iframe height as per the computed height received
+     * from the ThoughtSpot app.
+     * @param data The event payload
+     */
+    private updateIFrameHeight;
+    private embedIframeCenter;
+    private handleRouteChangeFullHeightPinboard;
+    /**
+     * Render an embedded ThoughtSpot pinboard or visualization
+     * @param renderOptions An object specifying the pinboard ID,
+     * visualization ID and the runtime filters.
+     */
+    render(): PinboardEmbed;
+}

package/dist/src/embed/ts-embed.d.ts

@@ -6,7 +6,11 @@
  * @summary Base classes
  * @author Ayon Ghosh <ayon.ghosh@thoughtspot.com>
  */
-import { DOMSelector, HostEvent, EmbedEvent, MessageCallback, Action, RuntimeFilter, EmbedConfig } from '../types';
+import { DOMSelector, HostEvent, EmbedEvent, MessageCallback, Action, RuntimeFilter, EmbedConfig, MessageOptions } from '../types';
+/**
+ * Global prefix for all Thoughtspot postHash Params.
+ */
+export declare const THOUGHTSPOT_PARAM_PREFIX = "ts-";
 export interface LayoutConfig {
 }
 /**
@@ -21,6 +25,11 @@ export interface FrameParams {
      * The height of the iFrame (unit is pixels if numeric).
      */
     height?: number | string;
+    /**
+     * This parameters will be passed on the iframe
+     * as is.
+     */
+    [key: string]: string | number | boolean;
 }
 /**
  * The configuration object for an embedded view.
@@ -62,15 +71,28 @@ export interface ViewConfig {
      * @version 1.6.0 or later
      */
     visibleActions?: Action[];
+    /**
+     * Show alert messages and toast messages in the embedded view.
+     * @version 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    showAlerts?: boolean;
     /**
      * The list of runtime filters to apply to a search answer,
      * visualization, or Liveboard.
      */
     runtimeFilters?: RuntimeFilter[];
+    /**
+     * The locale/language to use for the embedded view.
+     * @version 1.9.4 or later
+     */
+    locale?: string;
     /**
      * This is an object (key/val) of override flags which will be applied
      * to the internal embedded object. This can be used to add any
      * URL flag.
+     * Warning: This option is for advanced use only and is used internally
+     * to control embed behavior in non-regular ways. We do not publish the
+     * list of supported keys and values associated with each.
      * @version SDK: 1.9.0 | ThoughtSpot: 8.1.0.cl
      */
     additionalFlags?: {
@@ -183,7 +205,7 @@ export declare class TsEmbed {
      * @param url
      * @param frameOptions
      */
-    protected renderIFrame(url: string, frameOptions: FrameParams): void;
+    protected renderIFrame(url: string, frameOptions?: FrameParams): void;
     /**
      * Sets the height of the iframe
      * @param height The height in pixels
@@ -227,9 +249,10 @@ export declare class TsEmbed {
      * sends an event of a particular message type to the host application.
      *
      * @param messageType The message type
-     * @param callback A callback function
+     * @param callback A callback as a function
+     * @param options The message options
      */
-    on(messageType: EmbedEvent, callback: MessageCallback): typeof TsEmbed.prototype;
+    on(messageType: EmbedEvent, callback: MessageCallback, options?: MessageOptions): typeof TsEmbed.prototype;
     /**
      * Triggers an event on specific Port registered against
      * for the EmbedEvent
@@ -250,6 +273,12 @@ export declare class TsEmbed {
      * @param args
      */
     render(): TsEmbed;
+    /**
+     * Get the Post Url Params for THOUGHTSPOT from the current
+     * host app URL.
+     * THOUGHTSPOT URL params starts with a prefix "ts-"
+     */
+    getThoughtSpotPostUrlParams(): string;
 }
 /**
  * Base class for embedding v1 experience

package/dist/src/types.d.ts

@@ -140,11 +140,31 @@ export interface EmbedConfig {
      */
     customCssUrl?: string;
 }
+/**
+ * MessagePayload: Embed event payload: message type, data and status (start/end)
+ */
 export declare type MessagePayload = {
     type: string;
     data: any;
+    status?: string;
+};
+/**
+ * MessageOptions: By Providing options, getting specific event start / end based on option
+ */
+export declare type MessageOptions = {
+    start?: boolean;
 };
+/**
+ * MessageCallback: Embed event message callback
+ */
 export declare type MessageCallback = (payload: MessagePayload, responder?: (data: any) => void) => void;
+/**
+ * MessageCallbackObj: contains message options & callback function
+ */
+export declare type MessageCallbackObj = {
+    options: MessageOptions;
+    callback: MessageCallback;
+};
 export declare type GenericCallbackFn = (...args: any[]) => any;
 export declare type QueryParams = {
     [key: string]: string;
@@ -292,6 +312,12 @@ export declare enum EmbedEvent {
      * @version 1.5.0 or later
      */
     VizPointDoubleClick = "vizPointDoubleClick",
+    /**
+     * A click has been triggered on table/chart
+     * @return ContextMenuInputPoints - data point that is clicked
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    VizPointClick = "vizPointClick",
     /**
      * An error has occurred.
      * @return error - An error object or message
@@ -356,7 +382,102 @@ export declare enum EmbedEvent {
      * rendered liveboard
      * @version 1.9.1 or later
      */
-    LiveboardRendered = "PinboardRendered"
+    LiveboardRendered = "PinboardRendered",
+    /**
+     * Emitted when answer is saved in the app
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    Save = "save",
+    /**
+     * Emitted when the download action is triggered on an answer
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    Download = "download",
+    /**
+     * Emitted when the Download as PDF action is triggered on an answer
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    DownloadAsPdf = "downloadAsPdf",
+    /**
+     * Emitted when the Download as CSV action is triggered on an answer
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    DownloadAsCsv = "downloadAsCsv",
+    /**
+     * Emitted when the Download as XLSX action is triggered on an answer
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    DownloadAsXlsx = "downloadAsXlsx",
+    /**
+     * Emitted when an answer is deleted in the app
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    AnswerDelete = "answerDelete",
+    /**
+     * Emitted when an answer is pinned to a Liveboard
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    Pin = "pin",
+    /**
+     * Emitted when SpotIQ analysis is triggered
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    SpotIQAnalyze = "spotIQAnalyze",
+    /**
+     * Emitted when a user shares an object with another user or group
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    Share = "share",
+    /**
+     * Emitted when a user clicks the Include action to include a specific value or data on a chart or table
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    DrillInclude = "context-menu-item-include",
+    /**
+     * Emitted when a user clicks the Exclude action to exclude a specific value or data on a chart or table
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    DrillExclude = "context-menu-item-exclude",
+    /**
+     * Emitted when copied column value on the app
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    CopyToClipboard = "context-menu-item-copy-to-clipboard",
+    /**
+     * Emitted when a user clicks the Update TML action
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    UpdateTML = "updateTSL",
+    /**
+     * Emitted when a user clicks the Edit TML action
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    EditTML = "editTSL",
+    /**
+     * Emitted when ExportTML trigger in answer on the app
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    ExportTML = "exportTSL",
+    /**
+     * Emitted when an answer is saved as a view
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    SaveAsView = "saveAsView",
+    /**
+     * Emitted when copy of existing answer on the app
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    CopyAEdit = "copyAEdit",
+    /**
+     * Emitted when a user clicks Show underlying data on an answe
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    ShowUnderlyingData = "showUnderlyingData",
+    /**
+     * Emitted when an answer is switched to a chart or table view
+     * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl
+     */
+    AnswerChartSwitcher = "answerChartSwitcher"
 }
 /**
  * Event types that can be triggered by the host application
@@ -404,7 +525,14 @@ export declare enum HostEvent {
      * @param - {@link RuntimeFilter}[] an array of {@link RuntimeFilter} Types.
      * @version SDK: 1.9.0 | ThoughtSpot: 8.1.0.cl
      */
-    UpdateRuntimeFilters = "UpdateRuntimeFilters"
+    UpdateRuntimeFilters = "UpdateRuntimeFilters",
+    /**
+     * Navigate to a specific page in App embed without any reload.
+     * This is the same as calling `appEmbed.navigateToPage(path, true)`
+     * @param path - the path to navigate to (can be a number[1/-1] to go forward/back)
+     * @version SDK: 1.12.0 | ThoughtSpot: 8.4.0.cl
+     */
+    Navigate = "Navigate"
 }
 /**
  * The different visual modes that the data sources panel within
@@ -455,7 +583,10 @@ export declare enum Param {
     VisibleActions = "visibleAction",
     CustomCSSUrl = "customCssUrl",
     DisableLoginRedirect = "disableLoginRedirect",
-    visibleVizs = "pinboardVisibleVizs"
+    visibleVizs = "pinboardVisibleVizs",
+    LiveboardV2Enabled = "isPinboardV2Enabled",
+    ShowAlerts = "showAlerts",
+    Locale = "locale"
 }
 /**
  * The list of actions that can be performed on visual ThoughtSpot
@@ -463,30 +594,57 @@ export declare enum Param {
  */
 export declare enum Action {
     Save = "save",
+    /**
+     * @hidden
+     */
     Update = "update",
+    /**
+     * @hidden
+     */
     SaveUntitled = "saveUntitled",
     SaveAsView = "saveAsView",
     MakeACopy = "makeACopy",
     EditACopy = "editACopy",
     CopyLink = "embedDocument",
+    /**
+     * @hidden
+     */
     ResetLayout = "resetLayout",
     Schedule = "subscription",
     SchedulesList = "schedule-list",
     Share = "share",
     AddFilter = "addFilter",
     ConfigureFilter = "configureFilter",
+    /**
+     * @hidden
+     */
     AddFormula = "addFormula",
+    /**
+     * @hidden
+     */
     SearchOnTop = "searchOnTop",
     SpotIQAnalyze = "spotIQAnalyze",
+    /**
+     * @hidden
+     */
     ExplainInsight = "explainInsight",
+    /**
+     * @hidden
+     */
     SpotIQFollow = "spotIQFollow",
     ShareViz = "shareViz",
+    /**
+     * @hidden
+     */
     ReplaySearch = "replaySearch",
     ShowUnderlyingData = "showUnderlyingData",
     Download = "download",
     DownloadAsPdf = "downloadAsPdf",
     DownloadAsCsv = "downloadAsCSV",
     DownloadAsXlsx = "downloadAsXLSX",
+    /**
+     * @hidden
+     */
     DownloadTrace = "downloadTrace",
     ExportTML = "exportTSL",
     ImportTML = "importTSL",
@@ -497,18 +655,39 @@ export declare enum Action {
     Edit = "edit",
     EditTitle = "editTitle",
     Remove = "delete",
+    /**
+     * @hidden
+     */
     Ungroup = "ungroup",
+    /**
+     * @hidden
+     */
     Describe = "describe",
+    /**
+     * @hidden
+     */
     Relate = "relate",
+    /**
+     * @hidden
+     */
     CustomizeHeadlines = "customizeHeadlines",
     /**
      * @hidden
      */
     PinboardInfo = "pinboardInfo",
     LiveboardInfo = "pinboardInfo",
+    /**
+     * @hidden
+     */
     SendAnswerFeedback = "sendFeedback",
+    /**
+     * @hidden
+     */
     DownloadEmbraceQueries = "downloadEmbraceQueries",
     Pin = "pin",
+    /**
+     * @hidden
+     */
     AnalysisInfo = "analysisInfo",
     Subscription = "subscription",
     Explore = "explore",
@@ -516,16 +695,18 @@ export declare enum Action {
     DrillExclude = "context-menu-item-exclude",
     CopyToClipboard = "context-menu-item-copy-to-clipboard",
     CopyAndEdit = "context-menu-item-copy-and-edit",
+    /**
+     * @hidden
+     */
     DrillEdit = "context-menu-item-edit",
     EditMeasure = "context-menu-item-edit-measure",
     Separator = "context-menu-item-separator",
+    /**
+     * @hidden
+     */
     DrillDown = "DRILL",
     RequestAccess = "requestAccess",
     QueryDetailsButtons = "queryDetailsButtons",
-    /**
-     * @version SDK: 1.9.0 | ThoughtSpot: 8.1.0.cl
-     */
-    Monitor = "createMonitor",
     /**
      * @version SDK: 1.9.0 | ThoughtSpot: 8.1.0.cl
      */

package/dist/src/utils.d.ts

@@ -34,3 +34,10 @@ export declare const getCssDimension: (value: number | string) => string;
 export declare const appendToUrlHash: (url: string, stringToAppend: string) => string;
 export declare const getEncodedQueryParamsString: (queryString: string) => string;
 export declare const getOffsetTop: (element: any) => any;
+export declare const embedEventStatus: {
+    START: string;
+    END: string;
+};
+export declare const setAttributes: (element: HTMLElement, attributes: {
+    [key: string]: string | number | boolean;
+}) => void;