@sisense/sdk-ui 2.29.0 → 2.31.0

package/dist/packages/sdk-ui/src/infra/plugins/types.d.ts

@@ -1,8 +1,17 @@
-import type { AnyWidgetPlugin } from './widget-plugins/types.js';
+import type { WidgetPlugin } from './widget-plugins/types.js';
 /**
- * Base plugin information
+ * Defines base information shared by all plugin types.
  *
- * @sisenseInternal
+ * @group Plugin System
+ * @example
+ * ```ts
+ * const info: BasePluginInfo = {
+ *   name: 'my-widget-plugin',
+ *   version: '1.0.0',
+ *   requiredApiVersion: '^2.9.0',
+ * };
+ * ```
+ * @beta
  */
 export interface BasePluginInfo {
     /**
@@ -50,9 +59,28 @@ export interface PluginValidationResult {
     reason?: string;
 }
 /**
- * Plugin declaration.
+ * Declares a plugin for registration with the Compose SDK.
  * Currently only widget plugins are supported.
  *
- * @sisenseInternal
+ * @group Plugin System
+ * @example
+ * ```tsx
+ * import { SisenseContextProvider } from '@sisense/sdk-ui';
+ *
+ * const myPlugin: Plugin = {
+ *   name: 'my-widget-plugin',
+ *   version: '1.0.0',
+ *   requiredApiVersion: '^2.9.0',
+ *   pluginType: 'widget',
+ *   customWidget: {
+ *     name: 'my-widget',
+ *     displayName: 'My Widget',
+ *     visualization: { Component: MyVisualization },
+ *   },
+ * };
+ *
+ * <SisenseContextProvider plugins={[myPlugin]} {...props} />
+ * ```
+ * @beta
  */
-export type Plugin = AnyWidgetPlugin;
+export type Plugin = WidgetPlugin<any>;

package/dist/packages/sdk-ui/src/infra/plugins/widget-plugins/types.d.ts

@@ -5,9 +5,32 @@ import { AnyObject } from '../../../shared/utils/utility-types';
 import type { AbstractDataPointWithEntries, GenericDataOptions } from '../../../types';
 import type { BasePluginInfo } from '../types';
 /**
- * Widget plugin declaration.
+ * Declares a widget plugin for registration with the Compose SDK.
  *
- * @sisenseInternal
+ * Pass an instance to the `plugins` prop on {@link SisenseContextProvider} to register a custom
+ * visualization that appears in the dashboard widget picker.
+ *
+ * @typeParam Props - Props type for the custom visualization component, extending {@link CustomVisualizationProps}.
+ * @group Plugin System
+ * @example
+ * ```tsx
+ * import { WidgetPlugin, CustomVisualization } from '@sisense/sdk-ui';
+ *
+ * const MyChart: CustomVisualization = ({ dataOptions }) => <div>{String(dataOptions)}</div>;
+ *
+ * const myPlugin: WidgetPlugin = {
+ *   name: 'my-widget-plugin',
+ *   version: '1.0.0',
+ *   requiredApiVersion: '^2.9.0',
+ *   pluginType: 'widget',
+ *   customWidget: {
+ *     name: 'my-widget',
+ *     displayName: 'My Widget',
+ *     visualization: { Component: MyChart },
+ *   },
+ * };
+ * ```
+ * @beta
  */
 export interface WidgetPlugin<Props extends CustomVisualizationProps<any, any, any, any> = CustomVisualizationProps> extends BasePluginInfo {
     /**
@@ -147,38 +170,44 @@ export interface WidgetPlugin<Props extends CustomVisualizationProps<any, any, a
  */
 export type AnyWidgetPlugin = WidgetPlugin<any>;
 /**
- * Props passed to a user-defined custom visualization component.
- *
- * @typeParam DataOptions - The shape of data options for this custom visualization
- * @typeParam StyleOptions - The shape of style options for this custom visualization
- * @typeParam DataPoint - The shape of data points for event handlers
+ * Defines props passed to a user-defined custom visualization component.
  *
+ * @typeParam DataOptions - The shape of data options for this custom visualization.
+ * @typeParam StyleOptions - The shape of style options for this custom visualization.
+ * @typeParam DataPoint - The shape of data points passed to event handlers.
+ * @typeParam CustomOptions - The shape of arbitrary plugin-specific state (not data- or style-related).
+ * @group Plugin System
  * @example
  * ```tsx
- * import { CustomVisualization, CustomVisualizationProps, CustomWidgetDataPoint, StyledColumn, StyledMeasureColumn, DataPointEntry, GenericDataOptions} from '@sisense/sdk-ui';
+ * import {
+ *   CustomVisualization,
+ *   CustomVisualizationProps,
+ *   CustomVisualizationDataPoint,
+ *   StyledColumn,
+ *   StyledMeasureColumn,
+ *   DataPointEntry,
+ *   GenericDataOptions,
+ * } from '@sisense/sdk-ui';
  *
  * interface MyDataOptions extends GenericDataOptions {
  *   category: StyledColumn[];
  *   value: StyledMeasureColumn[];
  * }
  *
- * interface MyDataPoint extends CustomWidgetDataPoint {
+ * interface MyDataPoint extends CustomVisualizationDataPoint {
  *   entries: {
  *     category: DataPointEntry[];
  *     value: DataPointEntry[];
  *   };
  * }
  *
- * type MyNewChartProps = CustomVisualizationProps<MyDataOptions, {}, MyDataPoint>;
+ * type MyChartProps = CustomVisualizationProps<MyDataOptions, {}, MyDataPoint>;
  *
- * const MyNewChart: CustomVisualization<MyNewChartProps> = (props) => {
- *   const { dataOptions, onDataPointClick } = props;
- *   // ... implementation based on props
- *   return <div>My New Awesome Chart</div>;
+ * const MyChart: CustomVisualization<MyChartProps> = ({ dataOptions, onDataPointClick }) => {
+ *   return <div>My Chart</div>;
  * };
  * ```
- *
- * @sisenseInternal
+ * @beta
  */
 export interface CustomVisualizationProps<DataOptions = GenericDataOptions, StyleOptions = CustomVisualizationStyleOptions, DataPoint extends AbstractDataPointWithEntries = AbstractDataPointWithEntries, CustomOptions = Record<string, unknown>> extends CustomVisualizationEventProps<DataPoint> {
     /** Data source for the custom visualization */
@@ -192,13 +221,16 @@ export interface CustomVisualizationProps<DataOptions = GenericDataOptions, Styl
     /** Highlight filters for interactive highlighting */
     highlights?: Filter[];
     /**
-     * Arbitrary plugin-specific options that is not data- or style-related.
+     * Arbitrary plugin-specific runtime state that is not data- or style-related
+     * (for example the current page of a table or a selected tab). Persisted back
+     * to the Sisense instance when the widget lives inside a Dashboard component,
+     * so it survives page reloads.
      *
-     * @sisenseInternal
+     * @beta
      */
     customOptions?: CustomOptions;
     /**
-     * Emit a partial state update to be persisted through the dashboard
+     * Emits a partial state update to be persisted through the dashboard
      * persistence layer. Injected by the dashboard when the widget lives inside a
      * Dashboard component; `undefined` in standalone use or read-only mode — always
      * call it with optional chaining.
@@ -208,7 +240,7 @@ export interface CustomVisualizationProps<DataOptions = GenericDataOptions, Styl
      * onChange?.({ customOptions: { lastPage: 3 } });
      * ```
      *
-     * @sisenseInternal
+     * @beta
      */
     onChange?: (update: VisualizationStateUpdate<StyleOptions, CustomOptions>) => void;
 }
@@ -225,25 +257,49 @@ export interface CustomVisualizationProps<DataOptions = GenericDataOptions, Styl
  * replaced wholesale (last-write-wins). Keys cannot be deleted via merge —
  * overwrite with an explicit value (e.g. `null`) instead.
  *
- * @sisenseInternal
+ * @typeParam StyleOptions - The shape of style options for the custom visualization.
+ * @typeParam CustomOptions - The shape of arbitrary plugin-specific runtime state.
+ * @group Plugin System
+ * @beta
  */
 export type VisualizationStateUpdate<StyleOptions = CustomVisualizationStyleOptions, CustomOptions = Record<string, unknown>> = {
     styleOptions?: DeepPartial<StyleOptions>;
     customOptions?: DeepPartial<CustomOptions>;
 };
 /**
- * Style options for a custom visualization.
+ * Defines style options for a custom visualization.
  *
- * @sisenseInternal
+ * Extend this interface to add plugin-specific style properties passed via `styleOptions`.
+ *
+ * @group Plugin System
+ * @example
+ * ```ts
+ * interface MyWidgetStyleOptions extends CustomVisualizationStyleOptions {
+ *   backgroundColor?: string;
+ *   fontSize?: number;
+ * }
+ * ```
+ * @beta
  */
 export interface CustomVisualizationStyleOptions extends AnyObject {
 }
 /**
- * A user-defined custom visualization component.
- * This can be any visual representation of the data - chart, table, map, etc.
+ * Defines a user-defined custom visualization component.
+ * Can be any visual representation of data — chart, table, map, etc.
  *
- * @typeParam Props - The props type for the custom visualization component
- * @sisenseInternal
+ * @typeParam Props - The props type for the custom visualization component, extending {@link CustomVisualizationProps}.
+ * @param props - Props injected by the dashboard, including `dataOptions`, `styleOptions`, `filters`, and event handlers.
+ * @returns A React node representing the rendered visualization.
+ * @group Plugin System
+ * @example
+ * ```tsx
+ * import { CustomVisualization, CustomVisualizationProps } from '@sisense/sdk-ui';
+ *
+ * const MyChart: CustomVisualization<CustomVisualizationProps> = ({ dataOptions, styleOptions }) => {
+ *   return <div className="my-chart">{JSON.stringify(dataOptions)}</div>;
+ * };
+ * ```
+ * @beta
  */
 export type CustomVisualization<Props = CustomVisualizationProps> = (props: Props) => ReactNode;
 /**
@@ -257,10 +313,19 @@ export type CustomVisualization<Props = CustomVisualizationProps> = (props: Prop
  */
 export type AnyCustomVisualization = CustomVisualization<any>;
 /**
- * Event props for custom visualizations with generic data point type.
+ * Defines event handler props for a custom visualization component.
  *
- * @typeParam DataPoint - The shape of data points for this custom visualization
- * @sisenseInternal
+ * Included automatically via {@link CustomVisualizationProps}. Extend to add custom event props.
+ *
+ * @typeParam DataPoint - The shape of data points for this custom visualization.
+ * @group Plugin System
+ * @example
+ * ```tsx
+ * interface MyEventProps extends CustomVisualizationEventProps<MyDataPoint> {
+ *   onCustomAction?: (id: string) => void;
+ * }
+ * ```
+ * @beta
  */
 export interface CustomVisualizationEventProps<DataPoint extends AbstractDataPointWithEntries = AbstractDataPointWithEntries> {
     /**
@@ -283,28 +348,35 @@ export interface CustomVisualizationEventProps<DataPoint extends AbstractDataPoi
     onDataPointsSelected?: CustomVisualizationDataPointsEventHandler<DataPoint>;
 }
 /**
- * Generic event handler for custom visualization data point click.
+ * Defines an event handler for a data point click in a custom visualization.
  *
- * @typeParam T - The shape of the data point
+ * @typeParam T - The shape of the data point.
+ * @group Plugin System
  * @example
  * ```tsx
  * const handleClick: CustomVisualizationDataPointEventHandler<MyChartDataPoint> = (point, event) => {
- *   console.log('Clicked:', point.label, point.value);
+ *   console.log('Clicked:', point.entries.category[0].value);
  * };
  * ```
- *
- * @sisenseInternal
+ * @beta
  */
-export type CustomVisualizationDataPointEventHandler<T extends AbstractDataPointWithEntries = AbstractDataPointWithEntries> = (point: CustomVisualizationDataPoint<T>, nativeEvent: PointerEvent | MouseEvent) => void;
+export type CustomVisualizationDataPointEventHandler<T extends AbstractDataPointWithEntries = AbstractDataPointWithEntries> = (
+/** Data point that was clicked. */
+point: CustomVisualizationDataPoint<T>, 
+/** Native browser pointer or mouse event. */
+nativeEvent: PointerEvent | MouseEvent) => void;
 /**
  * Represents a single data point in a custom visualization.
  *
- * This type is used to define the structure of a data point that is passed to event handlers
- * like `onDataPointClick`. It typically extends `AbstractDataPointWithEntries` to include
- * specific entries for categories, values, or other dimensions used in the widget.
+ * Extend `AbstractDataPointWithEntries` to define typed entries for your widget's data options.
+ * Instances are passed to event handlers such as `onDataPointClick`.
  *
+ * @typeParam T - The concrete data point shape, extending {@link AbstractDataPointWithEntries}.
+ * @group Plugin System
  * @example
- * ```typescript
+ * ```ts
+ * import { CustomVisualizationDataPoint, DataPointEntry } from '@sisense/sdk-ui';
+ *
  * interface MyChartDataPoint extends CustomVisualizationDataPoint {
  *   entries: {
  *     category: DataPointEntry[];
@@ -316,15 +388,25 @@ export type CustomVisualizationDataPointEventHandler<T extends AbstractDataPoint
  *   console.log('Clicked category:', point.entries.category[0].value);
  * };
  * ```
- *
- * @sisenseInternal
+ * @beta
  */
 export type CustomVisualizationDataPoint<T extends AbstractDataPointWithEntries = AbstractDataPointWithEntries> = T;
 /**
- * Generic event handler for custom widget data point context menu.
+ * Defines an event handler for a data point context-menu event in a custom visualization.
  *
- * @typeParam T - The shape of the data point
- * @sisenseInternal
+ * @typeParam T - The shape of the data point.
+ * @group Plugin System
+ * @example
+ * ```tsx
+ * const handleContextMenu: CustomVisualizationDataPointContextMenuHandler<MyChartDataPoint> = (
+ *   point,
+ *   event,
+ * ) => {
+ *   event.preventDefault();
+ *   showContextMenu({ x: event.clientX, y: event.clientY, point });
+ * };
+ * ```
+ * @beta
  */
 export type CustomVisualizationDataPointContextMenuHandler<T extends AbstractDataPointWithEntries = AbstractDataPointWithEntries> = (
 /** Data point that triggered the context menu */
@@ -332,17 +414,20 @@ point: CustomVisualizationDataPoint<T>,
 /** Native browser event */
 nativeEvent: MouseEvent) => void;
 /**
- * Generic event handler for custom visualization data points selection.
+ * Defines an event handler for multi-point selection in a custom visualization.
  *
- * @typeParam T - The shape of the data point
+ * @typeParam T - The shape of the data point.
+ * @group Plugin System
  * @example
  * ```tsx
- * const handleSelect: CustomVisualizationDataPointsEventHandler<MyChartDataPoint> = (points, event) => {
+ * const handleSelect: CustomVisualizationDataPointsEventHandler<MyChartDataPoint> = (
+ *   points,
+ *   event,
+ * ) => {
  *   console.log('Selected:', points.length, 'points');
  * };
  * ```
- *
- * @sisenseInternal
+ * @beta
  */
 export type CustomVisualizationDataPointsEventHandler<T extends AbstractDataPointWithEntries = AbstractDataPointWithEntries> = (
 /** Data points that were selected */
@@ -350,17 +435,58 @@ points: CustomVisualizationDataPoint<T>[],
 /** Native browser event */
 nativeEvent: MouseEvent) => void;
 /**
- * Props for the design panel component for the custom widget.
+ * Defines props passed to a custom design panel component.
  *
- * @sisenseInternal
+ * @typeParam StyleOptions - The shape of style options managed by this design panel, extending {@link CustomVisualizationStyleOptions}.
+ * @group Plugin System
+ * @example
+ * ```tsx
+ * import { DesignPanel, DesignPanelProps } from '@sisense/sdk-ui';
+ *
+ * interface MyStyleOptions extends CustomVisualizationStyleOptions {
+ *   color?: string;
+ * }
+ *
+ * const MyDesignPanel: DesignPanel<MyStyleOptions> = ({ styleOptions, onChange }) => (
+ *   <input
+ *     type="color"
+ *     value={styleOptions.color ?? '#000000'}
+ *     onChange={(e) => onChange({ ...styleOptions, color: e.target.value })}
+ *   />
+ * );
+ * ```
+ * @beta
  */
 export interface DesignPanelProps<StyleOptions = CustomVisualizationStyleOptions> {
+    /** Current style options managed by the design panel. */
     styleOptions: StyleOptions;
+    /** Callback invoked when the user changes a style option. */
     onChange: (styleOptions: StyleOptions) => void;
 }
 /**
- * The design panel component for the custom widget.
+ * Defines a design panel component for a custom widget.
  *
- * @sisenseInternal
+ * Renders inside the widget's style/design settings pane and receives the current
+ * `styleOptions` and an `onChange` callback to persist style changes.
+ *
+ * @typeParam StyleOptions - The shape of style options managed by this design panel, extending {@link CustomVisualizationStyleOptions}.
+ * @group Plugin System
+ * @example
+ * ```tsx
+ * import { DesignPanel, CustomVisualizationStyleOptions } from '@sisense/sdk-ui';
+ *
+ * interface MyStyleOptions extends CustomVisualizationStyleOptions {
+ *   color?: string;
+ * }
+ *
+ * const MyDesignPanel: DesignPanel<MyStyleOptions> = ({ styleOptions, onChange }) => (
+ *   <input
+ *     type="color"
+ *     value={styleOptions.color ?? '#000000'}
+ *     onChange={(e) => onChange({ ...styleOptions, color: e.target.value })}
+ *   />
+ * );
+ * ```
+ * @beta
  */
 export type DesignPanel<StyleOptions = CustomVisualizationStyleOptions> = FunctionComponent<DesignPanelProps<StyleOptions>>;

package/dist/packages/sdk-ui/src/infra/translation/resources/__external__/de-de.d.ts

@@ -256,6 +256,8 @@ declare const _default: {
                 yes: string;
                 no: string;
                 seeMore: string;
+                generateNarrative: string;
+                hideNarrative: string;
             };
             disclaimer: {
                 poweredByAi: string;
@@ -309,6 +311,8 @@ declare const _default: {
                 from: string;
                 to: string;
                 includeCurrent: string;
+                rankedBy: string;
+                selectField: string;
             };
             placeholders: {
                 selectFromList: string;
@@ -333,6 +337,8 @@ declare const _default: {
                 greaterThan: string;
                 greaterThanOrEqual: string;
                 isWithin: string;
+                top: string;
+                bottom: string;
             };
             validationErrors: {
                 invalidNumber: string;
@@ -427,6 +433,11 @@ declare const _default: {
             table: {
                 label: string;
             };
+            sankey: {
+                alerts: {
+                    tooManyStages: string;
+                };
+            };
         };
         loadingOverlay: {
             label: string;
@@ -452,6 +463,17 @@ declare const _default: {
             median: string;
             variance: string;
         };
+        measuresAgg: {
+            countDistinct: string;
+            count: string;
+            sum: string;
+            average: string;
+            min: string;
+            max: string;
+            median: string;
+            variance: string;
+            stdev: string;
+        };
     };
 }[];
 export default _default;

package/dist/packages/sdk-ui/src/infra/translation/resources/__external__/en-us.d.ts

@@ -256,6 +256,8 @@ declare const _default: {
                 yes: string;
                 no: string;
                 seeMore: string;
+                generateNarrative: string;
+                hideNarrative: string;
             };
             disclaimer: {
                 poweredByAi: string;
@@ -309,6 +311,8 @@ declare const _default: {
                 from: string;
                 to: string;
                 includeCurrent: string;
+                rankedBy: string;
+                selectField: string;
             };
             placeholders: {
                 selectFromList: string;
@@ -333,6 +337,8 @@ declare const _default: {
                 greaterThan: string;
                 greaterThanOrEqual: string;
                 isWithin: string;
+                top: string;
+                bottom: string;
             };
             validationErrors: {
                 invalidNumber: string;
@@ -427,6 +433,11 @@ declare const _default: {
             table: {
                 label: string;
             };
+            sankey: {
+                alerts: {
+                    tooManyStages: string;
+                };
+            };
         };
         loadingOverlay: {
             label: string;
@@ -452,6 +463,17 @@ declare const _default: {
             median: string;
             variance: string;
         };
+        measuresAgg: {
+            countDistinct: string;
+            count: string;
+            sum: string;
+            average: string;
+            min: string;
+            max: string;
+            median: string;
+            variance: string;
+            stdev: string;
+        };
     };
 }[];
 export default _default;

package/dist/packages/sdk-ui/src/infra/translation/resources/__external__/es-ar.d.ts

@@ -256,6 +256,8 @@ declare const _default: {
                 yes: string;
                 no: string;
                 seeMore: string;
+                generateNarrative: string;
+                hideNarrative: string;
             };
             disclaimer: {
                 poweredByAi: string;
@@ -309,6 +311,8 @@ declare const _default: {
                 from: string;
                 to: string;
                 includeCurrent: string;
+                rankedBy: string;
+                selectField: string;
             };
             placeholders: {
                 selectFromList: string;
@@ -333,6 +337,8 @@ declare const _default: {
                 greaterThan: string;
                 greaterThanOrEqual: string;
                 isWithin: string;
+                top: string;
+                bottom: string;
             };
             validationErrors: {
                 invalidNumber: string;
@@ -427,6 +433,11 @@ declare const _default: {
             table: {
                 label: string;
             };
+            sankey: {
+                alerts: {
+                    tooManyStages: string;
+                };
+            };
         };
         loadingOverlay: {
             label: string;
@@ -452,6 +463,17 @@ declare const _default: {
             median: string;
             variance: string;
         };
+        measuresAgg: {
+            countDistinct: string;
+            count: string;
+            sum: string;
+            average: string;
+            min: string;
+            max: string;
+            median: string;
+            variance: string;
+            stdev: string;
+        };
     };
 }[];
 export default _default;

package/dist/packages/sdk-ui/src/infra/translation/resources/__external__/es-es.d.ts

@@ -256,6 +256,8 @@ declare const _default: {
                 yes: string;
                 no: string;
                 seeMore: string;
+                generateNarrative: string;
+                hideNarrative: string;
             };
             disclaimer: {
                 poweredByAi: string;
@@ -309,6 +311,8 @@ declare const _default: {
                 from: string;
                 to: string;
                 includeCurrent: string;
+                rankedBy: string;
+                selectField: string;
             };
             placeholders: {
                 selectFromList: string;
@@ -333,6 +337,8 @@ declare const _default: {
                 greaterThan: string;
                 greaterThanOrEqual: string;
                 isWithin: string;
+                top: string;
+                bottom: string;
             };
             validationErrors: {
                 invalidNumber: string;
@@ -427,6 +433,11 @@ declare const _default: {
             table: {
                 label: string;
             };
+            sankey: {
+                alerts: {
+                    tooManyStages: string;
+                };
+            };
         };
         loadingOverlay: {
             label: string;
@@ -452,6 +463,17 @@ declare const _default: {
             median: string;
             variance: string;
         };
+        measuresAgg: {
+            countDistinct: string;
+            count: string;
+            sum: string;
+            average: string;
+            min: string;
+            max: string;
+            median: string;
+            variance: string;
+            stdev: string;
+        };
     };
 }[];
 export default _default;