@thoughtspot/ts-chart-sdk 0.0.1-alpha.1 → 0.0.1-alpha.11

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/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,9 +30,26 @@ 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',
 }
 
 /**
@@ -74,13 +96,66 @@ export interface ChartToTSEventsPayloadMap {
      * @version SDK: 0.1 | ThoughtSpot:
      */
     [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
@@ -132,14 +207,44 @@ export interface OpenContextMenuEventPayload {
 }
 // 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
@@ -147,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;
+}

package/src/types/common.types.ts

@@ -160,12 +160,15 @@ export type VisualProps = JSON;
 type CustomStylingConfig = any;
 
 export interface AppConfig {
+    /**
+     * @hidden
+     */
     styleConfig?: CustomStylingConfig;
 
     appOptions?: {
         isMobile?: boolean;
         isPrintMode?: boolean; // export mode on/off
-
+        isLiveboardContext?: boolean; // if chart renders in liveboard context
         // runtime configurations
         isDebugMode?: boolean; // enables debug mode for logging
     };
@@ -177,8 +180,19 @@ export interface AppConfig {
         sessionTimezone: string;
     };
 
+    /**
+     * App url for the custom chart application where the chart app is hosted.
+     * This helps the chart developer to access app artifacts relative to this url.
+     * There can be different build systems that developers may have used and different ways
+     * to host the same. This helps in resolving the same.
+     */
+    appUrl?: string;
+
     // Idea: we might be able to map this to data and ask user to read data in a
     // certain way the transformations for point during context menu operations
     // need to be explored
+    /**
+     * @hidden
+     */
     customCalendarConfig?: any; // this is to initialize custom calendar service
 }

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

@@ -1,4 +1,5 @@
 import { ChartColumn } from './answer-column.types';
+import { Point } from './chart-to-ts-event.types';
 import {
     AppConfig,
     ChartConfig,
@@ -57,6 +58,16 @@ export enum TSToChartEvent {
      * @version SDK: 0.1 | ThoughtSpot:
      */
     VisualPropsUpdate = 'VisualPropsUpdate',
+    /**
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+
+    ContextMenuActionClick = 'ContextMenuActionClick',
+
+    /**
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    AxisMenuActionClick = 'AxisMenuActionClick',
 }
 
 /**
@@ -104,6 +115,14 @@ export interface TSToChartInternalEventsPayloadMap {
     ) => ValidationResponse;
 
     [TSToChartEvent.TriggerRenderChart]: () => void;
+
+    [TSToChartEvent.ContextMenuActionClick]: (
+        payload: ContextMenuCustomActionPayload,
+    ) => void;
+
+    [TSToChartEvent.AxisMenuActionClick]: (
+        payload: AxisMenuCustomActionPayload,
+    ) => void;
 }
 
 /**
@@ -261,3 +280,54 @@ export interface ChartConfigValidateEventPayload {
      */
     chartConfig: ChartConfig[];
 }
+
+/**
+ * Custom action dispatched by context menu of the chart
+ *
+ * @group ThoughtSpot to Chart Events
+ * @version SDK: 0.1 | ThoughtSpot:
+ */
+export interface CustomContextMenuAction {
+    id: string;
+    clickedPoint: Point;
+    selectedPoints?: Point[];
+    event: Pick<PointerEvent, 'clientX' | 'clientY'>;
+}
+
+/**
+ *
+ * @group ThoughtSpot to Chart Events
+ */
+export interface ContextMenuCustomActionPayload {
+    /**
+     * Dispatched custom action from context menu
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    customAction: CustomContextMenuAction;
+}
+
+/**
+ * Custom action dispatched by axis menu of the chart
+ *
+ * @group ThoughtSpot to Chart Events
+ * @version SDK: 0.1 | ThoughtSpot:
+ */
+export interface CustomAxisMenuAction {
+    id: string;
+    columnIds: string[];
+    event: Pick<PointerEvent, 'clientX' | 'clientY'>;
+}
+
+/**
+ *
+ * @group ThoughtSpot to Chart Events
+ */
+export interface AxisMenuCustomActionPayload {
+    /**
+     * Dispatched custom action from context menu
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    customAction: CustomAxisMenuAction;
+}