@sisense/sdk-ui 2.10.0 → 2.12.0

package/dist/packages/sdk-ui/src/dashboard/dashboard-helpers.d.ts

@@ -1,5 +1,6 @@
-import { DashboardProps } from './types';
 import { Filter, FilterRelations } from '@sisense/sdk-data';
+import type { JumpToDashboardConfig } from './hooks/jtd/jtd-types';
+import { DashboardProps } from './types';
 /**
  * Creates a new dashboard instance with its filters replaced by a new set of filters.
  *
@@ -107,3 +108,111 @@ export declare const removeFilter: (dashboard: DashboardProps, filterToRemove: F
  * @returns A new dashboard instance with the specified filters removed.
  */
 export declare const removeFilters: (dashboard: DashboardProps, filtersToRemove: Filter[]) => DashboardProps;
+/**
+ * Creates a new `DashboardProps` instance with JTD (Jump To Dashboard) configuration applied to a single widget.
+ *
+ * Jump To Dashboard (JTD) allows users to navigate from one dashboard to another when interacting with widgets,
+ * such as clicking on chart data points or using context menus. This function applies JTD configuration to a specific
+ * widget in a dashboard, enabling jump-to-dashboard functionality.
+ *
+ * This function does not modify the original dashboard; instead, it returns a new `DashboardProps` instance with the JTD
+ * configuration applied. If the specified widget does not exist in the dashboard, the function returns the original
+ * `DashboardProps` unchanged and logs a warning to the console.
+ *
+ * @example
+ * Apply JTD configuration to a dashboard widget.
+ * ```ts
+ * const jtdConfig: JumpToDashboardConfig = {
+ *   targets: [{ id: 'dashboardId1', caption: 'Analytics Dashboard' }],
+ *   interaction: {
+ *     triggerMethod: 'rightclick',
+ *     contextMenuCaption: 'Jump to Analytics'
+ *   }
+ * };
+ *
+ * const updatedDashboard = dashboardHelpers.applyJtdConfig(dashboard, 'widgetId3', jtdConfig);
+ * ```
+ *
+ * @param dashboard - The original dashboard to modify. Must be a valid `DashboardProps` object containing the target widget.
+ * @param widgetOid - The unique identifier (OID) of the widget to apply JTD configuration to. Must match an existing widget ID in the dashboard.
+ * @param config - The JTD configuration to apply.
+ *
+ * @returns A new `DashboardProps` instance with the JTD configuration applied to the specified widget. If the widget doesn't exist, returns the original dashboard unchanged.
+ *
+ * @group Dashboard Utilities
+ */
+export declare const applyJtdConfig: (dashboard: DashboardProps, widgetOid: string, config: JumpToDashboardConfig) => DashboardProps;
+/**
+ * Creates a new `DashboardProps` instance with JTD (Jump To Dashboard) configurations applied to multiple widgets in a single operation.
+ *
+ * Jump To Dashboard (JTD) allows users to navigate from one dashboard to another when interacting with widgets.
+ * This function efficiently applies JTD configurations to multiple widgets in a single operation.
+ *
+ * This function does not modify the original dashboard; instead, it returns a new `DashboardProps` instance with all valid
+ * JTD configurations applied. Configurations for non-existent widgets are automatically filtered out, and warnings
+ * are logged to the console for invalid widget OIDs.
+ *
+ * @example
+ * Apply a variety of Jump To Dashboard configuration options to multiple widgets in a single operation.
+ * ```ts
+ * import { dashboardHelpers } from '@sisense/sdk-ui';
+ *
+ * const dashboard: DashboardProps = {
+ *   title: 'Executive Dashboard',
+ *   widgets: [
+ *     { id: 'widgetId1', widgetType: 'chart', chartType: 'column', dataOptions: {...} },
+ *     { id: 'widgetId2', widgetType: 'chart', chartType: 'pie', dataOptions: {...} },
+ *     { id: 'widgetId3', widgetType: 'table', dataOptions: {...} }
+ *   ]
+ * };
+ *
+ * const jtdConfigs = {
+ *   'widgetId1': {
+ *     enabled: true,
+ *     targets: [{ id: 'dashboardId1', caption: 'Sales Breakdown' }],
+ *     interaction: {
+ *       triggerMethod: 'rightclick'
+ *     }
+ *   },
+ *   'widgetId2': {
+ *     targets: [{ id: 'dashboardId2', caption: 'Revenue Analysis' }],
+ *     interaction: {
+ *       triggerMethod: 'click',
+ *       contextMenuCaption: 'Analyze Revenue'
+ *     }
+ *   },
+ *   'widgetId3': {
+ *     enabled: true,
+ *     targets: [
+ *       { id: 'dashboardId3', caption: 'Customer Details' },
+ *       { id: 'dashboardId4', caption: 'Product Analytics' }
+ *     ],
+ *     interaction: {
+ *       triggerMethod: 'rightclick'
+ *     }
+ *   }
+ * };
+ *
+ * const updatedDashboard = dashboardHelpers.applyJtdConfigs(dashboard, jtdConfigs);
+ * ```
+ *
+ * @example Error handling
+ * Batch apply JTD configurations with error handling.
+ * ```ts
+ * const configsWithInvalidWidget = {
+ *   'widgetId1': { targets: [{ id: 'dashboardId1', caption: 'Target' }] },
+ *   'invalidWidgetId': { targets: [{ id: 'dashboardId2', caption: 'Other' }] } // Will be filtered out
+ * };
+ *
+ * const result = dashboardHelpers.applyJtdConfigs(dashboard, configsWithInvalidWidget);
+ * // Console warning: "Widgets with OIDs [invalidWidgetId] not found in dashboard..."
+ * // Only 'widgetId1' gets the JTD configuration applied
+ * ```
+ *
+ * @param dashboard - The original dashboard to modify. Must be a valid `DashboardProps` object with widgets to configure.
+ * @param jtdConfigs - An object mapping widget OIDs (keys) to their respective JTD configurations (values).
+ * @returns A new `DashboardProps` instance with all valid JTD configurations applied to their respective widgets. Invalid widget configurations are skipped and warnings are logged.
+ *
+ * @group Dashboard Utilities
+ */
+export declare const applyJtdConfigs: (dashboard: DashboardProps, jtdConfigs: Record<string, JumpToDashboardConfig>) => DashboardProps;

package/dist/packages/sdk-ui/src/dashboard/dashboard.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="react" />
-import { DashboardProps } from '../dashboard/types';
 import { Filter, FilterRelations } from '@sisense/sdk-data';
+import { DashboardProps } from '../dashboard/types';
 import { WidgetsPanelLayout } from '../models';
 export declare enum DashboardChangeType {
     /** Dashboard filters have been updated */

package/dist/packages/sdk-ui/src/dashboard/hooks/index.d.ts

@@ -0,0 +1,7 @@
+export { type JumpToDashboardConfig, type JumpToDashboardConfigForPivot, type JtdTarget, type TriggerMethod, } from './jtd';
+/**
+ * Internal JTD hook for dashboard composition
+ * @internal
+ */
+export { useJtdInternal } from './use-jtd';
+export { useJtdWidget } from './use-jtd-widget';

package/dist/packages/sdk-ui/src/dashboard/hooks/jtd/index.d.ts

@@ -1,5 +1,20 @@
-export { getFiltersFromDataPoint, getFormulaContextFilters, filterByAllowedDimensions, handleFormulaDuplicateFilters, mergeJtdFilters, } from './jtd-filters';
-export { getJtdClickHandler, getJtdClickHandlerForMultiplePoints, handleDataPointClick, handleTextWidgetClick, } from './jtd-handlers';
-export { getJumpToDashboardMenuItem, getJumpToDashboardMenuItemForMultiplePoints, } from './jtd-menu';
-export { addPointerCursorToChart, applyClickNavigationForChart, applyClickNavigationForText, applyClickNavigationForPivot, applyRightClickNavigation, applyRightClickNavigationForPivot, applyPivotLinkStyling, addJtdIconToHeader, } from './jtd-widget-transforms';
-export { type JtdCoreData, type JtdContext, type JtdActions, type JtdClickHandlerData, type JtdWidgetTransformConfig, type JtdDataPointClickEvent, type JtdMenuItem, } from './jtd-types';
+/**
+ * Jump To Dashboard configuration for regular widgets
+ * @group Dashboards
+ */
+export { type JumpToDashboardConfig } from './jtd-types';
+/**
+ * Jump To Dashboard configuration for pivot widgets
+ * @group Dashboards
+ */
+export { type JumpToDashboardConfigForPivot } from './jtd-types';
+/**
+ * Target dashboard configuration for Jump To Dashboard
+ * @group Dashboards
+ */
+export { type JtdTarget } from './jtd-types';
+/**
+ * Trigger method for Jump To Dashboard interactions
+ * @group Dashboards
+ */
+export { type TriggerMethod } from './jtd-types';

package/dist/packages/sdk-ui/src/dashboard/hooks/jtd/jtd-config-transformers.d.ts

@@ -0,0 +1,85 @@
+import type { Attribute, Dimension, Measure } from '@sisense/sdk-data';
+import { PivotTableDataOptions } from '../../../chart-data-options/types';
+import { WidgetProps } from '../../../props';
+import type { Panel } from '../../../widget-by-id/types';
+import type { JtdConfig, JtdTarget, JumpToDashboardConfig, JumpToDashboardConfigForPivot, PivotDimId } from './jtd-types';
+/**
+ * Transform legacy JtdConfig to new JumpToDashboardConfig format
+ *
+ * @param jtdConfig - The legacy JTD configuration
+ * @returns Transformed Jump To Dashboard configuration
+ * @internal
+ */
+export declare const transformJtdConfigToJumpToDashboardConfig: (jtdConfig: JtdConfig) => JumpToDashboardConfig;
+export declare const isPivotJumpToDashboardConfig: (config: JumpToDashboardConfig | JumpToDashboardConfigForPivot) => config is JumpToDashboardConfigForPivot;
+/**
+ * Transform common part of public JumpToDashboardConfig to inner JtdConfig format
+ *
+ * @param jumpConfig - The new Jump To Dashboard configuration
+ * @returns Transformed legacy JTD configuration
+ * @internal
+ */
+export declare const transformJumpToDashboardConfigToJtdConfigCommon: (jumpConfig: JumpToDashboardConfig | JumpToDashboardConfigForPivot) => Omit<JtdConfig, 'jumpTargets'>;
+export declare const transformJumpToDashboardConfigToJtdConfigForPivot: (jumpConfig: JumpToDashboardConfigForPivot, dataOptions: PivotTableDataOptions) => JtdConfig;
+/**
+ * Type guard to check if a config is a JumpToDashboardConfig
+ *
+ * @param config - The configuration to check
+ * @returns True if the config is a JumpToDashboardConfig
+ * @internal
+ */
+export declare const isJumpToDashboardConfig: (config: JtdConfig | JumpToDashboardConfig | JumpToDashboardConfigForPivot) => config is JumpToDashboardConfig | JumpToDashboardConfigForPivot;
+/**
+ * Normalize configuration to JumpToDashboardConfig format
+ * Accepts both legacy JtdConfig and new JumpToDashboardConfig
+ *
+ * @internal
+ * @param config - Either JtdConfig or JumpToDashboardConfig
+ * @returns Normalized JumpToDashboardConfig
+ */
+export declare const normalizeToJumpToDashboardConfig: (config: JtdConfig | JumpToDashboardConfig) => JumpToDashboardConfig;
+/**
+ * Normalize configuration to legacy JtdConfig format
+ * Accepts both legacy JtdConfig and new JumpToDashboardConfig
+ *
+ * @internal
+ * @param config - Either JtdConfig or JumpToDashboardConfig
+ * @returns Normalized JtdConfig
+ */
+export declare const normalizeToJtdConfig: (config: JtdConfig | JumpToDashboardConfig | JumpToDashboardConfigForPivot, widgetProps: WidgetProps) => JtdConfig;
+/**
+ * Enhanced matching strategy that considers location, expression, level, and other properties
+ * @param dimension - The dimension or measure object
+ * @param panels - Constructed panels with PanelItems
+ * @returns PivotDimId like "columns.0", "rows.1", "values.0"
+ * @internal
+ */
+export declare const dimensionToPivotDimId: (dimension: Attribute | Measure | {
+    dimension: Attribute;
+    location: 'row' | 'column' | 'value';
+}, panels: Panel[]) => PivotDimId | null;
+/**
+ * Convert PivotDimId back to Dimension/Measure using widget structure
+ * @param pivotDimId - PivotDimId like "columns.0", "rows.1", "values.0"
+ * @param widgetStructure - Widget structure with rows/columns/values arrays
+ * @returns The dimension or measure object, or null if not found
+ * @internal
+ */
+export declare const pivotDimIdToDimension: (pivotDimId: PivotDimId, widgetStructure: {
+    rows?: Array<Dimension | Measure>;
+    columns?: Array<Dimension | Measure>;
+    values?: Array<Dimension | Measure>;
+}) => Dimension | Measure | null;
+/**
+ * Convert Map-based pivot targets to array-based pivot targets (for internal JtdConfig)
+ * @param targetsMap - Map of dimensions/measures to targets
+ * @param panels - Widget metadata panels (source of truth for dimension positions)
+ * @returns Array of targets with pivotDimensions
+ * @internal
+ */
+export declare const mapTargetsToArrayTargets: (targetsMap: Map<Attribute | {
+    dimension: Attribute;
+    location: 'row' | 'column' | 'value';
+} | Measure, JtdTarget[]>, panels: Panel[]) => Array<JtdTarget & {
+    pivotDimensions?: PivotDimId[];
+}>;

package/dist/packages/sdk-ui/src/dashboard/hooks/jtd/jtd-filters.d.ts

@@ -1,9 +1,9 @@
 import { type Filter } from '@sisense/sdk-data';
 import { WidgetProps } from '../../../props.js';
 import { DataPoint, ScatterDataPoint } from '../../../types';
-import { JtdConfig } from '../../../widget-by-id/types';
+import { JtdConfig } from './jtd-types';
 /**
- * Jump to Dashboard (JTD) Filter Merging Logic:
+ * Jump To Dashboard (JTD) Filter Merging Logic:
  *
  * When a user clicks on a datapoint to open a JTD modal, multiple types of filters are merged:
  *
@@ -57,6 +57,7 @@ import { JtdConfig } from '../../../widget-by-id/types';
  * @param clickedWidget - The clicked widget
  * @param jtdConfig - The JTD configuration
  * @returns Array of formula context filters
+ * @internal
  */
 export declare const getFormulaContextFilters: (clickedWidget: WidgetProps, jtdConfig: JtdConfig) => Filter[];
 /**

package/dist/packages/sdk-ui/src/dashboard/hooks/jtd/jtd-formatters.d.ts

@@ -1,5 +1,67 @@
 import type { CustomDataCellFormatter, CustomHeaderCellFormatter } from '../../../pivot-table/formatters/types';
-import { JtdConfig } from '../../../widget-by-id/types';
+import { PivotTableDataPoint } from '../../../types';
+import { JtdConfig, JtdTarget } from './jtd-types';
+/**
+ * Check if a formatter cell ID is actionable for JTD
+ * Used by hyperlink formatters with cell IDs like "rows.0", "columns.1", "values.2"
+ *
+ * @param jtdConfig - The JTD configuration
+ * @param cellId - The cell ID from formatters (e.g., "rows.0")
+ * @returns Object with actionable status and matching target
+ * @internal
+ */
+export declare function getPivotFormatterCellActionability(jtdConfig: JtdConfig, cellId: string): {
+    isActionable: boolean;
+    matchingTarget?: JtdTarget;
+};
+/**
+ * Check if a click handler pivot point is actionable for JTD
+ * Used by click handlers with pivot data points containing custom dimension IDs
+ *
+ * @param jtdConfig - The JTD configuration
+ * @param pivotPoint - The pivot data point from click handlers
+ * @returns Object with actionable status and matching target
+ * @internal
+ */
+export declare function isPivotClickHandlerActionable(jtdConfig: JtdConfig, pivotPoint: PivotTableDataPoint): {
+    isActionable: boolean;
+    matchingTarget?: JtdTarget;
+};
+/**
+ * Find all actionable jump targets for a pivot point (for right-click menus)
+ * Used by right-click handlers that need to show multiple targets
+ *
+ * @param jtdConfig - The JTD configuration
+ * @param pivotPoint - The pivot data point from click handlers
+ * @returns Object with actionable status and all matching targets
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * // Usage in right-click menu handler for pivot tables
+ * const onPivotRightClick = (pivotPoint: PivotTableDataPoint) => {
+ *   const { isActionable, matchingTargets } = findAllActionablePivotTargets(jtdConfig, pivotPoint);
+ *
+ *   if (!isActionable) {
+ *     return; // No menu - headers are not clickable or no valid targets
+ *   }
+ *
+ *   // Only valid targets are returned:
+ *   // - Targets with matching pivot dimensions for this cell
+ *   // - NEVER targets with non-matching pivot dimensions
+ *   const menuItems = matchingTargets.map(target => ({
+ *     caption: target.caption,
+ *     onClick: () => handleJumpToDashboard(target, pivotPoint)
+ *   }));
+ *
+ *   openContextMenu({ items: menuItems });
+ * };
+ * ```
+ */
+export declare function getPivotTargetActionability(jtdConfig: JtdConfig, pivotPoint: PivotTableDataPoint): {
+    isActionable: boolean;
+    matchingTargets: JtdTarget[];
+};
 /**
  * Creates a data cell formatter that applies hyperlink styling for JTD navigation
  *
@@ -12,7 +74,7 @@ export declare function createJtdHyperlinkDataCellFormatter(hyperlinkColor: stri
  * Creates a header cell formatter that applies hyperlink styling for JTD navigation
  *
  * @param hyperlinkColor - The color to use for hyperlink text (uses theme's hyperlinkColor or defaults to DEFAULT_HYPERLINK_COLOR)
- * @param jtdConfig - JTD configuration containing drill targets
+ * @param jtdConfig - JTD configuration containing jump targets
  * @returns A header cell formatter that applies hyperlink styling to matching header cells
  */
 export declare function createJtdHyperlinkHeaderCellFormatter(hyperlinkColor: string, jtdConfig: JtdConfig): CustomHeaderCellFormatter;

package/dist/packages/sdk-ui/src/dashboard/hooks/jtd/jtd-handlers.d.ts

@@ -1,13 +1,12 @@
 import { type Filter } from '@sisense/sdk-data';
-import { WidgetProps } from '../../../props.js';
-import { PivotTableDataPoint, DataPoint } from '../../../types';
-import { JtdConfig } from '../../../widget-by-id/types';
 import { OpenModalFn } from '../../../common/components/modal/modal-context';
-import { JtdCoreData, JtdContext, JtdActions, JtdClickHandlerData, JtdDataPointClickEvent } from './jtd-types';
+import { WidgetProps } from '../../../props.js';
+import { DataPoint, PivotTableDataPoint } from '../../../types';
+import { JtdActions, JtdClickHandlerData, JtdConfig, JtdContext, JtdCoreData, JtdDataPointClickEvent } from './jtd-types';
 /**
  * Get the JTD click handler for a specific data point of the specific widget
  *
- * @param data - Core data with drill target (config, drill target, widget props, point)
+ * @param data - Core data with jump target (config, jump target, widget props, point)
  * @param context - Context data (filters)
  * @param actions - Action functions
  * @returns The JTD click handler
@@ -17,7 +16,7 @@ export declare const getJtdClickHandler: (data: JtdClickHandlerData, context: Jt
 /**
  * Get the JTD click handler for multiple data points
  *
- * @param data - Core data with drill target (config, drill target, widget props, points)
+ * @param data - Core data with jump target (config, jump target, widget props, points)
  * @param context - Context data (filters)
  * @param actions - Action functions
  * @returns The JTD click handler
@@ -45,7 +44,7 @@ export declare const convertPivotToDataPoint: (pivotPoint: PivotTableDataPoint)
 /**
  * Handle pivot table data point click
  *
- * @param data - Core data with drill target (config, drill target, widget props, pivot point)
+ * @param data - Core data with jump target (config, jump target, widget props, pivot point)
  * @param context - Context data (filters)
  * @param actions - Action functions
  * @param eventData - Event-related data

package/dist/packages/sdk-ui/src/dashboard/hooks/jtd/jtd-menu.d.ts

@@ -1,4 +1,5 @@
-import { JtdCoreData, JtdContext, JtdActions } from './jtd-types';
+import { JtdActions, JtdContext, JtdCoreData } from './jtd-types';
+export declare const jumpToDashboardMenuId = "jump-to-dashboard-menu";
 /**
  * Get the JTD menu item for a specific data point of the specific widget
  *