@sisense/sdk-ui 2.31.1 → 2.32.0

package/dist/packages/sdk-ui/src/domains/visualizations/components/chart/restructured-charts/kpi-chart/renderer/use-element-size.d.ts

@@ -0,0 +1,26 @@
+import { RefObject } from 'react';
+/**
+ * An element's border-box size, in CSS pixels (matches `getBoundingClientRect`, which this hook
+ * measures with -- border- and padding-inclusive, not the content box).
+ * @internal
+ */
+export type ElementSize = {
+    width: number;
+    height: number;
+};
+/**
+ * Observes the element referenced by `ref` via `ResizeObserver` and returns its current border
+ * box size (via `getBoundingClientRect`, border- and padding-inclusive), in CSS pixels. Reports
+ * `{ width: 0, height: 0 }` until the element is measured, or when no element is attached.
+ *
+ * This hook owns the KPI renderer's element-tracker/`ResizeObserver` lifecycle pattern in one
+ * place: the renderer derives the card's coarse tier from this raw size (via the pure
+ * `getSizeTier`, see `use-size-tier.ts`), and other callers consume the size directly -- e.g.
+ * sizing a Highcharts sparkline to its cell, or computing a non-circular height budget for an
+ * auto-fit sibling (whose own border-subtraction logic, see `kpi-chart-renderer.tsx`, relies on
+ * this being border-box, not content-box).
+ * @param ref - Ref to the element whose size should be observed.
+ * @returns The element's current border box size.
+ * @internal
+ */
+export declare function useElementSize(ref: RefObject<HTMLElement | null>): ElementSize;

package/dist/packages/sdk-ui/src/domains/visualizations/components/chart/restructured-charts/kpi-chart/renderer/use-size-tier.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Coarse size classification for a KPI card, used to switch layout/typography rules
+ * as the card is resized rather than continuously scaling every property.
+ * @internal
+ */
+export type KpiSizeTier = 'xs' | 'sm' | 'md' | 'lg';
+/**
+ * Classifies a width/height pair into a coarse {@link KpiSizeTier}.
+ *
+ * Width and height are classified independently against their own thresholds, and the
+ * smaller-tier axis wins -- a card that's wide but short is still capped to the smaller
+ * tier. For example, 600x100 is `'xs'` (not `'lg'`) because the height falls below the
+ * `'xs'` floor even though the width alone would qualify for `'lg'`.
+ * @param width - Card width in CSS pixels.
+ * @param height - Card height in CSS pixels.
+ * @returns The size tier: `'xs'`, `'sm'`, `'md'`, or `'lg'`.
+ * @internal
+ */
+export declare function getSizeTier(width: number, height: number): KpiSizeTier;

package/dist/packages/sdk-ui/src/domains/visualizations/components/chart/restructured-charts/kpi-chart/types.d.ts

@@ -0,0 +1,62 @@
+import { ChartData } from '../../../../../../domains/visualizations/core/chart-data/types';
+import { NumberFormatConfig } from '../../../../../../types';
+/**
+ * Computed comparison data for a KPI chart, as resolved by the data layer.
+ * Mirrors the public {@link KpiComparison} union, with all math and coloring resolved.
+ *
+ * @internal
+ */
+export type KpiComparisonData = {
+    type: 'previous-period';
+    baseline: number;
+    deltaValue: number;
+    deltaPercent?: number;
+    labelKey: string;
+} | {
+    type: 'delta';
+    baseline: number;
+    deltaValue: number;
+    deltaPercent?: number;
+    label: string;
+    color?: string;
+} | {
+    type: 'target';
+    target: number;
+    percentOfTarget?: number;
+    toGo: number;
+    label: string;
+    color?: string;
+} | {
+    type: 'value';
+    value: number;
+    label: string;
+    color?: string;
+    numberFormatConfig?: NumberFormatConfig;
+};
+/**
+ * Processed chart data ready for the KPI renderer.
+ *
+ * @internal
+ */
+export type KpiChartData = {
+    type: 'kpi';
+    /** Whether the query returned any rows; false triggers the no-results overlay. */
+    hasRows: boolean;
+    value?: number;
+    valueTitle: string;
+    valueColor?: string;
+    /** Last date bucket as epoch milliseconds — shown in the header when the headline is the last bucket. */
+    valuePeriodMs?: number;
+    numberFormatConfig?: NumberFormatConfig;
+    comparison?: KpiComparisonData;
+    /** `null` points are gaps in the sparkline, never rendered as zero. */
+    sparklinePoints?: {
+        x: number;
+        y: number | null;
+    }[];
+};
+/**
+ * Checks whether the given generic chart data is shaped as {@link KpiChartData}.
+ * @internal
+ */
+export declare const isKpiChartData: (chartData: ChartData) => chartData is KpiChartData;

package/dist/packages/sdk-ui/src/domains/visualizations/components/chart/restructured-charts/types.d.ts

@@ -6,29 +6,52 @@ import { QueryDescription } from '../../../../../domains/query-execution/core/ex
 import type { ChartRendererProps } from '../../../../../domains/visualizations/components/chart';
 import { ScattermapProps } from '../../../../../domains/visualizations/components/chart/components/scattermap/scattermap';
 import { AreamapProps } from '../../../../../domains/visualizations/components/chart/restructured-charts/areamap-chart/renderer';
-import { AreamapChartDataOptions, AreamapChartDataOptionsInternal, CalendarHeatmapChartDataOptions, CalendarHeatmapChartDataOptionsInternal, CartesianChartDataOptions, CartesianChartDataOptionsInternal, CategoricalChartDataOptions, CategoricalChartDataOptionsInternal, ChartDataOptionsInternal, SankeyChartDataOptions, SankeyChartDataOptionsInternal, ScattermapChartDataOptions, ScattermapChartDataOptionsInternal } from '../../../../../domains/visualizations/core/chart-data-options/types';
+import { AreamapChartDataOptions, AreamapChartDataOptionsInternal, CalendarHeatmapChartDataOptions, CalendarHeatmapChartDataOptionsInternal, CartesianChartDataOptions, CartesianChartDataOptionsInternal, CategoricalChartDataOptions, CategoricalChartDataOptionsInternal, ChartDataOptionsInternal, KpiChartDataOptions, KpiChartDataOptionsInternal, SankeyChartDataOptions, SankeyChartDataOptionsInternal, ScattermapChartDataOptions, ScattermapChartDataOptionsInternal } from '../../../../../domains/visualizations/core/chart-data-options/types';
 import { DataTable } from '../../../../../domains/visualizations/core/chart-data-processor/table-processor';
-import type { CartesianChartData, CategoricalChartData, ScattermapChartData } from '../../../../../domains/visualizations/core/chart-data/types';
+import type { CartesianChartData, CategoricalChartData, ChartData, ScattermapChartData } from '../../../../../domains/visualizations/core/chart-data/types';
 import { DesignOptions } from '../../../../../domains/visualizations/core/chart-options-processor/translations/types';
 import { type ClientApplication } from '../../../../../infra/app/types';
-import type { AreamapStyleOptions, AreaStyleOptions, CalendarHeatmapStyleOptions, ChartDataOptions, ChartStyleOptions, FunnelStyleOptions, LineStyleOptions, PieStyleOptions, PolarStyleOptions, SankeyStyleOptions, ScattermapStyleOptions, StackableStyleOptions, StreamgraphStyleOptions, SunburstStyleOptions, TreemapStyleOptions } from '../../../../../types';
+import type { AreamapStyleOptions, AreaStyleOptions, CalendarHeatmapStyleOptions, ChartDataOptions, ChartStyleOptions, FunnelStyleOptions, KpiStyleOptions, LineStyleOptions, PieStyleOptions, PolarStyleOptions, SankeyStyleOptions, ScattermapStyleOptions, StackableStyleOptions, StreamgraphStyleOptions, SunburstStyleOptions, TreemapStyleOptions } from '../../../../../types';
 import { AreamapData } from './areamap-chart/types';
 import { CalendarHeatmapChartData } from './highchart-based-charts/calendar-heatmap-chart/data';
 import { HighchartsBasedChartRendererProps } from './highchart-based-charts/highcharts-based-chart-renderer/highcharts-based-chart-renderer';
 import { SankeyChartData } from './highchart-based-charts/sankey-chart/types';
-export type SupportedChartType = 'areamap' | 'column' | 'bar' | 'line' | 'area' | 'polar' | 'pie' | 'funnel' | 'calendar-heatmap' | 'treemap' | 'sunburst' | 'streamgraph' | 'sankey';
-export type TypedChartDataOptions<CT extends SupportedChartType> = CT extends 'areamap' ? AreamapChartDataOptions : CT extends 'scattermap' ? ScattermapChartDataOptions : CT extends 'pie' | 'funnel' | 'treemap' | 'sunburst' ? CategoricalChartDataOptions : CT extends 'column' | 'bar' | 'line' | 'area' | 'polar' | 'streamgraph' ? CartesianChartDataOptions : CT extends 'calendar-heatmap' ? CalendarHeatmapChartDataOptions : CT extends 'sankey' ? SankeyChartDataOptions : never;
-export type TypedDataOptionsInternal<CT extends SupportedChartType> = CT extends 'areamap' ? AreamapChartDataOptionsInternal : CT extends 'scattermap' ? ScattermapChartDataOptionsInternal : CT extends 'pie' | 'funnel' | 'treemap' | 'sunburst' ? CategoricalChartDataOptionsInternal : CT extends 'column' | 'bar' | 'line' | 'area' | 'polar' | 'streamgraph' ? CartesianChartDataOptionsInternal : CT extends 'calendar-heatmap' ? CalendarHeatmapChartDataOptionsInternal : CT extends 'sankey' ? SankeyChartDataOptionsInternal : never;
-export type TypedChartStyleOptions<CT extends SupportedChartType> = CT extends 'areamap' ? AreamapStyleOptions : CT extends 'scattermap' ? ScattermapStyleOptions : CT extends 'pie' ? PieStyleOptions : CT extends 'funnel' ? FunnelStyleOptions : CT extends 'treemap' ? TreemapStyleOptions : CT extends 'sunburst' ? SunburstStyleOptions : CT extends 'column' | 'bar' ? StackableStyleOptions : CT extends 'line' ? LineStyleOptions : CT extends 'area' ? AreaStyleOptions : CT extends 'polar' ? PolarStyleOptions : CT extends 'calendar-heatmap' ? CalendarHeatmapStyleOptions : CT extends 'streamgraph' ? StreamgraphStyleOptions : CT extends 'sankey' ? SankeyStyleOptions : never;
+import { KpiChartRendererProps } from './kpi-chart/renderer/index';
+import { KpiChartData } from './kpi-chart/types';
+export type SupportedChartType = 'areamap' | 'column' | 'bar' | 'line' | 'area' | 'polar' | 'pie' | 'funnel' | 'calendar-heatmap' | 'kpi' | 'treemap' | 'sunburst' | 'streamgraph' | 'sankey';
+export type TypedChartDataOptions<CT extends SupportedChartType> = CT extends 'areamap' ? AreamapChartDataOptions : CT extends 'scattermap' ? ScattermapChartDataOptions : CT extends 'pie' | 'funnel' | 'treemap' | 'sunburst' ? CategoricalChartDataOptions : CT extends 'column' | 'bar' | 'line' | 'area' | 'polar' | 'streamgraph' ? CartesianChartDataOptions : CT extends 'calendar-heatmap' ? CalendarHeatmapChartDataOptions : CT extends 'sankey' ? SankeyChartDataOptions : CT extends 'kpi' ? KpiChartDataOptions : never;
+export type TypedDataOptionsInternal<CT extends SupportedChartType> = CT extends 'areamap' ? AreamapChartDataOptionsInternal : CT extends 'scattermap' ? ScattermapChartDataOptionsInternal : CT extends 'pie' | 'funnel' | 'treemap' | 'sunburst' ? CategoricalChartDataOptionsInternal : CT extends 'column' | 'bar' | 'line' | 'area' | 'polar' | 'streamgraph' ? CartesianChartDataOptionsInternal : CT extends 'calendar-heatmap' ? CalendarHeatmapChartDataOptionsInternal : CT extends 'sankey' ? SankeyChartDataOptionsInternal : CT extends 'kpi' ? KpiChartDataOptionsInternal : never;
+export type TypedChartStyleOptions<CT extends SupportedChartType> = CT extends 'areamap' ? AreamapStyleOptions : CT extends 'scattermap' ? ScattermapStyleOptions : CT extends 'pie' ? PieStyleOptions : CT extends 'funnel' ? FunnelStyleOptions : CT extends 'treemap' ? TreemapStyleOptions : CT extends 'sunburst' ? SunburstStyleOptions : CT extends 'column' | 'bar' ? StackableStyleOptions : CT extends 'line' ? LineStyleOptions : CT extends 'area' ? AreaStyleOptions : CT extends 'polar' ? PolarStyleOptions : CT extends 'calendar-heatmap' ? CalendarHeatmapStyleOptions : CT extends 'kpi' ? KpiStyleOptions : CT extends 'streamgraph' ? StreamgraphStyleOptions : CT extends 'sankey' ? SankeyStyleOptions : never;
 export type TypedDesignOptions<CT extends SupportedChartType> = DesignOptions<CT>;
-export type TypedChartData<CT extends SupportedChartType> = CT extends 'areamap' ? AreamapData : CT extends 'scattermap' ? ScattermapChartData : CT extends 'pie' | 'funnel' | 'treemap' | 'sunburst' ? CategoricalChartData : CT extends 'column' | 'bar' | 'line' | 'area' | 'polar' | 'streamgraph' ? CartesianChartData : CT extends 'calendar-heatmap' ? CalendarHeatmapChartData : CT extends 'sankey' ? SankeyChartData : never;
+export type TypedChartData<CT extends SupportedChartType> = CT extends 'areamap' ? AreamapData : CT extends 'scattermap' ? ScattermapChartData : CT extends 'pie' | 'funnel' | 'treemap' | 'sunburst' ? CategoricalChartData : CT extends 'column' | 'bar' | 'line' | 'area' | 'polar' | 'streamgraph' ? CartesianChartData : CT extends 'calendar-heatmap' ? CalendarHeatmapChartData : CT extends 'sankey' ? SankeyChartData : CT extends 'kpi' ? KpiChartData : never;
 export type TypedLoadDataFunction<CT extends SupportedChartType> = (options: {
     app: ClientApplication;
     chartDataOptionsInternal: TypedDataOptionsInternal<CT>;
     queryDescription: QueryDescription;
     executionConfig?: QueryExecutionConfig;
 }) => Promise<QueryResultData>;
-export type TypedChartRendererProps<CT extends SupportedChartType> = CT extends 'areamap' ? AreamapProps : CT extends 'scattermap' ? ScattermapProps : CT extends 'column' | 'bar' | 'line' | 'area' | 'polar' | 'pie' | 'funnel' | 'calendar-heatmap' | 'treemap' | 'sunburst' | 'streamgraph' | 'sankey' ? HighchartsBasedChartRendererProps<CT> : never;
+export type TypedChartRendererProps<CT extends SupportedChartType> = CT extends 'areamap' ? AreamapProps : CT extends 'scattermap' ? ScattermapProps : CT extends 'column' | 'bar' | 'line' | 'area' | 'polar' | 'pie' | 'funnel' | 'calendar-heatmap' | 'treemap' | 'sunburst' | 'streamgraph' | 'sankey' ? HighchartsBasedChartRendererProps<CT> : CT extends 'kpi' ? KpiChartRendererProps : never;
+/**
+ * State signals passed to a chart's {@link ChartBuilder.onReady} readiness
+ * predicate to compute rising-edge readiness for the consumer `onReady`
+ * callback (Fusion `domready` / PDF).
+ *
+ * @internal
+ */
+export type ChartOnReadyStateInput = {
+    /** Whether a query / data sync is in progress. */
+    isLoading: boolean;
+    /**
+     * Whether the active renderer has signaled paint for the current cycle
+     * (`ChartRendererProps.onReady`, e.g. Highcharts `chart.events.load` /
+     * `render`).
+     */
+    rendererPainted: boolean;
+    /** Whether data options have no attributes or measures. */
+    hasNoDimensions: boolean;
+    /** Prepared chart data, or `null` while unavailable. */
+    chartData: ChartData | null;
+};
 /**
  * Chart builder interface.
  */
@@ -107,4 +130,19 @@ export interface ChartBuilder<CT extends SupportedChartType = SupportedChartType
          */
         isCorrectRendererProps: (props: ChartRendererProps) => props is TypedChartRendererProps<CT>;
     };
+    /**
+     * Optional consumer `onReady` (Fusion `domready` / PDF) readiness contract.
+     *
+     * When present, RegularChart wires the renderer's paint signal
+     * (`ChartRendererProps.onReady`) into this predicate and fires the consumer
+     * `onReady` callback on each rising edge of readiness. Chart types that omit
+     * this field do not participate in the `onReady` contract.
+     */
+    onReady?: {
+        /**
+         * Computes whether the consumer `onReady` callback should fire for the
+         * current cycle, given the loading, paint, and data signals.
+         */
+        isReadyForOnReady: (state: ChartOnReadyStateInput) => boolean;
+    };
 }

package/dist/packages/sdk-ui/src/domains/visualizations/components/chart/types.d.ts

@@ -19,4 +19,13 @@ export type ChartRendererProps = {
     onDataPointContextMenu?: ChartProps['onDataPointContextMenu'];
     onDataPointsSelected?: ChartProps['onDataPointsSelected'];
     onBeforeRender?: ChartProps['onBeforeRender'];
+    /**
+     * Paint signal from the active renderer after it finishes painting.
+     * Used for Sankey `onReady` (Fusion `domready`): RegularChart stores the
+     * flag and fires the consumer callback via `useFireOnReady`. Highcharts
+     * wires this to `chart.events.load` / `render`.
+     *
+     * @internal
+     */
+    onReady?: ChartProps['onReady'];
 };

package/dist/packages/sdk-ui/src/domains/visualizations/components/kpi-chart.d.ts

@@ -0,0 +1,23 @@
+/// <reference types="react" />
+import { KpiChartProps } from '../../../props';
+/**
+ * A React component that displays a KPI card: primary value with an optional
+ * sparkline trend and a comparison readout — previous period, another measure,
+ * or a target.
+ *
+ * @example
+ * ```tsx
+ * <KpiChart
+ *   dataSet={DM.DataSource}
+ *   dataOptions={{
+ *     value: measureFactory.sum(DM.Commerce.Revenue),
+ *     trend: DM.Commerce.Date.Months,
+ *   }}
+ * />
+ * ```
+ * @param props - KPI chart properties
+ * @returns KPI Chart component
+ * @group Charts
+ * @beta
+ */
+export declare const KpiChart: import("react").FunctionComponent<KpiChartProps>;

package/dist/packages/sdk-ui/src/domains/visualizations/core/apply-on-ready-to-highcharts-options.d.ts

@@ -0,0 +1,11 @@
+import { HighchartsOptionsInternal } from './chart-options-processor/chart-options-service.js';
+/**
+ * Wraps `chart.events.load` / `render` so `onReady` fires after Highcharts paints,
+ * while preserving any existing handlers.
+ *
+ * @param options - Highcharts options to augment.
+ * @param onReady - Callback invoked after each preserved load/render handler.
+ * @returns Options with load/render handlers that also call `onReady`.
+ * @internal
+ */
+export declare function applyOnReadyToHighchartsOptions(options: HighchartsOptionsInternal, onReady: () => void): HighchartsOptionsInternal;

package/dist/packages/sdk-ui/src/domains/visualizations/core/chart-data/types.d.ts

@@ -2,6 +2,7 @@ import { Coordinates } from '../../../../domains/visualizations/components/chart
 import { AreamapData } from '../../../../domains/visualizations/components/chart/restructured-charts/areamap-chart/types';
 import { CalendarHeatmapChartData } from '../../../../domains/visualizations/components/chart/restructured-charts/highchart-based-charts/calendar-heatmap-chart/data';
 import { SankeyChartData } from '../../../../domains/visualizations/components/chart/restructured-charts/highchart-based-charts/sankey-chart/types';
+import { KpiChartData } from '../../../../domains/visualizations/components/chart/restructured-charts/kpi-chart/types';
 import { ComparableData, Value } from '../../../../domains/visualizations/core/chart-data-processor/table-processor';
 import { IndicatorChartType } from '../../../../domains/visualizations/core/chart-options-processor/translations/types';
 import { NumberFormatConfig } from '../../../../types';
@@ -142,5 +143,5 @@ export type BoxplotChartData = {
  *
  * @internal
  */
-export type ChartData = CartesianChartData | CategoricalChartData | ScatterChartData | IndicatorChartData | BoxplotChartData | AreamapData | ScattermapChartData | RangeChartData | CalendarHeatmapChartData | SankeyChartData;
+export type ChartData = CartesianChartData | CategoricalChartData | ScatterChartData | IndicatorChartData | BoxplotChartData | AreamapData | ScattermapChartData | RangeChartData | CalendarHeatmapChartData | SankeyChartData | KpiChartData;
 export {};

package/dist/packages/sdk-ui/src/domains/visualizations/core/chart-data-options/types.d.ts

@@ -570,7 +570,7 @@ export type CommonDataOptions = ChartDataOptions | PivotTableDataOptions | Gener
 /**
  * Configuration for how to query aggregate data and assigning data to chart encodings of regular charts.
  */
-export type RegularChartDataOptions = CartesianChartDataOptions | CategoricalChartDataOptions | ScatterChartDataOptions | IndicatorChartDataOptions | BoxplotChartDataOptions | BoxplotChartCustomDataOptions | AreamapChartDataOptions | ScattermapChartDataOptions | RangeChartDataOptions | CalendarHeatmapChartDataOptions | SankeyChartDataOptions;
+export type RegularChartDataOptions = CartesianChartDataOptions | CategoricalChartDataOptions | ScatterChartDataOptions | IndicatorChartDataOptions | BoxplotChartDataOptions | BoxplotChartCustomDataOptions | AreamapChartDataOptions | ScattermapChartDataOptions | RangeChartDataOptions | CalendarHeatmapChartDataOptions | SankeyChartDataOptions | KpiChartDataOptions;
 /** @internal */
 export interface CartesianChartDataOptionsInternal {
     x: StyledColumn[];
@@ -644,7 +644,7 @@ export interface PivotTableDataOptionsInternal {
     grandTotals?: PivotGrandTotals;
 }
 /** @internal */
-export type ChartDataOptionsInternal = CartesianChartDataOptionsInternal | CategoricalChartDataOptionsInternal | ScatterChartDataOptionsInternal | IndicatorChartDataOptionsInternal | BoxplotChartDataOptionsInternal | AreamapChartDataOptionsInternal | ScattermapChartDataOptionsInternal | RangeChartDataOptionsInternal | CalendarHeatmapChartDataOptionsInternal | SankeyChartDataOptionsInternal;
+export type ChartDataOptionsInternal = CartesianChartDataOptionsInternal | CategoricalChartDataOptionsInternal | ScatterChartDataOptionsInternal | IndicatorChartDataOptionsInternal | BoxplotChartDataOptionsInternal | AreamapChartDataOptionsInternal | ScattermapChartDataOptionsInternal | RangeChartDataOptionsInternal | CalendarHeatmapChartDataOptionsInternal | SankeyChartDataOptionsInternal | KpiChartDataOptionsInternal;
 /** @internal */
 export type IndicatorChartDataOptionsInternal = {
     value?: StyledMeasureColumn[];
@@ -714,3 +714,109 @@ export type SankeyChartDataOptionsInternal = {
     value: StyledMeasureColumn;
     seriesToColorMap?: ValueToColorMap | MultiColumnValueToColorMap;
 };
+/**
+ * Which number becomes the KPI headline when {@link KpiChartDataOptions.trend} is set.
+ * 'last' — the last date bucket; 'total' — aggregate over the whole period
+ * (computed by a separate ungrouped query — correct SQL semantics).
+ *
+ * @beta
+ */
+export type KpiValueMode = 'last' | 'total';
+/**
+ * What the KPI headline value is compared against.
+ * Each variant carries its own baseline, so invalid combinations are unrepresentable.
+ *
+ * @beta
+ */
+export type KpiComparison = 
+/** Compares the last trend bucket against the previous one. Requires `trend`. */
+{
+    type: 'previous-period';
+}
+/** Compares against a second measure: delta and percent change, up/down arrow. */
+ | {
+    type: 'delta';
+    value: MeasureColumn | CalculatedMeasureColumn | StyledMeasureColumn;
+}
+/** Treats the baseline as a goal: “82% of goal, $12K to go”. Fixed number or measure. */
+ | {
+    type: 'target';
+    target: MeasureColumn | CalculatedMeasureColumn | StyledMeasureColumn | number;
+}
+/** Shows a plain second value next to the headline; no delta, no coloring. */
+ | {
+    type: 'value';
+    value: MeasureColumn | CalculatedMeasureColumn | StyledMeasureColumn;
+};
+/**
+ * Configuration for how to query aggregate data and assign data to a
+ * {@link KpiChartType | KPI chart}.
+ *
+ * @beta
+ *
+ * @example
+ * ```tsx
+ * <KpiChart
+ *   dataSet={DM.DataSource}
+ *   dataOptions={{
+ *     value: measureFactory.sum(DM.Commerce.Revenue),
+ *     trend: DM.Commerce.Date.Months,
+ *     comparison: { type: 'previous-period' },
+ *   }}
+ * />
+ * ```
+ */
+export interface KpiChartDataOptions {
+    /** Primary measure — the headline KPI value. Conditional coloring via `color` on the styled measure. */
+    value: MeasureColumn | CalculatedMeasureColumn | StyledMeasureColumn;
+    /**
+     * Sets the card's trend axis (typically a date dimension): enables the sparkline, the
+     * current-period caption, the 'previous-period' comparison, and the `valueMode` semantics.
+     * Granularity comes from the column.
+     *
+     * @example
+     * ```ts
+     * trend: DM.Commerce.Date.Months
+     * ```
+     */
+    trend?: Column | StyledColumn;
+    /**
+     * Selects which number is the headline when `trend` is set.
+     *
+     * @example
+     * ```ts
+     * valueMode: 'total' // aggregate over the whole period instead of the last trend bucket
+     * ```
+     * @defaultValue 'last'
+     */
+    valueMode?: KpiValueMode;
+    /**
+     * Configures what the headline is compared against.
+     *
+     * @example
+     * ```ts
+     * comparison: { type: 'target', target: 10000 }
+     * ```
+     */
+    comparison?: KpiComparison;
+}
+/** @internal */
+export type KpiComparisonInternal = {
+    type: 'previous-period';
+} | {
+    type: 'delta';
+    value: StyledMeasureColumn;
+} | {
+    type: 'target';
+    target: StyledMeasureColumn | number;
+} | {
+    type: 'value';
+    value: StyledMeasureColumn;
+};
+/** @internal */
+export type KpiChartDataOptionsInternal = {
+    value: StyledMeasureColumn;
+    trend?: StyledColumn;
+    valueMode: KpiValueMode;
+    comparison?: KpiComparisonInternal;
+};

package/dist/packages/sdk-ui/src/domains/visualizations/core/chart-options-processor/chart-options-service.d.ts

@@ -175,6 +175,7 @@ export type HighchartsOptionsInternal = {
         renderTo?: string;
         events?: {
             load?: () => void;
+            render?: () => void;
             redraw?: () => void;
             selection?: (nativeEvent: HighchartsSelectEvent) => void;
         };

package/dist/packages/sdk-ui/src/domains/visualizations/core/chart-options-processor/translations/design-options.d.ts

@@ -1,5 +1,6 @@
 import { CalendarDayOfWeek } from '../../../../../domains/visualizations/components/chart/restructured-charts/highchart-based-charts/calendar-heatmap-chart/utils';
-import { CalendarHeatmapSubtype, CalendarHeatmapViewType, Convolution, FunnelSeriesLabels, LegendOptions, LineOptions, PieSeriesLabels, SankeyStyleOptions, ScattermapMarkers, SeriesLabels, SunburstStyleOptions, TotalLabels, TreemapStyleOptions } from '../../../../../types';
+import { CalendarHeatmapSubtype, CalendarHeatmapViewType, Convolution, FunnelSeriesLabels, KpiIconCondition, LegendOptions, LineOptions, PieSeriesLabels, SankeyStyleOptions, ScattermapMarkers, SeriesLabels, SunburstStyleOptions, TotalLabels, TreemapStyleOptions } from '../../../../../types';
+import { DataColorOptions } from '../../chart-data/data-coloring';
 import { Axis } from './axis-section';
 import { FunnelDirection, FunnelSize, FunnelType } from './funnel-plot-options';
 import { Marker } from './marker-section';
@@ -83,6 +84,44 @@ export type CalendarHeatmapChartDesignOptions = BaseDesignOptionsType & {
         startMonth?: Date;
     };
 };
+/**
+ * Resolved, internal-use design options for a KPI chart -- the translated form of
+ * {@link KpiStyleOptions} (see `translateKpiStyleOptionsToDesignOptions`), consumed directly by
+ * `KpiChartRenderer`.
+ * @internal
+ */
+export type KpiChartDesignOptions = BaseDesignOptionsType & {
+    width?: number;
+    height?: number;
+    layout: 'standard' | 'big-comparison';
+    value: {
+        /** `'auto'` for auto-fit sizing, or a fixed font size in px. */
+        textSize: 'auto' | number;
+        noDataText?: string;
+        conditionalIcons?: KpiIconCondition[];
+    };
+    title: {
+        enabled: boolean;
+        text?: string;
+    };
+    card: {
+        backgroundColor?: string;
+        textAlign: 'left' | 'center' | 'right';
+        showBorder: boolean;
+        cornerRadius: number;
+    };
+    sparkline: {
+        enabled: boolean;
+        chartType: 'line' | 'spline' | 'area' | 'column';
+    };
+    comparison: {
+        display: 'percent' | 'value' | 'both';
+        label?: string;
+        color?: DataColorOptions;
+        showIcon: boolean;
+        conditionalIcons?: KpiIconCondition[];
+    };
+};
 export type PolarType = 'line' | 'area' | 'column';
 export type PolarChartDesignOptions = CartesianChartDesignOptions & {
     polarType: PolarType;
@@ -110,6 +149,7 @@ export type SankeyChartDesignOptions = BaseDesignOptionsType & {
     linkOpacity?: SankeyStyleOptions['linkOpacity'];
     nodeWidth?: SankeyStyleOptions['nodeWidth'];
     nodePadding?: SankeyStyleOptions['nodePadding'];
+    minLinkWidth?: SankeyStyleOptions['minLinkWidth'];
     nodeAlignment?: SankeyStyleOptions['nodeAlignment'];
 };
 export type ScatterChartDesignOptions = BaseDesignOptionsType & {

package/dist/packages/sdk-ui/src/domains/visualizations/core/chart-options-processor/translations/types.d.ts

@@ -1,7 +1,7 @@
 import { AreamapChartDesignOptions } from '../../../../../domains/visualizations/components/chart/restructured-charts/areamap-chart/types';
 import { StreamgraphChartDesignOptions } from '../../../../../domains/visualizations/components/chart/restructured-charts/highchart-based-charts/cartesians/stackable/streamgraph-chart/types';
 import { ChartType } from '../../../../../types';
-import { AreaChartDesignOptions, AreaRangeChartDesignOptions, BarChartDesignOptions, BaseDesignOptionsType, BoxplotChartDesignOptions, CalendarHeatmapChartDesignOptions, ColumnChartDesignOptions, FunnelChartDesignOptions, IndicatorChartDesignOptions, LineChartDesignOptions, PieChartDesignOptions, PolarChartDesignOptions, SankeyChartDesignOptions, ScatterChartDesignOptions, ScattermapChartDesignOptions, SunburstChartDesignOptions, TreemapChartDesignOptions } from './design-options';
+import { AreaChartDesignOptions, AreaRangeChartDesignOptions, BarChartDesignOptions, BaseDesignOptionsType, BoxplotChartDesignOptions, CalendarHeatmapChartDesignOptions, ColumnChartDesignOptions, FunnelChartDesignOptions, IndicatorChartDesignOptions, KpiChartDesignOptions, LineChartDesignOptions, PieChartDesignOptions, PolarChartDesignOptions, SankeyChartDesignOptions, ScatterChartDesignOptions, ScattermapChartDesignOptions, SunburstChartDesignOptions, TreemapChartDesignOptions } from './design-options';
 /**
  * Style configuration for text elements in charts and UI components.
  * Defines the visual appearance and behavior of text rendering.
@@ -81,6 +81,20 @@ export type ImageChartType = (typeof IMAGE_CHART_TYPES)[number];
 export declare const SCATTERMAP_CHART_TYPES: readonly ["scattermap"];
 /** Scattermap chart types  @expandType */
 export type ScattermapChartType = (typeof SCATTERMAP_CHART_TYPES)[number];
+/** Chart type strings recognized as KPI charts. @internal */
+export declare const KPI_CHART_TYPES: readonly ["kpi"];
+/**
+ * KPI chart types.
+ *
+ * @expandType
+ * @beta
+ */
+export type KpiChartType = (typeof KPI_CHART_TYPES)[number];
+/**
+ * Checks whether the given chart type is a {@link KpiChartType}.
+ * @internal
+ */
+export declare const isKpi: (chartType: ChartType) => chartType is "kpi";
 export declare const CALENDAR_HEATMAP_CHART_TYPES: readonly ["calendar-heatmap"];
 /**
  * Calendar heatmap chart types
@@ -103,7 +117,7 @@ export type ChartDataType = 'cartesian' | 'categorical' | 'scatter' | 'table' |
 /**
  * Design options for a specific chart type
  */
-export type DesignOptions<SpecificChartType extends ChartType = ChartType> = SpecificChartType extends 'line' ? LineChartDesignOptions : SpecificChartType extends 'area' ? AreaChartDesignOptions : SpecificChartType extends 'bar' ? BarChartDesignOptions : SpecificChartType extends 'column' ? ColumnChartDesignOptions : SpecificChartType extends 'streamgraph' ? StreamgraphChartDesignOptions : SpecificChartType extends 'pie' ? PieChartDesignOptions : SpecificChartType extends 'funnel' ? FunnelChartDesignOptions : SpecificChartType extends 'polar' ? PolarChartDesignOptions : SpecificChartType extends 'indicator' ? IndicatorChartDesignOptions : SpecificChartType extends 'scatter' ? ScatterChartDesignOptions : SpecificChartType extends 'treemap' ? TreemapChartDesignOptions : SpecificChartType extends 'sunburst' ? SunburstChartDesignOptions : SpecificChartType extends 'boxplot' ? BoxplotChartDesignOptions : SpecificChartType extends 'areamap' ? AreamapChartDesignOptions : SpecificChartType extends 'scattermap' ? ScattermapChartDesignOptions : SpecificChartType extends 'calendar-heatmap' ? CalendarHeatmapChartDesignOptions : SpecificChartType extends 'arearange' ? AreaRangeChartDesignOptions : SpecificChartType extends 'sankey' ? SankeyChartDesignOptions : never;
+export type DesignOptions<SpecificChartType extends ChartType = ChartType> = SpecificChartType extends 'line' ? LineChartDesignOptions : SpecificChartType extends 'area' ? AreaChartDesignOptions : SpecificChartType extends 'bar' ? BarChartDesignOptions : SpecificChartType extends 'column' ? ColumnChartDesignOptions : SpecificChartType extends 'streamgraph' ? StreamgraphChartDesignOptions : SpecificChartType extends 'pie' ? PieChartDesignOptions : SpecificChartType extends 'funnel' ? FunnelChartDesignOptions : SpecificChartType extends 'polar' ? PolarChartDesignOptions : SpecificChartType extends 'indicator' ? IndicatorChartDesignOptions : SpecificChartType extends 'scatter' ? ScatterChartDesignOptions : SpecificChartType extends 'treemap' ? TreemapChartDesignOptions : SpecificChartType extends 'sunburst' ? SunburstChartDesignOptions : SpecificChartType extends 'boxplot' ? BoxplotChartDesignOptions : SpecificChartType extends 'areamap' ? AreamapChartDesignOptions : SpecificChartType extends 'scattermap' ? ScattermapChartDesignOptions : SpecificChartType extends 'calendar-heatmap' ? CalendarHeatmapChartDesignOptions : SpecificChartType extends 'kpi' ? KpiChartDesignOptions : SpecificChartType extends 'arearange' ? AreaRangeChartDesignOptions : SpecificChartType extends 'sankey' ? SankeyChartDesignOptions : never;
 /** A unique identifier for a series to be found in {@link ChartDataOptionsInternal} */
 type SeriesId = string;
 /**
@@ -132,6 +146,6 @@ export declare const isAreamap: (chartType: ChartType) => chartType is "areamap"
 export declare const isRange: (chartType: ChartType) => chartType is "arearange";
 export declare const isCalendarHeatmap: (chartType: ChartType) => chartType is "calendar-heatmap";
 export declare const isSankey: (chartType: ChartType) => chartType is "sankey";
-export declare const ALL_CHART_TYPES: readonly ["line", "area", "bar", "column", "streamgraph", "polar", "pie", "funnel", "treemap", "sunburst", "scatter", "table", "indicator", "boxplot", "areamap", "image", "scattermap", "calendar-heatmap", "arearange", "sankey"];
+export declare const ALL_CHART_TYPES: readonly ["line", "area", "bar", "column", "streamgraph", "polar", "pie", "funnel", "treemap", "sunburst", "scatter", "table", "indicator", "boxplot", "areamap", "image", "scattermap", "calendar-heatmap", "kpi", "arearange", "sankey"];
 export type DynamicChartType = (typeof ALL_CHART_TYPES)[number];
 export {};

package/dist/packages/sdk-ui/src/domains/visualizations/core/highcharts-renderer.d.ts

@@ -1,6 +1,12 @@
 import { HighchartsOptionsInternal } from './chart-options-processor/chart-options-service';
 type HighchartsRendererProps = {
     options: HighchartsOptionsInternal;
+    /**
+     * Invoked after Highcharts paints the chart (`chart.events.load` and
+     * subsequent `chart.events.render`). Existing load/render handlers on
+     * `options` are preserved and called first.
+     */
+    onReady?: () => void;
 };
 /**
  * Renders a Highcharts chart with optimized behavior
@@ -9,5 +15,5 @@ type HighchartsRendererProps = {
  * by detecting key changes that require chart re-initialization.
  * It also handles cases where Highcharts mutates input options by making deep clone.
  */
-export declare const HighchartsRenderer: ({ options }: HighchartsRendererProps) => import("react/jsx-runtime").JSX.Element;
+export declare const HighchartsRenderer: ({ options, onReady }: HighchartsRendererProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/packages/sdk-ui/src/domains/visualizations/core/query-definition/query-definition-style-constants.d.ts

@@ -12,6 +12,6 @@ export declare const QUERY_DEFINITION_TEXT_STYLE: {
  * @internal
  */
 export declare const QUERY_PILL_LABEL_STYLE: {
-    readonly lineHeight: "17px";
+    readonly lineHeight: "16px";
     readonly fontSize: "13px";
 };

package/dist/packages/sdk-ui/src/domains/widgets/components/chart-widget/types.d.ts

@@ -99,10 +99,9 @@ export interface ChartWidgetProps extends ChartEventProps {
     /**
      * Widget identifier
      *
-     * The optional property which is only meaningful for some internal features (for example Excel export).
+     * Used to identify the widget when exporting its data (for example, the "Download as Excel" action).
      *
      * @category Widget
-     * @internal
      */
     id?: string;
     /**

package/dist/packages/sdk-ui/src/domains/widgets/components/chart-widget/use-chart-widget-excel-download.d.ts

@@ -7,7 +7,7 @@ export type UseChartWidgetExcelDownloadResult = {
     headerConfig: WidgetHeaderConfig;
 };
 /**
- * Enhances a chart widget header with Excel download menu items (placeholder).
+ * Enhances a chart widget header with Excel download menu items.
  * Excel menu is shown only when the widget/dashboard allows download.
  * **Repeat rows** sets `mergeRows: false`; **Merge rows** sets `mergeRows: true`).
  *

package/dist/packages/sdk-ui/src/domains/widgets/components/custom-widget/types.d.ts

@@ -60,10 +60,9 @@ export interface CustomWidgetProps extends CustomWidgetEventProps {
     /**
      * Widget identifier
      *
-     * The optional property which is only meaningful for some internal features (for example Excel export).
+     * Used to identify the widget when exporting its data (for example, the "Download as Excel" action).
      *
      * @category Widget
-     * @internal
      */
     id?: string;
     /**

package/dist/packages/sdk-ui/src/domains/widgets/components/filter-widget/filter-widget-dropdown.d.ts

@@ -13,6 +13,13 @@ type FilterWidgetDropdownProps = Pick<FilterWidgetProps, 'attribute' | 'dataSour
      * channel as a `dateLevel/changed` event (e.g. to sync Fusion widget metadata).
      */
     onDateLevelChange?: (attribute: Attribute) => void;
+    /**
+     * Calls the provided callback on every rising edge of readiness — after member data loads
+     * successfully and the list is ready to display, including after subsequent
+     * reloads (e.g. dimension change, refetch). Used by the host FilterWidget to
+     * surface the `onRender` prop.
+     */
+    onReady?: () => void;
 };
 /**
  * Effective selection mode for the dropdown. The widget and its linked dashboard filter
@@ -23,6 +30,15 @@ type FilterWidgetDropdownProps = Pick<FilterWidgetProps, 'attribute' | 'dataSour
  * @internal
  */
 export declare function getEffectiveMultiselect(widgetMultiselect: boolean, selectedCount: number, filterMultiSelection: boolean | undefined): boolean;
+/**
+ * Reduces a member selection to a single deterministic member (the alphabetically first)
+ * when it holds more than one, for switching a filter from multi- to single-select.
+ *
+ * @param members - Current member selection (treated as immutable).
+ * @returns A newly-allocated array: the single retained member, or a copy of the input.
+ * @internal
+ */
+export declare function asSingleSelectionMembers(members: readonly string[]): string[];
 /**
  * Renders a searchable member-select dropdown using the existing CSDK filter editor select
  * components (SearchableMultiSelect / SearchableSingleSelect).