@sisense/sdk-ui 2.23.0 → 2.25.0

package/dist/packages/sdk-ui/src/infra/contexts/custom-widgets-provider/use-custom-widgets.d.ts

@@ -1,4 +1,4 @@
-import { CustomWidgetComponent } from './types';
+import { CustomWidgetComponent, CustomWidgetComponentProps } from './types';
 /**
  * Hook that provides API for configuring custom widgets.
  *
@@ -18,8 +18,15 @@ import { CustomWidgetComponent } from './types';
  *
  * @group Dashboards
  */
-export declare const useCustomWidgets: () => {
-    registerCustomWidget: <T = any>(customWidgetType: string, customWidget: CustomWidgetComponent<T>) => void;
+export declare const useCustomWidgets: () => UseCustomWidgetsResult;
+/**
+ * Result of the `useCustomWidgets` hook.
+ */
+export type UseCustomWidgetsResult = {
+    /** Registers a custom widget. */
+    registerCustomWidget: <T = CustomWidgetComponentProps>(customWidgetType: string, customWidget: CustomWidgetComponent<T>) => void;
+    /** Checks if a custom widget is registered. */
     hasCustomWidget: (customWidgetType: string) => boolean;
-    getCustomWidget: (customWidgetType: string) => CustomWidgetComponent<any> | undefined;
+    /** Gets a custom widget. */
+    getCustomWidget: (customWidgetType: string) => CustomWidgetComponent | undefined;
 };

package/dist/packages/sdk-ui/src/infra/contexts/emotion-cache-provider/emotion-cache-provider.d.ts

@@ -1,10 +1,38 @@
 import React, { ReactNode } from 'react';
 export interface EmotionCacheProviderProps {
     children: ReactNode;
+    /**
+     * An ancestor CSS selector (e.g. `'#sdk-scope'`) to prepend to every Emotion
+     * CSS rule to increase specificity.
+     *
+     * When omitted (`undefined`), no prefix logic is applied.
+     */
+    cssSelectorPrefix?: string;
 }
 /**
- * A provider component that uses the Emotion cache, but only creates one if a nonce is found in the DOM.
- * This ensures that styles are injected in a way that is compliant with CSP if necessary.
- * If no nonce is found, it simply renders the children without the CacheProvider.
+ * Provides an Emotion cache to the component tree.  Handles two concerns:
+ *
+ * 1. **CSP nonce** — when a `<meta property="csp-nonce">` tag is present, a
+ *    cache carrying that nonce is created so Emotion's `<style>` tags comply
+ *    with Content Security Policy.
+ *
+ * 2. **CSS selector prefix** — when `cssSelectorPrefix` is provided, a Stylis
+ *    plugin is installed that prepends the selector to every compiled CSS rule,
+ *    increasing specificity so CSDK styles win over host-app overrides.
+ *
+ * The component is designed to be used at two levels:
+ *
+ * - **Top-level** (in `SisenseContextProvider`, no `cssSelectorPrefix` prop) —
+ *   creates a nonce-only cache if needed and establishes the internal context
+ *   so nested instances can detect they are not the first provider.
+ *
+ * - **Nested** (in `ThemeProvider`, with `cssSelectorPrefix` prop) — compares
+ *   the requested prefix against the ancestor's value via `EmotionCacheContext`.
+ *   A new cache is created only when the prefix has actually changed; otherwise
+ *   children are rendered as-is, reusing the ancestor's cache.
+ *
+ * When a nested provider creates a cache (nonce is always included when present),
+ * it also updates `EmotionCacheContext` so that further nested providers can
+ * detect the new prefix value and avoid creating duplicate caches.
  */
 export declare const EmotionCacheProvider: React.FC<EmotionCacheProviderProps>;

package/dist/packages/sdk-ui/src/infra/contexts/emotion-cache-provider/stylis-plugins/css-selector-prefix-plugin.d.ts

@@ -0,0 +1,18 @@
+import type { Middleware } from 'stylis';
+/**
+ * Creates a Stylis plugin that prepends a CSS selector prefix to every rule.
+ *
+ * Given configured prefix, for example "#sdk-root", a compiled rule like ".css-abc { color: red }"
+ * becomes "#sdk-root .css-abc { color: red }", increasing its specificity so
+ * that library styles win over same-specificity rules from the host application.
+ *
+ * Operating at the Stylis (CSS compilation) layer means all CSS is covered —
+ * template strings, interpolation functions, object styles, and keyframe
+ * declarations — without any changes to the styled-component call sites.
+ *
+ * @param prefix - An ancestor CSS selector, e.g. `'#sdk-scope'` or `'.my-app'`.
+ *   Must match an element that wraps all library components in the DOM.
+ * @returns A Stylis v4 middleware function compatible with `@emotion/cache`'s
+ *   `stylisPlugins` option.
+ */
+export declare function createCssSelectorPrefixPlugin(prefix: string): Middleware;

package/dist/packages/sdk-ui/src/infra/plugins/custom-plugin-context-provider.d.ts

@@ -0,0 +1,18 @@
+import { type PropsWithChildren } from 'react';
+import { CustomContextProviderProps } from '../../types';
+import type { Plugin } from './types.js';
+/** @internal */
+export type CustomPluginContextProviderContext = {
+    plugins: Plugin[];
+};
+/** @internal */
+export type CustomPluginContextProviderProps = CustomContextProviderProps<CustomPluginContextProviderContext>;
+/**
+ * Custom Plugin Context Provider component that allows passing external plugin context.
+ *
+ * Specifically designed to serve as a bridge for passing plugin context between an
+ * external framework wrapper and child React components.
+ *
+ * @internal
+ */
+export declare const CustomPluginContextProvider: React.FC<PropsWithChildren<CustomPluginContextProviderProps>>;

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

@@ -0,0 +1,29 @@
+/// <reference types="react" />
+import { WidgetPlugin } from './widget-plugins/types.js';
+import type { WidgetPluginRegistry } from './widget-plugins/widget-plugin-registry.js';
+/**
+ * Context for accessing registered plugins
+ *
+ * @internal
+ */
+export interface PluginContextValue {
+    /**
+     * Validated widget plugin declarations (metadata)
+     */
+    widgetPlugins: readonly WidgetPlugin[];
+    /**
+     * Central widget component registry (used for lookup and legacy bridge)
+     */
+    widgetRegistry: WidgetPluginRegistry;
+}
+/**
+ * Error message when a plugin hook/component is used outside PluginProvider.
+ * @internal
+ */
+export declare const PLUGIN_CONTEXT_MISSING_MESSAGE = "PluginContext is missing. Ensure PluginProvider (or a compatible provider) is an ancestor.";
+/**
+ * React context for plugin management.
+ * Default is null to avoid a shared WidgetPluginRegistry at module load (cross-test/consumer pollution).
+ * PluginProvider supplies a real value; consumers must check for null and throw if missing.
+ */
+export declare const PluginContext: import("react").Context<PluginContextValue | null>;

package/dist/packages/sdk-ui/src/infra/{contexts/plugin-provider → plugins}/plugin-provider.d.ts

@@ -1,9 +1,9 @@
 import { type ReactNode } from 'react';
-import { Plugin } from './types';
+import { Plugin } from './types.js';
 /**
  * Props for PluginProvider component
  *
- * @internal
+ * @sisenseInternal
  */
 export interface PluginProviderProps {
     /**
@@ -17,5 +17,7 @@ export interface PluginProviderProps {
 }
 /**
  * Plugin Provider component that validates and provides access to plugins
+ *
+ * @sisenseInternal
  */
 export declare const PluginProvider: React.FC<PluginProviderProps>;

package/dist/packages/sdk-ui/src/infra/{contexts/plugin-provider → plugins}/types.d.ts

@@ -1,9 +1,10 @@
+import type { WidgetPlugin } from './widget-plugins/types.js';
 /**
- * Plugin with metadata information
+ * Base plugin information
  *
- * @internal
+ * @sisenseInternal
  */
-export interface Plugin {
+export interface BasePluginInfo {
     /**
      * Unique name identifier for the plugin
      */
@@ -32,7 +33,7 @@ export interface Plugin {
 /**
  * Result of plugin validation
  *
- * @internal
+ * @sisenseInternal
  */
 export interface PluginValidationResult {
     /**
@@ -48,3 +49,10 @@ export interface PluginValidationResult {
      */
     reason?: string;
 }
+/**
+ * Plugin declaration.
+ * Currently only widget plugins are supported.
+ *
+ * @sisenseInternal
+ */
+export type Plugin = WidgetPlugin;

package/dist/packages/sdk-ui/src/infra/plugins/use-widget-plugin-registry.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Hook for accessing the widget plugin registry.
+ * Used internally by the CustomWidget renderer to look up components.
+ *
+ * @internal
+ */
+export declare const useWidgetPluginRegistry: () => import("./widget-plugins/widget-plugin-registry.js").WidgetPluginRegistry;

package/dist/packages/sdk-ui/src/infra/{contexts/plugin-provider → plugins}/validate-plugins.d.ts

@@ -1,4 +1,4 @@
-import { Plugin } from './types';
+import { Plugin } from './types.js';
 /**
  * Validates and returns only valid plugins.
  *

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

@@ -0,0 +1,302 @@
+import { FunctionComponent, ReactNode } from 'react';
+import type { DataSource, Filter, FilterRelations } from '@sisense/sdk-data';
+import { AnyObject } from '../../../shared/utils/utility-types';
+import type { AbstractDataPointWithEntries, GenericDataOptions } from '../../../types';
+import type { BasePluginInfo } from '../types';
+/**
+ * Widget plugin declaration.
+ *
+ * @sisenseInternal
+ */
+export interface WidgetPlugin<Props = CustomVisualizationProps, StyleOptions = CustomVisualizationStyleOptions> extends BasePluginInfo {
+    /**
+     * The type of plugin
+     */
+    pluginType: 'widget';
+    /**
+     * The custom widget declaration to be registered
+     */
+    customWidget?: {
+        /**
+         * The unique name of the custom widget type (used for registration and identification)
+         * @example 'my-custom-widget'
+         */
+        name: string;
+        /**
+         * The display name of the custom widget type (used for display in the UI)
+         * @example 'My Custom Widget'
+         */
+        displayName: string;
+        /**
+         * Configuration options for the custom widget
+         */
+        config?: {
+            /**
+             * Configuration options for the widget header
+             */
+            header?: {
+                /**
+                 * Whether the header is visible.
+                 * If not specified, the header is visible by default.
+                 * @example true
+                 */
+                visible?: boolean;
+            };
+        };
+        /**
+         * Definition of the custom visualization to be rendered in the new custom widget
+         */
+        visualization: {
+            /**
+             * The custom visualization component to be rendered in the new custom widget
+             */
+            Component: CustomVisualization<Props>;
+        };
+        /**
+         * Definition of the design panel for the custom widget
+         */
+        designPanel?: {
+            Component?: DesignPanel<StyleOptions>;
+        };
+        /**
+         * Definition of the data panel for the custom widget
+         */
+        dataPanel?: {
+            /**
+             * Configuration options for the data panel
+             * @example
+             * ```tsx
+             * {
+             *   inputs: [
+             *     { name: 'category', displayName: 'Category', type: 'dimension' },
+             *     { name: 'value', displayName: 'Value', type: 'measure' },
+             *   ],
+             * }
+             * ```
+             */
+            config?: {
+                /**
+                 * Inputs for the data panel
+                 * @example
+                 * ```tsx
+                 * [
+                 *   { name: 'category', displayName: 'Category', type: 'dimension' },
+                 *   { name: 'value', displayName: 'Value', type: 'measure' },
+                 * ]
+                 * ```
+                 */
+                inputs?: {
+                    /**
+                     * The name of the input
+                     * @example 'category'
+                     */
+                    name: string;
+                    /**
+                     * The display name of the input
+                     * @example 'Category'
+                     */
+                    displayName?: string;
+                    /**
+                     * The type of the input
+                     */
+                    type: 'dimension' | 'measure';
+                    /**
+                     * The minimum number of items that can be selected
+                     * @example 1
+                     */
+                    minItems?: number;
+                    /**
+                     * The maximum number of items that can be selected
+                     * @example 5
+                     */
+                    maxItems?: number;
+                    /**
+                     * Whether the items can be sorted
+                     */
+                    canSort?: boolean;
+                    /**
+                     * Whether the items can be formatted
+                     */
+                    canFormat?: boolean;
+                }[];
+            };
+            /**
+             * The icon of the custom widget to be displayed in the widget selector
+             * @example
+             * ```tsx
+             * const MyWidgetIcon = () => <PieChartIcon />;
+             * ```
+             */
+            icon?: () => ReactNode;
+        };
+    };
+}
+/**
+ * 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
+ *
+ * @example
+ * ```tsx
+ * import { CustomVisualization, CustomVisualizationProps, CustomWidgetDataPoint, StyledColumn, StyledMeasureColumn, DataPointEntry, GenericDataOptions} from '@sisense/sdk-ui';
+ *
+ * interface MyDataOptions extends GenericDataOptions {
+ *   category: StyledColumn[];
+ *   value: StyledMeasureColumn[];
+ * }
+ *
+ * interface MyDataPoint extends CustomWidgetDataPoint {
+ *   entries: {
+ *     category: DataPointEntry[];
+ *     value: DataPointEntry[];
+ *   };
+ * }
+ *
+ * type MyNewChartProps = CustomVisualizationProps<MyDataOptions, {}, MyDataPoint>;
+ *
+ * const MyNewChart: CustomVisualization<MyNewChartProps> = (props) => {
+ *   const { dataOptions, onDataPointClick } = props;
+ *   // ... implementation based on props
+ *   return <div>My New Awesome Chart</div>;
+ * };
+ * ```
+ *
+ * @sisenseInternal
+ */
+export interface CustomVisualizationProps<DataOptions = GenericDataOptions, StyleOptions = CustomVisualizationStyleOptions, DataPoint extends AbstractDataPointWithEntries = AbstractDataPointWithEntries> extends CustomVisualizationEventProps<DataPoint> {
+    /** Data source for the custom visualization */
+    dataSource?: DataSource;
+    /** Data options defining what data to display */
+    dataOptions: DataOptions;
+    /** Style options for customizing appearance */
+    styleOptions?: StyleOptions;
+    /** Filters to apply to the data */
+    filters?: Filter[] | FilterRelations;
+    /** Highlight filters for interactive highlighting */
+    highlights?: Filter[];
+}
+/**
+ * Style options for a custom visualization.
+ *
+ * @sisenseInternal
+ */
+export interface CustomVisualizationStyleOptions extends AnyObject {
+}
+/**
+ * A user-defined custom visualization component.
+ * This can be any visual representation of the data - chart, table, map, etc.
+ *
+ * @typeParam Props - The props type for the custom visualization component
+ * @sisenseInternal
+ */
+export type CustomVisualization<Props = CustomVisualizationProps> = (props: Props) => ReactNode;
+/**
+ * Event props for custom visualizations with generic data point type.
+ *
+ * @typeParam DataPoint - The shape of data points for this custom visualization
+ * @sisenseInternal
+ */
+export interface CustomVisualizationEventProps<DataPoint extends AbstractDataPointWithEntries = AbstractDataPointWithEntries> {
+    /**
+     * Click handler callback for a data point
+     *
+     * @category Callbacks
+     */
+    onDataPointClick?: CustomVisualizationDataPointEventHandler<DataPoint>;
+    /**
+     * Context menu handler callback for a data point
+     *
+     * @category Callbacks
+     */
+    onDataPointContextMenu?: CustomVisualizationDataPointContextMenuHandler<DataPoint>;
+    /**
+     * Handler callback for selection of multiple data points
+     *
+     * @category Callbacks
+     */
+    onDataPointsSelected?: CustomVisualizationDataPointsEventHandler<DataPoint>;
+}
+/**
+ * Generic event handler for custom visualization data point click.
+ *
+ * @typeParam T - The shape of the data point
+ * @example
+ * ```tsx
+ * const handleClick: CustomVisualizationDataPointEventHandler<MyChartDataPoint> = (point, event) => {
+ *   console.log('Clicked:', point.label, point.value);
+ * };
+ * ```
+ *
+ * @sisenseInternal
+ */
+export type CustomVisualizationDataPointEventHandler<T extends AbstractDataPointWithEntries = AbstractDataPointWithEntries> = (point: CustomVisualizationDataPoint<T>, 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.
+ *
+ * @example
+ * ```typescript
+ * interface MyChartDataPoint extends CustomVisualizationDataPoint {
+ *   entries: {
+ *     category: DataPointEntry[];
+ *     value: DataPointEntry[];
+ *   };
+ * }
+ *
+ * const onDataPointClick = (point: MyChartDataPoint) => {
+ *   console.log('Clicked category:', point.entries.category[0].value);
+ * };
+ * ```
+ *
+ * @sisenseInternal
+ */
+export type CustomVisualizationDataPoint<T extends AbstractDataPointWithEntries = AbstractDataPointWithEntries> = T;
+/**
+ * Generic event handler for custom widget data point context menu.
+ *
+ * @typeParam T - The shape of the data point
+ * @sisenseInternal
+ */
+export type CustomVisualizationDataPointContextMenuHandler<T extends AbstractDataPointWithEntries = AbstractDataPointWithEntries> = (
+/** Data point that triggered the context menu */
+point: CustomVisualizationDataPoint<T>, 
+/** Native browser event */
+nativeEvent: MouseEvent) => void;
+/**
+ * Generic event handler for custom visualization data points selection.
+ *
+ * @typeParam T - The shape of the data point
+ * @example
+ * ```tsx
+ * const handleSelect: CustomVisualizationDataPointsEventHandler<MyChartDataPoint> = (points, event) => {
+ *   console.log('Selected:', points.length, 'points');
+ * };
+ * ```
+ *
+ * @sisenseInternal
+ */
+export type CustomVisualizationDataPointsEventHandler<T extends AbstractDataPointWithEntries = AbstractDataPointWithEntries> = (
+/** Data points that were selected */
+points: CustomVisualizationDataPoint<T>[], 
+/** Native browser event */
+nativeEvent: MouseEvent) => void;
+/**
+ * Props for the design panel component for the custom widget.
+ *
+ * @sisenseInternal
+ */
+export interface DesignPanelProps<StyleOptions = CustomVisualizationStyleOptions> {
+    styleOptions: StyleOptions;
+    onChange: (styleOptions: StyleOptions) => void;
+}
+/**
+ * The design panel component for the custom widget.
+ *
+ * @sisenseInternal
+ */
+export type DesignPanel<StyleOptions = CustomVisualizationStyleOptions> = FunctionComponent<DesignPanelProps<StyleOptions>>;

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

@@ -0,0 +1,33 @@
+import type { CustomVisualization } from './types.js';
+/**
+ * Central widget registration and lookup.
+ * Plugin-sourced entries take priority over legacy-sourced entries.
+ *
+ * @internal
+ */
+export declare class WidgetPluginRegistry {
+    private readonly entries;
+    /**
+     * Register a widget component by type name.
+     * Plugin-sourced entries take priority over legacy-sourced entries.
+     * Within the same source, first-write-wins (no silent overwrites).
+     */
+    register(widgetTypeName: string, component: CustomVisualization, source?: 'plugin' | 'legacy'): void;
+    /**
+     * Unregister a widget by type name and source.
+     * Only removes the entry if it matches the given source.
+     */
+    unregister(widgetTypeName: string, source: 'plugin' | 'legacy'): void;
+    /**
+     * Get a widget component by type name.
+     * When `source` is provided, returns the component only if the entry matches that source.
+     * When omitted, returns the component for any source (plugin takes priority over legacy).
+     */
+    getComponent(widgetTypeName: string, source?: 'plugin' | 'legacy'): CustomVisualization | undefined;
+    /**
+     * Check if a widget is registered.
+     * When `source` is provided, returns true only if an entry exists for that source.
+     * When omitted, returns true for any registered entry.
+     */
+    has(widgetTypeName: string, source?: 'plugin' | 'legacy'): boolean;
+}

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

@@ -223,6 +223,8 @@ declare const _default: {
                 deleteWidget: string;
                 renameWidget: string;
                 distributeEqualWidth: string;
+                download: string;
+                csvFile: string;
             };
         };
         customWidgets: {
@@ -407,6 +409,33 @@ declare const _default: {
                 lockGroup: string;
                 unlockGroup: string;
             };
+            toggleSwitch: string;
+        };
+        chart: {
+            indicator: {
+                label: string;
+            };
+            visualization: {
+                label: string;
+            };
+            pivotTable: {
+                label: string;
+            };
+            table: {
+                label: string;
+            };
+        };
+        loadingOverlay: {
+            label: string;
+        };
+        queryDefinition: {
+            showMorePills: string;
+            showLess: string;
+            connectorBy: string;
+            connectorWhere: string;
+            tooltipType: string;
+            tooltipColumn: string;
+            tooltipFormula: string;
         };
         measures: {
             countShort: string;

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

@@ -223,6 +223,8 @@ declare const _default: {
                 deleteWidget: string;
                 renameWidget: string;
                 distributeEqualWidth: string;
+                download: string;
+                csvFile: string;
             };
         };
         customWidgets: {
@@ -407,6 +409,33 @@ declare const _default: {
                 lockGroup: string;
                 unlockGroup: string;
             };
+            toggleSwitch: string;
+        };
+        chart: {
+            indicator: {
+                label: string;
+            };
+            visualization: {
+                label: string;
+            };
+            pivotTable: {
+                label: string;
+            };
+            table: {
+                label: string;
+            };
+        };
+        loadingOverlay: {
+            label: string;
+        };
+        queryDefinition: {
+            showMorePills: string;
+            showLess: string;
+            connectorBy: string;
+            connectorWhere: string;
+            tooltipType: string;
+            tooltipColumn: string;
+            tooltipFormula: string;
         };
         measures: {
             countShort: string;

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

@@ -223,6 +223,8 @@ declare const _default: {
                 deleteWidget: string;
                 renameWidget: string;
                 distributeEqualWidth: string;
+                download: string;
+                csvFile: string;
             };
         };
         customWidgets: {
@@ -407,6 +409,33 @@ declare const _default: {
                 lockGroup: string;
                 unlockGroup: string;
             };
+            toggleSwitch: string;
+        };
+        chart: {
+            indicator: {
+                label: string;
+            };
+            visualization: {
+                label: string;
+            };
+            pivotTable: {
+                label: string;
+            };
+            table: {
+                label: string;
+            };
+        };
+        loadingOverlay: {
+            label: string;
+        };
+        queryDefinition: {
+            showMorePills: string;
+            showLess: string;
+            connectorBy: string;
+            connectorWhere: string;
+            tooltipType: string;
+            tooltipColumn: string;
+            tooltipFormula: string;
         };
         measures: {
             countShort: string;