@thoughtspot/ts-chart-sdk 0.0.1-alpha.0 → 0.0.1-alpha.10

package/src/react/use-custom-chart-context.util.ts

@@ -0,0 +1,101 @@
+import _ from 'lodash';
+import { CustomChartContext } from '../main/custom-chart-context';
+import {
+    ChartToTSEvent,
+    ChartToTSEventsPayloadMap,
+} from '../types/chart-to-ts-event.types';
+import {
+    TSToChartEvent,
+    TSToChartEventsPayloadMap,
+} from '../types/ts-to-chart-event.types';
+import {
+    ChartToTSEventEmitters,
+    TSToChartEventListener,
+    TSToChartEventOffListener,
+} from './use-custom-chart-types';
+
+/**
+ *
+ * @param ctx Custom Chart Context
+ * @returns List of event emitters
+ */
+export const emitter = (ctx: CustomChartContext): ChartToTSEventEmitters => {
+    const validEvents = Object.keys(
+        ChartToTSEvent,
+    ) as (keyof ChartToTSEventsPayloadMap)[];
+    return validEvents.reduce((acc, eventKey) => {
+        const eventName = eventKey as keyof ChartToTSEventsPayloadMap;
+        const emitterKey = `emit${eventKey}` as keyof ChartToTSEventEmitters;
+
+        acc[emitterKey] = (
+            ...args: ChartToTSEventsPayloadMap[keyof ChartToTSEventsPayloadMap]
+        ): Promise<void> => {
+            if (!ctx || _.isEmpty(ctx)) {
+                console.log('Context is not initialized');
+                return Promise.reject(new Error('Context not initialized'));
+            }
+            return ctx.emitEvent(eventName, ...args);
+        };
+
+        return acc;
+    }, {} as ChartToTSEventEmitters);
+};
+
+/**
+ *
+ * @param ctx Custom Chart Context
+ * @returns List of event listeners
+ */
+export const eventListener = (
+    ctx: CustomChartContext,
+): TSToChartEventListener => {
+    const validEvents = Object.keys(
+        TSToChartEvent,
+    ) as (keyof TSToChartEventsPayloadMap)[];
+    return validEvents.reduce((acc, eventKey) => {
+        const eventName = eventKey as keyof TSToChartEventsPayloadMap;
+        const emitterKey = `setOn${eventKey}` as keyof TSToChartEventListener;
+
+        acc[emitterKey] = (
+            callbackFn: TSToChartEventsPayloadMap[keyof TSToChartEventsPayloadMap],
+        ): Promise<void> => {
+            if (!ctx || _.isEmpty(ctx)) {
+                console.log('Context is not initialized');
+                return Promise.reject(new Error('Context not initialized'));
+            }
+            ctx.on(eventName, callbackFn);
+            return Promise.resolve();
+        };
+
+        return acc;
+    }, {} as TSToChartEventListener);
+};
+
+/**
+ *
+ * @param ctx Custom Chart Context
+ * @returns List of event listeners
+ */
+export const eventOffListener = (
+    ctx: CustomChartContext,
+): TSToChartEventOffListener => {
+    const validEvents = Object.keys(
+        TSToChartEvent,
+    ) as (keyof TSToChartEventsPayloadMap)[];
+    return validEvents.reduce((acc, eventKey) => {
+        const eventName = eventKey as keyof TSToChartEventsPayloadMap;
+        const emitterKey =
+            `setOff${eventKey}` as keyof TSToChartEventOffListener;
+
+        acc[emitterKey] = (): Promise<void> => {
+            if (!ctx || _.isEmpty(ctx)) {
+                console.log('Context is not initialized');
+                return Promise.reject(new Error('Context not initialized'));
+            }
+            ctx.off(eventName);
+            return Promise.resolve();
+        };
+
+        return acc;
+    }, {} as TSToChartEventOffListener);
+};

package/src/react/use-custom-chart-types.ts

@@ -0,0 +1,70 @@
+import React from 'react';
+import { ChartToTSEventsPayloadMap } from '../types/chart-to-ts-event.types';
+import { ChartModel } from '../types/common.types';
+import { TSToChartEventsPayloadMap } from '../types/ts-to-chart-event.types';
+
+/**
+ * For all events that we trigger from React Chart to TS Host,
+ * this enum provides the trigger functions for each event.
+ * All the trigger functions have a prefix of emit.
+ */
+export type ChartToTSEventEmitters = {
+    [key in keyof ChartToTSEventsPayloadMap as `emit${Capitalize<key>}`]: (
+        ...args: ChartToTSEventsPayloadMap[key]
+    ) => Promise<void>;
+};
+
+/**
+ * For all events that we trigger from TS Host to React Chart,
+ * this enum provides the event listener on functions for each external event listener.
+ * All the event listener functions have a prefix of on.
+ */
+export type TSToChartEventListener = {
+    [key in keyof TSToChartEventsPayloadMap as `setOn${Capitalize<key>}`]: (
+        args: TSToChartEventsPayloadMap[key],
+    ) => Promise<void>;
+};
+
+/**
+ * For all events that we trigger from TS Host to React Chart,
+ * this enum provides the event listener on functions for each external event listener.
+ * All the event listener functions have a prefix of on.
+ */
+export type TSToChartEventOffListener = {
+    [key in keyof TSToChartEventsPayloadMap as `setOff${Capitalize<key>}`]: () => Promise<void>;
+};
+
+export interface TSChartContextProps {
+    /**
+     * Child App which renders chart
+     * wrapper is used to control rendering of child app
+     */
+    children: React.ReactNode;
+}
+
+export interface ChartContextProps
+    extends ChartToTSEventEmitters,
+        TSToChartEventListener,
+        TSToChartEventOffListener {
+    /**
+     * decides if the chart context is initialzed
+     */
+    hasInitialized: boolean;
+    /**
+     * chart model to be used by client having
+     * config, data and visual props
+     */
+    chartModel: ChartModel | undefined;
+    /**
+     * For destroying current chart context
+     * @returns void
+     */
+    destroy: () => void;
+    /**
+     * Parent component wrapped around chart app
+     * for controlling re-rendering of chart
+     * @param children
+     * @returns React.JSX.Element
+     */
+    TSChartContext: ({ children }: TSChartContextProps) => React.JSX.Element;
+}

package/src/types/answer-column.types.ts

@@ -72,14 +72,14 @@ export enum CurrencyFormatType {
 }
 
 /**
- * Currency Format for the columm defined in the worksheet
+ * Currency format for the column defined in the worksheet
  *
  * @version SDK: 0.1 | ThoughtSpot:
  */
 export interface CurrencyFormat {
     type: CurrencyFormatType;
     /**
-     * column id of the column in case of currency formatted by a column
+     * column ID of the column in case of currency formatted by a column
      *
      * @version SDK: 0.1 | ThoughtSpot:
      */
@@ -118,13 +118,13 @@ export interface ColumnFormat {
 
 export interface ChartColumn {
     /**
-     * Column Id
+     * Column ID
      *
      * @version SDK: 0.1 | ThoughtSpot:
      */
     id: string;
     /**
-     * Column Name
+     * Column name
      *
      * @version SDK: 0.1 | ThoughtSpot:
      */
@@ -137,7 +137,7 @@ export interface ChartColumn {
     type: ColumnType;
 
     /**
-     * Type of the time based aggregation
+     * Type of the time-based aggregation
      * when the column data is of type Date, Datetime, Time
      *
      * @version SDK: 0.1 | ThoughtSpot:

package/src/types/chart-to-ts-event.types.ts

@@ -1,4 +1,9 @@
 import { VisualProps } from './common.types';
+import {
+    CustomAxisMenuAction,
+    CustomContextMenuAction,
+    Query,
+} from './ts-to-chart-event.types';
 
 /**
  *
@@ -25,13 +30,30 @@ export enum ChartToTSEvent {
     RenderComplete = 'RenderComplete',
 
     /**
-     * Visual Props Update
+     * Visual props update
      */
     UpdateVisualProps = 'UpdateVisualProps',
+
+    /**
+     * TML events
+     */
+    GetTMLString = 'GetTMLString',
+    SetTMLString = 'SetTMLString',
+
+    /**
+     * Fetch data for custom query
+     */
+    GetDataForQuery = 'GetDataForQuery',
+
+    /**
+     * Tooltip events
+     */
+    ShowToolTip = 'ShowToolTip',
+    HideToolTip = 'HideToolTip',
 }
 
 /**
- * This map defines the event type and its corresponding payload needed by event
+ * This map defines the event type and its corresponding payload needed by the event
  *
  * @version SDK: 0.1 | ThoughtSpot:
  * @group Chart to ThoughtSpot Events
@@ -42,55 +64,108 @@ export interface ChartToTSEventsPayloadMap {
      *
      * @version SDK: 0.1 | ThoughtSpot:
      */
-    [ChartToTSEvent.OpenContextMenu]: OpenContextMenuEventPayload;
+    [ChartToTSEvent.OpenContextMenu]: [OpenContextMenuEventPayload];
     /**
      * Trigger to close Context Menu
      *
      * @version SDK: 0.1 | ThoughtSpot:
      */
-    [ChartToTSEvent.CloseContextMenu]: null;
+    [ChartToTSEvent.CloseContextMenu]: [];
 
     /**
      * Trigger to notify the render start
      *
      * @version SDK: 0.1 | ThoughtSpot:
      */
-    [ChartToTSEvent.RenderStart]: null;
+    [ChartToTSEvent.RenderStart]: [];
     /**
      * Trigger to notify the render completion
      *
      * @version SDK: 0.1 | ThoughtSpot:
      */
-    [ChartToTSEvent.RenderComplete]: null;
+    [ChartToTSEvent.RenderComplete]: [];
     /**
      * Trigger to notify the render error
      *
      * @version SDK: 0.1 | ThoughtSpot:
      */
-    [ChartToTSEvent.RenderError]: RenderErrorEventPayload;
+    [ChartToTSEvent.RenderError]: [RenderErrorEventPayload];
     /**
      * Trigger to update the visual props
      *
      * @version SDK: 0.1 | ThoughtSpot:
      */
-    [ChartToTSEvent.UpdateVisualProps]: UpdateVisualPropsEventPayload;
+    [ChartToTSEvent.UpdateVisualProps]: [UpdateVisualPropsEventPayload];
+
+    /**
+     * Trigger to get the TML string
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    [ChartToTSEvent.GetTMLString]: [];
+    /**
+     * Trigger to set the TML string
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    [ChartToTSEvent.SetTMLString]: [SetTMLStringEventPayload];
+    /**
+     * Trigger to get the data for custom query
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    [ChartToTSEvent.GetDataForQuery]: [GetDataForQueryEventPayload];
+    /**
+     * Trigger to update the visual props
+     *
+     * @version SDK: 0.0.1-alpha.4 | ThoughtSpot:
+     */
+    [ChartToTSEvent.ShowToolTip]: [ShowToolTipEventPayload];
+    /**
+     * Trigger to update the visual props
+     *
+     * @version SDK: 0.0.1-alpha.4 | ThoughtSpot:
+     */
+    [ChartToTSEvent.HideToolTip]: [];
+    /**
+     * Trigger to open Axis Menu
+     *
+     * @version SDK: 0.0.1-alpha.7 | ThoughtSpot:
+     */
+    [ChartToTSEvent.OpenAxisMenu]: [OpenAxisMenuEventPayload];
+    /**
+     *  Trigger to close Axis Menu
+     *
+     * @version SDK: 0.0.1-alpha.7 | ThoughtSpot:
+     */
+    [ChartToTSEvent.CloseAxisMenu]: [];
+}
+
+/**
+ *
+ * @group Chart to ThoughtSpot Events
+ */
+export interface UpdateVisualPropsEventPayload {
+    visualProps: VisualProps;
 }
 
 /**
  *
  * @group Chart to ThoughtSpot Events
  */
-type UpdateVisualPropsEventPayload = VisualProps;
+export interface SetTMLStringEventPayload {
+    // TML string to be set
+    tmlString: string;
+}
 
 /**
  * @group Chart to ThoughtSpot Events / Context Menu
  */
 // start - open context menu payload
 export interface PointVal {
-    // column id of the column associated with the value
+    // Column ID of the column associated with the value
     columnId: string;
-    // value of the point clicked on, mostly makes sense for attributes.
-    // this can be an array of values as well.
+    // Value of the point clicked on, mostly makes sense for attributes.
+    // This can be an array of values as well.
     value: any;
 }
 /**
@@ -106,16 +181,16 @@ export interface Point {
  * @group Chart to ThoughtSpot Events / Context Menu
  */
 export interface CustomAction {
-    id: string; // id of the action user defined
-    label: string; // developer should i18n this
-    icon: string; // icon string to show on the context/axis menu
+    id: string; // ID of the user-defined action
+    label: string; // Developer should i18n this
+    icon?: string; // Icon string to show on the context/axis menu
 
     /**
-     * This function will need to have a defined set of args.
-     * For e.g., pointClick Event, point details and chart model in case on context menu
-     * For axis menu, it would be different.
+     * This function will need to have a defined set of arguments.
+     * For example, pointClick Event, point details and chart model in case of context menu
+     * For Axis menu, it would be different.
      *
-     * Callback will be triggered via postMessage api contract.
+     * Callback will be triggered via postMessage API contract.
      */
     onClick: (...args: any[]) => void;
 }
@@ -125,31 +200,51 @@ export interface CustomAction {
  * @group Chart to ThoughtSpot Events
  */
 export interface OpenContextMenuEventPayload {
-    event: Pick<
-        PointerEvent,
-        | 'x'
-        | 'y'
-        | 'clientX'
-        | 'clientY'
-        | 'pageX'
-        | 'pageY'
-        | 'screenX'
-        | 'screenY'
-    >;
+    event: Pick<PointerEvent, 'clientX' | 'clientY'>;
     clickedPoint: Point;
     selectedPoints?: Point[];
     customActions?: CustomAction[];
 }
 // end - open context menu payload
 
+/**
+ * Payload for the event triggered to show a tooltip
+ */
+export interface ShowToolTipEventPayload {
+    /**
+     * The pointer event that triggered the tooltip display
+     * It includes the client's X and Y coordinates.
+     */
+    event: Pick<PointerEvent, 'clientX' | 'clientY'>;
+    /**
+     * Optional custom content to display in the tooltip.
+     */
+    customTooltipContent?: string[];
+    /**
+     * Information about the data point associated
+     * with the tooltip
+     * User can also include both point and customTooltipContent
+     * depending upon the requirement
+     */
+    point?: Point;
+}
+// end - tooltip payload
+
 /**
  * @group Chart to ThoughtSpot Events
  */
-interface RenderErrorEventPayload {
+export interface RenderErrorEventPayload {
     hasError: boolean;
     error: any;
 }
 
+/**
+ * @group Chart to ThoughtSpot Events
+ */
+export interface GetDataForQueryEventPayload {
+    queries: Query[];
+}
+
 /**
  *
  * @group Chart to ThoughtSpot Events
@@ -157,3 +252,110 @@ interface RenderErrorEventPayload {
 export enum ErrorType {
     MultipleContextsNotSupported = 'MultipleContextsNotSupported',
 }
+
+/**
+ * List of supported actions for the menu items in the axis menu
+ * @group Chart to ThoughtSpot Events
+ */
+export enum AxisMenuActions {
+    /**
+     * Change the aggregation of the column from the possible options.
+     * Only supported for numeric columns.
+     */
+    AGGREGATE = 'AGGREGATE',
+    /**
+     * Change the bucketing of the date or date time column from the possible options.
+     * Only supported for date or date time columns.
+     * */
+    TIME_BUCKET = 'TIME_BUCKET',
+    /**
+     * Add or update the filter for the column.
+     * */
+    FILTER = 'FILTER',
+    /**
+     * Sort the column in ascending or descending order.
+     * */
+    SORT = 'SORT',
+
+    /**
+     * These 2 methods are disabled currently as they are not supported by the backend.
+     * Following are the reasons for the same:
+     * 1. Remove is ambiguous as it can mean remove from the answer scope or remove from the chart.
+     * 2. Rename columns is not supported by the menu for now. If need be, this can be implemented.
+     */
+    // /**
+    //  * Rename the column.
+    //  * */
+    // RENAME = 'RENAME',
+    // /**
+    //  * Remove the column from the answer scope.
+    //  * */
+    // REMOVE = 'REMOVE',
+    /**
+     * Defines a separator element between the actions.
+     * Can be added multiple times.
+     * */
+    SEPARATOR = 'SEPARATOR',
+}
+
+export interface AxisMenuCustomAction {
+    /**
+     * ID of the custom action.
+     * */
+    id: string;
+    /**
+     * Label of the custom action.
+     * */
+    label: string;
+    /**
+     * Icon of the custom action.
+     * */
+    icon?: string;
+    /**
+     * Callback function that will be triggered when the custom action is clicked.
+     * */
+    onClick: (...args: any[]) => void;
+}
+
+export interface OpenAxisMenuEventPayload {
+    /**
+     * The pointer event that triggered the event to position the axis menu.
+     */
+    event: Pick<PointerEvent, 'clientX' | 'clientY'>;
+    /**
+     * The column IDs of the columns that can be modified via the axis menu.
+     * This maps to the columns in chart model.
+     * The order of the column IDs is the same as the order of the columns in the axis menu.
+     * Atleast one column id is required.
+     * */
+    columnIds: string[];
+    /**
+     * The list of actions that are supported for the axis menu for each column.
+     * The order of the actions is the same as the order of the columns in the axis menu.
+     * If empty, all the supported actions in default order will be available.
+     * */
+    selectedActions?: AxisMenuActions[];
+    /**
+     * Custom action defined by the developer of the chart.
+     * This action will trigger the callback defined in the custom action payload.
+     * can be added multiple times.
+     * @hidden
+     * */
+    customActions?: AxisMenuCustomAction[];
+}
+
+/**
+ *
+ * @group Custom action callback mapping with action id/ Context Menu
+ */
+export interface ContextMenuActionHandler {
+    [key: string]: (args: CustomContextMenuAction) => void;
+}
+
+/**
+ *
+ * @group Custom action callback mapping with action id/ Axis Menu
+ */
+export interface AxisMenuActionHandler {
+    [key: string]: (args: CustomAxisMenuAction) => void;
+}