@thoughtspot/visual-embed-sdk 1.53.1 → 1.53.2-beta

package/src/contracts/embed-event-payloads.ts

@@ -4,39 +4,306 @@
  * Typed payload contracts for {@link EmbedEvent}s (ThoughtSpot app -> SDK).
  *
  * The SDK delivers embed events to `embed.on()` callbacks wrapped in the
- * {@link MessagePayload} envelope `{ type, data, status? }`. The map below
- * types the `data` field per event. Events absent from the map resolve to
- * `any` until their payload is audited against what the host actually sends
- * (codify observed behavior, not documented behavior).
+ * {@link MessagePayload} envelope `{ type, data, status? }`. {@link
+ * EmbedEventDataExtension} types the `data` field per event; events absent from
+ * it resolve to `any`. Shapes are composed from a few scope mixins so related
+ * events share one definition, and each is loose: known fields are typed, and
+ * the host may send more, so unknown keys stay `any` (a callback reading an
+ * un-typed field keeps compiling).
  *
+ * These mirror the host app's `embed-event-schema` (dispatch side). Codify what
+ * the host actually sends, not what the docs say, and keep the two in sync.
  * Same additive-only evolution rules as host-event-contracts.ts.
  * @module contracts
  */
-import type { CustomActionPayload, EmbedEvent, MessagePayload } from '../types';
+import type {
+    CustomActionPayload, EmbedEvent, MessagePayload, RuntimeFilter,
+} from '../types';
 // Type-only: AnswerService is an SDK-side enrichment (see
 // EmbedEventEnvelopeExtension). Type-only import keeps the contracts subpath
 // free of any runtime dependency on the answer-service implementation.
 import type { AnswerService } from '../utils/graphql/answerService/answerService';
 
+// ============================================================================
+// Scope mixins — the field clusters events share.
+// ============================================================================
+
+/**
+ * Base for every payload. Known fields are declared on the interfaces below;
+ * additional fields the host may send stay `any`, so a callback reading one
+ * keeps compiling.
+ */
+export interface EmbedEventPayloadBase {
+    [key: string]: any;
+}
+
+/** Present on events raised from a Spotter conversation. */
+export interface ConversationScope extends EmbedEventPayloadBase {
+    convId?: string;
+    messageId?: string;
+}
+
+/** Scoped to a single visualization (optionally within a conversation). */
+export interface VizScope extends ConversationScope {
+    vizId?: string;
+}
+
+/** Scoped to a Liveboard. */
+export interface LiveboardScope extends EmbedEventPayloadBase {
+    liveboardId?: string;
+}
+
+/** Scoped to an Answer. */
+export interface AnswerScope extends EmbedEventPayloadBase {
+    answerId?: string;
+    vizId?: string;
+}
+
+/** Actions available on a viz within a Liveboard. */
+export interface LiveboardVizScope extends LiveboardScope, VizScope {}
+
+/** An empty payload — the event carries no data. */
+export type EmptyPayload = Record<string, never>;
+
+// ============================================================================
+// Event payloads — one interface per distinct shape.
+// ============================================================================
+
+/** The answer data backing the embed, delivered with {@link EmbedEvent.Data}. */
+export interface DataEventPayload extends VizScope {
+    embedAnswerData?: any;
+}
+
+/** {@link EmbedEvent.Error}. `message` may be a single string or a list. */
+export interface EmbedErrorPayload extends EmbedEventPayloadBase {
+    errorType?: any;
+    message?: string | string[];
+    code?: any;
+    error?: { message?: string };
+    errors?: string[];
+}
+
+export interface FilterChangedPayload extends EmbedEventPayloadBase {
+    liveboardFilters?: any[];
+    runtimeFilters?: RuntimeFilter[];
+}
+
+export interface CrossFilterChangedPayload extends EmbedEventPayloadBase {
+    action?: string;
+    filterContentList?: any;
+    filterRemoved?: string[];
+    removableColumnsFilterContent?: any;
+}
+
+export interface ParameterChangedPayload extends ConversationScope {
+    parameters?: any[];
+}
+
+export interface QueryChangedPayload extends VizScope {
+    search?: string;
+}
+
+/**
+ * Data-source(s) chosen in the picker. The host sends an object; older hosts may
+ * send a bare list of worksheet ids, so {@link EmbedEvent.DataSourceSelected}
+ * resolves to `string[] | DataSourceSelectedPayload`.
+ */
+export interface DataSourceSelectedPayload extends EmbedEventPayloadBase {
+    worksheetId?: string;
+    worksheetName?: string;
+    worksheetIds?: string[];
+}
+
+/** Shared by {@link EmbedEvent.VizPointClick} and its siblings. */
+export interface VizInteractionPayload extends VizScope {
+    clickedPoint?: any;
+    selectedPoints?: any[];
+    embedAnswerData?: any;
+}
+
+export interface DrilldownPayload extends ConversationScope {
+    drillColumn?: any;
+    clickedPoint?: any;
+    selectedPoints?: any[];
+}
+
+export interface TableVizRenderedPayload extends VizScope {
+    id?: string;
+    data?: any;
+}
+
+export interface SaveEventPayload extends LiveboardVizScope {
+    answerId?: string;
+}
+
+export interface MakeACopyPayload extends LiveboardVizScope {
+    newLiveboardId?: string;
+}
+
+/** Downloads, either viz/answer scoped or Liveboard scoped. */
+export interface DownloadEventPayload extends VizScope {
+    answerId?: string;
+    liveboardId?: string;
+}
+
+/** TML export/edit/update — answer or Liveboard scoped. */
+export interface TmlEventPayload extends EmbedEventPayloadBase {
+    answerId?: string;
+    liveboardId?: string;
+    vizId?: string;
+}
+
+export interface AnswerChartSwitcherPayload extends ConversationScope {
+    answerId?: string;
+    /** The mode switched to (chart or table). */
+    chartType?: string;
+}
+
+export interface CopyToClipboardPayload extends ConversationScope {
+    answerId?: string;
+}
+
+export interface PinEventPayload extends VizScope {
+    liveboardId?: string;
+    containerId?: string;
+    answerId?: string;
+}
+
+export interface CopyLinkPayload extends LiveboardScope {
+    vizId?: string;
+    metricId?: any;
+}
+
+export interface FavoritePayload extends LiveboardScope {
+    isFavorite?: boolean;
+}
+
+export interface TestScheduleEmailPayload extends LiveboardScope {
+    sendToSelf?: boolean;
+}
+
+/** Note: the app sends `liveboardID` (capital ID) for this event. */
+export interface RenamePayload extends EmbedEventPayloadBase {
+    liveboardID?: string;
+    vizId?: string;
+    title?: string;
+    description?: string;
+}
+
+export interface PersonalisedViewPayload extends LiveboardScope {
+    viewName?: string;
+    viewId?: string;
+    isPublic?: boolean;
+}
+
+export interface ExitPresentModePayload extends EmbedEventPayloadBase {
+    type?: string;
+    data?: any;
+}
+
+/** {@link EmbedEvent.AuthInit}. */
+export interface AuthInitPayload extends EmbedEventPayloadBase {
+    /** Whether authentication was successful. */
+    isLoggedIn?: boolean;
+}
+
+// ============================================================================
+// The map — every typed embed event, grouped by domain.
+// ============================================================================
+
 /**
- * Typed `data` field per embed event. Seed with audited events only.
+ * Typed `data` field per embed event. Events not listed resolve to `any`.
  */
 export interface EmbedEventDataExtension {
-    [EmbedEvent.AuthInit]: {
-        /**
-         * Whether authentication was successful.
-         */
-        isLoggedIn?: boolean;
-        [key: string]: any;
-    };
+    // --- Lifecycle and auth ---
+    [EmbedEvent.AuthInit]: AuthInitPayload;
     [EmbedEvent.EmbedListenerReady]: Record<string, any>;
+    [EmbedEvent.Error]: EmbedErrorPayload | string;
+
+    // --- Custom actions ---
     /**
      * Fired when a callback-type custom action is triggered. Use
-     * `payload.data.id` to identify which action fired.
+     * `payload.data.id` to identify which action fired; see also
+     * {@link CustomActionEventPayload} for the `answerService` enrichment.
      */
     [EmbedEvent.CustomAction]: CustomActionPayload;
+
+    // --- Filters and parameters ---
+    [EmbedEvent.FilterChanged]: FilterChangedPayload;
+    [EmbedEvent.CrossFilterChanged]: CrossFilterChangedPayload;
+    [EmbedEvent.ParameterChanged]: ParameterChangedPayload;
+
+    // --- Visualization interactions ---
+    [EmbedEvent.VizPointClick]: VizInteractionPayload;
+    [EmbedEvent.VizPointDoubleClick]: VizInteractionPayload;
+    [EmbedEvent.VizPointRightClick]: VizInteractionPayload;
+    [EmbedEvent.Drilldown]: DrilldownPayload;
+    [EmbedEvent.TableVizRendered]: TableVizRenderedPayload;
+
+    // --- Data and query ---
+    [EmbedEvent.Data]: DataEventPayload;
+    [EmbedEvent.QueryChanged]: string | QueryChangedPayload;
+
+    // --- Answer and viz actions ---
+    [EmbedEvent.Save]: SaveEventPayload;
+    [EmbedEvent.Edit]: LiveboardVizScope;
+    [EmbedEvent.Present]: LiveboardVizScope;
+    [EmbedEvent.Explore]: LiveboardVizScope;
+    [EmbedEvent.MakeACopy]: MakeACopyPayload;
+    [EmbedEvent.AnswerDelete]: AnswerScope;
+    [EmbedEvent.AnswerChartSwitcher]: AnswerChartSwitcherPayload;
+    [EmbedEvent.CopyToClipboard]: CopyToClipboardPayload;
+    [EmbedEvent.SpotIQAnalyze]: AnswerScope;
+    [EmbedEvent.ShowUnderlyingData]: AnswerScope;
+    [EmbedEvent.AddToCoaching]: VizScope;
+    [EmbedEvent.Pin]: PinEventPayload;
+
+    // --- Downloads ---
+    [EmbedEvent.Download]: VizScope;
+    [EmbedEvent.DownloadAsPng]: DownloadEventPayload;
+    [EmbedEvent.DownloadAsCsv]: DownloadEventPayload;
+    [EmbedEvent.DownloadAsXlsx]: DownloadEventPayload;
+    [EmbedEvent.DownloadAsPdf]: DownloadEventPayload;
+    [EmbedEvent.DownloadLiveboardAsContinuousPDF]: LiveboardScope;
+
+    // --- TML ---
+    [EmbedEvent.ExportTML]: TmlEventPayload;
+    [EmbedEvent.EditTML]: TmlEventPayload;
+    [EmbedEvent.UpdateTML]: TmlEventPayload;
+
+    // --- Liveboard actions ---
+    [EmbedEvent.Cancel]: LiveboardScope;
+    [EmbedEvent.Delete]: LiveboardScope;
+    [EmbedEvent.Schedule]: LiveboardScope;
+    [EmbedEvent.SchedulesList]: LiveboardScope;
+    [EmbedEvent.SendTestScheduleEmail]: TestScheduleEmailPayload;
+    [EmbedEvent.LiveboardInfo]: LiveboardScope;
+    [EmbedEvent.AIHighlights]: LiveboardScope;
+    [EmbedEvent.Rename]: RenamePayload;
+    [EmbedEvent.AddToFavorites]: FavoritePayload;
+    [EmbedEvent.CopyLink]: CopyLinkPayload;
+    [EmbedEvent.ExitPresentMode]: ExitPresentModePayload;
+
+    // --- Personalised views ---
+    [EmbedEvent.SavePersonalisedView]: PersonalisedViewPayload;
+    [EmbedEvent.UpdatePersonalisedView]: PersonalisedViewPayload;
+
+    // --- Columns and sources ---
+    [EmbedEvent.AddRemoveColumns]: string[];
+    [EmbedEvent.DataSourceSelected]: string[] | DataSourceSelectedPayload;
+
+    // --- Dialogs and lifecycle ---
+    [EmbedEvent.DialogOpen]: EmptyPayload;
+    [EmbedEvent.DialogClose]: EmptyPayload;
+    [EmbedEvent.LiveboardRendered]: EmptyPayload;
+    [EmbedEvent.RequestVisibleEmbedCoordinates]: EmptyPayload;
+    [EmbedEvent.EmbedIframeCenter]: EmptyPayload;
 }
 
+// ============================================================================
+// Resolvers — what `on()` delivers and how to annotate a callback.
+// ============================================================================
+
 /**
  * Resolves the typed `data` payload for an embed event; `any` when the
  * event has not been audited/typed yet.

package/src/contracts/host-event-contracts.ts

@@ -381,6 +381,7 @@ export interface HostEventRequestMap {
     [HostEvent.AIHighlights]: void;
     [HostEvent.SendTestScheduleEmail]: ScheduleEmailRequest;
     [HostEvent.RefreshLiveboardBrowserCache]: ScheduleEmailRequest;
+    [HostEvent.OpenAddTabModal]: void;
 
     // ==================== SPOTTER ====================
     [HostEvent.SpotterSearch]: SpotterSearchRequest;

package/src/css-variables.ts

@@ -1784,4 +1784,172 @@ export interface CustomCssVariables {
      * Background color of the shimmer sweep animation's gradient mid-stop.
      */
     '--ts-var-shimmer-sweep-background'?: string;
+
+    /**
+     * Secondary accent color. Used as the background of cross-filter chips in the
+     * filter panel and to highlight Liveboard visualizations and Answer headers
+     * impacted by a cross filter.
+     */
+    '--ts-var-root-secondary-color'?: string;
+
+    /**
+     * Background color of the action items in the top navigation bar, such as the
+     * search bar, Help menu, Org switcher, user menu, and notifications, on hover
+     * or when selected.
+     */
+    '--ts-var-nav-action-item-background'?: string;
+
+    /**
+     * Border color of the action items in the top navigation bar, such as the
+     * Org switcher and the search bar.
+     */
+    '--ts-var-nav-action-item-border-color'?: string;
+
+    /**
+     * Border color of the search bar in the top navigation bar on hover.
+     */
+    '--ts-var-nav-action-item-border-secondary-color'?: string;
+
+    /**
+     * Placeholder text color of the search bar and menus in the top navigation
+     * bar. Also used as the background of the Help menu button when the menu
+     * is open.
+     */
+    '--ts-var-nav-action-item-placeholder-color'?: string;
+
+    /**
+     * Background color of the natural language search bar header in Sage
+     * embed.
+     */
+    '--ts-var-sage-bar-header-background-color'?: string;
+
+    /**
+     * Background color of the data source selector in the natural language
+     * search bar.
+     */
+    '--ts-var-source-selector-background-color'?: string;
+
+    /**
+     * Background color of the data source selector in the natural language
+     * search bar on hover.
+     */
+    '--ts-var-source-selector-hover-color'?: string;
+
+    /**
+     * Font color of the text in the natural language search box.
+     */
+    '--ts-var-sage-search-box-font-color'?: string;
+
+    /**
+     * Background color of the natural language search box.
+     */
+    '--ts-var-sage-search-box-background-color'?: string;
+
+    /**
+     * Background color of the AI-generated answer container in Sage embed.
+     */
+    '--ts-var-sage-embed-background-color'?: string;
+
+    /**
+     * Background color of the suggested (seed) questions shown in the natural
+     * language search bar and Spotter.
+     */
+    '--ts-var-sage-seed-questions-background'?: string;
+
+    /**
+     * Font color of the suggested (seed) questions shown in the natural
+     * language search bar and Spotter.
+     */
+    '--ts-var-sage-seed-questions-font-color'?: string;
+
+    /**
+     * Background color of the suggested (seed) questions shown in the natural
+     * language search bar and Spotter on hover.
+     */
+    '--ts-var-sage-seed-questions-hover-background'?: string;
+
+    /**
+     * Background of the AI gradient border around the natural language search bar
+     * and the Spotter prompt input. Accepts any CSS background value, for example,
+     * a `linear-gradient(...)` or a solid color.
+     */
+    '--ts-var-ai-gradient-color'?: string;
+
+    /**
+     * Background color of the separator line between sections of a menu.
+     */
+    '--ts-var-menu-seperator-background'?: string;
+
+    /**
+     * Start color of the gradient background on the icon of custom menu items in
+     * the navigation. Defaults to the value of `--ts-var-root-color`.
+     */
+    '--ts-var-home-card-color'?: string;
+
+    /**
+     * Font color of the heading text on the suggestion cards in the favorites
+     * carousel on the Home page.
+     */
+    '--ts-var-home-favorite-suggestion-card-text-font-color'?: string;
+
+    /**
+     * Background color of a highlighted checkbox row on hover.
+     */
+    '--ts-var-checkbox-highlighted-hover-color'?: string;
+
+    /**
+     * Font family of the group title in a Liveboard. Defaults to the value of
+     * `--ts-var-viz-title-font-family`.
+     */
+    '--ts-var-liveboard-group-title-font-family'?: string;
+
+    /**
+     * Font family of the group description in a Liveboard. Defaults to the value
+     * of `--ts-var-viz-description-font-family`.
+     */
+    '--ts-var-liveboard-group-description-font-family'?: string;
+
+    /**
+     * Font family of the visualization titles inside a Liveboard group. Defaults
+     * to the value of `--ts-var-viz-title-font-family`.
+     */
+    '--ts-var-liveboard-group-tile-title-font-family'?: string;
+
+    /**
+     * Font family of the visualization descriptions inside a Liveboard group.
+     * Defaults to the value of `--ts-var-viz-description-font-family`.
+     */
+    '--ts-var-liveboard-group-tile-description-font-family'?: string;
+
+    /**
+     * Font color of the filter chips in a Liveboard on hover. Defaults to the
+     * value of `--ts-var-chip--hover-color`.
+     */
+    '--ts-var-liveboard-chip--hover-color'?: string;
+
+    /**
+     * Font color of the filter chips in a Liveboard when active. Defaults to the
+     * value of `--ts-var-chip--active-color`.
+     */
+    '--ts-var-liveboard-chip--active-color'?: string;
+
+    /**
+     * Background color of the styling panel in the Liveboard. Defaults to the
+     * value of `--ts-var-liveboard-edit-bar-background`.
+     */
+    '--ts-var-liveboard-styling-panel-background'?: string;
+
+    /**
+     * Border radius of the visualization container on the Answer page. On a
+     * Liveboard, this value is derived from `--ts-var-liveboard-tile-border-radius`
+     * and `--ts-var-viz-border-radius`; use those to style Liveboard tiles.
+     */
+    '--ts-var-tile-viz-border-radius'?: string;
+
+    /**
+     * Color of the outline (halo) drawn around data labels on charts, which keeps
+     * the labels readable over chart elements. Defaults to the value of
+     * `--ts-var-root-color`.
+     */
+    '--ts-var-chart-data-label-stroke-color'?: string;
 }