@thoughtspot/ts-chart-sdk 0.0.2-alpha.9 → 1.1.0

package/README.md

@@ -6,58 +6,75 @@
 
 # ThoughtSpot Charts SDK <br/>
 
-ThoughtSpot Charts SDK allows developers to integrate custom charts into ThoughtSpot. Developers can create custom charts in Javascript using charting libraries such as HighCharts and upload them to ThoughtSpot.   
+ThoughtSpot Charts SDK allows developers to integrate custom charts into ThoughtSpot. Developers can create custom charts in Javascript using charting libraries such as HighCharts and upload them to ThoughtSpot.
 
+## Doc for custom chart examples
+
+-   [Custom Map charts](./example/custom-bar-chart/README.md)
+-   [Custom Bar Charts](./example/custom-bar-chart/README.md)
+
+## ⚠️ Important Information ⚠️
+
+### 🚀 Use `ts-chart-sdk` with TypeScript to enable static type checking.
+
+### 📊 See [Custom Bar Chart](./example/custom-bar-chart/) example for the latest update.
+
+---
 
 # Get started
-This tutorial demonstrates how to create a Gantt chart using HighCharts. 
+
+This tutorial demonstrates how to create a Gantt chart using HighCharts.
 <insert links and fiddle links above>
-* [Highchart demo link](https://www.highcharts.com/demo/gantt/progress-indicator)
-* [JSFiddle link](https://jsfiddle.net/gh/get/library/pure/highcharts/highcharts/tree/master/samples/gantt/demo/progress-indicator)
+
+-   [Highchart demo link](https://www.highcharts.com/demo/gantt/progress-indicator)
+-   [JSFiddle link](https://jsfiddle.net/gh/get/library/pure/highcharts/highcharts/tree/master/samples/gantt/demo/progress-indicator)
 
 ## Prerequisites
+
 Before you begin, check for the following requirements:
 
-* Access to a ThoughtSpot Cloud application instance
-* A Development Environment (IDE) for building custom charts
-* Working knowledge of JavaScript or Typescript
-* Familiarity with charting libraries such as Highcharts
-* Knowledge of the chart type
+-   Access to a ThoughtSpot Cloud application instance
+-   A Development Environment (IDE) for building custom charts
+-   Working knowledge of JavaScript or Typescript
+-   Familiarity with charting libraries such as Highcharts
+-   Knowledge of the chart type
 
 ## Set up your environment
+
 To create and test the application, this tutorial uses a Vite project setup.
 
 ### Create a new Vite project
 
 1. Open a terminal window and run the following commands:
 
-     ```bash
-     md gantt
-     cd gantt
-     ```
+    ```bash
+    md gantt
+    cd gantt
+    ```
 
 2. Create a Vite project.
-     ```bash
-     $ npm create vite@latest
-     ```
+    ```bash
+    $ npm create vite@latest
+    ```
 3. Configure the project name and development framework for your chart application. In this tutorial, we will use the Vanilla framework with TypeScript.
 
-     ```bash
-     ✔ Project name: … gantt demo
-     ✔ Package name: … gantt-demo
-     ✔ Select a framework: › Vanilla
-     ✔ Select a variant: › TypeScript
-     ```
+    ```bash
+    ✔ Project name: … gantt demo
+    ✔ Package name: … gantt-demo
+    ✔ Select a framework: › Vanilla
+    ✔ Select a variant: › TypeScript
+    ```
+
 4. Initialize your application.
 
-     ```bash
-     npm install
-     npm run dev
-     ```
+    ```bash
+    npm install
+    npm run dev
+    ```
 
 5. Go to the localhost link and check if the following page shows up.
 
-     ![initial-setup](assets/images/initial-setup.png)
+    ![initial-setup](assets/images/initial-setup.png)
 
 ### Install Highcharts and lodash
 
@@ -75,7 +92,7 @@ npm install --save @thoughtspot/ts-chart-sdk
 
 Render a chart in the application created from the preceding steps.
 
-This tutorial uses the  [chart from the Highcharts library](https://www.highcharts.com/demo/gantt/progress-indicator) to create a custom Gantt chart. 
+This tutorial uses the [chart from the Highcharts library](https://www.highcharts.com/demo/gantt/progress-indicator) to create a custom Gantt chart.
 
 ### Implement the chart code
 
@@ -83,7 +100,7 @@ This tutorial uses the implementation code of the Gantt chart from the [Highchar
 
 To implement the chart code in your application, complete these steps:
 
-1. To copy the implementation code from the Highcharts library, select a chart type and click **Copy JS Code**. 
+1. To copy the implementation code from the Highcharts library, select a chart type and click **Copy JS Code**.
 2. Paste this code into the `main.ts` file in your `src` folder.
 3. Import the dependencies for Highcharts and Highcharts Gantt module into your application code as shown in this example:
 
@@ -91,6 +108,7 @@ To implement the chart code in your application, complete these steps:
     import Highcharts from 'highcharts/es-modules/masters/highcharts.src';
     import 'highcharts/es-modules/masters/modules/gantt.src';
     ```
+
     Note the order of import.
 
 4. Replace the content of `index.html` with the following snippet:
@@ -111,8 +129,9 @@ To implement the chart code in your application, complete these steps:
       </body>
     </html>
     ```
+
 5. Refresh the application URL and check if the chart imported into your application code is rendered:
-    ![demo-chart-render](assets/images/demo-chart-render.png)
+   ![demo-chart-render](assets/images/demo-chart-render.png)
 6. Delete the unwanted files from your project folder
    The folder structure in your project at this point includes many files as shown in this figure.
 
@@ -120,11 +139,11 @@ To implement the chart code in your application, complete these steps:
 
     You can remove the following files.
 
-    * `/public/vite.svg`
-    * `/src/counter.ts`
-    * `/src/typescript.svg`
+    - `/public/vite.svg`
+    - `/src/counter.ts`
+    - `/src/typescript.svg`
 
-## Integrate ThoughtSpot Chart SDK 
+## Integrate ThoughtSpot Chart SDK
 
 The chart imported into your application has static data. To add ThoughtSpot capabilities such as drill, you need to fetch data from your ThoughtSpot application. To add ThoughtSpot capabilities and data to the chart code in your application, integrate ThoughtSpot Chart SDK and complete these steps:
 
@@ -207,16 +226,18 @@ const init = async () => {
 
 init();
 ```
-> NOTE: 
->For more information about the chart context component, refer to the following documentation resources:
-  >  * [https://ts-chart-sdk-docs.vercel.app/types/CustomChartContextProps.html](https://ts-chart-sdk-docs.vercel.app/types/CustomChartContextProps.html)
-  > * [https://github.com/thoughtspot/ts-chart-sdk/blob/main/src/main/custom-chart-context.ts#L40](https://github.com/thoughtspot/ts-chart-sdk/blob/main/src/main/custom-chart-context.ts#L40)
+
+> NOTE:
+> For more information about the chart context component, refer to the following documentation resources:
+>
+> -   [https://ts-chart-sdk-docs.vercel.app/types/CustomChartContextProps.html](https://ts-chart-sdk-docs.vercel.app/types/CustomChartContextProps.html)
+> -   [https://github.com/thoughtspot/ts-chart-sdk/blob/main/src/main/custom-chart-context.ts#L40](https://github.com/thoughtspot/ts-chart-sdk/blob/main/src/main/custom-chart-context.ts#L40)
 
 The custom chart context component must include the following mandatory properties to function:
 
-* [`getDefaultChartConfig (Doc)`](#getDefaultChartConfig-(Doc))
-* [`getQueriesFromChartConfig (Doc)`](#getQueriesFromChartConfig-(Doc))
-* [`renderChart (Doc)`](#getQueriesFromChartConfig-(Doc))
+-   [`getDefaultChartConfig (Doc)`](<#getDefaultChartConfig-(Doc)>)
+-   [`getQueriesFromChartConfig (Doc)`](<#getQueriesFromChartConfig-(Doc)>)
+-   [`renderChart (Doc)`](<#getQueriesFromChartConfig-(Doc)>)
 
 #### getDefaultChartConfig (Doc)
 
@@ -235,6 +256,7 @@ The point for the Gantt chart used in this tutorial looks like this:
     },
 }
 ```
+
 The above data can be represented as a table in CSV format as shown here:
 
 ```bash
@@ -332,9 +354,9 @@ getQueriesFromChartConfig: (
 This `renderChart (Doc)` function is required to render the chart implemented in your code. This function ensures that every time `chartContext` tries to re-render the chart due to the changes in data or chart model, the chart rendered in your application is updated.
 
 > **Note**:
-You can control render and re-render by implementing more granular control for the updates on data, visual props, or chart model.
+> You can control render and re-render by implementing more granular control for the updates on data, visual props, or chart model.
 >
-But we haven't yet implemented this. So let's proceed and implement this.
+> But we haven't yet implemented this. So let's proceed and implement this.
 
 #### Implement the renderChart function
 
@@ -352,13 +374,14 @@ const renderChart = (ctx) => {
 };
 ```
 
-2. Implement the `renderChart` function in `getChartContext` as shown in this example:  
+2. Implement the `renderChart` function in `getChartContext` as shown in this example:
 
 ```jsx
 ...
  renderChart: (context) => renderChart(context),
 ...
 ```
+
 At this point, you will notice that the chart is gone on the link.
 
 3. Wait for the chart to connect to the TS application.
@@ -369,6 +392,7 @@ At this point, you will notice that the chart is gone on the link.
 [vite] connected.
 Chart Context: initialization start
 ```
+
 5. Run your application and test the chart implementation in the Playground.
 
 #### Run the chart in the Playground
@@ -385,8 +409,8 @@ To run the chart and test your implementation, you need a Playground.
 
 2. Add the following details as shown in the following example:
 
-* App Url : `<your localhost url with port>`
-* Chart Model: `Gantt - 3 Attribute - 2 Date - 1 Measure`
+-   App Url : `<your localhost url with port>`
+-   Chart Model: `Gantt - 3 Attribute - 2 Date - 1 Measure`
 
 ![Playground](assets/images/playground.png)
 
@@ -408,7 +432,8 @@ For the Gantt chart, this tutorial uses the following format for data points:
     },
 }
 ```
-However, the data retrieved from the chart model includes an array of column types as shown in this example:  
+
+However, the data retrieved from the chart model includes an array of column types as shown in this example:
 
 ```jsx
 // inside chart model
@@ -563,12 +588,13 @@ const getDataModel = (chartModel: any) => {
 
 Use the data model created from the above function and plug the values into the Highchart configuration to render the chart.
 
-1. Create a data model object.   
+1. Create a data model object.  
    In your `renderChart` code, add the following line:
 
     ```jsx
     const dataModel = getDataModel(chartModel);
     ```
+
 2. Replace X Axis min and max values.
 
 ```jsx
@@ -577,13 +603,14 @@ xAxis: {
     max: dataModel.maxDate,
 },
 ```
+
 3. Replace the series.
 
 ```jsx
 series: dataModel.dataSeries,
 ```
 
-The chart implemented in your code now shows up on the playground with the data values you just plugged in. 
+The chart implemented in your code now shows up on the playground with the data values you just plugged in.
 
 The following example shows the entire chart code for the Gantt chart implementation described in this tutorial:
 
@@ -769,14 +796,63 @@ To deploy your charts, you can use Vercel, Netlify, or any server that can rende
 To deploy the chart on a test domain in Vercel, install <a href="https://vercel.com/docs/cli" target="_blank">Vercel CLI</a> and run the following command:
 
 ```jsx
-vercel
+vercel;
 ```
+
 For more information about Vercel deployment, see <a href="https://vercel.com/docs/getting-started-with-vercel" target="_blank">Vercel documentation</a>.
 
 ### Content Security Policy Overrides
 
 To allow the use of Vercel application content in Thoughtspot, add the Vercel domain URL to the CSP allow-list. For more information, see the <a href="https://developers.thoughtspot.com/docs/?pageid=security-settings" target="_blank">Security settings section in ThoughtSpot documentation</a>.
 
+## Useful URLs
+
+### API references
+
+-   Check out [ts-charts-sdk docs](https://ts-chart-sdk-docs.vercel.app/) to get API reference.
+
+### Test framework
+
+-   Open [Playground](https://ts-chart-playground.vercel.app/) to play with ts-chart-sdk with mock chartModel.
+
+### Code Walkthrough
+
+-   Play [demo](https://drive.google.com/drive/u/0/folders/1DbfiT1VP7j4SqhiCtM2JksTeIjbkI8h3) to get a viedo demo of code walkthrough and custom gantt-chart implementation.
+
+## FAQ
+
+#### How to save some chart specific state after client have made some changes in charts?
+
+You can use `ChartToTSEvent.UpdateVisualProps` eventType inside `ctx.emitEvent()`. Since the payload type for this event is `unkown` you can just add a key value pair naming `clientState`.
+
+**Sample** -
+
+```js
+ctx.emitEvent(ChartTOTSEvent.UpdateVisualProps,{
+    visualProps:{
+        clientState:"<req_state_in_string_format>"
+        ...rest_of_visualProp
+    }
+})
+```
+
+-   NOTE: client State currently support only string data type. To use it with json object you can use `JSON.stringify(somelocalstate)`
+
+#### Why my chart is getting re render in an infinte loop?
+
+Probably you are implementing `update client state` logic inside the the `render` function of `getChartContext`. Since it `render` will be calling `update client state` logic and this logic might again cause `render` this will cause a cyclic call of `render`. Hence,it is advised not to implement it inside `render` function.
+
+> NOTE:
+> This can be called inside render function just that to avoid having an infinite loop clientState updates should be handled by chart developer properly.
+
+#### How to add dynamic config for visualPorpEditorDefintion?
+
+Since in our previous implementation of `visualPropEditorDefintion` we provided this as an static object of type `VisualPropEditorDefinition` but with the resent update this is converted function of type `VisualEditorDefinitonSetter` along with `VisualEditorDefintion`. So currently you can provide static config or dynamic config based on use case.
+
+#### Only 1000 points are getting fetched for my query even though there are more results. How to increase that?
+
+In `getQueriesFromChartConfig` along with `QueryColumn` you can provide additional optional key `queryParams`. In `queryParams` you can provide `size` to deal with the number of data points that need to fetched. Also there is hard limit of 100K data points to be fetched from the backend.
+
 <br/>
 
 ThoughtSpot Chart SDK, © ThoughtSpot, Inc. 2023