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

package/src/main/custom-chart-context.ts

@@ -35,6 +35,8 @@ import {
     ChartModelUpdateEventPayload,
     ContextMenuCustomActionPayload,
     DataUpdateEventPayload,
+    GetColumnDataPayload,
+    GetColumnDataResponsePayload,
     GetDataQueryPayload,
     GetDataQueryResponsePayload,
     InitializeEventPayload,
@@ -50,16 +52,127 @@ import {
     VisualEditorDefinitionSetter,
     VisualPropEditorDefinition,
 } from '../types/visual-prop.types';
+import { setLocaleBasedStringFormats } from '../utils/number-formatting/number-formatting-utils';
+import { create } from './logger';
 import {
     globalThis,
     initMessageListener,
     postMessageToHostApp,
 } from './post-message-event-bridge';
 
+const logger = create('TsChartSDKContext');
+/**
+ * Configuration for allowing or disallowing specific TS UI features.
+ *
+ * @fileoverview
+ * This configuration defines the ability to toggle specific features such as
+ * column number formatting, conditional formatting, and measure names/values.
+ *
+ * @version SDK: 0.1 | ThoughtSpot:
+ */
 export type AllowedConfigurations = {
-    allowColumnNumberFormatting: boolean;
-    allowColumnConditionalFormatting: boolean;
-    allowMeasureNamesAndValues: boolean;
+    /**
+     * Allows column-level number formatting.
+     *
+     * @default false
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    allowColumnNumberFormatting?: boolean;
+
+    /**
+     * Allows conditional formatting at the column level.
+     * This allows users to apply rules that visually highlight or differentiate data.
+     *
+     * @default false
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    allowColumnConditionalFormatting?: boolean;
+
+    /**
+     * Allows Gradient coloring at the column level.
+     *
+     * @default false
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    allowGradientColoring?: boolean;
+
+    /**
+     * Enables measure_name and measure_values in the chart configuration.
+     *
+     * @default false
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    allowMeasureNamesAndValues?: boolean;
+};
+/**
+ * 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:
+ */
+export type PersistedVisualPropKeys = string[];
+/**
+ * Configuration parameters for setting chart-specific options.
+ *
+ * @fileoverview
+ * This configuration includes settings for controlling measure name/value columns
+ * and batch size limits for data processing.
+ *
+ * @version SDK: 0.1 | ThoughtSpot:
+ */
+export type ChartConfigParameters = {
+    /**
+     * Configurations related to measure name and value columns.
+     * These parameters allow for enabling/disabling and aliasing the columns
+     * used to represent measure names and values.
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    measureNameValueColumns?: {
+        /**
+         * Enables or disables the measure_name column.
+         *
+         * @default false
+         * @version SDK: 0.1 | ThoughtSpot:
+         */
+        enableMeasureNameColumn?: boolean;
+
+        /**
+         * Enables or disables the measure_value column.
+         *
+         * @default false
+         * @version SDK: 0.1 | ThoughtSpot:
+         */
+        enableMeasureValueColumn?: boolean;
+
+        /**
+         * Alias for the measure_name column.
+         * This allows users to define a custom name for the measure_name column.
+         *
+         * @default 'Measure Name'
+         * @version SDK: 0.1 | ThoughtSpot:
+         */
+        measureNameColumnAlias?: string;
+
+        /**
+         * Alias for the measure_value column.
+         * This allows users to define a custom name for the measure_value column.
+         *
+         * @default 'Measure Value'
+         * @version SDK: 0.1 | ThoughtSpot:
+         */
+        measureValueColumnAlias?: string;
+    };
+
+    /**
+     * Limit on the batch size for data processing.
+     * This sets an upper limit on how much data can be processed in a single batch.
+     *
+     * @default 20000
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    batchSizeLimit?: number;
 };
 
 export type CustomChartContextProps = {
@@ -116,6 +229,7 @@ export type CustomChartContextProps = {
     validateVisualProps?: (
         updatedVisualProps: VisualProps,
         chartModel: ChartModel,
+        activeColumnId?: string,
     ) => ValidationResponse;
 
     /**
@@ -141,8 +255,36 @@ export type CustomChartContextProps = {
         | VisualEditorDefinitionSetter
         | VisualPropEditorDefinition;
 
-    // Whether user wants thoughtspot default number and conditional formatting
+    /**
+     * Optional configuration to toggle native TS UI configurations, such as column number
+     * formatting and conditional formatting.
+     *
+     * @type {AllowedConfigurations}
+     * @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.
+     * 
+     * @type {PersistedVisualPropKeys}
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    persistedVisualPropKeys?: PersistedVisualPropKeys;
+    /**
+     * Optional parameters for configuring specific chart-related features, such as measure name
+     * and value columns.
+     *
+     * @type {ChartConfigParameters}
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    chartConfigParameters?: ChartConfigParameters;
 };
 
 export type ValidationFunctions =
@@ -159,8 +301,19 @@ const DEFAULT_CHART_CONTEXT_PROPS: Partial<CustomChartContextProps> = {
     allowedConfigurations: {
         allowColumnNumberFormatting: false,
         allowColumnConditionalFormatting: false,
+        allowGradientColoring: false,
         allowMeasureNamesAndValues: false,
     },
+    persistedVisualPropKeys: undefined,
+    chartConfigParameters: {
+        measureNameValueColumns: {
+            enableMeasureNameColumn: false,
+            enableMeasureValueColumn: false,
+            measureNameColumnAlias: 'Measure Name',
+            measureValueColumnAlias: 'Measure Values',
+        },
+        batchSizeLimit: 20000,
+    },
 };
 
 export class CustomChartContext {
@@ -269,6 +422,9 @@ export class CustomChartContext {
         this.hasInitializedPromise = new Promise((resolve, reject) => {
             this.triggerInitResolve = resolve;
         });
+        // Not using this.emitEvent as the context is not yet completely
+        // initialized, thus short circuiting.
+        postMessageToHostApp('', '*', null, ChartToTSEvent.InitStart);
     }
 
     /**
@@ -279,7 +435,7 @@ export class CustomChartContext {
      * @version SDK: 0.1 | ThoughtSpot:
      */
     public initialize = (): Promise<void> => {
-        console.log('Chart Context: initialization start');
+        logger.log('Chart Context: initialization start');
         return this.hasInitializedPromise;
     };
 
@@ -311,7 +467,7 @@ export class CustomChartContext {
      */
     public off<T extends keyof TSToChartEventsPayloadMap>(eventType: T): void {
         if (_.isNil(this.eventListeners[eventType])) {
-            console.log('No event listener found to remove');
+            logger.log('No event listener found to remove');
             this.eventListeners[eventType] = [];
             return;
         }
@@ -424,6 +580,7 @@ export class CustomChartContext {
      * @returns {VisualPropEditorDefinition}
      */
     private getVisualPropEditorDefinition = (
+        activeColumnId?: string,
         currentState: Partial<ChartModel> = {},
     ) => {
         if (_.isFunction(this.chartContextProps.visualPropEditorDefinition)) {
@@ -433,6 +590,7 @@ export class CustomChartContext {
                     ...currentState,
                 },
                 this,
+                activeColumnId,
             );
         }
         return this.chartContextProps.visualPropEditorDefinition;
@@ -500,8 +658,10 @@ export class CustomChartContext {
     private validationsResponseProcessor(
         currentValidationState: Partial<ChartModel>,
         validationResponse: ValidationResponse,
+        activeColumnId?: string,
     ) {
         const visualPropEditorDefinition = this.getVisualPropEditorDefinition(
+            activeColumnId,
             currentValidationState,
         );
         const chartConfigEditorDefinition = this.getChartConfigEditorDefinition(
@@ -528,7 +688,7 @@ export class CustomChartContext {
         ...eventPayload: ChartToTSEventsPayloadMap[T]
     ): Promise<any> {
         if (!globalThis.isInitialized) {
-            console.log(
+            logger.log(
                 'Chart Context: not initialized the context, something went wrong',
             );
             return Promise.reject(new Error('Context not initialized'));
@@ -551,7 +711,7 @@ export class CustomChartContext {
      */
     private registerEventProcessor = () => {
         if (globalThis.isInitialized) {
-            console.error(
+            logger.error(
                 'The context is already initialized. you cannot have multiple contexts',
             );
             throw new Error(ErrorType.MultipleContextsNotSupported);
@@ -567,12 +727,12 @@ export class CustomChartContext {
      * @param event : Message Event Object
      */
     private eventProcessor = (data: any) => {
-        console.log('Chart Context: message received:', data.eventType, data);
+        logger.log('Chart Context: message received:', data.eventType, data);
 
         const messageResponse = this.executeEventListenerCBs(data);
 
         // respond back to parent to confirm/ack the receipt
-        return messageResponse;
+        return messageResponse || {};
     };
 
     /**
@@ -617,15 +777,17 @@ export class CustomChartContext {
                         this.chartContextProps.validateVisualProps(
                             payload.visualProps,
                             this.chartModel,
+                            payload?.activeColumnId,
                         );
                     if (validationResponse.isValid) {
                         const currentVisualState = {
                             visualProps: payload.visualProps,
                         };
-
+                        const activeColumnId = payload?.activeColumnId;
                         return this.validationsResponseProcessor(
                             currentVisualState,
                             validationResponse,
+                            activeColumnId,
                         );
                     }
                     return validationResponse;
@@ -690,6 +852,28 @@ export class CustomChartContext {
             },
         );
 
+        /**
+         * This event is triggered when the TS app asks for data in a specific columns
+         * for certain validations for settings and drop down options related to Conditional
+         * formatting and other advanced settings
+         */
+        this.onInternal(
+            TSToChartEvent.GetColumnData,
+            (payload: GetColumnDataPayload): GetColumnDataResponsePayload => {
+                const parsedData = this.chartModel.data?.[0].data;
+                const dataIdx = parsedData?.columns.findIndex(
+                    (columnId) => columnId === payload.columnId,
+                );
+                const dataArray =
+                    !_.isNil(dataIdx) && dataIdx > -1
+                        ? parsedData?.dataValue.map((it) => it[dataIdx])
+                        : [];
+                return {
+                    data: dataArray,
+                };
+            },
+        );
+
         /**
          * This event is triggered when the TS app re-renders the chart
          */
@@ -728,7 +912,7 @@ export class CustomChartContext {
                         isValid: true,
                     };
                 } catch (error: unknown) {
-                    console.log(
+                    logger.log(
                         'ContextMenuCustomAction: payload recieved:',
                         payload,
                         'CustomActionCallbackStore:',
@@ -771,7 +955,7 @@ export class CustomChartContext {
                         isValid: true,
                     };
                 } catch (error: unknown) {
-                    console.log(
+                    logger.log(
                         'AxisMenuCustomAction: payload recieved:',
                         payload,
                         'CustomActionCallbackStore:',
@@ -859,7 +1043,9 @@ export class CustomChartContext {
         this.containerEl = payload.containerElSelector
             ? document.querySelector(payload.containerElSelector)
             : null;
-
+        setLocaleBasedStringFormats(
+            this.appConfig.dateFormatsConfig?.tsLocaleBasedStringsFormats,
+        );
         return this.publishChartContextPropsToHost();
     };
 
@@ -901,6 +1087,10 @@ export class CustomChartContext {
                     this.getVisualPropEditorDefinition(),
                 allowedConfigurations:
                     this.chartContextProps.allowedConfigurations,
+                chartConfigParameters:
+                    this.chartContextProps.chartConfigParameters,
+                persistedVisualPropKeys:
+                    this.chartContextProps.persistedVisualPropKeys,
             };
         };
 
@@ -928,7 +1118,7 @@ export class CustomChartContext {
             };
         }
 
-        console.log(
+        logger.log(
             'ChartContext: Response:',
             data.eventType,
             response,
@@ -951,6 +1141,5 @@ export const getChartContext = async (
     // wait for initialization here as the host app
     // needs to first handshake with the client app.
     await ctx.initialize();
-
     return ctx;
 };

package/src/main/logger.spec.ts

@@ -0,0 +1,114 @@
+import { create, LogLevel, logMethods } from './logger';
+
+jest.mock('./util', () => ({
+    getQueryParam: jest.fn().mockReturnValue('true'),
+}));
+
+describe('Logger', () => {
+    let originalConsole: Record<string, any>;
+    let logger: any;
+
+    beforeAll(() => {
+        // Save original console methods
+        originalConsole = {
+            error: console.error,
+            warn: console.warn,
+            info: console.info,
+            log: console.log,
+            trace: console.trace,
+        };
+        // Mock console methods
+        const error = jest.fn();
+        const warn = jest.fn();
+        const info = jest.fn();
+        const log = jest.fn();
+        const trace = jest.fn();
+        logMethods[LogLevel.ERROR] = error;
+        logMethods[LogLevel.WARN] = warn;
+        logMethods[LogLevel.INFO] = info;
+        logMethods[LogLevel.DEBUG] = log;
+        logMethods[LogLevel.TRACE] = trace;
+        console.error = error;
+        console.warn = warn;
+        console.info = info;
+        console.log = log;
+        console.trace = trace;
+    });
+
+    afterAll(() => {
+        // Restore original console methods
+        logMethods[LogLevel.ERROR] = originalConsole.error;
+        logMethods[LogLevel.WARN] = originalConsole.warn;
+        logMethods[LogLevel.INFO] = originalConsole.info;
+        logMethods[LogLevel.DEBUG] = originalConsole.log;
+        logMethods[LogLevel.TRACE] = originalConsole.trace;
+        console.error = originalConsole.error;
+        console.warn = originalConsole.warn;
+        console.info = originalConsole.info;
+        console.log = originalConsole.log;
+        console.trace = originalConsole.trace;
+    });
+
+    beforeEach(() => {
+        // Set debug to 'true' to enable logging
+        (global as any).window = {
+            location: { href: 'https://example.com/?debug=true' },
+        };
+        logger = create('TestLogger');
+    });
+
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    describe('logMessages', () => {
+        it('should log messages with appropriate prefixes for DEBUG level', async () => {
+            await logger.debug('Debug message');
+            expect(console.log).toHaveBeenCalledWith(
+                'DEBUG (TestLogger)(] Debug message)',
+            );
+        });
+
+        it('should log messages with appropriate prefixes for INFO level', async () => {
+            await logger.info('Info message');
+            expect(console.info).toHaveBeenCalledWith(
+                'INFO (TestLogger)(] Info message)',
+            );
+        });
+
+        it('should log messages with appropriate prefixes for WARN level', async () => {
+            await logger.warn('Warn message');
+            expect(console.warn).toHaveBeenCalledWith(
+                'WARN (TestLogger)(] Warn message)',
+            );
+        });
+
+        it('should log messages with appropriate prefixes for ERROR level', async () => {
+            await logger.error('Error message');
+            expect(console.error).toHaveBeenCalledWith(
+                'ERROR (TestLogger)(] Error message)',
+            );
+        });
+
+        it('should log messages with appropriate prefixes for TRACE level', async () => {
+            await logger.trace('Trace message');
+            expect(console.trace).toHaveBeenCalledWith(
+                'TRACE (TestLogger)(] Trace message)',
+            );
+        });
+    });
+
+    describe('create function', () => {
+        it('should create a new logger instance if one does not exist', () => {
+            const newLogger = create('NewLogger');
+            expect(newLogger).not.toBe(undefined);
+            expect(newLogger).toBeInstanceOf(Object);
+        });
+
+        it('should return the same logger instance if it already exists', () => {
+            const logger1 = create('SharedLogger');
+            const logger2 = create('SharedLogger');
+            expect(logger1).toBe(logger2);
+        });
+    });
+});

package/src/main/logger.ts

@@ -0,0 +1,97 @@
+import { getQueryParam } from './util';
+
+const loggers: Record<string, any> = {};
+const url = window.location.href;
+
+export enum LogLevel {
+    SILENT = -1 as number,
+    ERROR = 0 as number,
+    WARN = 1 as number,
+    INFO = 2 as number,
+    DEBUG = 3 as number,
+    TRACE = 4 as number,
+}
+
+export const logMethods: { [key: number]: any } = {
+    [LogLevel.ERROR]: console.error,
+    [LogLevel.WARN]: console.warn,
+    [LogLevel.INFO]: console.info,
+    [LogLevel.DEBUG]: console.log,
+    [LogLevel.TRACE]: console.trace,
+};
+
+class Logger {
+    private msgPrefix: string;
+
+    constructor(name: string) {
+        this.msgPrefix = name ? `(${name})` : '';
+    }
+
+    private getFormattedMessage(msg: string, logLevel: LogLevel) {
+        return (
+            `${LogLevel[logLevel]} ${this.msgPrefix}` +
+            `(${msg ? `] ${msg}` : ''})`
+        );
+    }
+
+    public async logMessages(args: any, logLevel: LogLevel) {
+        const newArgs = args;
+        if (getQueryParam(url, 'debug') !== 'true') {
+            return;
+        }
+        const logFn = logMethods[logLevel];
+        newArgs[0] = this.getFormattedMessage(newArgs[0], logLevel);
+        if (logFn) {
+            logFn(...newArgs);
+        }
+    }
+
+    public async trace(...args: any) {
+        this.logMessages(args, LogLevel.TRACE);
+    }
+
+    /**
+     * Wrapper for log.log() with debug level
+     * @param msg
+     */
+    public async debug(...args: any) {
+        this.logMessages(args, LogLevel.DEBUG);
+    }
+
+    public async log(...args: any) {
+        this.debug(...args);
+    }
+
+    /**
+     * Wrapper for log.info() with info level
+     * @param msg
+     */
+    public async info(...args: any) {
+        this.logMessages(args, LogLevel.INFO);
+    }
+
+    /**
+     * Wrapper for log.warn() with warn level
+     *
+     * @param {string} msg The log message
+     */
+    public async warn(...args: any) {
+        this.logMessages(args, LogLevel.WARN);
+    }
+
+    /**
+     * Wrapper for log.error() with error level
+     * Error is propagated via callback
+     * @param {string}  msg  The log message
+     */
+    public async error(...args: any) {
+        const stackTrace = this.logMessages(args, LogLevel.ERROR);
+    }
+}
+
+export function create(name: string): any {
+    if (!loggers[name]) {
+        loggers[name] = new Logger(name);
+    }
+    return loggers[name];
+}

package/src/main/util.spec.ts

@@ -0,0 +1,94 @@
+import { getQueryParam, handleMissingValue, timeout } from './util';
+
+describe('timeout function', () => {
+    jest.useFakeTimers();
+
+    it('should resolve with the original promise result if it completes before timeout', async () => {
+        const promise = Promise.resolve('success');
+        const result = timeout(promise, 1000);
+
+        await expect(result).resolves.toBe('success');
+    });
+
+    it('should reject with a timeout error if the promise takes too long', async () => {
+        const promise = new Promise((resolve) => {
+            setTimeout(resolve, 2000);
+        });
+        const result = timeout(promise, 1000);
+
+        jest.advanceTimersByTime(1000);
+
+        await expect(result).rejects.toThrow('Operation timed out.');
+    });
+
+    it('should use the custom error message when provided', async () => {
+        const promise = new Promise((resolve) => {
+            setTimeout(resolve, 2000);
+        });
+        const result = timeout(promise, 1000, 'Custom timeout message');
+
+        jest.advanceTimersByTime(1000);
+
+        await expect(result).rejects.toThrow('Custom timeout message');
+    });
+
+    it('should reject with the original promise error if it rejects before timeout', async () => {
+        const promise = Promise.reject(new Error('Original error'));
+        const result = timeout(promise, 1000);
+
+        await expect(result).rejects.toThrow('Original error');
+    });
+});
+
+describe('getQueryParam', () => {
+    it('should return the value of a query parameter if it exists', () => {
+        const url = 'https://example.com/?key=value';
+        expect(getQueryParam(url, 'key')).toBe('value');
+    });
+
+    it('should return an empty string if the query parameter does not exist', () => {
+        const url = 'https://example.com/';
+        expect(getQueryParam(url, 'missingKey')).toBe('');
+    });
+
+    it('should return "false" if the query parameter is "debug" and it is not present', () => {
+        const url = 'https://example.com/';
+        expect(getQueryParam(url, 'debug')).toBe('false');
+    });
+
+    it('should return the default value "false" if the query parameter is "debug" and is set to an empty value', () => {
+        const url = 'https://example.com/?debug=';
+        expect(getQueryParam(url, 'debug')).toBe('');
+    });
+
+    it('should handle complex URLs with multiple parameters correctly', () => {
+        const url = 'https://example.com/?key1=value1&key2=value2';
+        expect(getQueryParam(url, 'key2')).toBe('value2');
+    });
+});
+
+describe('handleMissingValue', () => {
+    it('should return "false" if paramKey is "debug" and paramValue is undefined', () => {
+        expect(handleMissingValue('debug', undefined)).toBe('false');
+    });
+
+    it('should return "false" if paramKey is "debug" and paramValue is null', () => {
+        expect(handleMissingValue('debug', null)).toBe('false');
+    });
+
+    it('should return an empty string if paramValue is undefined and paramKey is not "debug"', () => {
+        expect(handleMissingValue('param', undefined)).toBe('');
+    });
+
+    it('should return an empty string if paramValue is null and paramKey is not "debug"', () => {
+        expect(handleMissingValue('param', null)).toBe('');
+    });
+
+    it('should return the paramValue if paramValue is defined and not null', () => {
+        expect(handleMissingValue('param', 'value')).toBe('value');
+    });
+
+    it('should return the paramValue even if paramKey is "debug" and paramValue is defined', () => {
+        expect(handleMissingValue('debug', 'true')).toBe('true');
+    });
+});