@thoughtspot/visual-embed-sdk 1.10.0-alpha.0 → 1.10.0-alpha.3

package/CHANGELOG.md

@@ -1,6 +1,54 @@
 # Changelog
 
 Please find the comprehensive list of changes for ThoughtSpot releases and SDK [here](https://developers.thoughtspot.com/docs/?pageid=whats-new)
+This project follows Semantic Versioning.
+
+## Unreleased
+
+### 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)
+
+### New Features 
+- Ability to trigger events on React components
+  - Added new `useEmbedRef` hook, check README for usage.
+
+### Fixed
+
+- Typings for `on*` event handlers for React components
+
+
+## 1.9.1 (03-15-2022)
+
+### New Features
+
+- `visibleVizs` option in the `LiveboardEmbed`
+- `LiveboardRendered` new `EmbedEvent` emitted when a liveboard completes rendering.
+
+
+## 1.9.0
+
+- Release to support TS version 8.1.0.cl
+- Please check the full list of changes [here](https://developers.thoughtspot.com/docs/?pageid=whats-new)
+
 
 ## 1.8.1
 

package/README.md

@@ -1,11 +1,10 @@
-
 <p align="center">
     <img src="https://raw.githubusercontent.com/thoughtspot/visual-embed-sdk/main/static/doc-images/images/TS-Logo-black-no-bg.svg" width=100 align="center" alt="ThoughtSpot" />
 </p>
 
 <br/>
 
-# ThoughtSpot Visual Embed SDK  [![Coverage Status](https://coveralls.io/repos/github/ts-blink/embed-sdk/badge.svg?branch=main)](https://coveralls.io/github/ts-blink/embed-sdk?branch=main) ![npm (scoped with tag)](https://img.shields.io/npm/v/@thoughtspot/visual-embed-sdk) [![](https://data.jsdelivr.com/v1/package/npm/@thoughtspot/visual-embed-sdk/badge?style=rounded)](https://www.jsdelivr.com/package/npm/@thoughtspot/visual-embed-sdk)
+# ThoughtSpot Visual Embed SDK [![Coverage Status](https://coveralls.io/repos/github/ts-blink/embed-sdk/badge.svg?branch=main)](https://coveralls.io/github/ts-blink/embed-sdk?branch=main) ![npm (scoped with tag)](https://img.shields.io/npm/v/@thoughtspot/visual-embed-sdk) [![](https://data.jsdelivr.com/v1/package/npm/@thoughtspot/visual-embed-sdk/badge?style=rounded)](https://www.jsdelivr.com/package/npm/@thoughtspot/visual-embed-sdk)
 
 SDK to embed ThoughtSpot into your web apps.
 
@@ -28,11 +27,16 @@ The SDK is written in TypeScript and is also provided both as ES Module (ESM) an
 import * as TsEmbedSDK from '@thoughtspot/visual-embed-sdk';
 
 // NPM <script>
-<script src='https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.js'></script>
+<script src="https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.js"></script>;
 
 // ES6 from web
-import { LiveboardEmbed, AuthType, init } from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js';
+import {
+    LiveboardEmbed,
+    AuthType,
+    init,
+} from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js';
 ```
+
 <br/>
 
 ## Live Playground
@@ -43,8 +47,8 @@ Visit our [code playground](https://try-everywhere.thoughtspot.cloud/v2/#/everyw
 
 ## Full API Reference
 
-- Detailed [developer guide](https://try-everywhere.thoughtspot.cloud/v2/#/everywhere/documentation/en/?pageid=getting-started).
-- Please visit our [API reference docs](https://developers.thoughtspot.com/docs/typedoc/modules.html). 
+-   Detailed [developer guide](https://try-everywhere.thoughtspot.cloud/v2/#/everywhere/documentation/en/?pageid=getting-started).
+-   Please visit our [API reference docs](https://developers.thoughtspot.com/docs/typedoc/modules.html).
 
 <br/>
 
@@ -55,7 +59,7 @@ liveboards, visualizations or the even full app version.
 
 ### Embedded Search
 
-```js 
+```js
 // NPM
 import { SearchEmbed, AuthType, init } from '@thoughtspot/visual-embed-sdk';
 // or ES6
@@ -117,15 +121,13 @@ init({
     authType: AuthType.None,
 });
 
-const appEmbed = new AppEmbed(
-    document.getElementById('ts-embed'),
-    {
-        frameParams: {
-            width: '100%',
-            height: '100%',
-        },
-        pageId: Page.Data,
-    });
+const appEmbed = new AppEmbed(document.getElementById('ts-embed'), {
+    frameParams: {
+        width: '100%',
+        height: '100%',
+    },
+    pageId: Page.Data,
+});
 
 appEmbed.render();
 ```
@@ -136,6 +138,7 @@ All the above flavors of embedding are also provided as React components for you
 The constructor options are passed as props and the event listeners can be attached using `on<EventName>` convention.
 
 ### Search Component
+
 ```js
 import { init } from '@thoughtspot/visual-embed-sdk';
 import { SearchEmbed } from '@thoughtspot/visual-embed-sdk/react';
@@ -153,12 +156,39 @@ const MyComponent = ({ dataSources }) => {
     const onCustomAction = (actionEvent) => {
         // Do something with actionEvent.
     };
-    
-    return <SearchEmbed dataSources={dataSources} onCustomAction={onCustomAction} />
-}
+
+    return (
+        <SearchEmbed
+            dataSources={dataSources}
+            onCustomAction={onCustomAction}
+        />
+    );
+};
+```
+
+### Triggering events on React components
+
+```jsx
+import { HostEvent } from '@thoughtspot/visual-embed-sdk';
+import { LiveboardEmbed, useEmbedRef } from '@thoughtspot/visual-embed-sdk/react';
+
+const MyComponent = () => {
+    const embedRef = useEmbedRef();
+    const onLiveboardRendered = () => {
+        embedRef.current.trigger(HostEvent.SetVisibleVizs, ['viz1', 'viz2']);
+    };
+
+    return (
+        <LiveboardEmbed
+            ref={embedRef}
+            liveboardId="<liveboard-guid>"
+            onLiveboardRendered={onLiveboardRendered}
+        />
+    );
+};
 ```
 
-### 
+###
 
 <br/>
 <br/>

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.

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

@@ -12,7 +12,7 @@ export declare const getAuthPromise: () => Promise<void>;
  */
 export declare const prefetch: (url?: string) => void;
 /**
- * Initialize the ThoughtSpot embed settings globally and perform
+ * Initialize the ThoughtSpot embed SDK globally and perform
  * authentication if applicable.
  * @param embedConfig The configuration object containing ThoughtSpot host,
  * authentication mechanism and so on.

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

@@ -51,11 +51,26 @@ export interface LiveboardViewConfig extends ViewConfig {
      * Liveboard page will be read-only (no X buttons)
      */
     preventLiveboardFilterRemoval?: boolean;
+    /**
+     * Array of viz ids which should be visible when the liveboard
+     * first renders. This can be changed by triggering the "SetVisibleVizs"
+     * event.
+     * @version 1.9.1 or later
+     */
+    visibleVizs?: string[];
     /**
      * To support backward compatibilty
      * @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,91 @@
+/**
+ * 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;
+    /**
+     * An array of vizids which should be visible when this pinboard loads.
+     * The ids not in this array are hidden from the pinboard.
+     * _since: 1.6.0_
+     */
+    pinboardVisibleVizs?: string[];
+}
+/**
+ * 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/react/index.d.ts

@@ -1,16 +1,18 @@
-/// <reference types="react" />
+import React from 'react';
 import { SearchViewConfig } from '../embed/search';
 import { AppViewConfig } from '../embed/app';
 import { LiveboardViewConfig } from '../embed/liveboard';
+import { TsEmbed } from '../embed/ts-embed';
 import { EmbedProps } from './util';
 interface SearchProps extends EmbedProps, SearchViewConfig {
 }
-export declare const SearchEmbed: (props: SearchProps) => JSX.Element;
+export declare const SearchEmbed: React.ForwardRefExoticComponent<SearchProps & React.RefAttributes<TsEmbed>>;
 interface AppProps extends EmbedProps, AppViewConfig {
 }
-export declare const AppEmbed: (props: AppProps) => JSX.Element;
+export declare const AppEmbed: React.ForwardRefExoticComponent<AppProps & React.RefAttributes<TsEmbed>>;
 interface LiveboardProps extends EmbedProps, LiveboardViewConfig {
 }
-export declare const LiveboardEmbed: (props: LiveboardProps) => JSX.Element;
-export declare const PinboardEmbed: (props: LiveboardProps) => JSX.Element;
+export declare const LiveboardEmbed: React.ForwardRefExoticComponent<LiveboardProps & React.RefAttributes<TsEmbed>>;
+export declare const PinboardEmbed: React.ForwardRefExoticComponent<LiveboardProps & React.RefAttributes<TsEmbed>>;
+export declare const useEmbedRef: () => React.MutableRefObject<TsEmbed>;
 export {};

package/dist/src/react/util.d.ts

@@ -1,7 +1,7 @@
 import { EmbedEvent, MessageCallback } from '../types';
 import { ViewConfig } from '../embed/ts-embed';
 export declare type EmbedEventHandlers = {
-    [key in EmbedEvent as `on${Capitalize<key>}`]?: MessageCallback;
+    [key in keyof typeof EmbedEvent as `on${Capitalize<key>}`]?: MessageCallback;
 };
 export interface EmbedProps extends ViewConfig, EmbedEventHandlers {
     className?: string;