@sisense/sdk-ui 2.24.0 → 2.25.0

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

@@ -76,7 +76,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 = {
     /**

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

@@ -27,9 +27,12 @@ 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;
 };
 /**

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/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,7 +9,8 @@ export type UseComposedDashboardOptions = {
      */
     onFiltersChange?: (filters: Filter[] | FilterRelations) => void;
     /**
-     * @internal
+     * Persistence manager for the dashboard
+     * @sisenseInternal
      */
     persistence?: DashboardPersistenceManager;
     /**

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,28 @@
+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. */
+    isUnifiedNarrationEnabled?: boolean;
+    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;

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

@@ -0,0 +1,62 @@
+import type { WidgetProps } from '../../../domains/widgets/components/widget/types';
+import type { WidgetNarrativeOptions } from '../core/widget-narrative-options.js';
+import { type WidgetNarrativeQueryState } from './use-widget-narrative-state.js';
+/**
+ * Options for {@link useGetWidgetNarrative}.
+ *
+ * @remarks
+ * Narration endpoints and flags default from `app.settings` on {@link useSisenseContext} when
+ * `isUnifiedNarrationEnabled` / `isSisenseAiEnabled` are 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;
+};
+/**
+ * @sisenseInternal
+ */
+export type UseGetWidgetNarrativeParams = {
+    /** Widget configuration whose query drives the narrative (chart or pivot). */
+    widgetProps: WidgetProps;
+} & UseGetWidgetNarrativeOptions;
+/**
+ * @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`).
+     */
+    supported: boolean;
+    /**
+     * Mirrors {@link UseGetWidgetNarrativeOptions.enabled}. When `false`, narrative is opted out and
+     * `data` is not populated from cache.
+     */
+    enabled: boolean;
+};
+/**
+ * Fetches natural-language narrative for a widget {@link WidgetProps} using the same conversion
+ * path as {@link getNlgInsightsFromWidget}.
+ *
+ * Requires `useSisenseContext` with `app.httpClient` and a TanStack `QueryClientProvider` ancestor
+ * (typically provided by `SisenseContextProvider` in full apps).
+ *
+ * Text and custom widgets are unsupported: `supported` is false and no request runs.
+ *
+ * @example Headless usage
+ * ```tsx
+ * const { data, isLoading, supported } = useGetWidgetNarrative({
+ *   widgetProps,
+ *   defaultDataSource: DM.DataSource,
+ *   verbosity: 'Low',
+ * });
+ * ```
+ * @sisenseInternal
+ */
+export declare const useGetWidgetNarrative: (params: UseGetWidgetNarrativeParams) => UseGetWidgetNarrativeResult;

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

@@ -0,0 +1,39 @@
+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';
+/**
+ * Hook state aligned with legacy {@link UseGetNlgInsightsState}; used by {@link useGetWidgetNarrative}.
+ *
+ * @internal
+ */
+export type WidgetNarrativeQueryState = {
+    isLoading: boolean;
+    isError: boolean;
+    isSuccess: boolean;
+    data: string | undefined;
+    error: unknown;
+    refetch: () => void;
+};
+export type UseWidgetNarrativeStateParams = {
+    widgetProps: WidgetProps;
+    enabled?: boolean;
+} & WidgetNarrativeOptions;
+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.”
+     */
+    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`.
+ * Not exported from `@sisenseInternal` public API.
+ *
+ * @internal
+ */
+export declare function useWidgetNarrativeState({ widgetProps, defaultDataSource, verbosity, enabled, ignoreTrendAndForecast, isUnifiedNarrationEnabled: optionsUnified, isSisenseAiEnabled: optionsSisenseAi, }: UseWidgetNarrativeStateParams): UseWidgetNarrativeStateResult;

package/dist/packages/sdk-ui/src/domains/visualizations/core/chart-data-options/apply-styled-options-to-query.d.ts

@@ -0,0 +1,87 @@
+import { Attribute, CalculatedMeasureColumn, Column, Measure, MeasureColumn } from '@sisense/sdk-data';
+import type { CategoryStyle, SeriesStyle, StyledColumn, StyledMeasureColumn, ValueStyle } from './types.js';
+/**
+ * Name prefixes for trend and forecast measures in query payloads (aligned with NLQ JSON and chart).
+ *
+ * @internal
+ */
+export declare const TREND_PREFIX = "$trend";
+export declare const FORECAST_PREFIX = "$forecast";
+/**
+ * Dimension + optional category style for {@link adaptDimensionsForQuery}.
+ * Structurally matches NLQ `DimensionTranslationItem`.
+ *
+ * @internal
+ */
+export type DimensionQueryAdaptItem = {
+    attribute: Attribute;
+    style?: CategoryStyle;
+};
+/**
+ * Measure + optional value style for {@link adaptMeasuresForQuery}.
+ * Structurally matches NLQ `MeasureTranslationItem`.
+ *
+ * @internal
+ */
+export type MeasureQueryAdaptItem = {
+    measure: Measure;
+    style?: ValueStyle & SeriesStyle;
+};
+/**
+ * Dimensional {@link Attribute} instances expose JAQL sort APIs; plain {@link Column} does not.
+ *
+ * @internal
+ */
+export declare function isDimensionalAttribute(column: Column): column is Attribute;
+/**
+ * Narrative / NLQ query measures are dimensional {@link Measure} instances (e.g. from `measureFactory`).
+ *
+ * @internal
+ */
+export declare function isDimensionalMeasure(column: MeasureColumn | CalculatedMeasureColumn): column is Measure;
+/**
+ * Builds a dimension adapt item using `StyledColumn`’s own shape (no `splitColumn` merge).
+ *
+ * @internal
+ */
+export declare function toDimensionQueryAdaptItem(sc: StyledColumn): DimensionQueryAdaptItem;
+/**
+ * Builds a measure adapt item using `StyledMeasureColumn`’s own shape (no `splitColumn` merge).
+ *
+ * @internal
+ */
+export declare function toMeasureQueryAdaptItem(smc: StyledMeasureColumn): MeasureQueryAdaptItem;
+/**
+ * Applies sort from styled dimensions to attributes (NLQ JSON → query semantics).
+ *
+ * @internal
+ */
+export declare function adaptDimensionsForQuery(items: DimensionQueryAdaptItem[]): Attribute[];
+/**
+ * @internal
+ */
+export declare function isTrendMeasure(measure: Measure): boolean;
+/**
+ * @internal
+ */
+export declare function isForecastMeasure(measure: Measure): boolean;
+/**
+ * Options for {@link adaptMeasuresForQuery}.
+ *
+ * @internal
+ */
+export type AdaptMeasuresForQueryOptions = {
+    /**
+     * When `true`, trend and forecast companion measures are not appended (e.g. narrative when the
+     * backend does not yet support them).
+     *
+     * @default false
+     */
+    ignoreTrendAndForecast?: boolean;
+};
+/**
+ * Applies sort, trend, and forecast companion measures (NLQ JSON → query semantics).
+ *
+ * @internal
+ */
+export declare function adaptMeasuresForQuery(items: MeasureQueryAdaptItem[], options?: AdaptMeasuresForQueryOptions): Measure[];