@thoughtspot/visual-embed-sdk 1.21.0-alpha.0 → 1.21.0-alpha.2

package/src/types.ts

@@ -44,16 +44,47 @@ export enum AuthType {
     SAML = 'SSO_SAML',
     /**
      * SSO using SAML
-     * Will make the host application redirect to the SAML Idp.
+     * Will make the host application redirect to the SAML Idp. Use this
+     * when the idp does not allow itself to be embedded.
+     *
+     * This redirects the host application to the SAML Idp. The host application
+     * will be redirected back to the ThoughtSpot app after authentication.
      *
      * @example
      * ```js
      * init({
      *   // ...
      *   authType: AuthType.SAMLRedirect,
+     *  });
+     * ```
+     *
+     * This opens the SAML Idp in a popup window. The popup is triggered
+     * when the user clicks the trigger button. The popup window will be
+     * closed automatically after authentication.
+     * @example
+     * ```js
+     * init({
+     *   // ...
+     *   authType: AuthType.SAMLRedirect,
      *   authTriggerText: 'Login with SAML',
      *   authTriggerContainer: '#embed-container',
-     *  });
+     *   inPopup: true,
+     * });
+     * ```
+     *
+     * Can also use event to trigger the popup flow. Works the same
+     * as above example.
+     * @example
+     * ```js
+     * const authEE = init({
+     *  // ...
+     *  authType: AuthType.SAMLRedirect,
+     *  inPopup: true,
+     * });
+     *
+     * someButtonOnYourPage.addEventListener('click', () => {
+     *  authEE.emit(AuthEvent.TRIGGER_SSO_POPUP);
+     * });
      * ```
      */
     SAMLRedirect = 'SSO_SAML',
@@ -67,6 +98,7 @@ export enum AuthType {
     /**
      * SSO using OIDC
      * Will make the host application redirect to the OIDC Idp.
+     * See code samples in {@link SAMLRedirect}.
      */
     OIDCRedirect = 'SSO_OIDC',
     /**
@@ -677,18 +709,17 @@ export enum EmbedEvent {
     Load = 'load',
     /**
      * Data pertaining to answer or Liveboard is received
-     *
-     * @returns data - The answer or Liveboard data
+     * @return data - The answer or Liveboard data
+     * @important
      */
     Data = 'data',
     /**
-     * Search/answer/Liveboard filters have been applied/updated
-     *
+     * Search/answer/Liveboard filters have been applied/updated by the user.
      * @hidden
      */
     FiltersChanged = 'filtersChanged',
     /**
-     * Search query has been updated
+     * Search query has been updated by the user.
      */
     QueryChanged = 'queryChanged',
     /**
@@ -720,17 +751,29 @@ export enum EmbedEvent {
      */
     CustomAction = 'customAction',
     /**
-     * A double click has been triggered on table/chart
-     *
-     * @returns ContextMenuInputPoints - data point that is double clicked
+     * Listen to double clicks on a visualization
+     * @return ContextMenuInputPoints - data point that is double clicked
      * @version SDK: 1.5.0 | ThoughtSpot: ts7.oct.cl, 7.2.1
      */
     VizPointDoubleClick = 'vizPointDoubleClick',
     /**
-     * A click has been triggered on table/chart
+     * Listen to clicks on a visualization in a liveboard or Search result.
      *
-     * @returns ContextMenuInputPoints - data point that is clicked
+     * @example
+     * ```js
+     * embed.on(ThoughtSpotEmbed.Event.VizPointClick, (data) => {
+     *   console.log(
+     *    data.vizId, // viz id
+     *    data.clickedPoint.selectedAttributes[0].value,
+     *    data.clickedPoint.selectedAttributes[0].column.name,
+     *    data.clickedPoint.selectedMeasures[0].value,
+     *    data.clickedPoint.selectedMeasures[0].column.name,
+     *   )
+     * });
+     * ```
+     * @return {vizId, clickedPoint} - metadata about point that is clicked
      * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl, 8.4.1-sw
+     * @important
      */
     VizPointClick = 'vizPointClick',
     /**
@@ -845,6 +888,12 @@ export enum EmbedEvent {
      * @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl, 8.4.1-sw
      */
     Download = 'download',
+    /**
+     * Emitted when the download action is triggered on an answer
+     *
+     * @version SDK: 1.21.0 | ThoughtSpot: 9.2.0.cl, 9.4.0-sw
+     */
+    DownloadAsPng = 'downloadAsPng',
     /**
      * Emitted when the Download as PDF action is triggered on an answer
      *
@@ -1028,8 +1077,7 @@ export enum EmbedEvent {
      */
     CrossFilterChanged = 'cross-filter-changed',
     /**
-     * Emitted when a user right clicks on chart or table
-     *
+     * Emitted when a user right clicks on a visualization (chart or table)
      * @version SDK: 1.21.0 | ThoughtSpot: 9.2.0.cl
      */
     VizPointRightClick = 'vizPointRightClick',
@@ -1120,10 +1168,11 @@ export enum HostEvent {
      * @param - {@link RuntimeFilter}[] an array of {@link RuntimeFilter} Types.
      * @example
      * liveboardEmbed.trigger(HostEvent.UpdateRuntimeFilters, [
-     * {columnName: "state",operator: RuntimeFilterOp.EQ,values: ["michigan"]},
-     * {columnName: "item type",operator: RuntimeFilterOp.EQ,values:
-     * ["Jackets"]} ])
+     *   {columnName: "state",operator: RuntimeFilterOp.EQ,values: ["michigan"]},
+     *   {columnName: "item type",operator: RuntimeFilterOp.EQ,values: ["Jackets"]}
+     * ])
      * @version SDK: 1.9.0 | ThoughtSpot: 8.1.0.cl, 8.4.1-sw
+     * @important
      */
     UpdateRuntimeFilters = 'UpdateRuntimeFilters',
     /**
@@ -1375,9 +1424,14 @@ export enum HostEvent {
      *
      * @example
      * ```js
-     * searchEmbed.trigger(HostEvent.GetTML)
+     * searchEmbed.trigger(HostEvent.GetTML).then((tml) => {
+     *   console.log(
+     *      tml.search_query // TML representation of the search query
+     *   );
+     * })
      * ```
-     * @version SDK: 1.18.0 | ThoughtSpot: 8.10.0.cl
+     * @version SDK: 1.18.0 | ThoughtSpot: 8.10.0.cl, 9.0.1-sw
+     * @important
      */
     GetTML = 'getTML',
     /**
@@ -1426,12 +1480,29 @@ export enum HostEvent {
      * '730496d6-6903-4601-937e-2c691821af3c'})
      * vizEmbed.trigger(HostEvent.Download)
      * searchEmbed.trigger(HostEvent.Download)
+     * @deprecated from SDK: 1.21.0 | ThoughtSpot: 9.2.0.cl, 9.4.1-sw, Please use DownloadAsPng
      * @version SDK: 1.19.0 | ThoughtSpot: 9.0.0.cl, 9.0.1-sw
      */
-    Download = 'download',
+    Download = 'downloadAsPng',
+    /**
+     * Triggers the Download action on visualization or search when Displaymode is Chart
+     *
+     * @example
+     * ```js
+     * liveboardEmbed.trigger(HostEvent.DownloadAsPng,
+     * {vizId:'730496d6-6903-4601-937e-2c691821af3c'})
+     * ```
+     * ```js
+     * vizEmbed.trigger(HostEvent.DownloadAsPng)
+     * ```
+     * ```js
+     * searchEmbed.trigger(HostEvent.DownloadAsPng)
+     * ```
+     * @version SDK: 1.21.0 | ThoughtSpot: 9.2.0.cl, 9.4.1-sw
+     */
+    DownloadAsPng = 'downloadAsPng',
     /**
-     * Triggers the downloadAsCSV action on visualization or search when Displaymode is
-     * Table
+     * Triggers the downloadAsCSV action on visualization or search
      *
      * @example
      * liveboardEmbed.trigger(HostEvent.DownloadAsCsv, {vizId:
@@ -1442,8 +1513,7 @@ export enum HostEvent {
      */
     DownloadAsCsv = 'downloadAsCSV',
     /**
-     * Triggers the downloadAsXLSX action on visualization or search when Displaymode is
-     * Table
+     * Triggers the downloadAsXLSX action on visualization or search
      *
      * @example
      * liveboardEmbed.trigger(HostEvent.DownloadAsXlsx, {vizId:
@@ -1637,6 +1707,7 @@ export enum Action {
     ReplaySearch = 'replaySearch',
     ShowUnderlyingData = 'showUnderlyingData',
     Download = 'download',
+    DownloadAsPng = 'downloadAsPng',
     DownloadAsPdf = 'downloadAsPdf',
     DownloadAsCsv = 'downloadAsCSV',
     DownloadAsXlsx = 'downloadAsXLSX',