@sisense/sdk-ui 2.29.0 → 2.31.0

package/dist/packages/sdk-ui/src/domains/narrative/core/widget-narrative-config.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Location where the narrative is displayed in the widget.
+ *
+ * - `above`: displayed above the widget
+ * - `below`: displayed below the widget
+ * - `alone`: displayed alone, without any other widget content
+ *
+ * @default 'above'
+ */
+export type WidgetNarrativeDisplayLocation = 'above' | 'below' | 'alone';
+/**
+ * Narrative configuration options for widgets.
+ *
+ * Set on a chart or pivot widget via {@link WidgetConfig}.
+ */
+export type WidgetNarrativeConfig = {
+    /**
+     * Verbosity for narrative generation.
+     *
+     * @default low
+     */
+    verbosity?: 'low' | 'high';
+    /**
+     * Whether to include trend and forecast in the narrative.
+     *
+     * When `true`, any trend and forecast companion measures present on the widget are included in the narrative request.
+     *
+     * When `false`, they are not included in the narrative request.
+     *
+     * @default true
+     */
+    includeTrendAndForecast?: boolean;
+    /**
+     * Whether the narrative is enabled for the widget.
+     *
+     * When `true`, narrative is enabled for the widget.
+     *
+     * When `false`, narrative is disabled for the widget and will not be generated.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Location where the narrative is displayed in the widget. See {@link WidgetNarrativeDisplayLocation} for more details.
+     *
+     * @default 'above'
+     */
+    displayLocation?: WidgetNarrativeDisplayLocation;
+    /**
+     * Whether the narrative auto-shows on load without user interaction.
+     *
+     * When `true`, narrative is requested and displayed as soon as the widget loads.
+     *
+     * When `false`, narrative is requested and displayed only after user interaction.
+     *
+     * @default true (for backwards compatibility with older narrative settings in Fusion widgets)
+     */
+    autoShow?: boolean;
+    /**
+     * Settings for interactive AI feedback icons.
+     */
+    feedback?: {
+        /**
+         * Whether the interactive AI feedback icons are enabled.
+         *
+         * When `true`, the interactive AI feedback icons are shown.
+         *
+         * When `false`, the interactive AI feedback icons are not shown.
+         *
+         * @default false
+         */
+        enabled?: boolean;
+    };
+    /**
+     * Maximum fraction of the content area height the narrative area may occupy.
+     *
+     * The content area is the space below the widget header — i.e. the area previously occupied
+     * by the chart alone. `heightFraction = 0.5` therefore means the narrative receives half the space that
+     * was available to the chart.
+     *
+     * Accepts a value in the range `0`–`1`.
+     * - `undefined` (default): narrative takes whatever vertical space it needs; the chart fills the rest.
+     * - `0.3`: narrative is capped at 30 % of the content area; the chart always receives the remaining 70 %.
+     *
+     * Practical guidelines:
+     * - Values above `~0.8` leave very little room for the chart.
+     * - Values below `~0.1` may clip the collapsed narrative text (~46 px).
+     * - Has no effect when {@link WidgetNarrativeConfig.displayLocation | displayLocation} is `'alone'`
+     *   (the chart is already hidden in that mode).
+     */
+    heightFraction?: number;
+};
+/**
+ * {@link WidgetNarrativeConfig} with all optional fields filled using {@link getCompleteWidgetNarrativeConfig}.
+ */
+export type CompleteWidgetNarrativeConfig = {
+    enabled: boolean;
+    verbosity: 'low' | 'high';
+    displayLocation: WidgetNarrativeDisplayLocation;
+    autoShow: boolean;
+    includeTrendAndForecast: boolean;
+    feedback: {
+        enabled: boolean;
+    };
+    /** Resolved from {@link WidgetNarrativeConfig.heightFraction}. `undefined` means no constraint. */
+    heightFraction: number | undefined;
+};
+/**
+ * Returns {@link WidgetNarrativeConfig} with defaults applied for runtime.
+ *
+ * @param narrative - Optional narrative configuration to apply defaults to
+ * @returns Complete narrative configuration with defaults applied
+ */
+export declare function getCompleteWidgetNarrativeConfig(narrative?: WidgetNarrativeConfig): CompleteWidgetNarrativeConfig;

package/dist/packages/sdk-ui/src/domains/narrative/core/widget-props-to-narrative-params.d.ts

@@ -4,49 +4,66 @@ import type { PivotTableWidgetProps } from '../../../domains/widgets/components/
 import type { WidgetProps, WithCommonWidgetProps } from '../../../domains/widgets/components/widget/types';
 import type { NarrativeRequest } from '../../../infra/api/narrative/narrative-api-types.js';
 import type { NarrativeQueryParams } from './build-narrative-request.js';
+import { type CompleteWidgetNarrativeConfig } from './widget-narrative-config.js';
 /**
  * Converts ChartWidgetProps to {@link NarrativeQueryParams} by extracting dimensions and measures
  * from the chart data options.
  *
- * @param props - ChartWidgetProps to convert
+ * @param props - ChartWidgetProps to convert. `config.narrative` supplies {@link WidgetNarrativeConfig}. Defaults are calculated via {@link getCompleteWidgetNarrativeConfig}
  * @param defaultDataSource - Optional default data source to use if props.dataSource is undefined
- * @param verbosity - Optional verbosity for narrative text
- * @param ignoreTrendAndForecast - When `true`, omits trend/forecast companion measures from the narrative JAQL
  * @returns Params ready for {@link prepareNarrativeRequest}
  * @throws If neither `props.dataSource` nor `defaultDataSource` is set
  * @internal
  */
-export declare function convertChartWidgetPropsToNarrativeParams(props: ChartWidgetProps, defaultDataSource?: DataSource, verbosity?: 'Low' | 'High', ignoreTrendAndForecast?: boolean): NarrativeQueryParams;
+export declare function convertChartWidgetPropsToNarrativeParams(props: ChartWidgetProps, defaultDataSource?: DataSource): NarrativeQueryParams;
 /**
  * Builds a narrative API request from pivot widget props using the same JAQL as pivot query
  * execution ({@link getPivotJaqlQueryPayload}).
  *
- * @param props - Pivot widget props (`widgetType: 'pivot'`)
+ * @param props - Pivot widget props (`widgetType: 'pivot'`); `config.narrative` supplies
+ *   {@link WidgetNarrativeConfig} via {@link getWidgetNarrativeConfigFromWidgetProps}
  * @param defaultDataSource - Used when `props.dataSource` is undefined
- * @param verbosity - Optional verbosity for narrative text
- * @param ignoreTrendAndForecast - When `true`, omits trend/forecast from pivot value columns in the narrative JAQL
  * @returns Request ready for `getNarrative`
  * @throws If data source cannot be resolved, or pivot query description is invalid
  * @internal
  */
-export declare function convertPivotWidgetPropsToNarrativeRequest(props: WithCommonWidgetProps<PivotTableWidgetProps, 'pivot'>, defaultDataSource?: DataSource, verbosity?: 'Low' | 'High', ignoreTrendAndForecast?: boolean): NarrativeRequest;
+export declare function convertPivotWidgetPropsToNarrativeRequest(props: WithCommonWidgetProps<PivotTableWidgetProps, 'pivot'>, defaultDataSource?: DataSource): NarrativeRequest;
 /**
- * @deprecated Use {@link convertChartWidgetPropsToNarrativeParams}. Same function; kept for legacy `getNlgInsightsFromWidget`.
+ * @deprecated Use {@link convertChartWidgetPropsToNarrativeParams} for {@link NarrativeQueryParams},
+ *   or {@link convertWidgetPropsToNarrativeParams} for a ready {@link NarrativeRequest}.
  */
 export declare const convertChartWidgetPropsToUseGetNlgInsightsParams: typeof convertChartWidgetPropsToNarrativeParams;
 /**
- * Error message for imperative callers (e.g. {@link getNlgInsightsFromWidget}) when chart or pivot
- * props omit `dataSource` and no `defaultDataSource` is passed.
+ * Builds a {@link NarrativeRequest} from chart or pivot widget props (including `id` / `widgetType`).
  *
+ * @param props - Chart or pivot {@link WidgetProps}
+ * @param defaultDataSource - Used when `props.dataSource` is undefined
+ * @returns Request ready for {@link getNarrative}
+ * @throws If widget type is not chart or pivot, data source cannot be resolved, or conversion fails
+ * @internal
+ */
+export declare function convertWidgetPropsToNarrativeParams(props: WithCommonWidgetProps<ChartWidgetProps, 'chart'> | WithCommonWidgetProps<PivotTableWidgetProps, 'pivot'>, defaultDataSource?: DataSource): NarrativeRequest;
+/**
+ * Completes widget narrative options from chart/pivot `WidgetProps` for NLG (`config.narrative`).
+ *
+ * @param props - Widget props (chart, pivot, or other)
+ * @returns Complete narrative defaults for non-chart/pivot types
  * @internal
  */
-export declare const MISSING_DATASOURCE_NLG_ERROR = "dataSource is required. Provide it on the widget props or as defaultDataSource parameter.";
+export declare function getCompleteWidgetNarrativeConfigFromWidgetProps(props: WidgetProps): CompleteWidgetNarrativeConfig;
+/**
+ * Error message for imperative callers (e.g. {@link getNlgInsightsFromWidget}) when chart or pivot widget
+ * props omit `dataSource`, no defaultDataSource can be resolved from app context, and no defaultDataSource is provided.
+ *
+ * @internal
+ */
+export declare const MISSING_DATASOURCE_NLG_ERROR = "dataSource is required. Provide it on the widget props, defaultDataSource parameter or via SisenseContextProvider.";
 export type WidgetNarrativeRequestPair = {
     supported: boolean;
     narrativeRequest: NarrativeRequest | undefined;
     /**
-     * Same request with trend/forecast stripped. `undefined` when `ignoreTrendAndForecast` is
-     * already `true` (primary already stripped), when the widget type is unsupported, or when
+     * Same request with trend/forecast stripped. `undefined` when `includeTrendAndForecast` is
+     * already `false` (primary already stripped), when the widget type is unsupported, or when
      * the fallback conversion itself fails.
      */
     narrativeFallbackRequest: NarrativeRequest | undefined;
@@ -61,26 +78,12 @@ export type WidgetNarrativeRequestPair = {
  * stripped — both from the same widget props in a single call.
  *
  * @param props - Chart or pivot widget props
- * @param defaultDataSource - Used when `props.dataSource` is undefined
- * @param verbosity - Optional verbosity for narrative text
- * @param ignoreTrendAndForecast - When `true`, the primary request already omits trend/forecast
- *   and no fallback is needed
+ * @param defaultDataSource - Used when `props.dataSource` is undefined.
  * @returns `{ supported, narrativeRequest, narrativeFallbackRequest }`. `supported` is `false`
  *   when the widget type is unsupported, when no data source can be resolved for chart/pivot, or
  *   when the primary conversion fails.
- * @example Chart or pivot widget props
- * ```ts
- * const { supported, narrativeRequest, narrativeFallbackRequest } =
- *   buildWidgetNarrativeRequests(
- *     widgetProps, // `WithCommonWidgetProps<ChartWidgetProps, 'chart'>` or pivot equivalent
- *     defaultDataSource,
- *     'High',
- *     false,
- *   );
- * ```
- * On success, `supported` is `true` and `narrativeRequest` / `narrativeFallbackRequest` hold the
- * primary and trend-stripped NLG payloads; otherwise `supported` is `false` and requests are
- * `undefined` (and `missingDataSource` may be set when no source could be resolved).
+ * @remarks {@link WidgetNarrativeConfig} are derived from `props.config?.narrative`
+ *   via {@link getWidgetNarrativeConfigFromWidgetProps} and {@link getCompleteWidgetNarrativeConfig}.
  * @internal
  */
-export declare function buildWidgetNarrativeRequests(props: WidgetProps, defaultDataSource?: DataSource, verbosity?: 'Low' | 'High', ignoreTrendAndForecast?: boolean): WidgetNarrativeRequestPair;
+export declare function buildWidgetNarrativeRequests(props: WidgetProps, defaultDataSource?: DataSource): WidgetNarrativeRequestPair;

package/dist/packages/sdk-ui/src/domains/narrative/hooks/use-get-widget-narrative.d.ts

@@ -1,42 +1,33 @@
 import type { WidgetProps } from '../../../domains/widgets/components/widget/types';
-import type { WidgetNarrativeOptions } from '../core/widget-narrative-options.js';
+import type { HookEnableParam } from '../../../shared/hooks/types';
 import { type WidgetNarrativeQueryState } from './use-widget-narrative-state.js';
 /**
- * Options for {@link useGetWidgetNarrative}.
+ * Parameters for {@link useGetWidgetNarrative}.
  *
  * @remarks
- * Narration endpoint selection defaults from `app.settings.narrative.canGenerateNarrativeViaAI`
- * on {@link useSisenseContext} when `canGenerateNarrativeViaAI` is omitted. Optional overrides
- * match the imperative `getNlgInsightsFromWidget` helper for per-call behavior.
- * @sisenseInternal
- */
-export type UseGetWidgetNarrativeOptions = WidgetNarrativeOptions & {
-    /**
-     * When `false`, skips the narrative request.
-     *
-     * @default true
-     */
-    enabled?: boolean;
-};
-/**
+ * Narrative endpoint selection uses `app.settings.narrative.canGenerateNarrativeViaAI` from
+ * {@link useSisenseContext}. {@link WidgetNarrativeConfig} come from
+ * `widgetProps.config.narrative` (see {@link getCompleteWidgetNarrativeConfig}).
+ *
+ * The `enabled` flag follows {@link HookEnableParam} (defaults to `true` when omitted).
  * @sisenseInternal
  */
 export type UseGetWidgetNarrativeParams = {
     /** Widget configuration whose query drives the narrative (chart or pivot). */
     widgetProps: WidgetProps;
-} & UseGetWidgetNarrativeOptions;
+} & HookEnableParam;
 /**
  * @sisenseInternal
  */
 export type UseGetWidgetNarrativeResult = WidgetNarrativeQueryState & {
     /**
      * `true` when `widgetProps` is a chart or pivot widget and narrative params could be built
-     * (including resolving `dataSource` via `defaultDataSource`).
+     * (including resolving `dataSource` via context `defaultDataSource` when omitted on props).
      */
     supported: boolean;
     /**
-     * Mirrors {@link UseGetWidgetNarrativeOptions.enabled}. When `false`, narrative is opted out and
-     * `data` is not populated from cache.
+     * Effective value after applying {@link HookEnableParam} defaults (always `true` or `false`).
+     * When `false`, narrative is opted out and `data` is not populated from cache.
      */
     enabled: boolean;
 };
@@ -53,8 +44,6 @@ export type UseGetWidgetNarrativeResult = WidgetNarrativeQueryState & {
  * ```tsx
  * const { data, isLoading, supported } = useGetWidgetNarrative({
  *   widgetProps,
- *   defaultDataSource: DM.DataSource,
- *   verbosity: 'Low',
  * });
  * ```
  * @sisenseInternal

package/dist/packages/sdk-ui/src/domains/narrative/hooks/use-line-height.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="react" />
+/**
+ * Measures the line height of the element referenced by `ref` in pixels.
+ * Re-measures on resize and after fonts load. Returns `null` until measured.
+ *
+ * @param ref - Ref to the element whose line height should be measured.
+ * @returns The line height in pixels, or `null` if not yet measured.
+ * @internal
+ */
+export declare function useLineHeight<T extends HTMLElement>(ref: React.RefObject<T | null>): number | null;

package/dist/packages/sdk-ui/src/domains/narrative/hooks/use-widget-narrative-state.d.ts

@@ -1,6 +1,6 @@
 import { WidgetProps } from '../../../domains/widgets/components/widget/types';
 import type { NarrativeRequest } from '../../../infra/api/narrative/narrative-api-types.js';
-import type { WidgetNarrativeOptions } from '../core/widget-narrative-options.js';
+import type { HookEnableParam } from '../../../shared/hooks/types';
 /**
  * Hook state aligned with legacy {@link UseGetNlgInsightsState}; used by {@link useGetWidgetNarrative}.
  *
@@ -16,24 +16,23 @@ export type WidgetNarrativeQueryState = {
 };
 export type UseWidgetNarrativeStateParams = {
     widgetProps: WidgetProps;
-    enabled?: boolean;
-} & WidgetNarrativeOptions;
+} & HookEnableParam;
 export type UseWidgetNarrativeStateResult = WidgetNarrativeQueryState & {
     supported: boolean;
     /**
-     * Mirrors the `enabled` param. When `false`, the narrative is opted out: `data` is cleared (no
-     * cached fallback), `narrativeRequest` is undefined, and loading/error flags reflect a disabled
-     * query rather than "no insights."
+     * Effective value after applying {@link HookEnableParam} defaults (always `true` or `false`).
+     * When `false`, narrative is opted out: `data` is cleared (no cached fallback), `narrativeRequest`
+     * is undefined, and loading/error flags reflect a disabled query rather than "no insights."
      */
     enabled: boolean;
     /** Present when `supported` and `enabled`; used by {@link WidgetNarrative} for feedback payload only. */
     narrativeRequest: NarrativeRequest | undefined;
 };
 /**
- * Resolves chart or pivot widget props to a narration request and runs `getNarrative` via TanStack Query.
- * Depends on {@link useSisenseContext} (`httpClient`, narration settings) and a `QueryClientProvider`.
+ * Resolves chart or pivot widget props to a narrative request and runs `getNarrative` via TanStack Query.
+ * Depends on {@link useSisenseContext} (`httpClient`, narrative settings) and a `QueryClientProvider`.
  * Not exported from `@sisenseInternal` public API.
  *
  * @internal
  */
-export declare function useWidgetNarrativeState({ widgetProps, defaultDataSource, verbosity, enabled, ignoreTrendAndForecast, canGenerateNarrativeViaAI: optionsCanGenerateNarrativeViaAI, }: UseWidgetNarrativeStateParams): UseWidgetNarrativeStateResult;
+export declare function useWidgetNarrativeState({ widgetProps, enabled, }: UseWidgetNarrativeStateParams): UseWidgetNarrativeStateResult;

package/dist/packages/sdk-ui/src/domains/query-execution/core/execute-query.d.ts

@@ -1,6 +1,6 @@
 import { Attribute, DataSource, Measure, PivotAttribute, PivotMeasure, PivotQueryResultData, QueryResultData } from '@sisense/sdk-data';
 import type { PivotQueryDescription as InternalPivotQueryDescription, QueryDescription as InternalQueryDescription, QueryExecutionConfig } from '@sisense/sdk-query-client';
-import { CreateCacheKeyFn } from '../../../shared/utils/create-cache';
+import { CacheKey, CreateCacheKeyFn } from '../../../shared/utils/create-cache';
 import { type ClientApplication } from '../../../infra/app/types.js';
 /**
  * All the properties that fully describe a query you want to send.
@@ -30,9 +30,42 @@ export declare const prepareQueryParams: (queryDescription: QueryDescription, de
 /** @internal */
 export declare function executeQuery(queryDescription: QueryDescription, app: ClientApplication, executionConfig?: QueryExecutionConfig): Promise<QueryResultData>;
 /** @internal */
+export declare function executeRowCountQuery(queryDescription: QueryDescription, app: ClientApplication, executionConfig?: QueryExecutionConfig): Promise<number>;
+/** Result of a data query executed together with its total row count. */
+export type QueryResultWithRowCount = {
+    data: QueryResultData;
+    /**
+     * Total row count of the query, ignoring `count`/`offset` paging.
+     * Undefined when the total could not be retrieved.
+     */
+    rowCount?: number;
+};
+/**
+ * Executes a data query together with a row count query and returns both the
+ * result data and the total row count.
+ *
+ * A row count failure does not fail the data query: `rowCount` is left
+ * undefined when the total cannot be retrieved (e.g. a Sisense instance
+ * without the row count API).
+ *
+ * @internal
+ */
+export declare function executeQueryWithRowCount(queryDescription: QueryDescription, app: ClientApplication, executionConfig?: QueryExecutionConfig, baseExecuteQuery?: typeof executeQuery): Promise<QueryResultWithRowCount>;
+/** @internal */
 export declare const executeCsvQuery: (queryDescription: QueryDescription, app: ClientApplication, executionConfig?: QueryExecutionConfig) => Promise<Blob>;
 /** @internal */
 export declare const executePivotQuery: (queryDescription: PivotQueryDescription, app: ClientApplication, executionConfig?: QueryExecutionConfig) => Promise<PivotQueryResultData>;
 export declare const createExecuteQueryCacheKey: CreateCacheKeyFn<typeof executeQuery>;
 export declare const executeQueryWithCache: typeof executeQuery;
 export declare const clearExecuteQueryCache: (specificKey?: string | undefined) => void;
+/**
+ * Creates a cache key for a row count query.
+ *
+ * The key is page-independent: `count` and `offset` are excluded so the total
+ * row count is reused across pages of the same query.
+ *
+ * @internal
+ */
+export declare const createRowCountQueryCacheKey: CreateCacheKeyFn<typeof executeRowCountQuery>;
+/** @internal */
+export declare const clearRowCountQueryCache: (specificKey?: CacheKey) => void;

package/dist/packages/sdk-ui/src/domains/query-execution/hooks/use-execute-excel-query/excel-export/build-jaql-excel-export.d.ts

@@ -1,4 +1,4 @@
-import { type Attribute, type DataSource, type Measure } from '@sisense/sdk-data';
+import { type Attribute, type DataSource, type Filter, type FilterRelations, type Measure, type MetadataItem } from '@sisense/sdk-data';
 /** `by` field for JAQL export requests. */
 export declare const EXCEL_EXPORT_JAQL_BY = "export";
 /**
@@ -16,6 +16,7 @@ type ExcelExportJaqlWidgetContext = {
 type XlsxExportQueryParams = {
     dimensions?: readonly Attribute[];
     measures?: readonly Measure[];
+    filters?: readonly Filter[] | FilterRelations;
 };
 /**
  * Resolves XLSX metadata `panel` for a dimension.
@@ -32,17 +33,24 @@ export declare function resolveExcelDimensionMetadataPanel(dimension: Attribute,
  */
 export declare function createPanelsMetadataForXlsx(dimensions: XlsxExportQueryParams['dimensions'], measures: XlsxExportQueryParams['measures'], mergeRows: boolean): {
     jaql: {
-        column: any;
-        title: any;
-        dim: any;
+        column: string | undefined;
+        title: string | undefined;
+        dim: string | undefined;
         merged: boolean;
     };
     field: {
         id: string;
         index: number;
     };
-    format: Record<string, any>;
+    format: Record<string, unknown>;
     panel: "measures" | ExcelExportDimensionPanel;
 }[];
+/**
+ * Returns `scope`-panel metadata for filters.
+ *
+ * @param filters - Scope filters (plain list or filter relations)
+ * @returns Filter metadata for the export JAQL
+ */
+export declare function createFiltersMetadataForXlsx(filters: readonly Filter[] | FilterRelations | undefined): MetadataItem[];
 export declare function buildJaqlForExcelExport(params: XlsxExportQueryParams, context: ExcelExportJaqlWidgetContext): Record<string, unknown>;
 export {};

package/dist/packages/sdk-ui/src/domains/query-execution/hooks/use-execute-excel-query/excel-export/build-xlsx-export-payload.d.ts

@@ -21,6 +21,11 @@ export type XlsxExportRequestPayload = {
     jaql: Record<string, unknown>;
     mergeRows: boolean;
     language: string;
+    widgetStyles?: {
+        coloringRules?: {
+            alternatingRows?: boolean;
+        };
+    };
 };
 /**
  * Builds the XLSX JAQL export request body shared by chart, pivot, and custom widgets.

package/dist/packages/sdk-ui/src/domains/query-execution/hooks/use-execute-query-by-widget-id/use-execute-query-by-widget-id.d.ts

@@ -46,8 +46,9 @@ export declare function useExecuteQueryByWidgetIdInternal(params: ExecuteQueryBy
  */
 export declare function useParamsChanged(params: ExecuteQueryByWidgetIdParams): boolean;
 /** @internal */
-export declare function executeQueryByWidgetId({ widgetOid, dashboardOid, filters, highlights, filtersMergeStrategy, count, offset, includeDashboardFilters, app, onBeforeQuery, }: ExecuteQueryByWidgetIdParams & {
+export declare function executeQueryByWidgetId({ widgetOid, dashboardOid, filters, highlights, filtersMergeStrategy, count, offset, includeRowCount, includeDashboardFilters, app, onBeforeQuery, }: ExecuteQueryByWidgetIdParams & {
     app: ClientApplication;
 }): Promise<{
     data: QueryResultData;
+    rowCount?: number;
 } & QueryByWidgetIdQueryParams>;

package/dist/packages/sdk-ui/src/domains/query-execution/types.d.ts

@@ -197,6 +197,23 @@ export interface ExecuteQueryByWidgetIdParams {
     count?: number;
     /** {@inheritDoc ExecuteQueryParams.offset} */
     offset?: number;
+    /**
+     * Boolean flag whether to include the total row count of the query result,
+     * ignoring the `count` and `offset` paging.
+     *
+     * When enabled, the total is returned as `rowCount` in the query state
+     * ({@link QueryByWidgetIdState.rowCount}) and is reused for subsequent pages of the same query.
+     *
+     * Row count feature requires a Sisense instance version of 2026.3.0 or greater.
+     * On older versions, the query still succeeds and `rowCount` stays `undefined`.
+     *
+     * Not supported for pivot table widgets.
+     *
+     * If not specified, the default value is `false`
+     *
+     * @beta
+     */
+    includeRowCount?: boolean;
     /**
      * Strategy for merging the existing widget filters (including highlights) with the filters provided via the `filters` and `highlights` props:
      *
@@ -230,7 +247,17 @@ export type QueryByWidgetIdQueryParams = {
 /**
  * State of a query execution retrieving data of Fusion widget.
  */
-export type QueryByWidgetIdState = QueryState & QueryByWidgetIdQueryParams;
+export type QueryByWidgetIdState = QueryState & QueryByWidgetIdQueryParams & {
+    /**
+     * Total row count of the query result, ignoring the `count` and `offset` paging.
+     *
+     * Populated only when {@link ExecuteQueryByWidgetIdParams.includeRowCount} is enabled and
+     * the Sisense instance supports the row count API; `undefined` otherwise.
+     *
+     * @beta
+     */
+    rowCount?: number;
+};
 /**
  * Base query parameters
  *
@@ -287,6 +314,22 @@ export interface ExecuteQueryParams extends BaseQueryParams {
      * If not specified, the default value is `false`
      */
     ungroup?: boolean;
+    /**
+     * Boolean flag whether to include the total row count of the query result,
+     * ignoring the `count` and `offset` paging.
+     *
+     * When enabled, an additional row count query is sent to the server alongside
+     * the data query, and the total is returned in {@link ExecuteQueryResult.rowCount}.
+     * The retrieved total is reused for subsequent pages of the same query.
+     *
+     * Row count feature requires a Sisense instance version of 2026.3.0 or greater.
+     * On older versions, the query still succeeds and `rowCount` stays `undefined`.
+     *
+     * If not specified, the default value is `false`
+     *
+     * @beta
+     */
+    includeRowCount?: boolean;
     /**
      * Sync or async callback that allows to modify the JAQL payload before it is sent to the server.
      *
@@ -318,6 +361,15 @@ export type ExecuteQueryResult = QueryState & {
      * @internal
      */
     isAllItemsLoaded: boolean;
+    /**
+     * Total row count of the query result, ignoring the `count` and `offset` paging.
+     *
+     * Populated only when {@link ExecuteQueryParams.includeRowCount} is enabled and
+     * the Sisense instance supports the row count API; `undefined` otherwise.
+     *
+     * @beta
+     */
+    rowCount?: number;
 };
 /** Configuration for {@link useExecuteCsvQuery} hook. */
 export type ExecuteCSVQueryConfig = {
@@ -329,13 +381,13 @@ export type ExecuteCSVQueryConfig = {
 /**
  * Parameters for {@link useExecuteCsvQuery} hook.
  */
-export interface ExecuteCsvQueryParams extends ExecuteQueryParams {
+export interface ExecuteCsvQueryParams extends Omit<ExecuteQueryParams, 'includeRowCount'> {
     config?: ExecuteCSVQueryConfig;
 }
 /**
  * Parameters for {@link useExecuteExcelQueryInternal} (JAQL XLSX export).
  */
-export interface ExecuteExcelQueryParams extends ExecuteQueryParams {
+export interface ExecuteExcelQueryParams extends Omit<ExecuteQueryParams, 'includeRowCount'> {
     /** `false` = repeat rows (Angular default); `true` = merge rows. */
     mergeRows: boolean;
     /** Suggested download file name (e.g. from widget title). */

package/dist/packages/sdk-ui/src/domains/shared/header/header-item-cell.d.ts

@@ -0,0 +1,25 @@
+import { ResolvedHeaderItem } from './types.js';
+/**
+ * Props for {@link HeaderItemCell}.
+ */
+export interface HeaderItemCellProps {
+    /** The resolved header item to render. */
+    item: ResolvedHeaderItem;
+    /**
+     * Default size (px) applied when the item doesn't specify one, letting each host pick its own
+     * default (the dashboard uses 28). Defaults to {@link DEFAULT_HEADER_ITEM_SIZE}.
+     */
+    defaultSize?: number;
+}
+/**
+ * Renders a single header item.
+ *
+ * This is the **header item component** every item flows through: it owns the item's layout box —
+ * the width behavior (from the internal `fill`), the orchestrator-provided height, and centering the
+ * content on both axes — so individual items only render their content and never manage header
+ * alignment themselves.
+ *
+ * An item shorter than the cell height is centered vertically; an item taller than the default grows
+ * its cell (and, via the row's `align-items: center`, the whole header) while staying centered.
+ */
+export declare const HeaderItemCell: ({ item, defaultSize }: HeaderItemCellProps) => import("react/jsx-runtime").JSX.Element;

package/dist/packages/sdk-ui/src/domains/shared/header/header-item-size.d.ts

@@ -0,0 +1,31 @@
+import { CSSProperties } from 'react';
+import { HeaderItemFill, HeaderItemSize } from './types.js';
+/**
+ * Default size (in pixels) for a header item dimension that is not specified.
+ *
+ * Each component can override this with its own default (e.g. the dashboard uses 28px) by passing
+ * `defaultSize` to the renderer.
+ */
+export declare const DEFAULT_HEADER_ITEM_SIZE = 24;
+/**
+ * Applies the default-size fallback to a (possibly partial) size.
+ *
+ * The result is what gets passed to a {@link HeaderItemComponent} via `props.size`.
+ */
+export declare const resolveHeaderItemSize: (size?: HeaderItemSize, defaultSize?: number) => Required<HeaderItemSize>;
+/**
+ * Maps a resolved size and the internal {@link HeaderItemFill} to the CSS for an item's wrapper.
+ *
+ * - `fill: 'grow'` → flexible, grows to fill the row (the center spacer).
+ * - `fill: 'truncate'` → natural content width, shrinkable (the title — enables ellipsis).
+ * - `fill: 'content'` → natural content width, never shrinks (built-in action buttons/menu — so a
+ *   long title cannot squeeze and clip their icons).
+ * - no `fill` (external items) → fixed pixel `width` (provided or defaulted).
+ *
+ * `fill` is internal: it is set only on built-in items. External items never carry it, so they are
+ * always laid out at a fixed pixel width.
+ *
+ * `height` is applied as a fixed pixel height (provided or defaulted). Every cell uses
+ * `align-items: center`, so an item shorter than the cell is centered vertically;
+ */
+export declare const getHeaderItemStyle: (size: Required<HeaderItemSize>, fill?: HeaderItemFill) => CSSProperties;

package/dist/packages/sdk-ui/src/domains/shared/header/header-items-renderer.d.ts

@@ -0,0 +1,23 @@
+import { ResolvedHeaderItem } from './types.js';
+/**
+ * Props for {@link HeaderItemsRenderer}.
+ * @internal
+ */
+export interface HeaderItemsRendererProps {
+    /** The resolved, ordered header items to render. */
+    items: ResolvedHeaderItem[];
+    /**
+     * Default size (px) applied to items that don't specify one. Lets each component pick its own
+     * default (the dashboard uses 28). Defaults to {@link DEFAULT_HEADER_ITEM_SIZE}.
+     */
+    defaultSize?: number;
+    /**
+     * Gap (px) rendered between adjacent header items. Defaults to `0` (no gap); the dashboard uses
+     * `10` to match Fusion's spacing.
+     */
+    gap?: number;
+}
+/**
+ * Renders a resolved list of header items as a single horizontal flex row.
+ */
+export declare const HeaderItemsRenderer: ({ items, defaultSize, gap }: HeaderItemsRendererProps) => import("react/jsx-runtime").JSX.Element;

package/dist/packages/sdk-ui/src/domains/shared/header/header-spacer-item.d.ts

@@ -0,0 +1,9 @@
+import { HeaderItem } from './types.js';
+/**
+ * Creates a flexible, empty "spacer" header item.
+ *
+ * The spacer renders nothing but grows (`fill: 'grow'`) to fill the available width, separating the
+ * leading group of items (e.g. the title) from the trailing group (action buttons). It is also the
+ * anchor that `{ type: 'auto' }` items are placed after.
+ */
+export declare const createHeaderSpacerItem: (id: string) => HeaderItem;