@sisense/sdk-ui 1.4.1 → 1.6.0

package/dist/ai/translators/query-translator.d.ts

@@ -0,0 +1,122 @@
+import { ExpandedQueryModel, SimpleQueryModel, SimpleChartRecommendations } from '../../ai/translators/types';
+import { DataSourceField, MetadataItem, MetadataItemJaql } from '@sisense/sdk-query-client';
+import { ChartRecommendations } from '../../ai';
+/**
+ * A class that translates ExpandedQueryModel (Raw JAQL+Chart Recommendations)
+ * to SimpleQueryModel (Simple JAQL+Simple Chart Options) and vice versa.
+ *
+ * It also provides methods to stringify query models to YAML strings
+ * and parse YAML strings to query models.
+ *
+ * @internal
+ */
+export declare class QueryTranslator {
+    private readonly contextTitle;
+    private indexedFields;
+    /**
+     * Constructor for QueryTranslator.
+     *
+     * @param contextTitle - The context title
+     * @param fields - The data source fields
+     */
+    constructor(contextTitle: string, fields: DataSourceField[]);
+    /**
+     * Concatenates Aggregation Types.
+     */
+    private concatAggTypes;
+    /**
+     * Simplifies Aggregation Formula defined in MetadataItemJaql returned from chat response.
+     *
+     * @param aggFormula - The Aggregation Formula to simplify
+     * @returns The equivalent measure
+     * @privateRemarks
+     * See unit tests for examples of aggregation formulas and their equivalent measures.
+     */
+    simplifyAggFormula(aggFormula: MetadataItemJaql): MetadataItemJaql;
+    /**
+     * Simplifies MetadataItemJaql.
+     *
+     * @param item - The MetadataItemJaql to simplify
+     * @returns The simplified MetadataItemJaql
+     */
+    simplifyMetadataItemJaql(item: MetadataItemJaql): MetadataItemJaql;
+    /**
+     * Simplifies MetadataItem.
+     *
+     * @param item - The MetadataItem to simplify
+     * @returns The simplified MetadataItem
+     */
+    simplifyMetadataItem(item: MetadataItem): MetadataItem;
+    /**
+     * Simplifies Chart Recommendations.
+     *
+     * @param chartRecommendations - The Chart Recommendations to simplify
+     * @returns The simplified chart data options
+     */
+    simplifyChartRecommendations(chartRecommendations: ChartRecommendations | {}): SimpleChartRecommendations | {};
+    /**
+     * Returns the query title with the chart type.
+     *
+     * @param queryTitle - The query title
+     * @param chartRecommendations - The chart recommendations
+     * @returns The query title with the chart type
+     */
+    getQueryTitleWithChartType(queryTitle: string, chartRecommendations: {} | ChartRecommendations): string;
+    /**
+     * Takes a ExpandedQueryModel (e.g., from chat response) and translates it to SimpleQueryModel.
+     *
+     * @param expandedQueryModel - The Expanded Query model to simplify
+     * @returns The simplified query model
+     */
+    translateToSimple(expandedQueryModel: ExpandedQueryModel): SimpleQueryModel;
+    /**
+     * Stringifies a simple query model to YAML string.
+     *
+     * @param simpleQueryModel - The Simple Query model to convert
+     * @returns The YAML string representing the simple query model
+     */
+    stringifySimple(simpleQueryModel: SimpleQueryModel): string;
+    /**
+     * Parses a YAML string to Simple Query Model.
+     *
+     * @param simpleQueryYaml - The YAML string to parse
+     * @returns The Simple Query Model
+     */
+    parseSimple(simpleQueryYaml: string): SimpleQueryModel;
+    /**
+     * Derives chart family from chart type.
+     *
+     * @param chartType - chart type
+     * @returns chart family
+     */
+    private deriveChartFamily;
+    /**
+     * Expands Chart Recommendations.
+     *
+     * @param chartRecommendations - The Chart Recommendations to expand
+     * @returns The expanded chart recommendations
+     */
+    expandChartRecommendations(chartRecommendations: SimpleChartRecommendations | {}): ChartRecommendations | {};
+    /**
+     * Expands MetadataItemJaql by adding table, column, datatype, and title
+     * if they are missing from the item.
+     *
+     * @param item - The MetadataItemJaql to expand
+     * @returns The expanded MetadataItemJaql
+     */
+    expandMetadataItemJaql(item: MetadataItemJaql): MetadataItemJaql;
+    /**
+     * Expands MetadataItem
+     *
+     * @param item - The MetadataItem to expand
+     * @returns The expanded MetadataItem
+     */
+    expandMetadataItem(item: MetadataItem): MetadataItem;
+    /**
+     * Translates a Simple Query Model to Expanded Query Model.
+     *
+     * @param simpleQueryModel - The Simple Query model to convert
+     * @returns The Expanded Query Model
+     */
+    translateToExpanded(simpleQueryModel: SimpleQueryModel): ExpandedQueryModel;
+}

package/dist/ai/translators/translate-props-to-code.d.ts

@@ -0,0 +1,8 @@
+export type MembersFilterJaql = {
+    members: string[];
+};
+export type FromNotEqualFilterJaql = {
+    fromNotEqual: number;
+};
+export type FilterJaql = MembersFilterJaql | FromNotEqualFilterJaql;
+export declare const stringifyProps: (props: object, indent?: number, wrapInQuotes?: boolean) => string;

package/dist/ai/translators/types.d.ts

@@ -0,0 +1,105 @@
+import { MetadataItem } from '@sisense/sdk-query-client';
+import { AxesMapping, NlqResponseData } from '../../ai';
+import { ChartType, TableType } from '../../types';
+import { WidgetModel } from '../../models';
+/**
+ * Expanded Query Model that is based on NlqResponseData.
+ * It contains expanded JAQL and chart recommendations returned from the chat response.
+ *
+ * @internal
+ */
+export type ExpandedQueryModel = Pick<NlqResponseData, 'jaql' | 'chartRecommendations' | 'queryTitle'>;
+/**
+ * Expanded Query Model
+ *
+ * Used as a default value for ExpandedQueryModel
+ *
+ * @internal
+ */
+export declare const EMPTY_EXPANDED_QUERY_MODEL: ExpandedQueryModel;
+/**
+ * Simple Chart Recommendations
+ *
+ * @internal
+ */
+export interface SimpleChartRecommendations {
+    chartType: string;
+    dataOptions: AxesMapping;
+}
+/**
+ * Simple Query Model that is a simplified version of ExpandedQueryModel.
+ *
+ * It removes any JAQL syntax or information that already exists in the schema.
+ * Also, any parameters that have a default do not need to be specified.
+ *
+ * Users manipulates this model via the query in YAML format.
+ *
+ * ModelTranslator is responsible for translating this query model to SimpleWidgetModel.
+ *
+ * @internal
+ */
+export interface SimpleQueryModel {
+    /**
+     * The data model or perspective title.
+     */
+    model: string;
+    metadata: MetadataItem[];
+    chart: SimpleChartRecommendations | {};
+    /**
+     * Title of the query
+     */
+    queryTitle: string;
+}
+/**
+ * Empty Simple Query Model
+ *
+ * Used as a default value for SimpleQueryModel
+ *
+ * @internal
+ */
+export declare const EMPTY_SIMPLE_QUERY_MODEL: SimpleQueryModel;
+/**
+ * All Chart Types including Table
+ * Note: Table will be re-united with ChartType in a future MR
+ *
+ * @internal
+ */
+export type AllChartType = ChartType | TableType;
+/**
+ * Chart Widget Model
+ *
+ * This model serves two purposes:
+ *
+ * (1) For rendering a chart or table widget in the Query Composer.
+ * (2) For reverse engineered (translated) to CSDK code
+ *
+ * Naming TBD
+ *
+ * @internal
+ */
+export type ChartWidgetModel = Pick<WidgetModel, 'getChartWidgetProps' | 'getTableWidgetProps'> & {
+    chartType: AllChartType;
+    queryTitle: string;
+};
+/**
+ * UI Framework
+ *
+ * @internal
+ */
+export type UiFramework = 'react' | 'vue' | 'angular';
+/**
+ * Code Template Key
+ *
+ * @internal
+ */
+export type CodeTemplateKey = 'baseChartTmpl' | 'chartTmpl' | 'chartWidgetTmpl' | 'tableWidgetTmpl';
+/**
+ * Code Templates
+ *
+ * @internal
+ */
+export type CodeTemplates = {
+    [key in UiFramework]: {
+        [key in CodeTemplateKey]: string;
+    };
+};

package/dist/ai/translators/use-get-data-source.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Gets the fields of a data source.
+ *
+ * Alternative hook implementation of QueryApiDispatcher.getDataSourceFields
+ *
+ * @param dataSource - The data source to get the fields for
+ * @internal
+ */
+export declare const useGetDataSource: (dataSource: string | undefined) => {
+    data: import("@sisense/sdk-query-client").DataSourceField[] | undefined;
+    isLoading: boolean;
+};

package/dist/ai/translators/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function toKebabCase(str: string): string;
+export declare function capitalizeFirstLetter(str: string): string;

package/dist/ai/use-chat-session.d.ts

@@ -1,11 +1,18 @@
-import type { ChatMessage } from './api/types';
-interface UseChatSessionResult {
+import type { ChatMessage, NlqMessage, NlqResponseData } from './api/types';
+/**
+ * Result of the useChatSession hook.
+ *
+ * @internal
+ */
+export interface UseChatSessionResult {
     chatId: string | undefined;
     history: ChatMessage[];
+    lastNlqResponse: NlqResponseData | null;
     sendMessage: (message: string) => void;
     isAwaitingResponse: boolean;
     isLoading: boolean;
 }
+export declare const isNlqMessage: (message: ChatMessage | null | undefined) => message is NlqMessage;
 /**
  * React hook that returns a chat session object for the given data model or
  * perspective.
@@ -19,4 +26,3 @@ interface UseChatSessionResult {
  * @internal
  */
 export declare const useChatSession: (contextTitle: string) => UseChatSessionResult;
-export {};

package/dist/ai/use-get-nlg-query-result.d.ts

@@ -1,9 +1,18 @@
-import type { GetNlgQueryResultRequest } from './api/types.js';
+import { Attribute, DataSource, Filter, FilterRelations, Measure } from '@sisense/sdk-data';
+import { GetNlgQueryResultRequest } from './api/types';
+import { GetNlgQueryResultProps } from './get-nlg-query-result';
 /**
  * Parameters for {@link useGetNlgQueryResult} hook.
- *
  */
-export interface UseGetNlgQueryResultParams extends GetNlgQueryResultRequest {
+export interface UseGetNlgQueryResultParams {
+    /** 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
      *
@@ -11,18 +20,30 @@ export interface UseGetNlgQueryResultParams extends GetNlgQueryResultRequest {
      */
     enabled?: boolean;
 }
-export declare const useGetNlgQueryResultInternal: (params: UseGetNlgQueryResultParams) => {
-    data: string | undefined;
-    isError: boolean;
+/**
+ * State for {@link useGetNlgQueryResult} hook.
+ */
+export interface UseGetNlgQueryResultState {
+    /** Whether the data fetching is loading */
     isLoading: boolean;
+    /** Whether the data fetching has failed */
+    isError: boolean;
+    /** Whether the data fetching has succeeded */
     isSuccess: boolean;
-    fetchStatus: import("@tanstack/react-query").FetchStatus;
+    /** The result data */
+    data: string | undefined;
+    /** The error if any occurred */
+    error: unknown;
+    /** Callback to trigger a refetch of the data */
     refetch: () => void;
-};
+}
 /**
- * React hook that fetches an analysis of the provided JAQL using natural language generation (NLG).
- *
- * Note that in the example below, this hook expects `metadata` to be in standard JAQL syntax.
+ * @internal
+ */
+export declare const useGetNlgQueryResultInternal: (params: GetNlgQueryResultProps | GetNlgQueryResultRequest, enabled?: boolean) => UseGetNlgQueryResultState;
+/**
+ * React hook that fetches an analysis of the provided query using natural language generation (NLG).
+ * Specifying a query is similar to providing parameters to a {@link useExecuteQuery} hook, using dimensions, measures, and filters.
  *
  * ::: warning Note
  * This hook is currently under private beta for selected customers and is subject to change as we make fixes and improvements.
@@ -30,66 +51,21 @@ export declare const useGetNlgQueryResultInternal: (params: UseGetNlgQueryResult
  *
  * @example
  * ```tsx
- * import { SisenseContextProvider } from '@sisense/sdk-ui';
- * import { AiContextProvider, useGetNlgQueryResult } from '@sisense/sdk-ui/ai';
+ * const { data, isLoading } = useGetNlgQueryResult({
+ *   dataSource: 'Sample ECommerce',
+ *   dimensions: [DM.Commerce.Date.Years],
+ *   measures: [measureFactory.sum(DM.Commerce.Revenue)],
+ * });
  *
- * function Page() {
- *   const { data } = useGetNlgQueryResult({
- *     jaql: {
- *       datasource: { title: 'Sample ECommerce' },
- *       metadata: [
- *         {
- *           jaql: {
- *             column: 'Date',
- *             datatype: 'datetime',
- *             dim: '[Commerce.Date]',
- *             firstday: 'mon',
- *             level: 'years',
- *             table: 'Commerce',
- *             title: 'Date',
- *           },
- *         },
- *         {
- *           jaql: {
- *             agg: 'sum',
- *             column: 'Revenue',
- *             datatype: 'numeric',
- *             dim: '[Commerce.Revenue]',
- *             table: 'Commerce',
- *             title: 'total of Revenue',
- *           },
- *         },
- *       ],
- *     },
- *     style: 'Large',
- *   });
- *   return (
- *     <>
- *       <h1>Summary</h1>
- *       <p>{data}</p>
- *     </>
- *   );
+ * if (isLoading) {
+ *   return <div>Loading...</div>;
  * }
  *
- * function App() {
- *   return (
- *     <SisenseContextProvider {...sisenseContextProps}>
- *       <AiContextProvider>
- *         <Page />
- *       </AiContextProvider>
- *     </SisenseContextProvider>
- *   );
- * }
+ * return <p>{data}</p>;
  * ```
  * @param params - {@link UseGetNlgQueryResultParams}
  * @returns Response object containing a text summary
+ * @group Generative AI
  * @beta
  */
-export declare const useGetNlgQueryResult: (params: UseGetNlgQueryResultParams) => {
-    data: string | undefined;
-    isError: boolean;
-    isLoading: boolean;
-    isSuccess: boolean;
-    fetchStatus: import("@tanstack/react-query").FetchStatus;
-    refetch: () => void;
-};
+export declare const useGetNlgQueryResult: (params: UseGetNlgQueryResultParams) => UseGetNlgQueryResultState;

package/dist/ai/use-get-query-recommendations.d.ts

@@ -1,3 +1,4 @@
+import { QueryRecommendation } from './api/types';
 /**
  * Parameters for {@link useGetQueryRecommendations} hook.
  */
@@ -11,10 +12,24 @@ export interface UseGetQueryRecommendationsParams {
      */
     count?: number;
 }
-export declare const useGetQueryRecommendationsInternal: (params: UseGetQueryRecommendationsParams) => {
-    data: import(".").QueryRecommendationResponse;
+/**
+ * State for {@link useGetQueryRecommendations} hook.
+ */
+export interface UseGetQueryRecommendationsState {
+    /** Whether the data fetching is loading */
     isLoading: boolean;
-};
+    /** Whether the data fetching has failed */
+    isError: boolean;
+    /** Whether the data fetching has succeeded */
+    isSuccess: boolean;
+    /** The result data */
+    data: QueryRecommendation[];
+    /** The error if any occurred */
+    error: unknown;
+    /** Callback to trigger a refetch of the data */
+    refetch: () => void;
+}
+export declare const useGetQueryRecommendationsInternal: (params: UseGetQueryRecommendationsParams) => UseGetQueryRecommendationsState;
 /**
  * React hook that fetches recommended questions for a data model or perspective.
  *
@@ -26,42 +41,25 @@ export declare const useGetQueryRecommendationsInternal: (params: UseGetQueryRec
  *
  * @example
  * ```tsx
- * import { SisenseContextProvider } from '@sisense/sdk-ui';
- * import { AiContextProvider, useGetQueryRecommendations } from '@sisense/sdk-ui/ai';
- *
- * function Page() {
- *   const { data } = useGetQueryRecommendations({
- *     contextTitle: 'Sample ECommerce',
- *   });
+ * const { data, isLoading } = useGetQueryRecommendations({
+ *   contextTitle: 'Sample ECommerce',
+ * });
  *
- *   if (!data) {
- *     return <div>Loading recommendations</div>;
- *   }
- *
- *   return (
- *     <ul>
- *       {data.map((item, index) => (
- *         <li key={index}>{item.nlqPrompt}</li>
- *       ))}
- *     </ul>
- *   );
+ * if (isLoading) {
+ *   return <div>Loading recommendations</div>;
  * }
  *
- * function App() {
- *   return (
- *     <SisenseContextProvider {...sisenseContextProps}>
- *       <AiContextProvider>
- *         <Page />
- *       </AiContextProvider>
- *     </SisenseContextProvider>
- *   );
- * }
+ * return (
+ *   <ul>
+ *     {data.map((item, index) => (
+ *       <li key={index}>{item.nlqPrompt}</li>
+ *     ))}
+ *   </ul>
+ * );
  * ```
  * @param params - {@link UseGetQueryRecommendationsParams}
  * @returns An array of objects, each containing recommended question text and its corresponding JAQL
+ * @group Generative AI
  * @beta
  */
-export declare const useGetQueryRecommendations: (params: UseGetQueryRecommendationsParams) => {
-    data: import(".").QueryRecommendationResponse;
-    isLoading: boolean;
-};
+export declare const useGetQueryRecommendations: (params: UseGetQueryRecommendationsParams) => UseGetQueryRecommendationsState;