@sisense/sdk-ui 2.26.0 → 2.28.0

package/dist/packages/sdk-ui/src/modules/ai/api/chat-rest-api.d.ts

@@ -19,7 +19,7 @@ export declare class ChatRestApi {
     private deleteChatHistory;
     private sendFeedback;
     ai: {
-        getNlgInsights: (request: GetNlgInsightsRequest, options?: GetNarrativeOptions) => Promise<import("../../../infra/api/narrative/narrative-api-types").NarrativeResponse>;
+        getNlgInsights: (request: GetNlgInsightsRequest, options?: GetNarrativeOptions) => Promise<import("../../../infra/api/narrative/narrative-api-types").NarrativeResponse | undefined>;
         getNlqResult: (contextTitle: string, request: GetNlqResultRequest) => Promise<NlqResult | undefined>;
         getQueryRecommendations: (contextTitle: string, config: QueryRecommendationConfig) => Promise<QueryRecommendationResponse | undefined>;
         setLlmConfig: (config: LlmConfig) => Promise<unknown>;

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/dashboard/translate-dashboard-from-json.d.ts

@@ -0,0 +1,17 @@
+import { DashboardProps } from '../../../../domains/dashboarding/types.js';
+import type { NlqTranslationResult } from '../../types.js';
+import type { DashboardInput } from '../types.js';
+/**
+ * Translates NLQ DashboardJSON format to CSDK DashboardProps.
+ * Direction: JSON → CSDK
+ *
+ * Translates each widget using `translateWidgetFromJSON` (which requires each widget JSON to
+ * have an `id`). Dashboard-level filters are translated using the shared filter translator.
+ *
+ * Translation fails if any widget or filter translation fails.
+ *
+ * @param input - DashboardInput containing dashboardJSON and data schema context
+ * @returns NlqTranslationResult with DashboardProps or errors
+ * @internal
+ */
+export declare const translateDashboardFromJSON: (input: DashboardInput) => NlqTranslationResult<DashboardProps>;

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/dashboard/translate-dashboard-to-json.d.ts

@@ -0,0 +1,15 @@
+import { DashboardProps } from '../../../../domains/dashboarding/types.js';
+import type { NlqTranslationResult } from '../../types.js';
+import type { DashboardJSON } from '../types.js';
+/**
+ * Translates CSDK DashboardProps to NLQ DashboardJSON format.
+ * Direction: CSDK → JSON
+ *
+ * Translates each widget using `translateWidgetToJSON` and dashboard-level filters using
+ * the shared filter translator. Translation fails if any widget or filter translation fails.
+ *
+ * @param dashboardProps - Dashboard props to serialize
+ * @returns NlqTranslationResult with DashboardJSON or errors
+ * @internal
+ */
+export declare const translateDashboardToJSON: (dashboardProps: DashboardProps) => NlqTranslationResult<DashboardJSON>;

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/index.d.ts

@@ -4,5 +4,9 @@ export * from './chart/translate-chart-from-json.js';
 export * from './chart/translate-chart-to-json.js';
 export * from './pivot-table/translate-pivot-table-from-json.js';
 export * from './pivot-table/translate-pivot-table-to-json.js';
+export * from './widget/translate-widget-from-json.js';
+export * from './widget/translate-widget-to-json.js';
+export * from './dashboard/translate-dashboard-from-json.js';
+export * from './dashboard/translate-dashboard-to-json.js';
 export * from './query/translate-query-to-jaql.js';
-export type { ChartJSON, DataOptionsJSON, ChartInput, PivotTableJSON, PivotTableDataOptionsJSON, PivotTableInput, } from './types.js';
+export type { ChartJSON, DataOptionsJSON, ChartInput, DataSourceJSON, PivotTableJSON, PivotTableDataOptionsJSON, PivotTableInput, ChartWidgetJSON, PivotTableWidgetJSON, TextWidgetJSON, CustomWidgetJSON, WidgetJSON, WidgetInput, SpecificWidgetOptionsJSON, WidgetsOptionsJSON, DashboardJSON, DashboardInput, } from './types.js';

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/query/translate-query-from-json.d.ts

@@ -1,11 +1,11 @@
-import { BaseQueryParams } from '../../../../domains/query-execution/index.js';
+import type { ExecuteQueryParams } from '../../../../domains/query-execution/index.js';
 import { NlqTranslationResult } from '../../types.js';
 import { QueryInput } from '../../types.js';
 /**
- * Translates NLQ JSON format to CSDK BaseQueryParams object.
+ * Translates NLQ JSON format to CSDK ExecuteQueryParams object.
  * Direction: JSON → CSDK
  *
- * Translate Query JSON generated by the new NLQ API to BaseQueryParams object.
+ * Translate Query JSON generated by the new NLQ API to ExecuteQueryParams object.
  *
  * @example
  * {
@@ -219,7 +219,7 @@ import { QueryInput } from '../../types.js';
   ],
 }}
  * @param input - QueryInput object
- * @returns NlqTranslationResult<BaseQueryParams>
+ * @returns NlqTranslationResult<ExecuteQueryParams>
  * @internal
  */
-export declare const translateQueryFromJSON: (input: QueryInput) => NlqTranslationResult<BaseQueryParams>;
+export declare const translateQueryFromJSON: (input: QueryInput) => NlqTranslationResult<ExecuteQueryParams>;

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/query/translate-query-to-jaql.d.ts

@@ -1,18 +1,18 @@
 import { type DataSource } from '@sisense/sdk-data';
 import type { JaqlQueryPayload } from '@sisense/sdk-query-client';
-import { BaseQueryParams } from '../../../../domains/query-execution/types.js';
+import type { ExecuteQueryParams } from '../../../../domains/query-execution/types.js';
 /**
- * Converts BaseQueryParams to JAQL payload
+ * Converts ExecuteQueryParams to JAQL payload
  *
  * This is a pure TypeScript function that works in Node.js environments
  * and converts query parameters to JAQL without requiring React hooks or browser APIs.
  *
  * Reuses the existing query preparation logic from executeQuery to avoid duplication.
  *
- * @param queryParams - The base query parameters from NLQ translation
+ * @param queryParams - Query parameters (execution-only fields are not reflected in JAQL beyond prepareQueryParams)
  * @param defaultDataSource - Default data source if not specified in queryParams
  * @param shouldSkipHighlightsWithoutAttributes - Whether to skip highlights without corresponding attributes
  * @returns The JAQL query payload
  * @internal
  */
-export declare function translateQueryToJaql(queryParams: BaseQueryParams, defaultDataSource?: DataSource, shouldSkipHighlightsWithoutAttributes?: boolean): JaqlQueryPayload;
+export declare function translateQueryToJaql(queryParams: ExecuteQueryParams, defaultDataSource?: DataSource, shouldSkipHighlightsWithoutAttributes?: boolean): JaqlQueryPayload;

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/query/translate-query-to-json.d.ts

@@ -1,14 +1,14 @@
-import { BaseQueryParams } from '../../../../domains/query-execution/index.js';
+import type { ExecuteQueryParams } from '../../../../domains/query-execution/index.js';
 import { NlqResponseJSON, NlqTranslationResult } from '../../types.js';
 /**
- * Translates CSDK BaseQueryParams to NLQ JSON format.
+ * Translates CSDK ExecuteQueryParams to NLQ JSON format.
  * Direction: CSDK → JSON
  *
  * Converts CSDK objects (Attribute[], Measure[], Filter[], FilterRelations) to NLQ FunctionCall format.
  *
  * @example
  * ```typescript
- * const query: BaseQueryParams = {
+ * const query: ExecuteQueryParams = {
  *   dimensions: [DM.Category.Category, DM.Brand.Brand],
  *   measures: [
  *     measureFactory.sum(DM.Commerce.Revenue, 'Total Revenue'),
@@ -49,8 +49,8 @@ import { NlqResponseJSON, NlqTranslationResult } from '../../types.js';
  * });
  * ```
  *
- * @param query - BaseQueryParams object with CSDK objects
+ * @param query - ExecuteQueryParams object with CSDK objects
  * @returns NlqTranslationResult<NlqResponseJSON> with FunctionCall format or structured errors
  * @internal
  */
-export declare function translateQueryToJSON(query: BaseQueryParams): NlqTranslationResult<NlqResponseJSON>;
+export declare function translateQueryToJSON(query: ExecuteQueryParams): NlqTranslationResult<NlqResponseJSON>;

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/shared/data-options/adapters.d.ts

@@ -13,7 +13,4 @@ export type AxisType = 'dimension' | 'measure';
 export declare function adaptDimensionsToStyledColumn(items: DimensionTranslationItem[]): (Attribute | StyledColumn)[];
 export declare function adaptMeasuresToStyledMeasureColumn(items: MeasureTranslationItem[]): (Measure | StyledMeasureColumn)[];
 export declare function toJSONArray(value: DimensionItemJSON | DimensionItemJSON[] | MeasureItemJSON | MeasureItemJSON[]): JSONArray;
-/**
- * Maps inner translation errors to dataOptions axis context.
- */
 export declare function withAxisContext(axisKey: string): (e: NlqTranslationError) => NlqTranslationError;

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/shared/expression/custom-formula/process-custom-formula.d.ts

@@ -12,6 +12,7 @@ import { FunctionContext, ProcessedArg } from '../../../types.js';
  *
  * @param processedArgs - [title: string, formula: string, context: Record<string, unknown>, format?: string, description?: string]
  * @param context - Processing context with error prefix and other metadata
+ * @returns New args array with `processedContext` at index 2 (does not mutate `processedArgs`)
  * @throws Error with descriptive message if validation fails
  */
-export declare function processCustomFormula(processedArgs: ProcessedArg[], context: FunctionContext): void;
+export declare function processCustomFormula(processedArgs: ProcessedArg[], context: FunctionContext): ProcessedArg[];

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/shared/expression/factory-function-processors.d.ts

@@ -13,7 +13,6 @@ import { CustomFunctionProcessor } from '../../types.js';
  * ```typescript
  * // Adding a new custom processor
  * 'measureFactory.rank': processRankingParameters,
- * 'filterFactory.dateRange': processDateRangeLogic,
  * ```
  */
 export declare const FUNCTION_PROCESSORS: Record<string, CustomFunctionProcessor>;

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/shared/expression/filter-processors.d.ts

@@ -5,33 +5,37 @@ import { FunctionContext, ProcessedArg } from '../../types.js';
  *
  * @param processedArgs - [attribute, value, config?]
  * @param context - Processing context with error prefix and other metadata
+ * @returns Same `processedArgs` reference when validation succeeds
  * @throws Error with descriptive message if validation fails
  */
-export declare function processStringOrNumericFilter(processedArgs: ProcessedArg[], context: FunctionContext): void;
+export declare function processStringOrNumericFilter(processedArgs: ProcessedArg[], context: FunctionContext): ProcessedArg[];
 /**
  * Processes filters that only accept numeric values
  * Used by: greaterThan, lessThan, between, etc.
  *
  * @param processedArgs - [attribute, value, config?]
  * @param context - Processing context with error prefix and other metadata
+ * @returns Same `processedArgs` reference when validation succeeds
  * @throws Error with descriptive message if validation fails
  */
-export declare function processNumericFilter(processedArgs: ProcessedArg[], context: FunctionContext): void;
+export declare function processNumericFilter(processedArgs: ProcessedArg[], context: FunctionContext): ProcessedArg[];
 /**
  * Processes filters that only accept string values
  * Used by: contains, startsWith, endsWith, like, etc.
  *
  * @param processedArgs - [attribute, value, config?]
  * @param context - Processing context with error prefix and other metadata
+ * @returns Same `processedArgs` reference when validation succeeds
  * @throws Error with descriptive message if validation fails
  */
-export declare function processStringFilter(processedArgs: ProcessedArg[], context: FunctionContext): void;
+export declare function processStringFilter(processedArgs: ProcessedArg[], context: FunctionContext): ProcessedArg[];
 /**
  * Processes exclude filter to validate that it only accepts members filters
  * Used by: exclude
  *
  * @param processedArgs - [filter, inputFilter?, config?]
  * @param context - Processing context with error prefix and other metadata
+ * @returns Same `processedArgs` reference when validation succeeds
  * @throws Error with descriptive message if validation fails
  */
-export declare function processExcludeFilter(processedArgs: ProcessedArg[], context: FunctionContext): void;
+export declare function processExcludeFilter(processedArgs: ProcessedArg[], context: FunctionContext): ProcessedArg[];

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/shared/utils/error-path.d.ts

@@ -0,0 +1,37 @@
+import type { NlqTranslationError } from '../../../types.js';
+/**
+ * Builds a path string for a dataOptions field.
+ *
+ * @internal
+ */
+export declare function dataOptionsPath(axisKey: string | number, itemIndex?: number): string;
+/**
+ * Joins path segments using pathPrefix notation (e.g. "widgets[0].dataOptions.category[0]").
+ *
+ * @internal
+ */
+export declare function joinPathStrings(prefix: string, suffix?: string): string;
+/**
+ * Prefixes an error path with a structural segment.
+ *
+ * @internal
+ */
+export declare function prefixPath(prefix: string): (error: NlqTranslationError) => NlqTranslationError;
+/**
+ * Prefixes path with widgets[index] for dashboard-level widget errors.
+ *
+ * @internal
+ */
+export declare function withWidgetsArrayPath(widgetIndex: number): (error: NlqTranslationError) => NlqTranslationError;
+/**
+ * Prefixes filter errors with filters[index] at dashboard level.
+ *
+ * @internal
+ */
+export declare function withFilterPath(filterIndex: number): (error: NlqTranslationError) => NlqTranslationError;
+/**
+ * Maps errors from a translation result through a mapper.
+ *
+ * @internal
+ */
+export declare function mapTranslationErrors(errors: readonly NlqTranslationError[], mapError: (error: NlqTranslationError) => NlqTranslationError): NlqTranslationError[];

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/shared/utils/translation-helpers.d.ts

@@ -3,17 +3,49 @@
  *
  * @internal
  */
-import { JSONValue } from '@sisense/sdk-data';
+import type { DataSource, JSONObject } from '@sisense/sdk-data';
+import type { WidgetsOptions } from '../../../../../domains/dashboarding/dashboard-model/types.js';
 import type { NlqTranslationError, NlqTranslationResult } from '../../../types.js';
+import type { DataSourceJSON, WidgetsOptionsJSON } from '../../types.js';
+type WithOptionalToJSON = {
+    toJSON?: () => JSONObject;
+};
+/**
+ * Returns a JSON-friendly snapshot for translation error reporting.
+ * Uses `toJSON()` when present (CSDK Attribute/Measure); otherwise returns the value as-is.
+ *
+ * @internal
+ */
+/**
+ * Serializes a CSDK data source to NLQ JSON (title string only).
+ *
+ * @param dataSource - Widget or dashboard data source
+ * @returns Data source title for JSON output
+ * @internal
+ */
+export declare function translateDataSourceToJSON(dataSource: DataSource): DataSourceJSON;
+/**
+ * Extracts JSON-serializable widget options from dashboard `widgetsOptions`.
+ * Omits `jtdConfig` and other non-JSON-safe fields.
+ *
+ * @param widgetsOptions - Dashboard widget options map
+ * @returns Widget options safe for NLQ JSON, or `undefined` when empty
+ * @internal
+ */
+export declare function translateWidgetsOptionsToJSON(widgetsOptions: WidgetsOptions): WidgetsOptionsJSON | undefined;
+export declare function toNlqErrorInput(value: WithOptionalToJSON | unknown): unknown;
 /**
  * Recursively strips [[delimiters]] from all strings in a JSON structure.
  * Transforms "DM.[[Commerce Sales]].[[Order Date]]" → "DM.Commerce Sales.Order Date"
  *
- * @param value - The JSON value to process
+ * Accepts NLQ output shapes (e.g. ChartJSON) that are JSON-serializable at runtime but are not
+ * assignable to sdk-data `JSONValue` because of `Record<string, unknown>` style fields.
+ *
+ * @param value - The value to process
  * @returns The value with all [[delimiters]] stripped from strings
  * @internal
  */
-export declare function stripDelimitersFromJson<T extends JSONValue>(value: T): T;
+export declare function stripDelimitersFromJson<T>(value: T): T;
 export declare function getSuccessData<T>(result: NlqTranslationResult<T>): T;
 export declare function getErrors<T>(result: NlqTranslationResult<T>): string[];
 /**
@@ -29,3 +61,4 @@ export declare function getErrors<T>(result: NlqTranslationResult<T>): string[];
  * @internal
  */
 export declare function collectTranslationErrors<T>(translateFn: () => NlqTranslationResult<T>, errors: NlqTranslationError[], mapError?: (e: NlqTranslationError) => NlqTranslationError): T | null;
+export {};

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/types.d.ts

@@ -1,6 +1,9 @@
 import { type Arg, type ArgValue, Attribute, Filter, FilterRelations, type FunctionCall, JaqlDataSourceForDto, JSONArray, Measure, PivotGrandTotals } from '@sisense/sdk-data';
-import { CategoryStyle, SeriesStyle, ValueStyle } from '../../../public-api/index.js';
-import type { PivotTableStyleOptions } from '../../../types.js';
+import type { CommonFiltersOptions } from '../../../domains/dashboarding/common-filters/types.js';
+import type { DashboardConfig, DashboardLayoutOptions, DashboardStyleOptions } from '../../../domains/dashboarding/types.js';
+import { CategoryStyle, SeriesStyle, ValueStyle } from '../../../domains/visualizations/core/chart-data-options/types.js';
+import type { WidgetConfig, WidgetType } from '../../../domains/widgets/components/widget/types.js';
+import type { CustomWidgetStyleOptions, PivotTableStyleOptions, TextWidgetStyleOptions } from '../../../types.js';
 import { DataSchemaContext, NlqTranslationInput } from '../types.js';
 import type { SchemaIndex } from './shared/utils/schema-index.js';
 /**
@@ -49,8 +52,12 @@ export type NodeInput = NlqTranslationInput<FunctionCall, FunctionContext>;
 export type ArgInput = NlqTranslationInput<Arg, ArgContext>;
 /**
  * Custom processor function signature.
+ *
+ * Implementations must not mutate `processedArgs`. Returns the argument list to pass to
+ * `executeFunction`—typically the same array reference when only validating, or a new array when
+ * normalizing or replacing nested values.
  */
-export type CustomFunctionProcessor = (processedArgs: ProcessedArg[], context: FunctionContext) => void;
+export type CustomFunctionProcessor = (processedArgs: ProcessedArg[], context: FunctionContext) => ProcessedArg[];
 /**
  * Type guard: value is a non-null object (Record<string, unknown>).
  * @internal
@@ -209,3 +216,125 @@ export interface PivotTableJSON {
  * @internal
  */
 export type PivotTableInput = NlqTranslationInput<PivotTableJSON, DataSchemaContext>;
+/**
+ * Mirrors `WithCommonWidgetProps` for the JSON layer
+ */
+type WithCommonWidgetJSON<Base, Type extends WidgetType> = Base & {
+    widgetType: Type;
+    readonly id: string;
+};
+/**
+ * Data source in NLQ JSON — title only. Full JAQL details live in {@link DataSchemaContext}.
+ *
+ * @internal
+ */
+export type DataSourceJSON = string;
+/**
+ * JSON representation of a chart widget
+ *
+ * @internal
+ */
+export type ChartWidgetJSON = ChartJSON & {
+    title?: string;
+    description?: string;
+    dataSource?: DataSourceJSON;
+    config?: WidgetConfig;
+    highlightSelectionDisabled?: boolean;
+};
+/**
+ * JSON representation of a pivot table widget.
+ *
+ * @internal
+ */
+export type PivotTableWidgetJSON = PivotTableJSON & {
+    title?: string;
+    description?: string;
+    dataSource?: DataSourceJSON;
+    config?: WidgetConfig;
+};
+/**
+ * JSON representation of a text widget
+ *
+ * @internal
+ */
+export type TextWidgetJSON = {
+    styleOptions: TextWidgetStyleOptions;
+    config?: WidgetConfig;
+};
+/**
+ * JSON representation of a custom/plugin widget payload.
+ * `dataOptions` is passed through as opaque JSON — `GenericDataOptions` cannot be reliably
+ * round-tripped without custom-widget-specific schema knowledge.
+ * Only `filters` and `highlights` are translated; all other fields are pass-through.
+ * `widgetType` and `id` are added on `WidgetJSON` via `WithCommonWidgetJSON`.
+ *
+ * @internal
+ */
+export type CustomWidgetJSON = {
+    customWidgetType: string;
+    title?: string;
+    description?: string;
+    dataSource?: DataSourceJSON;
+    config?: WidgetConfig;
+    filters?: FunctionCall[];
+    highlights?: FunctionCall[];
+    /** Opaque pass-through — GenericDataOptions serialized as plain JSON */
+    dataOptions?: Record<string, unknown>;
+    styleOptions?: CustomWidgetStyleOptions;
+    customOptions?: Record<string, unknown>;
+};
+/**
+ * Dashboard-level options for a specific widget in NLQ JSON.
+ * Excludes non-JSON-safe fields such as `jtdConfig` (Map / Filter objects).
+ *
+ * @internal
+ */
+export type SpecificWidgetOptionsJSON = {
+    filtersOptions?: CommonFiltersOptions;
+    partialDtoOptions?: {
+        options?: Record<string, unknown>;
+        style?: Record<string, unknown>;
+    };
+};
+/**
+ * Widget options map for NLQ dashboard JSON.
+ *
+ * @internal
+ */
+export type WidgetsOptionsJSON = Record<string, SpecificWidgetOptionsJSON>;
+/**
+ * Discriminated union of all NLQ widget JSON representations.
+ * Mirrors the `WidgetProps` discriminated union in serializable JSON form.
+ *
+ * @internal
+ */
+export type WidgetJSON = WithCommonWidgetJSON<ChartWidgetJSON, 'chart'> | WithCommonWidgetJSON<PivotTableWidgetJSON, 'pivot'> | WithCommonWidgetJSON<TextWidgetJSON, 'text'> | WithCommonWidgetJSON<CustomWidgetJSON, 'custom'>;
+/**
+ * JSON representation of a dashboard.
+ *
+ * @internal
+ */
+export interface DashboardJSON {
+    id?: string;
+    title?: string;
+    filters?: FunctionCall[];
+    widgets: WidgetJSON[];
+    layoutOptions?: DashboardLayoutOptions;
+    config?: DashboardConfig;
+    /** Data source title only — schema details live in {@link DataSchemaContext}. */
+    defaultDataSource?: DataSourceJSON;
+    styleOptions?: DashboardStyleOptions;
+    widgetsOptions?: WidgetsOptionsJSON;
+}
+/**
+ * Input type for widget translation (JSON → CSDK).
+ *
+ * @internal
+ */
+export type WidgetInput = NlqTranslationInput<WidgetJSON, DataSchemaContext>;
+/**
+ * Input type for dashboard translation (JSON → CSDK).
+ *
+ * @internal
+ */
+export type DashboardInput = NlqTranslationInput<DashboardJSON, DataSchemaContext>;

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/widget/helpers/index.d.ts

@@ -0,0 +1,6 @@
+export { translateCustomWidgetFiltersFromJSON } from './translate-custom-widget-filters-from-json.js';
+export { translateEnvelopeWidgetFromJSON } from './translate-envelope-widget-from-json.js';
+export { toChartWidgetProps, toPivotTableWidgetProps } from './to-widget-props.js';
+export type { WidgetMeta } from './to-widget-props.js';
+export { validateWidgetType } from './validate-widget-json.js';
+export { hasRequiredWidgetId, missingWidgetIdError } from './widget-id.js';

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/widget/helpers/to-widget-props.d.ts

@@ -0,0 +1,27 @@
+import type { WidgetConfig, WidgetProps } from '../../../../../domains/widgets/components/widget/types.js';
+import type { ChartProps, PivotTableProps } from '../../../../../props.js';
+import type { DataSourceJSON } from '../../types.js';
+export type WidgetMeta = {
+    readonly id: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly dataSource?: DataSourceJSON;
+    readonly config?: WidgetConfig;
+    readonly highlightSelectionDisabled?: boolean;
+};
+/**
+ * Maps chart component props (with `dataSet`) to chart widget props (with `dataSource`).
+ *
+ * @internal
+ */
+export declare const toChartWidgetProps: (chartProps: ChartProps, meta: WidgetMeta) => Extract<WidgetProps, {
+    widgetType: 'chart';
+}>;
+/**
+ * Maps pivot table component props (with `dataSet`) to pivot widget props (with `dataSource`).
+ *
+ * @internal
+ */
+export declare const toPivotTableWidgetProps: (pivotProps: PivotTableProps, meta: WidgetMeta) => Extract<WidgetProps, {
+    widgetType: 'pivot';
+}>;

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/widget/helpers/translate-custom-widget-filters-from-json.d.ts

@@ -0,0 +1,12 @@
+import type { Filter, FilterRelations, FunctionCall } from '@sisense/sdk-data';
+import type { DataSchemaContext, NlqTranslationResult } from '../../../types.js';
+export type CustomWidgetFiltersTranslation = {
+    readonly filters?: Filter[] | FilterRelations;
+    readonly highlights?: Filter[];
+};
+/**
+ * Translates custom-widget filters and highlights from NLQ JSON to CSDK filters.
+ *
+ * @internal
+ */
+export declare const translateCustomWidgetFiltersFromJSON: (filters: FunctionCall[] | undefined, highlights: FunctionCall[] | undefined, context: DataSchemaContext) => NlqTranslationResult<CustomWidgetFiltersTranslation>;

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/widget/helpers/translate-envelope-widget-from-json.d.ts

@@ -0,0 +1,20 @@
+import type { WidgetConfig } from '../../../../../domains/widgets/components/widget/types.js';
+import type { DataSchemaContext, NlqTranslationInput, NlqTranslationResult } from '../../../types.js';
+import type { DataSourceJSON } from '../../types.js';
+import type { WidgetMeta } from './to-widget-props.js';
+type WidgetEnvelopeJSON = {
+    readonly id: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly dataSource?: DataSourceJSON;
+    readonly config?: WidgetConfig;
+    readonly highlightSelectionDisabled?: boolean;
+};
+/**
+ * Strips widget envelope fields and delegates to a chart/pivot sub-translator,
+ * then maps component props to widget props with metadata.
+ *
+ * @internal
+ */
+export declare const translateEnvelopeWidgetFromJSON: <TWidgetJSON extends WidgetEnvelopeJSON, TPayload, TComponentProps, TWidgetProps>(widgetJSON: TWidgetJSON, context: DataSchemaContext, translate: (input: NlqTranslationInput<TPayload, DataSchemaContext>) => NlqTranslationResult<TComponentProps>, toWidgetProps: (props: TComponentProps, meta: WidgetMeta) => TWidgetProps) => NlqTranslationResult<TWidgetProps>;
+export {};

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/widget/helpers/validate-widget-json.d.ts

@@ -0,0 +1,8 @@
+import type { NlqTranslationError } from '../../../types.js';
+/**
+ * Validates that widget JSON includes a supported `widgetType`.
+ *
+ * @param rawInput - Raw widget JSON object
+ * @returns Validation error, or `null` when `widgetType` is present and valid
+ */
+export declare function validateWidgetType(rawInput: unknown): NlqTranslationError | null;

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/widget/helpers/widget-id.d.ts

@@ -0,0 +1,17 @@
+import type { NlqTranslationError } from '../../../types.js';
+/**
+ * Builds a translation error when widget JSON is missing a required `id`.
+ *
+ * @internal
+ */
+export declare const missingWidgetIdError: (input: unknown) => NlqTranslationError;
+/**
+ * Narrows widget JSON to require a present `id`.
+ *
+ * @internal
+ */
+export declare const hasRequiredWidgetId: <T extends {
+    id?: string | undefined;
+}>(widget: T) => widget is T & {
+    id: string;
+};

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/widget/translate-widget-from-json.d.ts

@@ -0,0 +1,19 @@
+import type { WidgetProps } from '../../../../domains/widgets/components/widget/types.js';
+import type { NlqTranslationResult } from '../../types.js';
+import type { WidgetInput } from '../types.js';
+/**
+ * Translates NLQ WidgetJSON format to CSDK widget props.
+ * Direction: JSON → CSDK
+ *
+ * Dispatches to the appropriate sub-translator based on `widgetType`:
+ * - `'chart'` → `translateChartFromJSON`
+ * - `'pivot'` → `translatePivotTableFromJSON`
+ * - `'text'` → pass-through (no data translation)
+ * - `'custom'` → filters/highlights translated; dataOptions passed through as opaque JSON
+ *
+ *
+ * @param input - WidgetInput containing widgetJSON and data schema context
+ * @returns NlqTranslationResult with WidgetProps or errors
+ * @internal
+ */
+export declare const translateWidgetFromJSON: (input: WidgetInput) => NlqTranslationResult<WidgetProps>;

package/dist/packages/sdk-ui/src/modules/analytics-composer/nlq-v3-translator/widget/translate-widget-to-json.d.ts

@@ -0,0 +1,18 @@
+import type { WidgetProps } from '../../../../domains/widgets/components/widget/types.js';
+import type { NlqTranslationResult } from '../../types.js';
+import type { WidgetJSON } from '../types.js';
+/**
+ * Translates CSDK widget props to NLQ WidgetJSON format.
+ * Direction: CSDK → JSON
+ *
+ * Dispatches to the appropriate sub-translator based on `widgetType`:
+ * - `'chart'` → `translateChartToJSON`
+ * - `'pivot'` → `translatePivotTableToJSON`
+ * - `'text'` → pass-through of styleOptions
+ * - `'custom'` → filters/highlights translated; dataOptions passed through as opaque JSON
+ *
+ * @param widgetProps - Widget props with widgetType discriminant (id required)
+ * @returns NlqTranslationResult with WidgetJSON or errors
+ * @internal
+ */
+export declare const translateWidgetToJSON: (widgetProps: WidgetProps) => NlqTranslationResult<WidgetJSON>;

package/dist/packages/sdk-ui/src/modules/analytics-composer/types.d.ts

@@ -348,15 +348,16 @@ export interface DataSchemaContext {
  */
 export type QueryInput = NlqTranslationInput<NlqResponseJSON, DataSchemaContext>;
 /**
- * Context information for error generation
+ * Context used when building translation errors (before message is attached).
  *
  * @internal
  */
 export type NlqTranslationErrorContext = {
-    /** The category of the query/chart element that failed (dimensions, measures, filters, highlights, dataOptions, chartType, styleOptions) */
-    category: 'dimensions' | 'measures' | 'filters' | 'highlights' | 'dataOptions' | 'chartType' | 'styleOptions';
-    /** The index of the element within its category array, or axis key for dataOptions (e.g. "category", "value") */
-    index: number | string;
+    /**
+     * Structural location in the JSON being translated, using pathPrefix notation.
+     * e.g. "widgets[0].dataOptions.category[0]" or "filters[0]"
+     */
+    path: string;
     /** The complete original input that caused the error */
     input: unknown;
 };

package/dist/packages/sdk-ui/src/modules/analytics-composer/widget/chart-options/get-widget-options.d.ts

@@ -15,6 +15,18 @@ export declare const getChartRecommendationsOrDefault: (response: ExpandedQueryM
  * @internal
  */
 export declare const getChartDataOptions: (metadataItems: MetadataItem[], chartFamily: string, axesMapping: AxesMapping) => ChartDataOptions;
+/**
+ * Minimal chart style overrides for consumers that persist widget props without merged SDK defaults.
+ * Compose merges these with per-chart defaults at render time (`extendStyleOptionsWithDefaults`).
+ *
+ * This function is used by buildChartEngine in sdk-ai-core
+ *
+ * @param chartType - chart type
+ * @param axesMapping - axes mapping
+ * @returns partial style options
+ * @internal
+ */
+export declare const getMinimalChartStyleOptions: (chartType: ChartType, axesMapping: AxesMapping) => Partial<ChartStyleOptions>;
 /**
  * Get chart style options for the chart widget.
  *