@sisense/sdk-ui 2.29.0 → 2.30.0

package/dist/packages/sdk-ui/src/domains/filters/components/criteria-filter-tile/criteria-filter-menu.d.ts

@@ -1,5 +1,5 @@
 import { FunctionComponent } from 'react';
-import { Measure } from '@sisense/sdk-data';
+import { Attribute, Measure } from '@sisense/sdk-data';
 import { FilterVariant } from '../common/filter-utils.js';
 import { CriteriaFilterValueType, FilterOptionType } from './criteria-filter-operations.js';
 /**
@@ -14,6 +14,7 @@ export interface CriteriaFilterMenuProps {
     onUpdate?: (values: CriteriaFilterValueType[]) => void;
     disabled?: boolean;
     measures?: Measure[];
+    attribute?: Attribute;
 }
 /**
  * UI component that provides field(s) for the user to enter values for a numeric filter.

package/dist/packages/sdk-ui/src/domains/filters/components/criteria-filter-tile/criteria-filter-operations.d.ts

@@ -63,5 +63,6 @@ export declare const filterToOption: (filter: Filter) => FilterOptionType;
 export type CriteriaFilterValueType = string | number | Measure;
 export declare const filterToDefaultValues: (filter: Filter) => CriteriaFilterValueType[];
 export declare const valuesToDisplayValues: (values: CriteriaFilterValueType[]) => (string | number)[];
+export declare const getRankingTypeLabel: (filterType: FilterOptionType, t: TFunction) => string;
 export declare const translatedMsgNoVal: (message: string, t: TFunction) => string;
 export declare const filterTypeToInputType: (filterType: string) => string;

package/dist/packages/sdk-ui/src/domains/filters/components/filter-editor-popover/filter-editor-context.d.ts

@@ -2,6 +2,7 @@ import { ReactNode } from 'react';
 import { DataSource, Filter } from '@sisense/sdk-data';
 type FilterEditorContextValue = {
     defaultDataSource: DataSource | null;
+    dataSources: DataSource[];
     parentFilters: Filter[];
     membersOnlyMode: boolean;
 };

package/dist/packages/sdk-ui/src/domains/filters/components/filter-editor-popover/filter-editor-popover.d.ts

@@ -10,8 +10,9 @@ type FilterEditorPopoverProps = {
     onClose?: () => void;
     /** Default data source used for filter attribute */
     defaultDataSource?: DataSource;
+    dataSources?: DataSource[];
     config?: FilterEditorConfig;
 };
 /** @internal */
-export declare const FilterEditorPopover: ({ filter, parentFilters, position, onChange, onClose, defaultDataSource, config, }: FilterEditorPopoverProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const FilterEditorPopover: ({ filter, parentFilters, position, onChange, onClose, defaultDataSource, dataSources, config, }: FilterEditorPopoverProps) => import("react/jsx-runtime").JSX.Element | null;
 export {};

package/dist/packages/sdk-ui/src/domains/filters/components/filter-editor-popover/filter-editor.d.ts

@@ -6,8 +6,9 @@ type FilterEditorProps = {
     onChange?: (filter: Filter | null) => void;
     /** Default data source used for filter attribute */
     defaultDataSource?: DataSource;
+    dataSources?: DataSource[];
     config?: FilterEditorConfig;
 };
 /** @internal */
-export declare const FilterEditor: ({ filter, parentFilters, config, onChange, defaultDataSource, }: FilterEditorProps) => import("react/jsx-runtime").JSX.Element;
+export declare const FilterEditor: ({ filter, parentFilters, config, onChange, defaultDataSource, dataSources, }: FilterEditorProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/packages/sdk-ui/src/domains/filters/components/filter-editor-popover/sections/numeric-condition-section/types.d.ts

@@ -1,3 +1,4 @@
+import { Measure } from '@sisense/sdk-data';
 export declare const NumericCondition: {
     readonly EXCLUDE: "exclude";
     readonly EQUALS: "numericequals";
@@ -6,6 +7,8 @@ export declare const NumericCondition: {
     readonly LESS_THAN_OR_EQUAL: "numericto";
     readonly GREATER_THAN: "numericfromNotEqual";
     readonly GREATER_THAN_OR_EQUAL: "numericfrom";
+    readonly TOP: "rankingtop";
+    readonly BOTTOM: "rankingbottom";
 };
 export type NumericConditionType = (typeof NumericCondition)[keyof typeof NumericCondition];
 export type NumericConditionFilterData = {
@@ -13,4 +16,6 @@ export type NumericConditionFilterData = {
     value: string;
     selectedMembers: string[];
     multiSelectEnabled: boolean;
+    rankingCount?: number;
+    rankingMeasure?: Measure | null;
 };

package/dist/packages/sdk-ui/src/domains/filters/components/filter-editor-popover/sections/ranking-condition/index.d.ts

@@ -0,0 +1,3 @@
+export { RankingConditionControls } from './ranking-condition-controls.js';
+export { createRankingFilter, DEFAULT_DATETIME_RANKING_COUNT, DEFAULT_RANKING_COUNT, getRankingCountFromFilter, getRankingMeasureFromFilter, getRankingStateFromFilter, isRankingCondition, } from './ranking-condition-utils.js';
+export type { RankingConditionType } from './ranking-condition-utils.js';

package/dist/packages/sdk-ui/src/domains/filters/components/filter-editor-popover/sections/ranking-condition/ranking-condition-controls.d.ts

@@ -0,0 +1,33 @@
+import { Measure } from '@sisense/sdk-data';
+/**
+ * Props for the ranking count, date level, and ranked-by measure controls.
+ *
+ * @property count - Current ranking count (minimum 1).
+ * @property measure - Selected measure used to rank members, or null when unset.
+ * @property onCountChange - Called when the user changes the ranking count.
+ * @property onMeasureChange - Called when the user selects a measure from the popover.
+ * @property showRankedBy - Whether to render the ranked-by measure selector (default true).
+ * @property showDateLevel - Whether to render the date level selector (default false).
+ * @property dateLevel - Current date granularity when `showDateLevel` is true.
+ * @property onDateLevelChange - Called when the user changes the date level.
+ * @property disabled - Disables count input and ranked-by selector when true.
+ */
+export type RankingConditionControlsProps = {
+    count: number;
+    measure: Measure | null;
+    onCountChange: (count: number) => void;
+    onMeasureChange: (measure: Measure) => void;
+    showRankedBy?: boolean;
+    showDateLevel?: boolean;
+    dateLevel?: string;
+    onDateLevelChange?: (granularity: string) => void;
+    disabled?: boolean;
+};
+/**
+ * Renders shared Top/Bottom ranking controls: count input, optional date level, and ranked-by measure.
+ *
+ * @param props - Ranking control state and change handlers.
+ * @returns Fragment containing ranking UI controls.
+ * @internal
+ */
+export declare const RankingConditionControls: ({ count, measure, onCountChange, onMeasureChange, showRankedBy, showDateLevel, dateLevel, onDateLevelChange, disabled, }: RankingConditionControlsProps) => import("react/jsx-runtime").JSX.Element;

package/dist/packages/sdk-ui/src/domains/filters/components/filter-editor-popover/sections/ranking-condition/ranking-condition-utils.d.ts

@@ -0,0 +1,13 @@
+import { Attribute, Filter, Measure } from '@sisense/sdk-data';
+import { FilterOption } from '../../../criteria-filter-tile/criteria-filter-operations.js';
+export declare const DEFAULT_RANKING_COUNT = 10;
+export declare const DEFAULT_DATETIME_RANKING_COUNT = 1;
+export type RankingConditionType = typeof FilterOption.TOP | typeof FilterOption.BOTTOM;
+export declare function isRankingCondition(condition: string): condition is RankingConditionType;
+export declare function getRankingCountFromFilter(filter: Filter): number;
+export declare function getRankingMeasureFromFilter(filter: Filter): Measure | null;
+export declare function getRankingStateFromFilter(filter: Filter): {
+    count: number;
+    measure: Measure | null;
+};
+export declare function createRankingFilter(baseFilter: Filter, condition: RankingConditionType, count: number, measure: Measure | null, attributeOverride?: Attribute): Filter | null;

package/dist/packages/sdk-ui/src/domains/filters/components/filters-panel/hooks/use-existing-filter-editing.d.ts

@@ -3,6 +3,7 @@ import type { UseExistingFilterEditingConfig } from '../types';
 type UseExistingFilterEditingParams = {
     onFilterChanged: (filter: Filter) => void;
     defaultDataSource?: DataSource;
+    dataSources?: DataSource[];
     config?: UseExistingFilterEditingConfig;
 };
 type UseExistingFilterEditingReturn = {
@@ -13,6 +14,6 @@ type UseExistingFilterEditingReturn = {
  * Hook that keeps editing process of existing filters.
  * Returns a function to start editing a filter and a component that renders the filter editing popover.
  */
-export declare const useExistingFilterEditing: ({ config, defaultDataSource, onFilterChanged, }: UseExistingFilterEditingParams) => UseExistingFilterEditingReturn;
+export declare const useExistingFilterEditing: ({ config, defaultDataSource, dataSources, onFilterChanged, }: UseExistingFilterEditingParams) => UseExistingFilterEditingReturn;
 export declare function isFilterSupportEditing(filter: Filter): boolean;
 export {};

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

@@ -1,13 +1,31 @@
 type NarrativeCollapsibleProps = {
     text: string;
+    noCollapse?: boolean;
+    /** When true, shows the loading overlay over the text area at its settled height. */
+    isLoading?: boolean;
+    isError?: boolean;
+    /** Fired when the collapsed state toggles. */
+    onCollapsedChange?: (isCollapsed: boolean) => void;
+    /**
+     * Reserved height in pixels for the collapsed state (line-aligned internally).
+     * The container always occupies this much vertical space; "show more" only appears when
+     * the text overflows it. Defaults to 5 text rows when `undefined`.
+     */
+    constrainedHeightPx?: number;
+    /**
+     * Absolute pixel cap applied when the narrative is expanded.
+     * Text scrolls rather than exceeding this limit.
+     */
+    maxConstrainedHeightPx?: number;
 };
 /**
- * Text container with an expand/collapse control for long narrative text.
+ * Narrative-specific collapsible: always reserves the collapsed height to prevent widget
+ * layout shifts during data loads.
  *
- * Uses `max-height` + `overflow: hidden` when collapsed (not `line-clamp`), because
- * `white-space: pre-wrap` is incompatible with `-webkit-line-clamp` in browsers.
+ * Thin wrapper around {@link Collapsible} that maps legacy prop names and sets
+ * narrative-appropriate defaults.
  *
  * @internal
  */
-export declare function NarrativeCollapsible({ text }: NarrativeCollapsibleProps): import("react/jsx-runtime").JSX.Element;
+export declare function NarrativeCollapsible({ constrainedHeightPx, maxConstrainedHeightPx, ...rest }: NarrativeCollapsibleProps): import("react/jsx-runtime").JSX.Element;
 export {};

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

@@ -4,6 +4,7 @@ import { Themable } from '../../../infra/contexts/theme-provider/types.js';
 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;
+export declare const NARRATIVE_TOP_SLOT_PADDING_TOP = 8;
 /**
  * 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).
@@ -15,6 +16,7 @@ export declare const NARRATIVE_TOP_SLOT_TRAILING_GUTTER_PX = 12;
  */
 export declare const NarrativeTopSlotShell: import("@emotion/styled").StyledComponent<{
     theme?: import("@emotion/react").Theme | undefined;
+    /** `gap` between icon and collapsible text in the narrative row. */
     as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
 } & Themable & {
     $horizontalInset?: boolean | undefined;

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

@@ -0,0 +1,17 @@
+type NarrativeTriggerButtonProps = {
+    onClick: () => void;
+    isVisible: boolean;
+};
+/**
+ * Toolbar icon button that triggers on-demand narrative generation when autoShow=false.
+ * Shows a "generate" icon when the narrative is hidden and a "hide" icon when visible.
+ * Rendered inside the widget header toolbar via an injected renderToolbar wrapper.
+ *
+ * @param props - Component props.
+ * @param props.onClick - Callback fired when the button is clicked.
+ * @param props.isVisible - Whether the narrative is currently visible; controls which icon is shown.
+ * @returns A tooltip-wrapped icon button.
+ * @internal
+ */
+export declare function NarrativeTriggerButton({ onClick, isVisible }: NarrativeTriggerButtonProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -1,11 +1,29 @@
+/// <reference types="react" />
 import type { NarrativeRequest } from '../../../infra/api/narrative/narrative-api-types.js';
+import { Themable } from '../../../infra/contexts/theme-provider/types';
 export type WidgetNarrativeInteractiveProps = {
-    summary: string;
+    text: string;
+    isError?: boolean;
+    isLoading?: boolean;
     narrativeRequest: NarrativeRequest;
+    onCollapsedChange?: (isCollapsed: boolean) => void;
+    constrainedHeightPx?: number;
+    maxConstrainedHeightPx?: number;
+    noCollapse?: boolean;
 };
+export declare const NarrativeTopSlotRow: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const IconDiv: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+} & Themable, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/** Sparkle AI icon rendered next to every narrative. */
+export declare function NarrativeAiIcon({ theme }: Themable): import("react/jsx-runtime").JSX.Element;
 /**
  * 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;
+export declare function WidgetNarrativeInteractive({ text, isError, isLoading, narrativeRequest, onCollapsedChange, constrainedHeightPx, maxConstrainedHeightPx, noCollapse, }: WidgetNarrativeInteractiveProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,22 +1,24 @@
 /// <reference types="react" />
 import { WidgetProps } from '../../../domains/widgets/components/widget/types';
-import type { WidgetNarrativeOptions } from '../core/widget-narrative-options.js';
+import type { HookEnableParam } from '../../../shared/hooks/types';
 /**
  * Props for {@link WidgetNarrative}.
  *
+ * @remarks
+ * Narrative options are read from `widgetProps.aiOptions.narrative` for chart and pivot widgets.
+ * Accepts {@link HookEnableParam}; `enabled` is forwarded to {@link useWidgetNarrativeState}.
  * @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;
+    /** Fired when the collapsed state of the narrative text changes (expand/collapse mode only). */
+    onCollapsedChange?: (isCollapsed: boolean) => void;
+    /** Forwarded to {@link NarrativeCollapsible} — external height constraint in pixels. */
+    constrainedHeightPx?: number;
+    /** Forwarded to {@link NarrativeCollapsible} — max height constraint in pixels. (Limit after 'show more' is expanded) */
+    maxConstrainedHeightPx?: number;
+} & HookEnableParam;
 /**
  * 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

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

@@ -22,7 +22,7 @@ export interface UseGetNlgInsightsParams {
     verbosity?: 'Low' | 'High';
 }
 /**
- * Parameters for building a narration request (before JAQL payload expansion).
+ * Parameters for building a narrative request (before JAQL payload expansion).
  *
  * @sisenseInternal
  */

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

@@ -3,7 +3,7 @@ import { type AdaptMeasuresForQueryOptions } from '../../../domains/visualizatio
 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.
+ * Dimensions and measures for narrative / JAQL, including styled sort, trend, and forecast.
  *
  * @internal
  */
@@ -12,7 +12,7 @@ export declare function getNarrativeDimensionsAndMeasures(chartDataOptions: Char
     measures: Measure[];
 };
 /**
- * Table dimensions and measures for narration / JAQL, including styled sort, trend, and forecast.
+ * Table dimensions and measures for narrative / JAQL, including styled sort, trend, and forecast.
  *
  * @internal
  */

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

@@ -0,0 +1,18 @@
+import type { ChartWidgetProps } from '../../../domains/widgets/components/chart-widget/types.js';
+import type { PivotTableWidgetProps } from '../../../domains/widgets/components/pivot-table-widget/types.js';
+import type { WidgetProps } from '../../../domains/widgets/components/widget/types.js';
+import type { WidgetNarrativeOptions } from '../../../types.js';
+type WidgetPropsWithNarrativeSupport = ChartWidgetProps | PivotTableWidgetProps | Extract<WidgetProps, {
+    widgetType: 'chart';
+} | {
+    widgetType: 'pivot';
+}>;
+/**
+ * Returns narrative options from chart or pivot widget props (`aiOptions.narrative`).
+ *
+ * @param props - Chart or pivot widget props (standalone or {@link WidgetProps} chart/pivot branches)
+ * @returns `WidgetNarrativeOptions` when present
+ * @internal
+ */
+export declare function getWidgetNarrativeOptionsFromWidgetProps(props: WidgetPropsWithNarrativeSupport): WidgetNarrativeOptions | undefined;
+export {};

package/dist/packages/sdk-ui/src/domains/narrative/core/to-nlg-api-verbosity.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Maps SDK narrative verbosity (`low` / `high`) to NLG API values (`Low` / `High`).
+ * @param verbosity - SDK verbosity level (`low` / `high`) or undefined
+ * @returns NLG API verbosity value (`Low` / `High`) or undefined when verbosity is undefined
+ * @internal
+ */
+export declare function toNlgApiVerbosity(verbosity?: 'low' | 'high'): 'Low' | 'High' | undefined;

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

@@ -1,36 +1,114 @@
-import type { DataSource } from '@sisense/sdk-data';
 /**
- * Options shared by {@link useGetWidgetNarrative} and imperative helpers such as
- * {@link getNlgInsightsFromWidget}.
+ * Location where the narrative is displayed in the widget.
  *
- * @internal
+ * - `above`: displayed above the widget
+ * - `below`: displayed below the widget
+ * - `alone`: displayed alone, without any other widget content
+ *
+ * @default 'above'
+ * @alpha
+ */
+export type WidgetNarrativeDisplayLocation = 'above' | 'below' | 'alone';
+/**
+ * Narrative configuration options for widgets.
+ *
+ * @alpha
  */
-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';
+export type WidgetNarrativeOptions = {
+    /**
+     * Verbosity for narrative generation.
+     *
+     * @default low
+     */
+    verbosity?: 'low' | 'high';
     /**
-     * When `true`, attempts the unified AI narrative endpoint and falls back to the legacy endpoint
-     * on 404. When `false` or omitted, only the legacy endpoint is used.
+     * When `true`, any trend and forecast companion measures present on the widget are included in the narrative request.
      *
-     * **Hook-based flows** (e.g. {@link useGetWidgetNarrative}): when omitted, the value is read
-     * from `app.settings.narrative.canGenerateNarrativeViaAI` via {@link useSisenseContext}.
+     * When `false`, they are not included in the narrative request.
      *
-     * **Imperative helpers** (e.g. {@link getNlgInsightsFromWidget}): no context fallback is
-     * performed — omitting this option is equivalent to `false` (legacy endpoint only).
+     * @default true
      */
-    canGenerateNarrativeViaAI?: boolean;
+    includeTrendAndForecast?: 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.
+     * When `true`, narrative is enabled for the widget.
+     *
+     * When `false`, narrative is disabled for the widget and will not be generated.
      *
      * @default false
      */
-    ignoreTrendAndForecast?: boolean;
-}
+    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 WidgetNarrativeOptions.displayLocation | displayLocation} is `'alone'`
+     *   (the chart is already hidden in that mode).
+     */
+    heightFraction?: number;
+};
+/**
+ * {@link WidgetNarrativeOptions} with all optional fields filled using {@link getCompleteWidgetNarrativeOptions}.
+ *
+ * @alpha
+ */
+export type CompleteWidgetNarrativeOptions = {
+    enabled: boolean;
+    verbosity: 'low' | 'high';
+    displayLocation: WidgetNarrativeDisplayLocation;
+    autoShow: boolean;
+    includeTrendAndForecast: boolean;
+    feedback: {
+        enabled: boolean;
+    };
+    /** Resolved from {@link WidgetNarrativeOptions.heightFraction}. `undefined` means no constraint. */
+    heightFraction: number | undefined;
+};
 /**
- * @deprecated Use {@link WidgetNarrativeOptions}. Same shape; kept for legacy naming.
- * @internal
+ * Returns {@link WidgetNarrativeOptions} with defaults applied for runtime.
+ *
+ * @param narrative - Optional narrative configuration to apply defaults to
+ * @returns Complete narrative configuration with defaults applied
+ * @alpha
  */
-export type WidgetNarrativeNlgOptions = WidgetNarrativeOptions;
+export declare function getCompleteWidgetNarrativeOptions(narrative?: WidgetNarrativeOptions): CompleteWidgetNarrativeOptions;

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 CompleteWidgetNarrativeOptions } from './widget-narrative-options.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. `aiOptions.narrative` supplies {@link WidgetNarrativeOptions}. Defaults are calculated via {@link getCompleteWidgetNarrativeOptions})
  * @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'`); `aiOptions.narrative` supplies
+ *   {@link WidgetNarrativeOptions} via {@link getWidgetNarrativeOptionsFromWidgetProps}
  * @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 (`aiOptions.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 getCompleteWidgetNarrativeOptionsFromWidgetProps(props: WidgetProps): CompleteWidgetNarrativeOptions;
+/**
+ * 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 WidgetNarrativeOptions} are derived from `props.aiOptions?.narrative`
+ *   via {@link getWidgetNarrativeOptionsFromWidgetProps} and {@link getCompleteWidgetNarrativeOptions}.
  * @internal
  */
-export declare function buildWidgetNarrativeRequests(props: WidgetProps, defaultDataSource?: DataSource, verbosity?: 'Low' | 'High', ignoreTrendAndForecast?: boolean): WidgetNarrativeRequestPair;
+export declare function buildWidgetNarrativeRequests(props: WidgetProps, defaultDataSource?: DataSource): WidgetNarrativeRequestPair;