@sisense/sdk-ui 0.14.0 → 0.16.0

package/dist/models/dashboard/get-dashboard-models.d.ts

@@ -3,7 +3,7 @@ export interface GetDashboardModelsOptions {
     /**
      * Dashboard title to search by
      *
-     * The dashboard title is not unique, therefore, the result may return multiple dashboards.
+     * Dashboard titles are not necessarily unique, so the result may contain multiple dashboards.
      */
     searchByTitle?: string;
     /**

package/dist/models/dashboard/types.d.ts

@@ -1,5 +1,5 @@
 import { type DataSource } from '@sisense/sdk-data';
-import { type WidgetModel } from '../widget/types';
+import { WidgetModel } from '../widget/widget-model';
 export type DashboardModel = {
     oid: string;
     title: string;

package/dist/models/dashboard/use-get-dashboard-model.d.ts

@@ -6,7 +6,7 @@ import { HookEnableParam } from '../../common/hooks/types';
  */
 export interface GetDashboardModelParams extends GetDashboardModelOptions, HookEnableParam {
     /**
-     * Identifier of the dashboard that contains the widget
+     * Dashboard identifier
      */
     dashboardOid: string;
 }

package/dist/models/widget/get-widget-model.d.ts

@@ -0,0 +1,4 @@
+import { HttpClient } from '@sisense/sdk-rest-client';
+import { WidgetModel } from './widget-model';
+/** @internal */
+export declare function getWidgetModel(httpClient: HttpClient, dashboardOid: string, widgetOid: string): Promise<WidgetModel>;

package/dist/models/widget/index.d.ts

@@ -1,2 +1,4 @@
-export * from './types';
 export * from './translate-widget';
+export * from './widget-model';
+export * from './get-widget-model';
+export * from './use-get-widget-model';

package/dist/models/widget/translate-widget.d.ts

@@ -1,3 +1,3 @@
 import { WidgetDto } from '../../dashboard-widget/types';
-import { WidgetModel } from './types';
+import { WidgetModel } from './widget-model';
 export declare function translateWidget(widget: WidgetDto): WidgetModel;

package/dist/models/widget/use-get-widget-model.d.ts

@@ -0,0 +1,102 @@
+import { HookEnableParam } from '../../common/hooks/types';
+import { WidgetModel } from './widget-model';
+/**
+ * Parameters for {@link useGetWidgetModel} hook.
+ */
+export interface GetWidgetModelParams extends HookEnableParam {
+    /**
+     * Identifier of the dashboard that contains the widget
+     */
+    dashboardOid: string;
+    /**
+     * Identifier of the widget to be retrieved
+     */
+    widgetOid: string;
+}
+/**
+ * States of a widget model load.
+ */
+export type WidgetModelState = WidgetModelLoadingState | WidgetModelErrorState | WidgetModelSuccessState;
+/**
+ * State of a widget model that is loading.
+ */
+export type WidgetModelLoadingState = {
+    /** Whether the widget model is loading */
+    isLoading: true;
+    /** Whether the widget model load has failed */
+    isError: false;
+    /** Whether the widget model load has succeeded */
+    isSuccess: false;
+    /** Error, if one occurred */
+    error: undefined;
+    /** Widget model, if the load succeeded */
+    widget: WidgetModel | undefined;
+    /** Loading status */
+    status: 'loading';
+};
+/**
+ * State of a widget model load that has failed.
+ */
+export type WidgetModelErrorState = {
+    /** Whether the widget model is loading */
+    isLoading: false;
+    /** Whether the widget model load has failed */
+    isError: true;
+    /** Whether the widget model load has succeeded */
+    isSuccess: false;
+    /** Error, if one occurred */
+    error: Error;
+    /** Widget model, if the load succeeded */
+    widget: undefined;
+    /** Loading status */
+    status: 'error';
+};
+/**
+ * State of a widget model load that has succeeded.
+ */
+export type WidgetModelSuccessState = {
+    /** Whether the widget model is loading */
+    isLoading: false;
+    /** Whether the widget model load has failed */
+    isError: false;
+    /** Whether the widget model load has succeeded */
+    isSuccess: true;
+    /** Error, if one occurred */
+    error: undefined;
+    /** Widget model, if the load succeeded */
+    widget: WidgetModel;
+    /** Loading status */
+    status: 'success';
+};
+/**
+ * React hook that retrieves an existing widget model from the Sisense instance.
+ *
+ * @example
+ * An example of retrieving an existing widget model from the Sisense instance:
+ ```tsx
+  const { widget, isLoading, isError } = useGetWidgetModel({
+    dashboardOid: '6448665edac1920034bce7a8',
+    widgetOid: '6448665edac1920034bce7a8',
+  });
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+  if (isError) {
+    return <div>Error</div>;
+  }
+  if (widget) {
+    return (
+      <Chart {...widget.getChartProps()} />
+    );
+  }
+  return null;
+ ```
+ * @param params - Parameters of the widget to be retrieved
+ * @returns Widget load state that contains the status of the execution, the result widget model, or the error if one has occurred
+ */
+export declare const useGetWidgetModel: (params: GetWidgetModelParams) => WidgetModelState;
+/**
+ * {@link useGetWidgetModel} without tracking to be used inside other hooks or components in Compose SDK.
+ * @internal
+ */
+export declare function useGetWidgetModelInternal(params: GetWidgetModelParams): WidgetModelState;

package/dist/models/widget/widget-model.d.ts

@@ -0,0 +1,122 @@
+import { Filter } from '@sisense/sdk-data';
+import { ChartDataOptions, TableDataOptions } from '../../chart-data-options/types';
+import { WidgetDto, WidgetType } from '../../dashboard-widget/types';
+import { ChartProps, ChartWidgetProps, TableProps, TableWidgetProps } from '../../props';
+import { ExecuteQueryParams } from '../../query-execution';
+import { ChartType, DrilldownOptions, StyleOptions, TableStyleOptions } from '../../types';
+/**
+ * Widget data options.
+ */
+export type WidgetDataOptions = ChartDataOptions | TableDataOptions;
+/**
+ * Model of Sisense widget defined in the abstractions of Compose SDK.
+ */
+export declare class WidgetModel {
+    /**
+     * Unique identifier of the widget.
+     */
+    oid: string;
+    /**
+     * Widget title.
+     */
+    title: string;
+    /**
+     * Widget description.
+     */
+    description: string;
+    /**
+     * Full name of the widget data source.
+     */
+    dataSource: string;
+    /**
+     * Widget type.
+     */
+    widgetType: WidgetType;
+    /**
+     * Widget data options.
+     */
+    dataOptions: WidgetDataOptions;
+    /**
+     * Widget style options.
+     */
+    styleOptions: StyleOptions | TableStyleOptions;
+    /**
+     * Widget filters.
+     */
+    filters: Filter[];
+    /**
+     * Widget highlights.
+     */
+    highlights: Filter[];
+    /**
+     * Widget chart type.
+     */
+    chartType?: ChartType;
+    /**
+     * Widget drilldown options.
+     */
+    drilldownOptions: DrilldownOptions;
+    /**
+     * Creates a new widget model.
+     *
+     * @param widgetDto - The widget DTO to be converted to a widget model
+     *
+     * @internal
+     */
+    constructor(widgetDto: WidgetDto);
+    /**
+     * Returns the parameters to be used for executing a query for the widget.
+     *
+     * @example
+     * ```tsx
+     * const {data, isLoading, isError} = useExecuteQuery(widget.getExecuteQueryParams());
+     * ```
+     */
+    getExecuteQueryParams(): ExecuteQueryParams;
+    /**
+     * Returns the props to be used for rendering a chart.
+  
+     * @example
+     * ```tsx
+     * <Chart {...widget.getChartProps()} />
+     * ```
+     *
+     * Note: this method is not supported for tabular widgets.
+     * Use {@link getTableProps} instead for getting props for the <Table> component.
+     */
+    getChartProps(): ChartProps;
+    /**
+     * Returns the props to be used for rendering a table.
+     * @example
+     * ```tsx
+     * <Table {...widget.getTableProps()} />
+     * ```
+     *
+     * Note: this method is not supported for chart widgets.
+     * Use {@link getChartProps} instead for getting props for the <Chart> component.
+     */
+    getTableProps(): TableProps;
+    /**
+     * Returns the props to be used for rendering a chart widget.
+     * @example
+     * ```tsx
+     * <ChartWidget {...widget.getChartWidgetProps()} />
+     * ```
+     *
+     * Note: this method is not supported for tabular widgets.
+     */
+    getChartWidgetProps(): ChartWidgetProps;
+    /**
+     * Returns the props to be used for rendering a table widget.
+     * @example
+     * ```tsx
+     * <TableWidget {...widget.getTableWidgetProps()} />
+     * ```
+     *
+     * Note: this method is not supported for chart widgets.
+     * Use {@link getChartWidgetProps} instead for getting props for the <ChartWidget> component.
+     *
+     * @internal
+     */
+    getTableWidgetProps(): TableWidgetProps;
+}

package/dist/props.d.ts

@@ -7,6 +7,7 @@ import { DataPointEventHandler, DataPointsEventHandler, ScatterDataPointEventHan
 import { AppConfig } from './app/client-application';
 import { ExecuteQueryParams } from './query-execution';
 import { FiltersMergeStrategy } from './dashboard-widget/types';
+import { HookEnableParam } from './common/hooks/types';
 export type { ScatterDataPointEventHandler, ScatterDataPointsEventHandler, DataPointEventHandler, DataPointsEventHandler, MenuItemSection, HighchartsOptions, };
 /**
  * Configurations for Sisense Context
@@ -613,7 +614,6 @@ export interface ChartWidgetProps extends BaseChartEventProps {
     /**
      * List of categories to allow drilldowns on
      *
-     * @deprecated Use {@link DrilldownWidget} instead
      * @category Widget
      */
     drilldownOptions?: DrilldownOptions;
@@ -821,21 +821,21 @@ export interface SunburstChartProps extends BaseChartProps, ChartEventProps {
 /**
  * Props for {@link ContextMenu} component.
  */
-export type ContextMenuProps = {
+export interface ContextMenuProps {
     /**
-     * Position of the context menu
+     * Context menu position
      *
      * @category Widget
      */
     position?: MenuPosition | null;
     /**
-     * Callback function that is evaluated when context menu is closed
+     * Callback function that is evaluated when the context menu is closed
      *
      * @category Widget
      */
     closeContextMenu: () => void;
     /**
-     * Sections of menu items
+     * Menu item sections
      *
      * @category Widget
      */
@@ -846,8 +846,8 @@ export type ContextMenuProps = {
      * @category Widget
      */
     children?: React.ReactNode;
-};
-export type DrilldownBreadcrumbsProps = {
+}
+export interface DrilldownBreadcrumbsProps {
     /**
      * List of drilldown filters formatted to be displayed as breadcrumbs
      *
@@ -861,7 +861,7 @@ export type DrilldownBreadcrumbsProps = {
      */
     currentDimension: Attribute;
     /**
-     * Callback function that is evaluated when X button is clicked
+     * Callback function that is evaluated when the close (X) button is clicked
      *
      * @category Widget
      */
@@ -872,7 +872,7 @@ export type DrilldownBreadcrumbsProps = {
      * @category Widget
      */
     sliceDrilldownSelections: (i: number) => void;
-};
+}
 /**
  * An object that allows users to pass advanced configuration options as a prop for the {@link DrilldownWidget} component
  */
@@ -901,7 +901,7 @@ export type DrilldownWidgetConfig = {
 /**
  * Props for the {@link DrilldownWidget} component
  */
-export type DrilldownWidgetProps = {
+export interface DrilldownWidgetProps {
     /**
      * List of dimensions to allow drilldowns on
      *
@@ -928,4 +928,23 @@ export type DrilldownWidgetProps = {
      * @category Widget
      */
     children: (customDrilldownResult: CustomDrilldownResult) => ReactNode;
-};
+}
+/**
+ * Params of the {@link useGetSharedFormula} hook
+ *
+ * Can consist either of an oid or a name/dataSource pair
+ */
+export interface UseGetSharedFormulaParams extends HookEnableParam {
+    /**
+     * Formula identifier
+     */
+    oid?: string;
+    /**
+     * Formula name
+     */
+    name?: string;
+    /**
+     * Data source - e.g. `Sample ECommerce`
+     */
+    dataSource?: DataSource;
+}

package/dist/query/execute-query.d.ts

@@ -17,3 +17,5 @@ export declare const QUERY_DEFAULT_LIMIT = 20000;
 export declare const QUERY_DEFAULT_OFFSET = 0;
 /** @internal */
 export declare const executeQuery: (queryDescription: QueryDescription, app: ClientApplication, executionConfig?: QueryExecutionConfig) => Promise<QueryResultData>;
+/** @internal */
+export declare const executeCsvQuery: (queryDescription: QueryDescription, app: ClientApplication, executionConfig?: QueryExecutionConfig) => Promise<Blob>;

package/dist/query-execution/csv-query-state-reducer.d.ts

@@ -0,0 +1,2 @@
+import { CsvQueryAction, CsvQueryState } from './types.js';
+export declare function downloadCsvQueryStateReducer(state: CsvQueryState, action: CsvQueryAction): CsvQueryState;

package/dist/query-execution/index.d.ts

@@ -1,5 +1,6 @@
 export { ExecuteQuery } from './execute-query';
-export { useExecuteQuery, type ExecuteQueryParams } from './use-execute-query';
+export { useExecuteQuery } from './use-execute-query';
+export { useExecuteCsvQuery } from './use-execute-csv-query';
 export { ExecuteQueryByWidgetId } from './execute-query-by-widget-id';
-export { useExecuteQueryByWidgetId, type ExecuteQueryByWidgetIdParams, type QueryByWidgetIdState, executeQueryByWidgetId, } from './use-execute-query-by-widget-id';
-export type { QueryState, QueryLoadingState, QuerySuccessState, QueryErrorState, } from './query-state-reducer';
+export { useExecuteQueryByWidgetId, executeQueryByWidgetId, } from './use-execute-query-by-widget-id';
+export type { QueryState, QueryLoadingState, QuerySuccessState, QueryErrorState, CsvQueryState, CsvQueryLoadingState, CsvQuerySuccessState, CsvQueryErrorState, ExecuteQueryParams, ExecuteCsvQueryParams, ExecuteQueryByWidgetIdParams, QueryByWidgetIdState, } from './types';

package/dist/query-execution/query-state-reducer.d.ts

@@ -1,59 +1,2 @@
-import { QueryResultData } from '@sisense/sdk-data';
-import { DataLoadAction } from '../common/hooks/data-load-state-reducer';
-/**
- * State of a query execution.
- */
-export type QueryState = QueryLoadingState | QueryErrorState | QuerySuccessState;
-/**
- * State of a query execution that is loading.
- */
-export type QueryLoadingState = {
-    /** Whether the query is loading */
-    isLoading: true;
-    /** Whether the query has failed */
-    isError: false;
-    /** Whether the query has succeeded */
-    isSuccess: false;
-    /** The error if any occurred */
-    error: undefined;
-    /** The result data if the query has succeeded */
-    data: QueryResultData | undefined;
-    /** The status of the query execution */
-    status: 'loading';
-};
-/**
- * State of a query execution that has failed.
- */
-export type QueryErrorState = {
-    /** Whether the query is loading */
-    isLoading: false;
-    /** Whether the query has failed */
-    isError: true;
-    /** Whether the query has succeeded */
-    isSuccess: false;
-    /** The error if any occurred */
-    error: Error;
-    /** The result data if the query has succeeded */
-    data: undefined;
-    /** The status of the query execution */
-    status: 'error';
-};
-/**
- * State of a query execution that has succeeded.
- */
-export type QuerySuccessState = {
-    /** Whether the query is loading */
-    isLoading: false;
-    /** Whether the query has failed */
-    isError: false;
-    /** Whether the query has succeeded */
-    isSuccess: true;
-    /** The error if any occurred */
-    error: undefined;
-    /** The result data if the query has succeeded */
-    data: QueryResultData;
-    /** The status of the query execution */
-    status: 'success';
-};
-export type QueryAction = DataLoadAction<QueryResultData>;
+import { QueryAction, QueryState } from './types';
 export declare function queryStateReducer(state: QueryState, action: QueryAction): QueryState;

package/dist/query-execution/types.d.ts

@@ -0,0 +1,190 @@
+import { Attribute, DataSource, Filter, Measure, QueryResultData } from '@sisense/sdk-data';
+import { DataLoadAction } from '../common/hooks/data-load-state-reducer';
+import { FiltersMergeStrategy } from '../dashboard-widget/types';
+/**
+ * State of a query execution.
+ */
+export type CsvQueryState = CsvQueryLoadingState | CsvQueryErrorState | CsvQuerySuccessState;
+/**
+ * State of a query execution that is loading.
+ */
+export type CsvQueryLoadingState = {
+    /** Whether the query is loading */
+    isLoading: true;
+    /** Whether the query has failed */
+    isError: false;
+    /** Whether the query has succeeded */
+    isSuccess: false;
+    /** The error if any occurred */
+    error: undefined;
+    /** The result data if the query has succeeded */
+    data: Blob | string | undefined;
+    /** The status of the query execution */
+    status: 'loading';
+};
+/**
+ * State of a query execution that has failed.
+ */
+export type CsvQueryErrorState = {
+    /** Whether the query is loading */
+    isLoading: false;
+    /** Whether the query has failed */
+    isError: true;
+    /** Whether the query has succeeded */
+    isSuccess: false;
+    /** The error if any occurred */
+    error: Error;
+    /** The result data if the query has succeeded */
+    data: undefined;
+    /** The status of the query execution */
+    status: 'error';
+};
+/**
+ * State of a query execution that has succeeded.
+ */
+export type CsvQuerySuccessState = {
+    /** Whether the query is loading */
+    isLoading: false;
+    /** Whether the query has failed */
+    isError: false;
+    /** Whether the query has succeeded */
+    isSuccess: true;
+    /** The error if any occurred */
+    error: undefined;
+    /** The result data if the query has succeeded */
+    data: Blob | string;
+    /** The status of the query execution */
+    status: 'success';
+};
+export type CsvQueryAction = DataLoadAction<Blob | string>;
+/**
+ * State of a query execution.
+ */
+export type QueryState = QueryLoadingState | QueryErrorState | QuerySuccessState;
+/**
+ * State of a query execution that is loading.
+ */
+export type QueryLoadingState = {
+    /** Whether the query is loading */
+    isLoading: true;
+    /** Whether the query has failed */
+    isError: false;
+    /** Whether the query has succeeded */
+    isSuccess: false;
+    /** The error if any occurred */
+    error: undefined;
+    /** The result data if the query has succeeded */
+    data: QueryResultData | undefined;
+    /** The status of the query execution */
+    status: 'loading';
+};
+/**
+ * State of a query execution that has failed.
+ */
+export type QueryErrorState = {
+    /** Whether the query is loading */
+    isLoading: false;
+    /** Whether the query has failed */
+    isError: true;
+    /** Whether the query has succeeded */
+    isSuccess: false;
+    /** The error if any occurred */
+    error: Error;
+    /** The result data if the query has succeeded */
+    data: undefined;
+    /** The status of the query execution */
+    status: 'error';
+};
+/**
+ * State of a query execution that has succeeded.
+ */
+export type QuerySuccessState = {
+    /** Whether the query is loading */
+    isLoading: false;
+    /** Whether the query has failed */
+    isError: false;
+    /** Whether the query has succeeded */
+    isSuccess: true;
+    /** The error if any occurred */
+    error: undefined;
+    /** The result data if the query has succeeded */
+    data: QueryResultData;
+    /** The status of the query execution */
+    status: 'success';
+};
+export type QueryAction = DataLoadAction<QueryResultData>;
+/**
+ * Parameters for {@link useExecuteQueryByWidgetId} hook.
+ */
+export interface ExecuteQueryByWidgetIdParams {
+    /** {@inheritDoc ExecuteQueryByWidgetIdProps.widgetOid} */
+    widgetOid: string;
+    /** {@inheritDoc ExecuteQueryByWidgetIdProps.dashboardOid} */
+    dashboardOid: string;
+    /** {@inheritDoc ExecuteQueryByWidgetIdProps.filters} */
+    filters?: Filter[];
+    /** {@inheritDoc ExecuteQueryByWidgetIdProps.highlights} */
+    highlights?: Filter[];
+    /** {@inheritDoc ExecuteQueryProps.count} */
+    count?: number;
+    /** {@inheritDoc ExecuteQueryProps.offset} */
+    offset?: number;
+    /** {@inheritDoc ExecuteQueryByWidgetIdProps.filtersMergeStrategy} */
+    filtersMergeStrategy?: FiltersMergeStrategy;
+    /** {@inheritDoc ExecuteQueryByWidgetIdProps.includeDashboardFilters} */
+    includeDashboardFilters?: boolean;
+    /** {@inheritDoc ExecuteQueryByWidgetIdProps.onBeforeQuery} */
+    onBeforeQuery?: (jaql: any) => any | Promise<any>;
+    /**
+     * Boolean flag to control if query is executed
+     *
+     * If not specified, the default value is `true`
+     */
+    enabled?: boolean;
+}
+export type QueryByWidgetIdState = QueryState & {
+    /** Query parameters constructed over the widget */
+    query: ExecuteQueryParams | undefined;
+};
+/**
+ * Parameters for {@link useExecuteQuery} hook.
+ */
+export interface ExecuteQueryParams {
+    /**
+     * Data source the query is run against - e.g. `Sample ECommerce`
+     *
+     * If not specified, the query will use the `defaultDataSource` specified in the parent Sisense Context.
+     */
+    dataSource?: DataSource;
+    /** Dimensions of the query */
+    dimensions?: Attribute[];
+    /** Measures of the query */
+    measures?: Measure[];
+    /** Filters that will slice query results */
+    filters?: Filter[];
+    /** Highlight filters that will highlight results that pass filter criteria */
+    highlights?: Filter[];
+    /** {@inheritDoc ExecuteQueryProps.count} */
+    count?: number;
+    /** {@inheritDoc ExecuteQueryProps.offset} */
+    offset?: number;
+    /**
+     * Boolean flag to control if query is executed
+     *
+     * If not specified, the default value is `true`
+     */
+    enabled?: boolean;
+    /** {@inheritDoc ExecuteQueryProps.onBeforeQuery} */
+    onBeforeQuery?: (jaql: any) => any | Promise<any>;
+}
+/**
+ * Parameters for {@link useExecuteCsvQuery} hook.
+ */
+export interface ExecuteCsvQueryParams extends ExecuteQueryParams {
+    config?: {
+        /**
+         * If set to true, the data will be returned as a Blob.
+         */
+        asDataStream?: boolean;
+    };
+}