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

package/src/types/common.types.ts

@@ -0,0 +1,187 @@
+/**
+ * @file: Common Types
+ * @fileoverview All commons types for the Custom Chart implementations
+ * @author Chetan Agrawal <chetan.agrawal@thoughtspot.com>
+ *
+ * Copyright: ThoughtSpot Inc. 2023
+ */
+
+import { ChartColumn, DataType } from './answer-column.types';
+
+/**
+ * List of Columns for a dimension in the Custom Chart Config.
+ * Associated with the key defined in the chart config editor definition
+ * Relates to ChartConfigSection
+ *
+ * @version SDK: 0.1 | ThoughtSpot:
+ * @group Chart Model
+ */
+export interface ChartConfigDimension {
+    /**
+     * key fo the dimension in the chart config
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    key: string;
+    /**
+     * list of columns added for the dimension
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    columns: ChartColumn[];
+}
+
+/**
+ * Custom Chart Config values stored in the metadata
+ * Relates to ChartConfigEditorDefinition
+ *
+ * @version SDK: 0.1 | ThoughtSpot:
+ * @group Chart Model
+ */
+export interface ChartConfig {
+    /**
+     * key of the custom chart config defined in the chart config editor definition
+     * this is used to differentiate between different custom chart configurations
+     * within the same chart
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    key: string;
+    /**
+     * Details of columns for each dimension
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    dimensions: ChartConfigDimension[];
+}
+
+/**
+ * Data Array inteface to define each column data
+ *
+ * @version SDK: 0.1 | ThoughtSpot:
+ * @group Chart Model
+ */
+export type DataArray = {
+    /**
+     * column id associated with the data array
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    columnId: string;
+    /**
+     * type of data
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    columnDataType: DataType;
+    /**
+     * The array of data values associated with the column
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    dataValue: any[];
+};
+
+/**
+ * For each query defined by the user, a query data object is sent
+ * in the following format
+ *
+ * @version SDK: 0.1 | ThoughtSpot:
+ * @group Chart Model
+ */
+export type QueryData = {
+    /**
+     * Data Array for each column
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    data: DataArray[];
+
+    /**
+     * @hidden
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    completionRatio: number;
+    /**
+     * @hidden
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    samplingRatio: number;
+
+    /**
+     * number of rows of data fetched for the query
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    totalRowCount: number;
+};
+
+/**
+ *
+ * @group Chart Model
+ * @version SDK: 0.1 | ThoughtSpot:
+ */
+export interface ChartModel {
+    /**
+     * List of columns in the search query
+     * They may or may not be part of the data query or chart config
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    columns: ChartColumn[];
+    /**
+     * Array of Datasets for each query
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    data?: QueryData[];
+    sortInfo?: any; // TODO(chetan):
+    visualProps?: VisualProps;
+    config: {
+        // chart config stored by chart developer
+        chartConfig?: ChartConfig[];
+    };
+}
+
+// Generic Validation Response
+export type ValidationResponse = {
+    isValid: boolean;
+    validationErrorMessage?: string[];
+};
+
+/**
+ * Custom Visual props is the stored metadata for the visual props definition
+ * configured by the user in the visual prop editor
+ * The JSON is defined by the visual prop types. See VisualPropEditorDefinition
+ *
+ * @group Chart Model
+ * @version SDK: 0.1 | ThoughtSpot:
+ */
+export type VisualProps = JSON;
+
+// Todo: this should be imported from custom style config package.
+type CustomStylingConfig = any;
+
+export interface AppConfig {
+    styleConfig?: CustomStylingConfig;
+
+    appOptions?: {
+        isMobile?: boolean;
+        isPrintMode?: boolean; // export mode on/off
+
+        // runtime configurations
+        isDebugMode?: boolean; // enables debug mode for logging
+    };
+
+    // locale related settings
+    localeOptions?: {
+        locale: string;
+        quarterStartMonth: string;
+        sessionTimezone: 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
+    customCalendarConfig?: any; // this is to initialize custom calendar service
+}

package/src/types/configurator.types.ts

@@ -0,0 +1,102 @@
+/**
+ * @file Column Configuration Definition
+ * @fileoverview
+ * Developers will use this to define the axis configuration that any
+ * creator of the chart can use the define the expected chart configuration.
+ *
+ * This will also be validated with the overall expectation
+ * of the chart developer using validate flow.
+ *
+ * Developer is expected to use this to be able to define the data queries
+ * required for the chart.
+ * @author Chetan Agrawal <chetan.agrawal@thoughtspot.com>
+ *
+ * Copyright: ThoughtSpot Inc. 2023
+ */
+
+/**
+ *
+ * @group Chart Configuration Editor
+ */
+export interface ChartConfigSection {
+    /**
+     * key to persist the columns
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    key: string;
+    /**
+     * i18n'ed string to show the section label on the config editor
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    label: string;
+
+    /**
+     * In the UI, the following values will only prevent from dropping unnecessary
+     * columns on the section config or prevent from opening a drop down in case of
+     * multiple queries. Validation is still expected to be done by developer.
+     */
+
+    /**
+     * Number of columns allowed in the section
+     *
+     * @default Number.POSITIVE_INFINITY
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    maxColumnCount?: number;
+    /**
+     * Allow Numeric Columns on the Section
+     *
+     * @default true
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    allowMeasureColumns?: boolean;
+    /**
+     * Allow Attribute/Dimensional Columns on the Section
+     * Example: strings, dates, etc
+     *
+     * @default true
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    allowAttributeColumns?: boolean;
+    /**
+     * Allow Date and Time based Columns on the Section
+     *
+     * @default true
+     * @hidden Not exposing this now to define more clearly
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    allowTimeSeriesColumns?: boolean;
+}
+
+/**
+ *
+ * @group Chart Configuration Editor
+ */
+export interface ChartConfigEditorDefinition {
+    /**
+     * key to store the chart config
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    key: string;
+    /**
+     * i18n'ed string to show the editor header for the chart config
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    label?: string;
+    /**
+     * i18n'ed string to show the editor description for the chart config
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    descriptionText?: string;
+    /**
+     * Following will define all the column sections for the chart config
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    columnSections: ChartConfigSection[];
+}

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

@@ -0,0 +1,257 @@
+import { ChartColumn } from './answer-column.types';
+import {
+    AppConfig,
+    ChartConfig,
+    ChartModel,
+    QueryData,
+    ValidationResponse,
+    VisualProps,
+} from './common.types';
+import { ChartConfigEditorDefinition } from './configurator.types';
+import { VisualPropEditorDefinition } from './visual-prop.types';
+
+/**
+ * All the events sent from TS application to Custom Chart App
+ *
+ * @version SDK: 0.1 | ThoughtSpot:
+ * @group ThoughtSpot to Chart Events
+ */
+export enum TSToChartEvent {
+    /**
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    Initialize = 'Initialize',
+
+    /**
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    GetDataQuery = 'GetDataQuery',
+
+    /**
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    ChartConfigValidate = 'ChartConfigValidate',
+    /**
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    ChartModelUpdate = 'ChartModelUpdate',
+    /**
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    DataUpdate = 'DataUpdate',
+
+    /**
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    TriggerRenderChart = 'TriggerRenderChart',
+
+    /**
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    VisualPropsValidate = 'VisualPropsValidate',
+    /**
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    VisualPropsUpdate = 'VisualPropsUpdate',
+}
+
+/**
+ * Map of callback function with the event types
+ *
+ * @version SDK: 0.1 | ThoughtSpot:
+ * @group ThoughtSpot to Chart Events
+ */
+export interface TSToChartEventsPayloadMap {
+    [TSToChartEvent.ChartModelUpdate]: (
+        payload: ChartModelUpdateEventPayload,
+    ) => void;
+    [TSToChartEvent.DataUpdate]: (payload: DataUpdateEventPayload) => void;
+    [TSToChartEvent.VisualPropsUpdate]: (
+        payload: VisualPropsUpdateEventPayload,
+    ) => void;
+}
+
+/**
+ * Map of internal events that will not be exposed to the developers
+ * and is only for internal usage.
+ *
+ * @internal
+ * @hidden
+ * @version SDK: 0.1 | ThoughtSpot:
+ * @group ThoughtSpot to Chart Events
+ */
+export interface TSToChartInternalEventsPayloadMap {
+    [TSToChartEvent.Initialize]: (
+        payload: InitializeEventPayload,
+    ) => InitializeEventResponsePayload;
+
+    [TSToChartEvent.GetDataQuery]: (
+        payload: GetDataQueryPayload,
+    ) => GetDataQueryResponsePayload;
+
+    [TSToChartEvent.ChartConfigValidate]: (
+        payload: ChartConfigValidateEventPayload,
+    ) => ValidationResponse;
+
+    [TSToChartEvent.VisualPropsValidate]: (
+        payload: VisualPropsValidateEventPayload,
+    ) => ValidationResponse;
+
+    [TSToChartEvent.TriggerRenderChart]: () => void;
+}
+
+/**
+ *
+ * @group ThoughtSpot to Chart Events
+ */
+export interface InitializeEventPayload {
+    /**
+     * The entire chart object with data
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    chartModel: ChartModel;
+
+    /**
+     * Additional App Configuration
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    appConfig?: AppConfig;
+
+    /**
+     * This is a unique component id that the context should send in every
+     * post message payload. This helps in identifying between multiple app components.
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    componentId: string;
+    /**
+     * The host url of the parent to send the post message requests to.
+     * We cannot use the window.parent object details to fetch this.
+     * Hence sending in init flow.
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    hostUrl: string;
+}
+
+/**
+ *
+ * @group ThoughtSpot to Chart Events
+ */
+export interface InitializeEventResponsePayload {
+    /**
+     * Boolean value to define if the current config is valid or not
+     * Would be true if the validateChartConfig function is not defined
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    isConfigValid: boolean;
+    /**
+     * Default Chart Config generated if the chart config is not valid or not present.
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    defaultChartConfig: ChartConfig[];
+    /**
+     * chart config editor definition
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    chartConfigEditorDefinition?: ChartConfigEditorDefinition[];
+    /**
+     * visual properties editor definition
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    visualPropEditorDefinition?: VisualPropEditorDefinition;
+}
+
+/**
+ *
+ * @group ThoughtSpot to Chart Events
+ */
+export interface GetDataQueryPayload {
+    config: ChartConfig[];
+}
+
+/**
+ *
+ * @group ThoughtSpot to Chart Events
+ */
+export interface Query {
+    queryColumns: ChartColumn[];
+    queryParams?: {
+        offset?: number;
+        size?: number;
+    };
+}
+
+/**
+ *
+ * @group ThoughtSpot to Chart Events
+ */
+export interface GetDataQueryResponsePayload {
+    queries: Query[];
+}
+
+/**
+ *
+ * @group ThoughtSpot to Chart Events
+ */
+export interface ChartModelUpdateEventPayload {
+    /**
+     * updated chart model
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    chartModel: ChartModel;
+}
+
+/**
+ *
+ * @group ThoughtSpot to Chart Events
+ */
+export interface DataUpdateEventPayload {
+    /**
+     * updated data in the chart model
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    data: QueryData[];
+}
+export interface VisualPropsUpdateEventPayload {
+    /**
+     * updated visual properties
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    visualProps: VisualProps;
+}
+
+/**
+ *
+ * @group ThoughtSpot to Chart Events
+ */
+export interface VisualPropsValidateEventPayload {
+    /**
+     * updated visual properties
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    visualProps: VisualProps;
+}
+
+/**
+ *
+ * @group ThoughtSpot to Chart Events
+ */
+export interface ChartConfigValidateEventPayload {
+    /**
+     * updated chart config properties
+     *
+     * @version SDK: 0.1 | ThoughtSpot:
+     */
+    chartConfig: ChartConfig[];
+}