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

package/src/main/util.ts

@@ -9,3 +9,23 @@ export function timeout(promise: Promise<any>, ms: number, message?: string) {
         }),
     ]);
 }
+
+export function handleMissingValue(
+    paramKey: string,
+    paramValue?: string | null,
+): string {
+    if (paramKey === 'debug') {
+        return paramValue ?? 'false';
+    }
+
+    return paramValue ?? '';
+}
+
+export function getQueryParam(url: string, paramName: string): string {
+    const urlObj = new URL(url);
+    const paramValue = handleMissingValue(
+        paramName,
+        urlObj.searchParams.get(paramName),
+    );
+    return paramValue;
+}

package/src/react/use-custom-chart-context.spec.tsx

@@ -236,7 +236,6 @@ describe('useChartContext emit', () => {
         });
         const promise = result.current.emitRenderStart();
         await expect(promise).rejects.toThrow('Context not initialized');
-        expect(mockPostMessageToHost).not.toHaveBeenCalled();
     });
 });
 

package/src/react/use-custom-chart-context.tsx

@@ -12,6 +12,7 @@ import {
     CustomChartContext,
     CustomChartContextProps,
 } from '../main/custom-chart-context';
+import { create } from '../main/logger';
 import { ChartModel } from '../types/common.types';
 import {
     ChartModelUpdateEventPayload,
@@ -28,6 +29,8 @@ import {
     TSChartContextProps,
 } from './use-custom-chart-types';
 
+const logger = create('CustomChartContextHookSdk');
+
 /**
  * A custom hook to manage the Chart Context state and provide necessary
  * chart-related functionality.
@@ -143,7 +146,7 @@ export const useChartContext = (
                 return true;
             })
             .catch((e) => {
-                console.log('Error in context initialization', e);
+                logger.log('Error in context initialization', e);
             });
     };
 

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

@@ -1,5 +1,6 @@
 import _ from 'lodash';
 import { CustomChartContext } from '../main/custom-chart-context';
+import { create } from '../main/logger';
 import {
     ChartToTSEvent,
     ChartToTSEventsPayloadMap,
@@ -14,6 +15,8 @@ import {
     TSToChartEventOffListener,
 } from './use-custom-chart-types';
 
+const logger = create('CustomChartContextUtilSdk');
+
 /**
  *
  * @param ctx Custom Chart Context
@@ -31,7 +34,7 @@ export const emitter = (ctx: CustomChartContext): ChartToTSEventEmitters => {
             ...args: ChartToTSEventsPayloadMap[keyof ChartToTSEventsPayloadMap]
         ): Promise<void> => {
             if (!ctx || _.isEmpty(ctx)) {
-                console.log('Context is not initialized');
+                logger.log('Context is not initialized');
                 return Promise.reject(new Error('Context not initialized'));
             }
             return ctx.emitEvent(eventName, ...args);
@@ -60,7 +63,7 @@ export const eventListener = (
             callbackFn: TSToChartEventsPayloadMap[keyof TSToChartEventsPayloadMap],
         ): Promise<void> => {
             if (!ctx || _.isEmpty(ctx)) {
-                console.log('Context is not initialized');
+                logger.log('Context is not initialized');
                 return Promise.reject(new Error('Context not initialized'));
             }
             ctx.on(eventName, callbackFn);
@@ -89,7 +92,7 @@ export const eventOffListener = (
 
         acc[emitterKey] = (): Promise<void> => {
             if (!ctx || _.isEmpty(ctx)) {
-                console.log('Context is not initialized');
+                logger.log('Context is not initialized');
                 return Promise.reject(new Error('Context not initialized'));
             }
             ctx.off(eventName);

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

@@ -1,4 +1,6 @@
-import { ConditionalFormatting, Maybe } from './conditional-formatting.types';
+import type { Maybe } from './common.types';
+import { ConditionalFormatting } from './conditional-formatting.types';
+import { FormatConfig } from './number-formatting.types';
 
 export enum ColumnType {
     UNKNOWN,
@@ -80,9 +82,9 @@ export enum FormatType {
  * @version SDK: 0.1 | ThoughtSpot:
  */
 export enum CurrencyFormatType {
-    USER_LOCALE,
-    COLUMN,
-    ISO_CODE,
+    USER_LOCALE = 'USER_LOCALE',
+    COLUMN = 'COLUMN',
+    ISO_CODE = 'ISO_CODE',
 }
 
 /**
@@ -183,7 +185,7 @@ export interface ChartColumn {
      */
     id: string;
     /**
-     * Column name
+     * Column name property
      *
      * @version SDK: 0.1 | ThoughtSpot:
      */
@@ -234,10 +236,11 @@ export interface ChartColumn {
     /**
      * Column Properties of the columns
      *
-     * @version SDK: 0.1 | ThoughtSpot:
+     * @version SDK: 0.0.2-alpha.15 | ThoughtSpot:
      */
     columnProperties?: {
         conditionalFormatting?: Maybe<ConditionalFormatting>;
+        numberFormatting?: Maybe<FormatConfig>;
     };
 
     /**

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

@@ -25,6 +25,7 @@ export enum ChartToTSEvent {
     /**
      * Render life cycle events
      */
+    InitStart = 'InitStart',
     RenderStart = 'RenderStart',
     RenderError = 'RenderError',
     RenderComplete = 'RenderComplete',
@@ -72,6 +73,12 @@ export interface ChartToTSEventsPayloadMap {
      */
     [ChartToTSEvent.CloseContextMenu]: [];
 
+    /**
+     * Trigger to notify the Initialization start
+     *
+     * @version SDK: 0.2 | ThoughtSpot:
+     */
+    [ChartToTSEvent.InitStart]: [];
     /**
      * Trigger to notify the render start
      *

package/src/types/common.types.ts

@@ -7,8 +7,8 @@
  */
 
 import { ChartColumn } from './answer-column.types';
-import { ChartConfigEditorDefinition } from './configurator.types';
-import { VisualPropEditorDefinition } from './visual-prop.types';
+import type { ChartConfigEditorDefinition } from './configurator.types';
+import type { VisualPropEditorDefinition } from './visual-prop.types';
 
 /**
  * Defines types of features for which font can be customised with Custom style config used in TS.
@@ -17,6 +17,24 @@ import { VisualPropEditorDefinition } from './visual-prop.types';
  * from customFontFaces
  */
 
+export type Maybe<T> = T | null;
+export type InputMaybe<T> = Maybe<T>;
+
+export type Scalars = {
+    ID: string;
+    String: string;
+    Boolean: boolean;
+    Int: number;
+    Float: number;
+    FileUpload: unknown;
+    GUID: string;
+    JSON: {
+        [key: string]: unknown;
+    };
+    JSONObject: unknown;
+    Long: unknown;
+};
+
 export enum CustomizableChartFeature {
     X_AXIS_LABEL,
     X_AXIS_TITLE,
@@ -170,10 +188,17 @@ export type SuccessValidationResponse = {
     visualPropEditorDefinition: VisualPropEditorDefinition;
 };
 
+export type VisualPropError = {
+    propElementKey: string;
+    propElementType: string;
+    value: unknown;
+};
+
 // Generic Validation Response
 export type ValidationResponse = {
     isValid: boolean;
     validationErrorMessage?: string[];
+    visualPropError?: VisualPropError;
 };
 
 /**
@@ -192,12 +217,14 @@ export type ValidationResponse = {
 export type VisualProps = unknown;
 
 /**
- * Custom Font Faces type from TS.
- *
+ *  Font Faces type from TS.
+ *  guid will be null in case of default Font types
+ *  If a custom Font is added in Dev section on TS this guid can be used to Match
+ *  the Font Face That needs to be applied to @link CustomizableChartFeature
  */
 
-export type CustomFontFaces = {
-    guid: string;
+export type TSFontFace = {
+    guid: string | null;
     family?: string;
     format?: string;
     url?: string;
@@ -224,14 +251,76 @@ export type ChartSdkCustomStylingConfig = {
         color?: string;
     };
     chartColorPalettes?: Array<{ colors: Array<string> }>;
+    numColorPalettes?: number;
     disableColorRotation?: boolean;
     chartFeatureToFontGuid?: Record<CustomizableChartFeature, string>;
-    customFontFaces?: Array<CustomFontFaces>;
+    fontFaces?: Array<TSFontFace>;
+};
+
+/**
+ * Defines a set of standardized date and datetime format strings used for
+ * displaying dates and times in various formats. Each format string represents
+ * a specific date or time pattern that can be used for localized display purposes.
+ */
+
+export interface DateFormats {
+    DATE_SHORT: string;
+    DATE_SHORT_2_DIGIT_YEAR: string;
+    DATE_SHORT_WITH_HOUR: string;
+    DATE_SHORT_WITH_HOUR_WITHOUT_YEAR: string;
+    DATE_SHORT_WITH_HOUR_24: string;
+    DATE_SHORT_WITH_HOUR_24_WITHOUT_YEAR: string;
+    DATETIME_SHORT: string;
+    DATETIME_SHORT_WITHOUT_YEAR: string;
+    DATETIME_24_SHORT: string;
+    DATETIME_24_SHORT_WITH_MILLIS: string;
+    DATETIME_24_SHORT_WITH_MILLIS_WITHOUT_YEAR: string;
+    DATETIME_SHORT_WITH_SECONDS: string;
+    DATETIME_SHORT_WITH_SECONDS_WITHOUT_YEAR: string;
+    DATETIME_SHORT_WITH_MILLIS: string;
+    DATETIME_SHORT_WITH_MILLIS_WITHOUT_YEAR: string;
+    QUARTER_WITH_YEAR: string;
+    QUARTER_WITH_2_DIGIT_YEAR: string;
+    DEFAULT_TIME_FORMAT: string;
+    MONTH_WITH_YEAR: string;
+    MONTH_WITH_DAY_AND_YEAR: string;
+    MONTH_WITH_2_DIGIT_YEAR: string;
+    DAY_WITH_MONTH: string;
+    DAY_WITH_MONTH_NUM: string;
+    QUARTER: string;
+    MONTH_ONLY: string;
+    DATETIME_WITH_SHORT_OFFSET: string;
+}
+
+/**
+ * Configuration object for date formats and settings in the Chart SDK.
+ * Provides locale-specific date and string formats, constants, and custom calendars.
+ *
+ * @type ChartSdkDateFormatsConfig
+ *
+ * @property tsLocaleBasedDateFormats - Optional. A record mapping locale identifiers to date format settings,
+ *   each represented by a `DateFormats` object.
+ * @property tsLocaleBasedStringsFormats - Optional. A record mapping locale identifiers to localized string
+ *   formats, where each format is represented by a string.
+ * @property tsDateConstants - Optional. A record mapping string keys to date-related constants, often used
+ *   for standard date patterns or other fixed date-related values(mostly used to identify the case
+ *   for backend proccessed date in case of MONTH_OF_YEAR,DAY_OF_WEEK).
+ * @property tsDefinedCustomCalenders - Optional. Custom calendar configurations, which have GUID of TS defined Custom calenders.
+ * @property defaultDataSourceId - Optional. The data source identifier for the date formats, used
+ *   to specify the primary data source for TS defined custom calenders.
+ */
+
+export type ChartSdkDateFormatsConfig = {
+    tsLocaleBasedDateFormats?: Record<string, DateFormats>;
+    tsLocaleBasedStringsFormats?: Record<string, string>;
+    tsDateConstants?: Record<string, string>;
+    tsDefinedCustomCalenders?: any;
+    defaultDataSourceId?: string;
 };
 
 export interface AppConfig {
     styleConfig?: ChartSdkCustomStylingConfig;
-
+    dateFormatsConfig?: ChartSdkDateFormatsConfig;
     appOptions?: {
         isMobile?: boolean;
         isPrintMode?: boolean; // export mode on/off
@@ -264,7 +353,8 @@ export interface AppConfig {
     customCalendarConfig?: any; // this is to initialize custom calendar service
 
     /**
-     * Unique identifier for the customer. This is used to identify the customer
+     * Unique identifier for the customer. This can be used as a way to maintain licensing by the
+     * third party developer
      */
-    customerId?: string;
+    chartAppAccessToken?: string;
 }

package/src/types/conditional-formatting.types.ts

@@ -3,30 +3,15 @@
  * @fileoverview All CF types for the Custom Chart implementations
  * @author Yashvardhan Nehra <yashvardhan.nehra@thoughtspot.com>
  *
- * Copyright: ThoughtSpot Inc. 2023
+ * Copyright: ThoughtSpot Inc. 2024
  */
 
-export type Maybe<T> = T | null;
-export type InputMaybe<T> = Maybe<T>;
+import type { InputMaybe, Maybe, Scalars } from './common.types';
 
 export type ConditionalFormatting = {
     __typename?: 'ConditionalFormatting';
     rows?: Maybe<Array<Maybe<ConditionalMetric>>>;
 };
-export type Scalars = {
-    ID: string;
-    String: string;
-    Boolean: boolean;
-    Int: number;
-    Float: number;
-    FileUpload: any;
-    GUID: string;
-    JSON: {
-        [key: string]: any;
-    };
-    JSONObject: any;
-    Long: any;
-};
 export declare enum BackgroundFormatTypes {
     Gradient = 'GRADIENT',
     Solid = 'SOLID',

package/src/types/configurator.types.ts

@@ -14,7 +14,7 @@
  * Copyright: ThoughtSpot Inc. 2023
  */
 
-import { CustomChartContext } from '../main/custom-chart-context';
+import type { CustomChartContext } from '../main/custom-chart-context';
 import { ChartModel } from './common.types';
 /**
  *

package/src/types/number-formatting.types.ts

@@ -0,0 +1,80 @@
+/**
+ * @file: Number Formatting Types
+ * @author Yashvardhan Nehra <yashvardhan.nehra@thoughtspot.com>
+ *
+ * Copyright: ThoughtSpot Inc. 2024
+ */
+
+import type { Maybe, Scalars } from './common.types';
+
+export enum CategoryType {
+    Currency = 'CURRENCY',
+    Custom = 'CUSTOM',
+    Number = 'NUMBER',
+    Percentage = 'PERCENTAGE',
+}
+
+export enum Unit {
+    Auto = 'AUTO',
+    Billion = 'BILLION',
+    Million = 'MILLION',
+    None = 'NONE',
+    Thousands = 'THOUSANDS',
+    Trillion = 'TRILLION',
+}
+
+export enum NegativeValueFormat {
+    BracesNodash = 'BRACES_NODASH',
+    PrefixDash = 'PREFIX_DASH',
+    SuffixDash = 'SUFFIX_DASH',
+}
+
+export type CurrencyFormatConfig = {
+    __typename?: 'CurrencyFormatConfig';
+    /** default to 2 */
+    decimals?: Maybe<Scalars['Float']>;
+    locale?: Maybe<Scalars['String']>;
+    /** default to false */
+    removeTrailingZeroes?: Maybe<Scalars['Boolean']>;
+    /** default to true */
+    toSeparateThousands?: Maybe<Scalars['Boolean']>;
+    /** default is MILLION */
+    unit?: Maybe<Unit>;
+};
+
+export type CustomFormatConfig = {
+    __typename?: 'CustomFormatConfig';
+    format?: Maybe<Scalars['String']>;
+};
+
+export type NumberFormatConfig = {
+    __typename?: 'NumberFormatConfig';
+    /** default to 2 */
+    decimals?: Maybe<Scalars['Float']>;
+    /** default to PREFIX_DASH */
+    negativeValueFormat?: Maybe<NegativeValueFormat>;
+    /** default to false */
+    removeTrailingZeroes?: Maybe<Scalars['Boolean']>;
+    /** default to true */
+    toSeparateThousands?: Maybe<Scalars['Boolean']>;
+    /** default is Auto */
+    unit?: Maybe<Unit>;
+};
+
+export type PercentageFormatConfig = {
+    __typename?: 'PercentageFormatConfig';
+    /** default to 2 */
+    decimals?: Maybe<Scalars['Float']>;
+    /** default to false */
+    removeTrailingZeroes?: Maybe<Scalars['Boolean']>;
+};
+
+export type FormatConfig = {
+    __typename?: 'FormatConfig';
+    category?: Maybe<CategoryType>;
+    currencyFormatConfig?: Maybe<CurrencyFormatConfig>;
+    customFormatConfig?: Maybe<CustomFormatConfig>;
+    isCategoryEditable?: Maybe<Scalars['Boolean']>;
+    numberFormatConfig?: Maybe<NumberFormatConfig>;
+    percentageFormatConfig?: Maybe<PercentageFormatConfig>;
+};

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

@@ -1,16 +1,21 @@
-import { AllowedConfigurations } from '../main/custom-chart-context';
+import type {
+    AllowedConfigurations,
+    ChartConfigParameters,
+    PersistedVisualPropKeys,
+} from '../main/custom-chart-context';
 import { ChartColumn } from './answer-column.types';
-import { Point } from './chart-to-ts-event.types';
+import type { Point } from './chart-to-ts-event.types';
 import {
     AppConfig,
     ChartConfig,
     ChartModel,
+    DataPointsArray,
     QueryData,
     ValidationResponse,
     VisualProps,
 } from './common.types';
-import { ChartConfigEditorDefinition } from './configurator.types';
-import { VisualPropEditorDefinition } from './visual-prop.types';
+import type { ChartConfigEditorDefinition } from './configurator.types';
+import type { VisualPropEditorDefinition } from './visual-prop.types';
 
 /**
  * All the events sent from the ThoughtSpot application to Custom Chart App
@@ -69,6 +74,10 @@ export enum TSToChartEvent {
      * @version SDK: 0.1 | ThoughtSpot:
      */
     AxisMenuActionClick = 'AxisMenuActionClick',
+    /**
+     * @version SDK: 0.2 | ThoughtSpot:
+     */
+    GetColumnData = 'GetColumnData',
 }
 
 /**
@@ -107,6 +116,10 @@ export interface TSToChartInternalEventsPayloadMap {
         payload: GetDataQueryPayload,
     ) => GetDataQueryResponsePayload;
 
+    [TSToChartEvent.GetColumnData]: (
+        payload: GetColumnDataPayload,
+    ) => GetColumnDataResponsePayload;
+
     [TSToChartEvent.ChartConfigValidate]: (
         payload: ChartConfigValidateEventPayload,
     ) => ValidationResponse;
@@ -206,6 +219,21 @@ export interface InitializeEventResponsePayload {
      * @version SDK: 0.1 | ThoughtSpot:
      */
     allowedConfigurations?: AllowedConfigurations;
+    /**
+     * Key stored in persistedVisualPropKeys array will be preserved on changing the
+     * visualPropeditorDefinition, any other key (expect clientState) would not be preserved for visual props.
+     * ### NOTE: like clientState this variable should be a string, preferrably a result of JSON.stringify(<yourlocalClientState>)
+     * ### USE CASE: This is to maintain different clientSate for different custom charts developed by same TS custom chart developer.
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    persistedVisualPropKeys?: PersistedVisualPropKeys;
+    /**
+     * Additional chart configuration parameters supported by TS UI. Ex: show/hide Measure Name/
+     * Value columns.
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    chartConfigParameters?: ChartConfigParameters;
 }
 
 /**
@@ -216,12 +244,30 @@ export interface GetDataQueryPayload {
     config: ChartConfig[];
 }
 
+export interface GetColumnDataPayload {
+    columnId: string;
+}
+
+/**
+ *
+ * @group ThoughtSpot to Chart Events
+ */
+export interface QueryColumn extends ChartColumn {
+    /**
+     * Flag to identify if the column is a measure value,
+     * to be used along with MEASURE_NAME/MEASUE_VALUE column in the query
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    isMeasureValue?: boolean;
+}
+
 /**
  *
  * @group ThoughtSpot to Chart Events
  */
 export interface Query {
-    queryColumns: ChartColumn[];
+    queryColumns: QueryColumn[];
     queryParams?: {
         offset?: number;
         size?: number;
@@ -236,6 +282,11 @@ export interface GetDataQueryResponsePayload {
     queries: Query[];
 }
 
+export interface GetColumnDataResponsePayload {
+    // Marked as any as the data from columns can be of any type
+    data?: any[];
+}
+
 /**
  *
  * @group ThoughtSpot to Chart Events
@@ -281,6 +332,13 @@ export interface VisualPropsValidateEventPayload {
      * @version SDK: 0.1 | ThoughtSpot:
      */
     visualProps: VisualProps;
+    /**
+     * used to identify active column for column level settings, empty string in case of overall
+     * chart settings
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    activeColumnId?: string;
 }
 
 /**