@thoughtspot/visual-embed-sdk 1.52.1 → 1.52.2-beta.0

package/dist/visual-embed-sdk-react-full.d.ts

@@ -7287,6 +7287,12 @@ export declare enum HostEvent {
 	 * ```js
 	 * const data = await liveboardEmbed.trigger(HostEvent.GetFilters);
 	 *     console.log('data', data);
+	 * // {
+	 * //   liveboardFilters: [ ... ],
+	 * //   runtimeFilters: [
+	 * //     { columnName: "Region", operator: "IN", values: ["West"] }
+	 * //   ]
+	 * // }
 	 * ```
 	 * @example
 	 * ```js
@@ -7311,9 +7317,9 @@ export declare enum HostEvent {
 	 *
 	 * Each filter object must include the following attributes:
 	 *
-	 * `column` - Name of the column to filter on.
+	 * `columnName` - Name of the column to filter on.
 	 *
-	 * `oper`  - Filter operator, for example, EQ, IN, CONTAINS.
+	 * `operator`  - Filter operator, for example, EQ, IN, CONTAINS.
 	 *  For information about the supported filter operators,
 	 *  see link:https://developers.thoughtspot.com/docs/runtime-filters#rtOperator[Developer Documentation].
 	 *
@@ -7340,8 +7346,8 @@ export declare enum HostEvent {
 	 *
 	 * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
 	 *     filter: {
-	 *         column: "item type",
-	 *         oper: "IN",
+	 *         columnName: "item type",
+	 *         operator: "IN",
 	 *         values: ["bags","shirts"]
 	 *        }
 	 *    });
@@ -7351,8 +7357,8 @@ export declare enum HostEvent {
 	 *
 	 * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
 	 *     filter: {
-	 *         column: "date",
-	 *         oper: "EQ",
+	 *         columnName: "date",
+	 *         operator: "EQ",
 	 *         values: ["JULY","2023"],
 	 *         type: "MONTH_YEAR"
 	 *        }
@@ -7363,18 +7369,18 @@ export declare enum HostEvent {
 	 * ```js
 	 * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
 	 *  filters: [{
-	 *      column: "Item Type",
-	 *      oper: 'IN',
+	 *      columnName: "Item Type",
+	 *      operator: 'IN',
 	 *      values: ["bags","shirts"]
 	 *  },
 	 *    {
-	 *      column: "Region",
-	 *      oper: 'IN',
+	 *      columnName: "Region",
+	 *      operator: 'IN',
 	 *      values: ["West","Midwest"]
 	 *  },
 	 *    {
-	 *      column: "Date",
-	 *      oper: 'EQ',
+	 *      columnName: "Date",
+	 *      operator: 'EQ',
 	 *      values: ["2023-07-31"],
 	 *      type: "EXACT_DATE"
 	 *    }]
@@ -7388,13 +7394,13 @@ export declare enum HostEvent {
 	 * ```js
 	 * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
 	 *  filters: [{
-	 *      column: "(Sample) Retail - Apparel::city",
-	 *      oper: 'IN',
+	 *      columnName: "(Sample) Retail - Apparel::city",
+	 *      operator: 'IN',
 	 *      values: ["atlanta"]
 	 *  },
 	 *  {
-	 *      column: "(Sample) Retail - Apparel::Region",
-	 *      oper: 'IN',
+	 *      columnName: "(Sample) Retail - Apparel::Region",
+	 *      operator: 'IN',
 	 *      values: ["West","Midwest"]
 	 *  }]
 	 * });
@@ -7405,8 +7411,8 @@ export declare enum HostEvent {
 	 * import { ContextType } from '@thoughtspot/visual-embed-sdk';
 	 * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
 	 *     filter: {
-	 *         column: "item type",
-	 *         oper: "IN",
+	 *         columnName: "item type",
+	 *         operator: "IN",
 	 *         values: ["shoes", "boots"]
 	 *     }
 	 * }, ContextType.Liveboard);
@@ -7416,8 +7422,8 @@ export declare enum HostEvent {
 	 * // Scope the filter to a specific Liveboard tab
 	 * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
 	 *     filter: {
-	 *         column: "item type",
-	 *         oper: "IN",
+	 *         columnName: "item type",
+	 *         operator: "IN",
 	 *         values: ["bags", "shirts"],
 	 *         applicability: {
 	 *             level: "TAB",
@@ -7426,6 +7432,12 @@ export declare enum HostEvent {
 	 *     }
 	 * });
 	 * ```
+	 * Use `columnName` and `operator` - the same spelling as
+	 * {@link RuntimeFilter}. The older `column` and `oper` spellings are
+	 * deprecated; they are still accepted, but pass only one spelling of each
+	 * field, never both. To reapply the filter state captured from
+	 * {@link EmbedEvent.FilterChanged}, use `convertFilterChangedToUpdateFiltersPayload`
+	 * to convert its payload into the shape expected here.
 	 * @version SDK: 1.23.0 | ThoughtSpot: 9.4.0.cl
 	 */
 	UpdateFilters = "updateFilters",
@@ -10467,7 +10479,19 @@ export declare enum Action {
 	 * }
 	 * ```
 	 */
-	DeleteCollection = "deleteCollection"
+	DeleteCollection = "deleteCollection",
+	/**
+	 * Controls the visibility of the "Customize homepage" button on the
+	 * embedded home page.
+	 * @version SDK: 1.55.0 | ThoughtSpot Cloud: 26.12.0.cl
+	 * @example
+	 * ```js
+	 * {
+	 *     hiddenActions: [Action.CustomizeHomepage],
+	 * }
+	 * ```
+	 */
+	CustomizeHomepage = "customizeHomepage"
 }
 export declare enum PrefetchFeatures {
 	FullApp = "FullApp",
@@ -11882,23 +11906,61 @@ export interface UpdateCrossFilterRequest {
 	conditions: CrossFilterCondition[];
 }
 /**
- * A single filter entry for {@link HostEvent.UpdateFilters}. Supports both
- * the current (columnName/operator) and legacy (column/oper) field names.
+ * The column to filter on. Supply `columnName`. A filter with no column is
+ * rejected at runtime, and passing both spellings silently discards the
+ * `column` one.
+ *
+ * When several columns share a name, qualify it as
+ * `WORKSHEET_NAME::COLUMN_NAME`, for example
+ * `"(Sample) Retail - Apparel::city"`.
  */
-export interface HostFilterUpdate {
-	columnName?: string;
+export type HostFilterUpdateColumn = {
+	/**
+	 * Name of the column to filter on, optionally qualified as
+	 * `WORKSHEET_NAME::COLUMN_NAME`.
+	 */
+	columnName: string;
+	column?: never;
+} | {
+	/**
+	 * @deprecated Use `columnName`, which matches {@link RuntimeFilter} and
+	 * the rest of the SDK. Still accepted, but not alongside `columnName`.
+	 */
+	column: string;
+	columnName?: never;
+};
+/**
+ * The filter operator. Supply `operator`. A filter with no operator is
+ * rejected at runtime, and passing both spellings silently discards the
+ * `oper` one.
+ */
+export type HostFilterUpdateOperator = {
+	/** Filter operator, for example EQ, IN, CONTAINS. */
+	operator: string;
+	oper?: never;
+} | {
+	/**
+	 * @deprecated Use `operator`, which matches {@link RuntimeFilter} and
+	 * the rest of the SDK. Still accepted, but not alongside `operator`.
+	 */
+	oper: string;
+	operator?: never;
+};
+/**
+ * A single filter entry for {@link HostEvent.UpdateFilters}.
+ *
+ * Use `columnName` and `operator` - the spelling used by
+ * {@link RuntimeFilter} and by the payload
+ * `convertFilterChangedToUpdateFiltersPayload` produces.
+ */
+export type HostFilterUpdate = HostFilterUpdateColumn & HostFilterUpdateOperator & {
 	columnId?: string;
-	operator?: string;
-	values: Array<string | number | boolean>;
+	values: Array<string | number | boolean | bigint>;
 	type?: string;
 	datePeriod?: string;
 	negate?: boolean;
-	/** Legacy field name for columnName. */
-	column?: string;
-	/** Legacy field name for operator. */
-	oper?: string;
 	applicability?: Applicability;
-}
+};
 /**
  * Request payload for {@link HostEvent.UpdateFilters} (singular or plural
  * form).
@@ -12157,8 +12219,8 @@ declare class HostEventClient {
 	protected handleDrillDownEvent(payload: HostEventRequest<HostEvent.DrillDown>, context?: ContextType): Promise<any>;
 	/**
 	 * Dispatches a host event using the appropriate channel:
-	 * 1. If the embedded app supports UI passthrough for this event, use it (custom handler or getter).
-	 * 2. Otherwise fall back to the legacy host event channel.
+	 * 1. If the embedded app supports UI passthrough for this event, use it (custom
+	 * handler or getter). 2. Otherwise fall back to the legacy host event channel.
 	 *
 	 * @param hostEvent - The host event to trigger
 	 * @param payload - Optional payload for the event
@@ -12233,7 +12295,7 @@ declare class TsEmbed {
 	private defaultHiddenActions;
 	private resizeObserver;
 	private preRenderContainerEl;
-	private containerScrollListener;
+	/** Last height the embedded app reported, once fullHeight has measured one. */
 	protected hostEventClient: HostEventClient;
 	protected isReadyForRenderPromise: Promise<void>;
 	protected shouldWaitForRenderPromise: boolean;
@@ -12489,10 +12551,26 @@ declare class TsEmbed {
 	 */
 	private createPreRenderPlaceholder;
 	/**
-	 * Resolves the configured preRenderContainer to a live element, falling
-	 * back to `document.body`. A string selector is re-queried on every call so
-	 * a remounted container (E.g.: React replacing the node) resolves to the
-	 * fresh element; an element passed directly cannot be re-resolved.
+	 * Resolves the configured preRenderContainer to a live element. A string
+	 * selector is re-queried on every call so a remounted container (E.g.: React
+	 * replacing the node) resolves to the fresh element; an element passed
+	 * directly cannot be re-resolved.
+	 *
+	 * With nothing configured the frame goes into the host element's nearest
+	 * scrolling ancestor, falling back to `document.body`.
+	 *
+	 * The wrapper is absolutely positioned, so it follows the page for free —
+	 * but only while it sits inside whatever scrolls. `document.body` is right
+	 * only when the document itself is the scroller; an app that scrolls an
+	 * inner element instead left the frame pinned to the viewport while the page
+	 * moved under it (SCAL-338563). Being inside the scroller also lets wheel
+	 * events chain out of the frame into it, which they cannot do from
+	 * `document.body`.
+	 *
+	 * A scrolling ancestor is layout chrome rather than route content, so it
+	 * outlives the embed in practice; and if it does go, the host element goes
+	 * with it and this instance is remounting anyway.
+	 * `reconcilePreRenderContainer` re-runs this on a detached container.
 	 */
 	private resolvePreRenderContainerTarget;
 	private inheritPreRenderContainer;
@@ -12509,8 +12587,9 @@ declare class TsEmbed {
 	 * Re-attaches the wrapper to a live container when the previously resolved
 	 * one has been detached or no longer holds the wrapper — e.g. the host app
 	 * remounted a custom preRenderContainer, which would otherwise leave a stale
-	 * reference and collapse the wrapper. Only string selectors can be
-	 * re-resolved; a container passed as an element is left untouched.
+	 * reference and collapse the wrapper. Selectors and the auto-resolved
+	 * scrolling ancestor are both re-resolved; a container passed as an element
+	 * is left untouched, as there is nothing to re-query.
 	 */
 	private reconcilePreRenderContainer;
 	protected insertIntoDOMForPreRender(child: string | Node): void;
@@ -12726,9 +12805,17 @@ declare class TsEmbed {
 	 */
 	private restorePreRenderContainerPosition;
 	/**
-	 * Detaches and clears the container scroll listener, if one is attached.
+	 * Re-sizes the wrapper when its placeholder changes size.
+	 *
+	 * Position deliberately has no equivalent. An absolutely positioned wrapper
+	 * follows its containing block for free, so a correctly placed frame is the
+	 * browser's job and costs nothing; repositioning it on scroll would mean a
+	 * layout read and a style write per frame to compensate for placing it in
+	 * the wrong box. Size is the one thing the browser will not do for us: the
+	 * placeholder grows when the embedded app reports a new height, and the
+	 * wrapper has to be told.
 	 */
-	private removeContainerScrollListener;
+	private observePreRenderSize;
 	/**
 	 * Destroys the ThoughtSpot embed, and remove any nodes from the DOM.
 	 * @version SDK: 1.19.1 | ThoughtSpot: *
@@ -14078,6 +14165,7 @@ export interface SpotterAppInitData extends DefaultAppInitData {
 		spotterShareConversationConfig?: SpotterShareConversationConfig;
 		visualOverridesParams?: VisualizationOverrides | null;
 		starterPrompts?: StarterPromptsConfig;
+		spotterAnalystConfig?: SpotterAnalystConfig;
 	};
 }
 declare class SpotterEmbed extends TsEmbed {
@@ -14799,9 +14887,10 @@ export interface AppViewConfig extends AllEmbedViewConfig, FullHeightViewConfig
 	 */
 	isPNGInScheduledEmailsEnabled?: boolean;
 	/**
-	 * Enables the 'what you see is what you get' PDF export for Liveboards. Each tab is rendered on a single page
-	 * following the exact UI layout, instead of splitting visualizations across multiple A4 pages.
-	 * This feature is GA from SDK version 1.51.0 and ThoughtSpot version 26.8.0.cl.
+	 * Enables the 'what you see is what you get' PDF export for Liveboards. Each tab is
+	 * rendered on a single page following the exact UI layout, instead of splitting
+	 * visualizations across multiple A4 pages. This feature is GA from SDK version
+	 * 1.51.0 and ThoughtSpot version 26.8.0.cl.
 	 *
 	 * Supported embed types: `AppEmbed`, `LiveboardEmbed`
 	 * @type {boolean}
@@ -15485,9 +15574,10 @@ export interface LiveboardViewConfig extends BaseViewConfig, FullHeightViewConfi
 	 */
 	isPNGInScheduledEmailsEnabled?: boolean;
 	/**
-	 * Enables the 'what you see is what you get' PDF export for Liveboards. Each tab is rendered on a single page
-	 * following the exact UI layout, instead of splitting visualizations across multiple A4 pages.
-	 * This feature is GA from SDK version 1.51.0 and ThoughtSpot version 26.8.0.cl.
+	 * Enables the 'what you see is what you get' PDF export for Liveboards. Each tab is
+	 * rendered on a single page following the exact UI layout, instead of splitting
+	 * visualizations across multiple A4 pages. This feature is GA from SDK version
+	 * 1.51.0 and ThoughtSpot version 26.8.0.cl.
 	 *
 	 * Supported embed types: `AppEmbed`, `LiveboardEmbed`
 	 * @type {boolean}
@@ -15911,6 +16001,100 @@ declare const getEmbedConfig: () => EmbedConfig;
  * @param eventProps
  */
 export declare function uploadMixpanelEvent(eventId: string, eventProps?: {}): void;
+export interface FilterChangedFilterContentValue {
+	key?: string | number | boolean | null;
+}
+export interface FilterChangedFilterContent {
+	filterType?: string;
+	negate?: boolean;
+	value?: FilterChangedFilterContentValue[];
+}
+export interface FilterChangedDateFilterValue {
+	type?: string;
+	op?: string;
+	epoch?: string | number | null;
+	dateRange?: {
+		lowEpoch?: string | number | null;
+		highEpoch?: string | number | null;
+	};
+	monthName?: string;
+	quarterName?: string;
+	yearName?: string;
+	number?: number | null;
+	datePeriod?: string;
+	includeCurrentPeriod?: boolean | null;
+}
+export interface FilterChangedDateFilterContent {
+	negate?: boolean;
+	dateFilter?: FilterChangedDateFilterValue;
+}
+export interface FilterChangedFilter {
+	filterContent?: FilterChangedFilterContent[];
+	dateFilterContent?: FilterChangedDateFilterContent[];
+}
+export interface FilterChangedFilterGroup {
+	columnInfo?: {
+		name?: string;
+	};
+	filters?: FilterChangedFilter[];
+	/**
+	 * Scope of the filter - `LIVEBOARD`, `TAB` or `GROUP`. Present from
+	 * SDK 1.53.0 / ThoughtSpot 26.10.0.cl. Omitted means Liveboard level.
+	 */
+	applicability?: Applicability;
+}
+/**
+ * Shape of the payload received via `LiveboardEmbed.on(EmbedEvent.FilterChanged, ...)`.
+ */
+export interface FilterChangedPayload {
+	liveboardFilters?: FilterChangedFilterGroup[];
+	runtimeFilters?: RuntimeFilter[];
+}
+export interface UpdateFiltersFilterParam {
+	columnName: string;
+	operator: string;
+	values: (string | number | boolean | bigint)[];
+	type?: string;
+	datePeriod?: string;
+	negate?: boolean;
+	includeCurrentPeriod?: boolean;
+	applicability?: Applicability;
+}
+/**
+ * Shape expected by `liveboardEmbed.trigger(HostEvent.UpdateFilters, ...)`.
+ */
+export interface UpdateFiltersPayload {
+	filters: UpdateFiltersFilterParam[];
+}
+/**
+ * Converts the payload emitted by {@link EmbedEvent.FilterChanged} into the
+ * payload shape expected by {@link HostEvent.UpdateFilters}, so the same
+ * filter state can be captured and re-applied later, for example on a
+ * subsequent page load.
+ *
+ * Both the Liveboard filters and the runtime filters present in the
+ * `FilterChanged` payload are included in the returned `filters` array.
+ *
+ * Note: a column with multiple date-filter conditions (e.g. an OR of two
+ * date ranges) is not guaranteed to round-trip losslessly - `HostEvent.UpdateFilters`
+ * treats date filters as replace-not-merge per column, so only the last
+ * converted entry for such a column will apply.
+ * @param filterChangedPayload The filter state carried by the
+ * `EmbedEvent.FilterChanged` callback, which is `payload.data` - the
+ * callback argument is the event envelope, and the filters sit under its
+ * `data` key.
+ * @example
+ * ```js
+ * let savedFilters;
+ * liveboardEmbed.on(EmbedEvent.FilterChanged, (payload) => {
+ *     savedFilters = convertFilterChangedToUpdateFiltersPayload(payload.data);
+ * });
+ *
+ * // later, e.g. after a fresh page load
+ * liveboardEmbed.trigger(HostEvent.UpdateFilters, savedFilters);
+ * ```
+ */
+export declare function convertFilterChangedToUpdateFiltersPayload(filterChangedPayload: FilterChangedPayload): UpdateFiltersPayload;
 /**
  * Resets the auth token and a new token will be fetched on the next request.
  * @example