@sisense/sdk-ui 2.24.0 → 2.26.0

package/dist/packages/sdk-ui/src/domains/dashboarding/dashboard-model/translate-dashboard-utils.d.ts

@@ -11,6 +11,7 @@ export declare const getJtdNavigateType: (widget: WidgetDto) => TriggerMethod;
 export declare const convertDimensionsToDimIndexes: (widget: WidgetDto, dimensionIds: string[]) => string[];
 /**
  * Extract pivot targets configuration from widget DTO and build Map-based targets
+ *
  * @param widget - Widget DTO with drillToDashboardConfig
  * @returns Map of dimensions/measures to their targets or undefined if no targets found
  * @internal
@@ -39,6 +40,7 @@ export declare function translateTabbersOptions(widgets?: WidgetDto[]): TabbersC
 export declare function withSharedFormulas(dashboard: DashboardDto, api: RestApi): Promise<DashboardDto>;
 /**
  * Find dimension or measure by instanceId in widget panels and convert to proper type
+ *
  * @param panels - Widget metadata panels to search
  * @param pivotDimension - Instance ID to find, this is not a PivotDimId, it is the instanceId of the dimension or measure
  * @returns Dimension/Measure object with optional location info or undefined if not found

package/dist/packages/sdk-ui/src/domains/dashboarding/dashboard-model/types.d.ts

@@ -1,5 +1,6 @@
 import { CommonFiltersOptions } from '../../../domains/dashboarding/common-filters/types';
 import type { JumpToDashboardConfig, JumpToDashboardConfigForPivot } from '../../../domains/dashboarding/hooks/jtd/jtd-types';
+import type { WidgetDto } from '../../../domains/widgets/components/widget-by-id/types';
 import { ColorPaletteTheme } from '../../../types';
 export type { CommonFiltersOptions, CommonFiltersApplyMode, FiltersIgnoringRules, } from '../../../domains/dashboarding/common-filters/types';
 /**
@@ -8,6 +9,7 @@ export type { CommonFiltersOptions, CommonFiltersApplyMode, FiltersIgnoringRules
 export interface WidgetsPanelCell {
     /**
      * Flag that indicates if the cell is hidden
+     *
      * @internal
      */
     hidden?: boolean;
@@ -66,6 +68,7 @@ export type WidgetsPanelLayout = WidgetsPanelColumnLayout;
 export type WidgetId = string;
 /**
  * Dashboard ID
+ *
  * @internal
  */
 export type DashboardId = string;
@@ -76,7 +79,7 @@ export type DashboardId = string;
  */
 export type WidgetsOptions = Record<WidgetId, SpecificWidgetOptions>;
 /**
- * Options for a specific widget
+ * Dashboard-level options for a specific widget
  */
 export type SpecificWidgetOptions = {
     /**
@@ -87,6 +90,14 @@ export type SpecificWidgetOptions = {
      * Jump To Dashboard config for widgets.
      */
     jtdConfig?: JumpToDashboardConfig | JumpToDashboardConfigForPivot;
+    /**
+     * Partial snapshot of raw DTO fields preserved from the server response.
+     * Required to include all existing options/style when PATCHing a single field (e.g. previousScrollerLocation),
+     * because the server replaces the entire object rather than merging.
+     *
+     * @internal
+     */
+    partialDtoOptions?: Partial<Pick<WidgetDto, 'options' | 'style'>>;
 };
 /**
  * Style options for the dashboard.

package/dist/packages/sdk-ui/src/domains/dashboarding/dashboard-model/use-dashboard-model/dashboard-model-reducer/persist-dashboard-model-middleware.d.ts

@@ -1,13 +1,25 @@
 import { RestApi } from '../../../../../infra/api/rest-api';
+import { AppSettings } from '../../../../../infra/app/settings/settings';
+import { CompleteThemeSettings } from '../../../../../types';
 import { UseDashboardModelInternalAction } from './types.js';
+export type PersistDashboardModelMiddlewareParams = {
+    /** Dashboard OID, or undefined if not initialized */
+    dashboardOid: string | undefined;
+    /** Internal dashboard model action to persist */
+    action: UseDashboardModelInternalAction;
+    /** Sisense REST API instance */
+    restApi: RestApi;
+    /** Whether the dashboard is in shared mode */
+    sharedMode: boolean;
+    /** Application settings forwarded to {@link toWidgetDto} (controls widget design feature flag) */
+    appSettings: AppSettings;
+    /** Theme settings forwarded to {@link toWidgetDto} (used as defaults for widget design) */
+    themeSettings: CompleteThemeSettings;
+};
 /**
  * Middleware that persists the dashboard model changes to the Sisense server.
  *
- * @param dashboardOid - Dashboard OID, or undefined if not initialized
- * @param action - Internal dashboard model action to persist
- * @param restApi - Sisense REST API instance
- * @param sharedMode - Whether the dashboard is in shared mode
  * @returns Promise resolving to the action (possibly transformed, e.g. for ADD_WIDGET)
  * @internal
  */
-export declare function persistDashboardModelMiddleware(dashboardOid: string | undefined, action: UseDashboardModelInternalAction, restApi: RestApi, sharedMode: boolean): Promise<UseDashboardModelInternalAction>;
+export declare function persistDashboardModelMiddleware({ dashboardOid, action, restApi, sharedMode, appSettings, themeSettings, }: PersistDashboardModelMiddlewareParams): Promise<UseDashboardModelInternalAction>;

package/dist/packages/sdk-ui/src/domains/dashboarding/dashboard-model/use-dashboard-model/dashboard-model-reducer/types.d.ts

@@ -1,5 +1,6 @@
 import { Filter, FilterRelations } from '@sisense/sdk-data';
 import { DashboardModel, SpecificWidgetOptions, WidgetsPanelLayout } from '../../../../../domains/dashboarding/dashboard-model';
+import type { WidgetDto } from '../../../../../domains/widgets/components/widget-by-id/types';
 import { WidgetModel } from '../../../../../domains/widgets/widget-model';
 export type UseDashboardModelState = DashboardModel | null;
 /**
@@ -27,10 +28,24 @@ export declare enum UseDashboardModelActionType {
  * Fields that can be safely patched on a widget without full DTO reconstruction.
  * Intentionally narrow — extend only when lossless roundtrip is guaranteed.
  *
- * @internal
+ * @sisenseInternal
  */
 export type WidgetPatch = {
+    /**
+     * The title of the widget.
+     */
     title?: string;
+    /**
+     * Full widget options to send in the PATCH request.
+     * Must include all existing option fields alongside the changed ones, because
+     * the server replaces the entire options object rather than merging.
+     */
+    options?: Partial<NonNullable<WidgetDto['options']>> & {
+        previousScrollerLocation: {
+            min: number;
+            max: number;
+        };
+    };
 };
 /**
  * Internal actions for the dashboard model state used in {@link useDashboardModel}.

package/dist/packages/sdk-ui/src/domains/dashboarding/dashboard-model/use-dashboard-model/dashboard-model-reducer/utils.d.ts

@@ -5,8 +5,11 @@ import { AddWidgetPayload } from './types.js';
 /**
  * Translates filters and relations to DTOs.
  *
- * @param filtersOrFilterRelations - The filters or filter relations to translate
- * @returns The translated filters and relations DTOs for Fusion
+ * `filterRelations[].datasource` is always a **string** (never `undefined`), so Fusion validation
+ * does not break. The value is derived from `filter.dataSource` / `filter.attribute.dataSource`
+ * when present; otherwise `''`.
+ *
+ * @param filtersOrFilterRelations - Flat filters or a filter-relations tree
  *
  * @sisenseInternal
  */

package/dist/packages/sdk-ui/src/domains/dashboarding/hooks/duplicate-widget/use-duplicate-widget-menu-item.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="react" />
 import type { WidgetsOptions, WidgetsPanelLayout } from '../../../../domains/dashboarding/dashboard-model/types.js';
 import { type WidgetProps } from '../../../../domains/widgets/components/widget/types.js';
-import type { DashboardPersistenceManager } from '../../types.js';
+import type { DashboardPersistenceManager } from '../../persistence/types.js';
 /** Setter for widgets array (e.g. React setState or updater function). */
 export type SetWidgets = React.Dispatch<React.SetStateAction<WidgetProps[]>>;
 /** Setter for widgets options array (e.g. React setState or updater function). */

package/dist/packages/sdk-ui/src/domains/dashboarding/hooks/rename-widget/use-widget-renaming.d.ts

@@ -1,5 +1,5 @@
 import type { WidgetProps } from '../../../../domains/widgets/components/widget/types.js';
-import type { DashboardPersistenceManager } from '../../types.js';
+import type { DashboardPersistenceManager } from '../../persistence/types.js';
 /** Options for the widget renaming middleware hook. */
 export type UseWidgetRenamingParams = {
     /** Current widgets. */

package/dist/packages/sdk-ui/src/domains/dashboarding/hooks/use-widget-scroll-persistence.d.ts

@@ -0,0 +1,16 @@
+import type { WidgetsOptions } from '../../../domains/dashboarding/dashboard-model';
+import type { DashboardPersistenceManager } from '../../../domains/dashboarding/persistence/types';
+type ScrollerChangeHandler = (min: number, max: number) => void;
+/**
+ * Returns a stable per-widget factory of debounced scroller-position savers.
+ * Each call with the same widgetOid reuses the same debounced function.
+ * All pending debouncers are cancelled on unmount.
+ *
+ * @param persistence - The dashboard persistence manager. When `undefined`, the returned factory is a no-op.
+ * @param widgetsOptions - Current widget DTO options map, used to include all existing options in the PATCH
+ *   so the server does not discard other option fields when updating `previousScrollerLocation`.
+ * @returns Function that maps a widget OID to its debounced save handler.
+ * @internal
+ */
+export declare function useWidgetScrollPersistence(persistence: DashboardPersistenceManager | undefined, widgetsOptions?: WidgetsOptions): (widgetOid: string) => ScrollerChangeHandler;
+export {};

package/dist/packages/sdk-ui/src/domains/dashboarding/index.d.ts

@@ -2,5 +2,7 @@ export { DashboardById } from './dashboard-by-id.js';
 export { Dashboard } from './dashboard.js';
 export { useComposedDashboard, useComposedDashboardInternal, type ComposableDashboardProps, type UseComposedDashboardOptions, type ComposedDashboardResult, } from './use-composed-dashboard.js';
 export { useDashboardTheme, type DashboardThemeParams } from './use-dashboard-theme.js';
+export { createDashboardPersistenceManager } from './persistence/persistence-manager.js';
+export type { DashboardPersistenceManager } from './persistence/types.js';
 export * from './hooks/index.js';
 export type { DashboardByIdProps, DashboardProps, DashboardLayoutOptions, DashboardStyleOptions, DashboardConfig, DashboardByIdConfig, WidgetsPanelConfig, EditModeConfig, DashboardFiltersPanelConfig, TabbersConfig, TabberConfig, TabberTabConfig, DashboardChangeEvent, DashboardFiltersUpdatedEvent, DashboardFiltersPanelCollapseChangedEvent, DashboardWidgetsPanelLayoutUpdatedEvent, DashboardWidgetsPanelIsEditingChangedEvent, DashboardWidgetsDeletedEvent, } from './types.js';

package/dist/packages/sdk-ui/src/domains/dashboarding/persistence/persistence-manager.d.ts

@@ -0,0 +1,11 @@
+import type { UseDashboardModelResult } from '../../../domains/dashboarding/dashboard-model';
+import type { DashboardPersistenceManager } from './types.js';
+/**
+ * Creates a {@link DashboardPersistenceManager} that forwards add/patch operations through
+ * the same `dispatchChanges` function returned by {@link useDashboardModelInternal} /
+ *
+ * @param dispatchDashboardModelChanges - Dashboard model dispatch (e.g. `dispatchChanges` from `useDashboardModelInternal`)
+ * @returns Persistence manager for the composition layer
+ * @sisenseInternal
+ */
+export declare function createDashboardPersistenceManager(dispatchDashboardModelChanges: UseDashboardModelResult['dispatchChanges']): DashboardPersistenceManager;

package/dist/packages/sdk-ui/src/domains/dashboarding/persistence/types.d.ts

@@ -0,0 +1,52 @@
+import type { SpecificWidgetOptions, WidgetPatch, WidgetsPanelLayout } from '../../../domains/dashboarding/dashboard-model';
+import type { WidgetProps } from '../../../domains/widgets/components/widget/types';
+/**
+ * Interface for persisting dashboard changes from the composition layer (e.g. add widget).
+ *
+ * @sisenseInternal
+ */
+export type DashboardPersistenceManager = {
+    /**
+     * Adds a widget to the dashboard.
+     * @sisenseInternal
+     */
+    addWidget: (
+    /**
+     * The new widget to add.
+     */
+    widget: WidgetProps, 
+    /**
+     * The layout with the new widget added to it.
+     */
+    widgetsPanelLayout: WidgetsPanelLayout, 
+    /**
+     * The dashboard-level options for the new widget.
+     */
+    widgetOptions?: SpecificWidgetOptions) => Promise<{
+        /**
+         * The persisted widget (possibly modified by the server, e.g. new id).
+         */
+        widget: WidgetProps;
+        /**
+         * The layout with updated widget (after server modifications).
+         */
+        widgetsPanelLayout: WidgetsPanelLayout;
+        /**
+         * The options for the widget (after server modifications).
+         */
+        widgetOptions?: SpecificWidgetOptions;
+    }>;
+    /**
+     * Patch a single field (e.g. title) on an existing widget.
+     * @sisenseInternal
+     */
+    patchWidget: (
+    /**
+     * The oid of the widget to patch.
+     */
+    widgetOid: string, 
+    /**
+     * The patch to apply to the widget.
+     */
+    patch: WidgetPatch) => Promise<void>;
+};

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

@@ -1,9 +1,10 @@
 import { ReactNode } from 'react';
 import { DataSource, Filter, FilterRelations } from '@sisense/sdk-data';
-import { DashboardStyleOptions, SpecificWidgetOptions, WidgetPatch, WidgetsOptions, WidgetsPanelLayout } from '../../domains/dashboarding/dashboard-model';
+import { DashboardStyleOptions, WidgetsOptions, WidgetsPanelLayout } from '../../domains/dashboarding/dashboard-model';
 import { TabbersConfig } from '../../domains/dashboarding/hooks/use-tabber';
 import { FiltersPanelConfig } from '../../domains/filters/components/filters-panel/types';
 import { WidgetProps } from '../../domains/widgets/components/widget/types';
+import type { DashboardPersistenceManager } from './persistence/types.js';
 export type { DashboardStyleOptions, SpecificWidgetOptions, WidgetsPanelColumnLayout, WidgetsPanelLayout, WidgetsPanelCell, WidgetsPanelRow, WidgetsPanelColumn, } from '../../domains/dashboarding/dashboard-model';
 export type { TabbersConfig, TabberConfig, TabberTabConfig, } from '../../domains/dashboarding/hooks/use-tabber';
 /**
@@ -331,32 +332,7 @@ export interface DashboardLayoutOptions {
      */
     widgetsPanel?: WidgetsPanelLayout;
 }
-/**
- * Interface for persisting dashboard changes from the composition layer (e.g. add widget).
- *
- * @internal
- */
-export type DashboardPersistenceManager = {
-    /**
-     * Adds a widget to the dashboard.
-     *
-     * @param widget - The widget to add.
-     * @param widgetsPanelLayout - The layout to add the widget to.
-     * @param widgetOptions - The options for the widget.
-     * @returns The persisted widget (possibly modified by the server, e.g. new id), the new widgets panel layout and the widget options.
-     */
-    addWidget: (widget: WidgetProps, widgetsPanelLayout: WidgetsPanelLayout, widgetOptions?: SpecificWidgetOptions) => Promise<{
-        widget: WidgetProps;
-        widgetsPanelLayout: WidgetsPanelLayout;
-        widgetOptions?: SpecificWidgetOptions;
-    }>;
-    /**
-     * Patch a single field (e.g. title) on an existing widget.
-     *
-     * @internal
-     */
-    patchWidget: (widgetOid: string, patch: WidgetPatch) => Promise<void>;
-};
+export type { DashboardPersistenceManager };
 /**
  * Props for the Dashboard component
  */
@@ -397,7 +373,8 @@ export interface DashboardProps {
      */
     onChange?: (event: DashboardChangeEvent) => void;
     /**
-     * @internal
+     * Persistence manager for the dashboard
+     * @sisenseInternal
      */
     persistence?: DashboardPersistenceManager;
 }

package/dist/packages/sdk-ui/src/domains/dashboarding/use-composed-dashboard.d.ts

@@ -1,6 +1,7 @@
 import { Filter, FilterRelations } from '@sisense/sdk-data';
 import type { WidgetsPanelLayout } from '../../domains/dashboarding/dashboard-model';
-import { DashboardPersistenceManager, DashboardProps } from './types.js';
+import type { DashboardPersistenceManager } from './persistence/types.js';
+import { DashboardProps } from './types.js';
 export type ComposableDashboardProps = Pick<DashboardProps, 'filters' | 'widgets' | 'widgetsOptions' | 'layoutOptions' | 'config'>;
 export type UseComposedDashboardOptions = {
     /**
@@ -8,14 +9,16 @@ export type UseComposedDashboardOptions = {
      */
     onFiltersChange?: (filters: Filter[] | FilterRelations) => void;
     /**
-     * @internal
+     * Persistence manager for the dashboard
+     *
+     * @sisenseInternal
      */
     persistence?: DashboardPersistenceManager;
     /**
      * Runtime edit mode state. When provided (e.g. by Dashboard), used for duplicate-widget visibility
      * instead of only config.widgetsPanel.editMode.isEditing.
-     * @internal
      *
+     * @internal
      * @deprecated Temporal workaround. Edit mode (with history management) should be managed by the `useComposedDashboard` hook instead of the Dashboard component.
      */
     isEditing?: boolean;
@@ -76,11 +79,9 @@ export declare function useComposedDashboardInternal<D extends ComposableDashboa
  * }
  *   export default CodeExample;
  * ```
- *
  * @template {D extends ComposableDashboardProps | DashboardProps} D - The type parameter for a dashboard properties, restricted to ComposableDashboardProps or DashboardProps
  * @param {D} initialDashboard - set of properties for the Dashboard component
  * @param {UseComposedDashboardOptions} [options] - Options for the composable.
- *
  * @return {ComposedDashboardResult} An object containing the composed dashboard and APIs to interact with it.
  * @group Dashboards
  */

package/dist/packages/sdk-ui/src/domains/data-browser/data-source-dimensional-model/hooks/use-get-data-source-dimensions.d.ts

@@ -69,10 +69,20 @@ export interface GetDataSourceDimensionsParams {
     /** The search value to filter by */
     searchValue?: string;
 }
+/**
+ * {@link useGetDataSourceDimensions} without tracking to be used inside other hooks or components.
+ *
+ * @param params - The parameters for getting the dimensions
+ * @returns The dimensions state
+ * @internal
+ */
+export declare function useGetDataSourceDimensionsInternal(params: GetDataSourceDimensionsParams): DataSourceDimensionsState;
 /**
  * Gets the dimensions of a data source.
  *
  * @param params - The parameters for getting the dimensions
  * @returns The dimensions state
+ * @group Fusion Assets
+ * @fusionEmbed
  */
 export declare const useGetDataSourceDimensions: (params: GetDataSourceDimensionsParams) => DataSourceDimensionsState;

package/dist/packages/sdk-ui/src/domains/data-browser/data-source-dimensional-model/hooks/use-get-data-source-fields.d.ts

@@ -9,6 +9,7 @@ import { RestApiHookState } from '../../../../shared/utils/utility-types';
  * @param params.count - The number of items to return
  * @param params.offset - The offset for pagination
  * @param params.searchValue - The search value to filter by
+ * @param params.cacheTime - The cache time in milliseconds
  * @returns The data source fields state
  * @internal
  */
@@ -18,6 +19,7 @@ export declare const useGetDataSourceFields: (params: {
     count?: number;
     offset?: number;
     searchValue?: string;
+    cacheTime?: number;
 }) => DataSourceFieldsState;
 type DataSourceFieldsState = RestApiHookState<'dataSourceFields', DataSourceField[]>;
 export {};

package/dist/packages/sdk-ui/src/domains/drilldown/components/drilldown-widget/drilldown-widget.d.ts

@@ -22,8 +22,8 @@ import { DrilldownWidgetProps } from '../../../../props';
  *
  * <iframe
  *  src='https://csdk-playground.sisense.com/?example=use-cases%2Fdrilldown&mode=docs'
- *  width=800
- *  height=870
+ *  width='800'
+ *  height='870'
  *  style='border:none;'
  * />
  *

package/dist/packages/sdk-ui/src/domains/narrative/components/narrative-collapsible.d.ts

@@ -0,0 +1,13 @@
+type NarrativeCollapsibleProps = {
+    text: string;
+};
+/**
+ * Text container with an expand/collapse control for long narrative text.
+ *
+ * Uses `max-height` + `overflow: hidden` when collapsed (not `line-clamp`), because
+ * `white-space: pre-wrap` is incompatible with `-webkit-line-clamp` in browsers.
+ *
+ * @internal
+ */
+export declare function NarrativeCollapsible({ text }: NarrativeCollapsibleProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/packages/sdk-ui/src/domains/narrative/components/narrative-top-slot-shell.d.ts

@@ -0,0 +1,21 @@
+/// <reference types="react" />
+import { Themable } from '../../../infra/contexts/theme-provider/types.js';
+/** Horizontal space before the AI icon in the default (interactive) narrative row. */
+export declare const NARRATIVE_TOP_SLOT_LEADING_GUTTER_PX = 18;
+/** Space after feedback controls (interactive) and plain narrative right inset. */
+export declare const NARRATIVE_TOP_SLOT_TRAILING_GUTTER_PX = 12;
+/**
+ * Full-bleed chart panel styling for narrative content in a widget top slot,
+ * so it visually continues into the chart content area (same colors, no gray gutters).
+ *
+ * Use `$horizontalInset` for plain narrative (no leading AI icon) so text aligns with the
+ * interactive variant and sits off the container edge.
+ *
+ * @internal
+ */
+export declare const NarrativeTopSlotShell: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+} & Themable & {
+    $horizontalInset?: boolean | undefined;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;

package/dist/packages/sdk-ui/src/domains/narrative/components/widget-narrative-interactive.d.ts

@@ -0,0 +1,11 @@
+import type { NarrativeRequest } from '../../../infra/api/narrative/narrative-api-types.js';
+export type WidgetNarrativeInteractiveProps = {
+    summary: string;
+    narrativeRequest: NarrativeRequest;
+};
+/**
+ * Chart-area narrative text with optional thumbs feedback; mirrors legacy ChartInsights without `modules/ai`.
+ *
+ * @internal
+ */
+export declare function WidgetNarrativeInteractive({ summary, narrativeRequest, }: WidgetNarrativeInteractiveProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,40 @@
+/// <reference types="react" />
+import { WidgetProps } from '../../../domains/widgets/components/widget/types';
+import type { WidgetNarrativeOptions } from '../core/widget-narrative-options.js';
+/**
+ * Props for {@link WidgetNarrative}.
+ *
+ * @sisenseInternal
+ */
+export type WidgetNarrativeProps = {
+    /** Widget whose query drives the narrative (chart or pivot). */
+    widgetProps: WidgetProps;
+    /**
+     * `default` — collapsible narrative with AI feedback actions (same pattern as NLQ chart insights).
+     * `plain` — collapsible text only (similar to the `GetNlgInsights` component).
+     */
+    variant?: 'default' | 'plain';
+    /** When false, the narrative query does not run (see {@link useWidgetNarrativeState}). */
+    enabled?: boolean;
+} & WidgetNarrativeOptions;
+/**
+ * Renders a natural-language narrative for chart or pivot `WidgetProps`. The request uses the same
+ * JAQL as the widget query (chart or pivot)—compose it next to or above a `ChartWidget` or
+ * `PivotTableWidget` with the same props.
+ *
+ * @example Widget header slot
+ * ```tsx
+ * <ChartWidget
+ *   {...chartWidgetProps}
+ *   topSlot={<WidgetNarrative widgetProps={chartWidgetProps} />}
+ * />
+ * ```
+ * @example Modal or custom layout (headless)
+ * ```tsx
+ * const { data, isLoading, supported } = useGetWidgetNarrative({ widgetProps });
+ * if (!supported) return null;
+ * return <DialogContent>{isLoading ? '…' : data}</DialogContent>;
+ * ```
+ * @sisenseInternal
+ */
+export declare const WidgetNarrative: import("react").FunctionComponent<WidgetNarrativeProps>;

package/dist/packages/sdk-ui/src/domains/narrative/core/build-narrative-request.d.ts

@@ -0,0 +1,36 @@
+import { Attribute, DataSource, Filter, FilterRelations, Measure } from '@sisense/sdk-data';
+import type { NarrativeRequest } from '../../../infra/api/narrative/narrative-api-types.js';
+/**
+ * Parameters for {@link useGetNlgInsights} hook.
+ */
+export interface UseGetNlgInsightsParams {
+    /** The data source that the query targets - e.g. `Sample ECommerce` */
+    dataSource: DataSource;
+    /** Dimensions of the query */
+    dimensions?: Attribute[];
+    /** Measures of the query */
+    measures?: Measure[];
+    /** Filters of the query */
+    filters?: Filter[] | FilterRelations;
+    /**
+     * Boolean flag to enable/disable API call by default
+     *
+     * If not specified, the default value is `true`
+     */
+    enabled?: boolean;
+    /** The verbosity of the NLG summarization */
+    verbosity?: 'Low' | 'High';
+}
+/**
+ * Parameters for building a narration request (before JAQL payload expansion).
+ *
+ * @sisenseInternal
+ */
+export interface NarrativeQueryParams extends UseGetNlgInsightsParams {
+}
+/** @internal */
+export declare function prepareNarrativeRequest(params: NarrativeQueryParams | NarrativeRequest): NarrativeRequest;
+/**
+ * @deprecated Use {@link prepareNarrativeRequest}. Same function; kept for legacy `modules/ai` and framework wrappers.
+ */
+export declare const prepareGetNlgInsightsPayload: typeof prepareNarrativeRequest;

package/dist/packages/sdk-ui/src/domains/narrative/core/get-narrative-dimensions-and-measures.d.ts

@@ -0,0 +1,22 @@
+import { Attribute, Measure } from '@sisense/sdk-data';
+import { type AdaptMeasuresForQueryOptions } from '../../../domains/visualizations/core/chart-data-options/apply-styled-options-to-query.js';
+import type { TableDataOptions } from '../../../domains/visualizations/core/chart-data-options/types.js';
+import { ChartDataOptions, ChartType } from '../../../types';
+/**
+ * Dimensions and measures for narration / JAQL, including styled sort, trend, and forecast.
+ *
+ * @internal
+ */
+export declare function getNarrativeDimensionsAndMeasures(chartDataOptions: ChartDataOptions, chartType: ChartType, adaptMeasureOptions?: AdaptMeasuresForQueryOptions): {
+    dimensions: Attribute[];
+    measures: Measure[];
+};
+/**
+ * Table dimensions and measures for narration / JAQL, including styled sort, trend, and forecast.
+ *
+ * @internal
+ */
+export declare function getNarrativeDimensionsAndMeasuresFromTable(dataOptions: TableDataOptions, adaptMeasureOptions?: AdaptMeasuresForQueryOptions): {
+    dimensions: Attribute[];
+    measures: Measure[];
+};

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

@@ -0,0 +1,29 @@
+import type { DataSource } from '@sisense/sdk-data';
+/**
+ * Options shared by {@link useGetWidgetNarrative} and imperative helpers such as
+ * {@link getNlgInsightsFromWidget}.
+ *
+ * @internal
+ */
+export interface WidgetNarrativeOptions {
+    /** Optional default data source to use if WidgetProps.dataSource is undefined */
+    defaultDataSource?: DataSource;
+    /** The verbosity of the NLG summarization */
+    verbosity?: 'Low' | 'High';
+    /** When false, legacy narration endpoint only; when true or undefined, try unified then fallback. */
+    isUnified?: boolean;
+    /** Computed SDK flag from server settings (`app.settings.narrative.isSisenseAiEnabled`), not raw AI API. */
+    isSisenseAiEnabled?: boolean;
+    /**
+     * When `true`, trend and forecast companion measures are omitted from the narrative JAQL so
+     * requests stay compatible with backends that do not yet support them.
+     *
+     * @default false
+     */
+    ignoreTrendAndForecast?: boolean;
+}
+/**
+ * @deprecated Use {@link WidgetNarrativeOptions}. Same shape; kept for legacy naming.
+ * @internal
+ */
+export type WidgetNarrativeNlgOptions = WidgetNarrativeOptions;

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

@@ -0,0 +1,36 @@
+import { DataSource } from '@sisense/sdk-data';
+import { ChartWidgetProps } from '../../../domains/widgets/components/chart-widget/types';
+import type { PivotTableWidgetProps } from '../../../domains/widgets/components/pivot-table-widget/types';
+import type { 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';
+/**
+ * Converts ChartWidgetProps to {@link NarrativeQueryParams} by extracting dimensions and measures
+ * from the chart data options.
+ *
+ * @param props - ChartWidgetProps to convert
+ * @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;
+/**
+ * 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 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;
+/**
+ * @deprecated Use {@link convertChartWidgetPropsToNarrativeParams}. Same function; kept for legacy `getNlgInsightsFromWidget`.
+ */
+export declare const convertChartWidgetPropsToUseGetNlgInsightsParams: typeof convertChartWidgetPropsToNarrativeParams;