@sisense/sdk-ui 2.31.1 → 2.32.0

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

@@ -0,0 +1,154 @@
+/// <reference types="react" />
+import { Themable } from '../../../../../../../infra/contexts/theme-provider/types.js';
+/**
+ * Gap between {@link BodyArea}'s two children (value/comparison), in px. Exported so
+ * `kpi-chart-renderer.tsx` can subtract the exact same amount when computing the headline auto-fit
+ * height budget (`bodyHeight - compactSiblingHeight - BODY_GAP_PX`) -- the two must stay in sync,
+ * since a smaller JS-side allowance than the real CSS gap would under-budget (safe, just
+ * conservative) while a larger one would over-budget (risking the exact clipping this fixes).
+ * @internal
+ */
+export declare const BODY_GAP_PX = 4;
+/** Card block padding: start (top) and end (bottom), in px. @internal */
+export declare const CARD_PADDING_BLOCK_START_PX = 14;
+/** @internal */
+export declare const CARD_PADDING_BLOCK_END_PX = 8;
+/** Gap between the card's grid rows (title/body/sparkline), in px. @internal */
+export declare const CARD_ROW_GAP_PX = 4;
+/**
+ * The card's border width when `card.showBorder` is on, in px. `useElementSize` measures via
+ * `getBoundingClientRect` (border-inclusive), so the renderer must subtract this from both
+ * block edges of the figure-derived height budget whenever the border is shown.
+ * @internal
+ */
+export declare const CARD_BORDER_PX = 1;
+/**
+ * The sparkline row's minimum height, in px. With a sparkline present the row is
+ * `minmax(this, 1fr)` -- it absorbs all leftover height below the content group on tall cards,
+ * by design, but never shrinks below this floor.
+ * @internal
+ */
+export declare const SPARKLINE_MIN_HEIGHT_PX = 32;
+/** `ConditionalIconSpan`'s font size relative to its parent text. @internal */
+export declare const CONDITIONAL_ICON_EM = 0.7;
+/** `ConditionalIconSpan`'s margin-inline-end, in px. @internal */
+export declare const CONDITIONAL_ICON_GAP_PX = 6;
+/** `ComparisonArrow`'s font size relative to the comparison primary text. @internal */
+export declare const COMPARISON_ARROW_EM = 0.85;
+/** `ComparisonPrimaryText`'s flex gap between its items, in px. @internal */
+export declare const COMPARISON_PRIMARY_GAP_PX = 3;
+/** The KPI card's root figure element: the grid container laid out by {@link GRID_TEMPLATE}. @internal */
+export declare const CardRoot: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+} & Themable & {
+    $backgroundColor?: string | undefined;
+    $textAlign: 'left' | 'center' | 'right';
+    $showBorder: boolean;
+    $cornerRadius: number;
+    $clickable: boolean;
+    $hasSparkline: boolean;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLElement>, HTMLElement>, {}>;
+/** The card's title row: the title text and, when present, the current-period caption. @internal */
+export declare const TitleArea: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * Groups the headline value and the comparison readout into one tight vertical block, occupying
+ * the grid's flexible `body` row. Its two {@link BodySlot} children are `flex: 0 0 auto` (natural
+ * size, packed at the top with no gap-induced growth between them), so any leftover height in the
+ * (grid-determined, non-content-based) `body` row trails *after* the last child -- i.e. below the
+ * value/comparison pair, immediately before the sparkline -- rather than appearing as dead space
+ * between the title/value/comparison trio.
+ * @internal
+ */
+export declare const BodyArea: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * Wraps one of `BodyArea`'s two children, ordering it per {@link CardLayout} (see `kpi-card.tsx`).
+ * @internal
+ */
+export declare const BodySlot: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+} & {
+    $order: number;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/** Wraps `KpiValue`'s rendered output inside {@link BodyArea}. @internal */
+export declare const ValueArea: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/** Wraps `KpiComparison`'s rendered output inside {@link BodyArea}. @internal */
+export declare const ComparisonArea: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * The card's sparkline row. Hidden from assistive tech by its consumer (`kpi-sparkline.tsx`);
+ * this element itself only owns the grid-area layout.
+ * @internal
+ */
+export declare const SparklineArea: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/** The card's title text, uppercased. @internal */
+export declare const TitleText: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+} & Themable & {
+    $onColor: boolean;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, {}>;
+/** The current-period caption shown next to the title (e.g. `'Jun 2026'`). @internal */
+export declare const PeriodText: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+} & Themable & {
+    $onColor: boolean;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, {}>;
+/** The card's headline value text. @internal */
+export declare const ValueText: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+} & Themable & {
+    $onColor: boolean;
+    $color?: string | undefined;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/** Condition-driven icon rendered next to the headline value or the comparison readout. @internal */
+export declare const ConditionalIconSpan: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+} & {
+    $color?: string | undefined;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, {}>;
+/** The comparison readout's root: row layout when `compact`, column layout otherwise. @internal */
+export declare const ComparisonRoot: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+} & {
+    $compact: boolean;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/** The comparison readout's primary line (e.g. the delta/percent-of-goal text). @internal */
+export declare const ComparisonPrimaryText: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+} & Themable & {
+    $color?: string | undefined;
+    $scale: 'compact' | 'headline';
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/** The comparison readout's secondary line (e.g. the target label or amount-to-go text). @internal */
+export declare const ComparisonSecondaryText: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+} & Themable & {
+    $onColor: boolean;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/** The up/down arrow glyph shown next to a delta-shaped comparison's primary text. @internal */
+export declare const ComparisonArrow: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, {}>;

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

@@ -0,0 +1,41 @@
+import { MouseEvent, ReactNode, RefObject } from 'react';
+import { KpiChartDesignOptions } from '../../../../../../../domains/visualizations/core/chart-options-processor/translations/design-options.js';
+import { KpiSizeTier } from './use-size-tier.js';
+/**
+ * Defines the props of {@link KpiCard}.
+ * @internal
+ */
+export type KpiCardProps = {
+    layout: KpiChartDesignOptions['layout'];
+    tier: KpiSizeTier;
+    ariaLabel: string;
+    card: KpiChartDesignOptions['card'];
+    /**
+     * Whether `onDataPointClick` or `onDataPointContextMenu` is wired up -- drives the pointer
+     * cursor and keyboard focusability, so a context-menu-only card is still reachable by keyboard
+     * even though Enter/Space only actuates a click.
+     */
+    clickable: boolean;
+    onClick?: (event: MouseEvent<HTMLElement>) => void;
+    onContextMenu?: (event: MouseEvent<HTMLElement>) => void;
+    title: ReactNode;
+    value: ReactNode;
+    comparison?: ReactNode;
+    sparkline?: ReactNode;
+    /**
+     * External ref to {@link BodyArea}, so the orchestrator can measure its grid-derived (safe,
+     * non-circular) height budget -- see `kpi-chart-renderer.tsx`'s `useElementSize(bodyRef)`.
+     */
+    bodyRef?: RefObject<HTMLDivElement | null>;
+};
+/**
+ * The KPI card's layout shell: a `<figure role="figure">` grid container that positions the
+ * title/value/comparison/sparkline subcomponents (passed in as already-rendered slots) and owns
+ * the card-level accessibility contract -- the composed `aria-label`, and, when clickable,
+ * keyboard activation (Enter/Space triggers the same native `click` the mouse handler listens
+ * for, via `element.click()`, so both paths share one code path and one correctly-typed
+ * `MouseEvent`). Groups `value`/`comparison` into a single {@link BodyArea} (see its TSDoc for
+ * why), ordered per `layout` via {@link valueOrderFor}/{@link comparisonOrderFor}.
+ * @internal
+ */
+export declare const KpiCard: import("react").ForwardRefExoticComponent<KpiCardProps & import("react").RefAttributes<HTMLElement>>;

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

@@ -0,0 +1,46 @@
+/// <reference types="react" />
+import { ChartRendererProps } from '../../../../../../../domains/visualizations/components/chart/types.js';
+import { KpiChartDataOptionsInternal } from '../../../../../../../domains/visualizations/core/chart-data-options/types.js';
+import { KpiChartDesignOptions } from '../../../../../../../domains/visualizations/core/chart-options-processor/translations/design-options.js';
+import { KpiChartData } from '../types.js';
+/**
+ * Props accepted by the KPI chart renderer.
+ *
+ * NOTE: the event-handler fields are intentionally typed as the generic
+ * `ChartRendererProps` handler unions (rather than the narrower
+ * `KpiDataPointEventHandler` / `KpiBeforeRenderHandler` from `@/types.js`).
+ * `ChartProps`/`ChartEventProps` in `src/props.tsx` do carry KPI variants
+ * (added as part of the public KPI surface), but they're only one member of
+ * a larger union of per-chart-type handler signatures with incompatible
+ * point-argument shapes (e.g. `DataPoint`, `ScatterDataPoint`,
+ * `IndicatorDataPoint`, ...). Narrowing `KpiChartRendererProps` to the KPI
+ * handler types directly would make it unassignable to `ChartRendererProps`,
+ * which breaks the `isCorrectRendererProps` type predicate used by
+ * `ChartBuilder<'kpi'>`, so this component narrows internally instead (see
+ * the cast below).
+ * @internal
+ */
+export type KpiChartRendererProps = {
+    chartData: KpiChartData;
+    dataOptions: KpiChartDataOptionsInternal;
+    designOptions: KpiChartDesignOptions;
+    onDataPointClick?: ChartRendererProps['onDataPointClick'];
+    onDataPointContextMenu?: ChartRendererProps['onDataPointContextMenu'];
+    onBeforeRender?: ChartRendererProps['onBeforeRender'];
+};
+/**
+ * KPI chart renderer.
+ *
+ * Composes the card shell ({@link KpiCard}) with its four subcomponents ({@link KpiTitle},
+ * {@link KpiValue}, {@link KpiComparison}, {@link KpiSparkline}), and owns everything that
+ * doesn't belong to a single subcomponent: the `onBeforeRender` pipeline, the no-data/no-results
+ * branch, size-tier-driven degradation, and the click/context-menu handlers.
+ * @internal
+ */
+export declare const KpiChartRenderer: React.FC<KpiChartRendererProps>;
+/**
+ * Checks whether the given generic chart renderer props are shaped as
+ * {@link KpiChartRendererProps}, narrowing on `chartData`, `dataOptions`, and `designOptions`.
+ * @internal
+ */
+export declare const isKpiChartRendererProps: (props: ChartRendererProps) => props is KpiChartRendererProps;

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

@@ -0,0 +1,60 @@
+import { RefObject } from 'react';
+import type { KpiIconCondition, NumberFormatConfig } from '../../../../../../../types.js';
+import { KpiComparisonDisplay } from './helpers.js';
+/**
+ * Defines the props of {@link KpiComparison}.
+ * @internal
+ */
+export type KpiComparisonProps = {
+    comparison: KpiComparisonDisplay;
+    /** Pre-resolved display color (via `resolveComparisonColor` for delta/target, or the data-driven color for `'value'`). */
+    color?: string;
+    /** Format config for the comparison's own numbers -- the `'value'` measure's format, or the headline's. */
+    numberFormatConfig?: NumberFormatConfig;
+    display: 'percent' | 'value' | 'both';
+    showIcon: boolean;
+    /**
+     * First matching condition-driven icon for the comparison readout, if any -- resolved by the
+     * renderer against the same metric the comparison color conditions evaluate (`deltaPercent` /
+     * `percentOfTarget`); mirrors the headline's `KpiValueProps.icon`.
+     */
+    conditionalIcon?: KpiIconCondition;
+    /** `designOptions.comparison.label` -- overrides the data-driven label when set. */
+    labelOverride?: string;
+    /**
+     * `'headline'` in the `'big-comparison'` layout, where the comparison takes over the headline
+     * role -- reading big and participating in auto-fit sizing exactly like the value does in the
+     * `'standard'` layout (mirrors `KpiValueProps.scale`). `'compact'` (the `'standard'` layout's
+     * default) keeps the fixed small readout.
+     */
+    scale: 'headline' | 'compact';
+    /**
+     * Collapses the two-line readout (value + label) onto a single line at the `'sm'`/`'xs'` tiers.
+     * Only honored at the `'compact'` scale: a `'headline'`-scale readout always stacks its label
+     * on its own line below the headline, so the label never competes with the auto-fitted
+     * headline for width.
+     */
+    compact: boolean;
+    onColor: boolean;
+    /**
+     * Non-circular height budget for the `'headline'` auto-fit computation, forwarded to
+     * {@link useAutoFitFontSize}'s `maxHeightPxOverride`. Required whenever `scale` is `'headline'`
+     * -- see `KpiValueProps.maxHeightPx`'s TSDoc for why `ComparisonArea`'s own box isn't a safe
+     * self-measurement target.
+     */
+    maxHeightPx?: number;
+    /**
+     * External ref to `ComparisonArea`, so the orchestrator can measure it (e.g. as the *other*
+     * sibling's height budget input when this component plays the `'compact'` role). Falls back to
+     * an internal ref when not supplied.
+     */
+    areaRef?: RefObject<HTMLDivElement | null>;
+};
+/**
+ * Renders the KPI card's comparison readout. Switches on {@link KpiComparisonDisplay}'s `type`:
+ * - `'previous-period'` / `'delta'`: an arrow plus the delta/percent (per `display`).
+ * - `'target'`: `'82% of goal'` + `'$250K to go'` (percent sign baked into the interpolation).
+ * - `'value'`: the label plus the comparison's own formatted number.
+ * @internal
+ */
+export declare function KpiComparison({ comparison, color, numberFormatConfig, display, showIcon, conditionalIcon, labelOverride, scale, compact, onColor, maxHeightPx, areaRef, }: KpiComparisonProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,23 @@
+import type { NumberFormatConfig } from '../../../../../../../types.js';
+import { SparklineChartType, SparklinePoint } from './sparkline-options.js';
+/**
+ * Defines the props of {@link KpiSparkline}.
+ * @internal
+ */
+export type KpiSparklineProps = {
+    points: SparklinePoint[];
+    chartType: SparklineChartType;
+    color: string;
+    numberFormatConfig?: NumberFormatConfig;
+};
+/**
+ * Renders the KPI card's inline sparkline. Hidden from assistive tech (`aria-hidden`) since it's
+ * a decorative echo of data already conveyed by the headline value and comparison readout.
+ *
+ * The chart is given an explicit `chart.width`/`chart.height` measured from its own cell (via
+ * {@link useElementSize}'s `ResizeObserver`), re-applied whenever the cell resizes -- see
+ * {@link buildSparklineOptions}'s `size` param for why this is needed instead of relying on
+ * Highcharts' own container auto-detection.
+ * @internal
+ */
+export declare function KpiSparkline({ points, chartType, color, numberFormatConfig }: KpiSparklineProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,28 @@
+import { RefObject } from 'react';
+/**
+ * Defines the props of {@link KpiTitle}.
+ * @internal
+ */
+export type KpiTitleProps = {
+    /** Title text -- the design option override, or the value measure's own title. */
+    title: string;
+    /** Whether the title text is shown at all (`designOptions.title.enabled`). */
+    enabled: boolean;
+    /** Formatted current-period caption (e.g. `'Jun 2026'`), shown when the headline is a single bucket. */
+    period?: string;
+    /** Whether the card has a custom background, so text needs to contrast against it instead of the theme. */
+    onColor: boolean;
+    /**
+     * External ref to `TitleArea`, so the orchestrator can measure its height as an input to the
+     * headline auto-fit budget on sparkline cards (see `kpi-chart-renderer.tsx`). Stays unattached
+     * when the component renders nothing -- an absent title measures as zero, which is exactly
+     * what the budget arithmetic expects.
+     */
+    areaRef?: RefObject<HTMLDivElement | null>;
+};
+/**
+ * Renders the KPI card's header: the title text and, when present, the current-period caption.
+ * Renders nothing when there's neither a title to show nor a period caption.
+ * @internal
+ */
+export declare function KpiTitle({ title, enabled, period, onColor, areaRef }: KpiTitleProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,55 @@
+import { RefObject } from 'react';
+import type { KpiIconCondition, KpiTextSize } from '../../../../../../../types.js';
+/**
+ * Auto-fit corridor for whichever of value/comparison currently plays the "headline" role.
+ * Exported so `kpi-comparison.tsx` uses the exact same range when it plays that role instead
+ * (`layout: 'big-comparison'`), keeping the two visually interchangeable.
+ * @internal
+ */
+export declare const AUTO_FIT_MIN_PX = 16;
+/** @internal */
+export declare const AUTO_FIT_MAX_PX = 64;
+/**
+ * Defines the props of {@link KpiValue}.
+ * @internal
+ */
+export type KpiValueProps = {
+    /** Already-formatted display text (the formatted value, or `designOptions.value.noDataText`). */
+    text: string;
+    /** Resolved display color: the measure's data-driven color (or an `onBeforeRender` override). */
+    color?: string;
+    /** `'auto'` for auto-fit sizing, or a fixed font size in px. */
+    textSize: KpiTextSize;
+    /** First matching conditional icon for the value, if any. */
+    icon?: KpiIconCondition;
+    onColor: boolean;
+    /**
+     * `'headline'` in the `'standard'` layout, where the value reads big and participates in
+     * auto-fit sizing; `'compact'` in `'big-comparison'`, where the comparison takes the headline
+     * role instead and the value renders small (mirrors `KpiComparisonProps.scale`). Only affects
+     * sizing when `textSize` is `'auto'` -- an explicit fixed `textSize` always wins.
+     */
+    scale: 'headline' | 'compact';
+    /**
+     * Non-circular height budget for the `'headline'` auto-fit computation, forwarded to
+     * {@link useAutoFitFontSize}'s `maxHeightPxOverride`. Required whenever `scale` is
+     * `'headline'`, since `ValueArea`'s own box is `flex: 0 0 auto` (content-sized) inside
+     * `BodyArea`, not a safe self-measurement target -- see that hook's TSDoc for why.
+     */
+    maxHeightPx?: number;
+    /**
+     * External ref to `ValueArea`, so the orchestrator can measure it (e.g. as the *other*
+     * sibling's height budget input when this component plays the `'compact'` role). Falls back to
+     * an internal ref when not supplied.
+     */
+    areaRef?: RefObject<HTMLDivElement | null>;
+};
+/**
+ * Renders the KPI card's headline value, auto-fitting its font size to the available box when
+ * `textSize` is `'auto'` and `scale` is `'headline'`. A conditional icon shares the value's
+ * nowrap box, so it's budgeted into the fit as an {@link AutoFitAffix} (its glyph is em-scaled
+ * with the fitted font; its margin is fixed px) -- otherwise the icon's width would push the
+ * text into `text-overflow: ellipsis` at exactly the size the fit claimed was safe.
+ * @internal
+ */
+export declare function KpiValue({ text, color, textSize, icon, onColor, scale, maxHeightPx, areaRef, }: KpiValueProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,70 @@
+/**
+ * Relative luminance (0 = black, 1 = white) below which a background color is treated as dark
+ * enough that the card's headline text and sparkline should switch to white for contrast.
+ * 0.179 is the WCAG crossover point: white text has a higher contrast ratio than black text
+ * exactly when the background's relative luminance L satisfies `(1.05) / (L + 0.05) >
+ * (L + 0.05) / 0.05`, i.e. below `sqrt(1.05 * 0.05) - 0.05 ~= 0.179`. Mid-gray backgrounds
+ * (e.g. `#999999`, luminance ~0.32) therefore keep dark text instead of forcing white at a
+ * failing ~2.85:1 ratio.
+ * @internal
+ */
+export declare const DARK_BACKGROUND_LUMINANCE_THRESHOLD = 0.179;
+/** A color's channels, each 0-255 except `a`, which is 0-1. */
+type Rgba = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+/**
+ * Parses a hex color string (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`) into its channels, or
+ * `undefined` when `color` doesn't match a hex color at all (named colors like `'green'`,
+ * functional notations like `rgb()`/`hsl()`, or an empty/missing value).
+ * @internal
+ */
+export declare function parseHexColor(color: string | undefined): Rgba | undefined;
+/**
+ * Computes the WCAG relative luminance of a hex color string (0 = black, 1 = white), or
+ * `undefined` when the color can't be parsed as hex, or is mostly transparent (alpha below 0.5)
+ * -- a mostly-transparent background shows whatever is behind the card, so there's no reliable
+ * color to measure contrast against.
+ * @internal
+ */
+export declare function relativeLuminance(color: string | undefined): number | undefined;
+/**
+ * Whether the card's headline text and sparkline should render in white for contrast against
+ * `backgroundColor`, instead of forcing white on any custom background regardless of how light
+ * it is (the bug this replaces). Only `true` for a background that both parses as a hex color
+ * and is dark enough ({@link relativeLuminance} below {@link DARK_BACKGROUND_LUMINANCE_THRESHOLD});
+ * an unset, unparseable (named color, `rgb()`/`hsl()`), or mostly transparent background falls
+ * back to `false` (the theme's own text color) rather than a guess that could make text invisible.
+ * @internal
+ */
+export declare function resolveOnColor(backgroundColor: string | undefined): boolean;
+/**
+ * Minimum WCAG contrast ratio for non-text graphics (WCAG 1.4.11), used to decide whether the
+ * theme's accent color is legible for the sparkline against a custom card background.
+ * @internal
+ */
+export declare const GRAPHICS_MIN_CONTRAST_RATIO = 3;
+/**
+ * Computes the WCAG contrast ratio (1-21) between two hex colors, or `undefined` when either
+ * color can't be measured ({@link relativeLuminance} returns `undefined` for it).
+ * @internal
+ */
+export declare function contrastRatio(a: string | undefined, b: string | undefined): number | undefined;
+/**
+ * Resolves the sparkline color against a custom card background: keeps the theme `accent` when
+ * it is legible (contrast ratio of at least {@link GRAPHICS_MIN_CONTRAST_RATIO}, per WCAG 1.4.11
+ * for graphics), and otherwise falls back to whichever of the theme `textColor` or white reads
+ * better against the background. With no custom background -- or one that can't be measured
+ * (named color, `rgb()`, mostly transparent) -- the accent is returned unchanged, matching the
+ * text behavior of {@link resolveOnColor}.
+ * @internal
+ */
+export declare function resolveSparklineColor(options: {
+    accent: string;
+    textColor: string;
+    backgroundColor: string | undefined;
+}): string;
+export {};

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

@@ -0,0 +1,51 @@
+import Highcharts from '@sisense/sisense-charts';
+import type { NumberFormatConfig } from '../../../../../../../types.js';
+/**
+ * A sparkline data point; a `null` `y` is a gap in the line/area, never rendered as zero.
+ *
+ * @internal
+ */
+export type SparklinePoint = {
+    x: number;
+    y: number | null;
+};
+/**
+ * Chart type the sparkline is drawn as.
+ *
+ * @internal
+ */
+export type SparklineChartType = 'line' | 'spline' | 'area' | 'column';
+/**
+ * Formatting inputs for the sparkline's tooltip.
+ *
+ * @internal
+ */
+export type SparklineFormatting = {
+    /** Format config for the `y` value, matching the headline measure's own format. */
+    numberFormatConfig?: NumberFormatConfig;
+    /** Formats the point's `x` (an epoch-ms date) for the tooltip; omitted when there's no date axis. */
+    formatDate?: (epochMs: number) => string;
+};
+/**
+ * Builds the Highcharts options for the KPI card's inline sparkline.
+ *
+ * `'spline'` is a core Highcharts series type -- it's registered directly inside `highcharts.js`
+ * (unlike `heatmap`/`sankey`/`streamgraph`/`series-label`, which are separate modules applied in
+ * `highcharts-overrides.ts`) -- so no extra module import is needed to support it here.
+ * @param points - Sparkline data; `null` `y` values are preserved as gaps.
+ * @param chartType - Series type to render.
+ * @param color - Series (and, for `'area'`, gradient fill) color.
+ * @param formatting - Tooltip formatting inputs.
+ * @param size - Explicit pixel size for the chart, measured from its cell. `HighchartsReact`'s
+ * container div never triggers a Highcharts reflow on its own resize (only on a window resize),
+ * so without an explicit `chart.width`/`chart.height` the chart can settle at Highcharts'
+ * hardcoded 600x400 default instead of the cell's actual (often much smaller) size. Omitted
+ * before the cell has been measured, letting Highcharts fall back to its own auto-detection for
+ * the very first paint.
+ * @returns Highcharts options for the sparkline, with mouse tracking and a tooltip enabled.
+ * @internal
+ */
+export declare function buildSparklineOptions(points: SparklinePoint[], chartType: SparklineChartType, color: string, formatting?: SparklineFormatting, size?: {
+    width: number;
+    height: number;
+}): Highcharts.Options;

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

@@ -0,0 +1,98 @@
+import { RefObject } from 'react';
+/**
+ * An inline decoration that shares the auto-fitted text's nowrap box and therefore consumes
+ * width the text itself cannot use -- e.g. a conditional icon next to the headline value, or
+ * the trend arrow before a headline-scale comparison delta. Affix glyphs are styled in em
+ * units, so their width scales with the fitted font and must be budgeted proportionally; their
+ * margins/flex gaps are fixed px.
+ * @internal
+ */
+export type AutoFitAffix = {
+    /** The affix's text content (e.g. the icon glyph or the arrow character). */
+    text: string;
+    /** The affix's font size relative to the fitted text's, e.g. `0.7` for a 0.7em icon. */
+    emScale: number;
+    /** Fixed spacing the affix adds (margins plus flex gaps), in px. */
+    gapPx: number;
+};
+/**
+ * Computes the font size (px) that fits `text` (plus any {@link AutoFitAffix}es sharing its
+ * box) into a `maxWidthPx` x `maxHeightPx` box.
+ *
+ * The width bound is derived by measuring `text` -- and each affix at its em-scaled size --
+ * at a {@link PROBE_FONT_SIZE_PX} probe font size (via canvas `measureText`, or the injected
+ * `measure`) and scaling that composite measurement to `maxWidthPx` minus the affixes' fixed
+ * gaps. The height bound is `maxHeightPx` divided by the {@link LINE_HEIGHT_FACTOR}
+ * line-height. The tighter of the two bounds is clamped to `[minPx, maxPx]`, floored to a
+ * whole pixel, and then VERIFIED: the composite is re-measured at the candidate size itself
+ * and stepped down proportionally if it turns out wider than `maxWidthPx` (extrapolation from
+ * the probe is near-linear but not exact -- hinting differs per size -- and `text-overflow:
+ * ellipsis` clips on ANY overflow, sub-pixel included). The whole-px floor doubles as a
+ * fractional-pixel safety margin against that same sub-pixel clipping.
+ * @param opts - Fit parameters.
+ * @param opts.text - The text to fit.
+ * @param opts.font - Font family and weight used to build the probe CSS font string.
+ * @param opts.maxWidthPx - Available width, in CSS pixels.
+ * @param opts.maxHeightPx - Available height, in CSS pixels.
+ * @param opts.minPx - Lower bound for the returned font size.
+ * @param opts.maxPx - Upper bound for the returned font size.
+ * @param opts.measure - Measures a string's rendered width (px) for a given CSS font
+ * shorthand string. Defaults to canvas `measureText`; injectable for tests.
+ * @param opts.affixes - Inline decorations sharing the text's box, budgeted into the fit.
+ * @returns The fitted font size, in CSS pixels, clamped to `[minPx, maxPx]`.
+ * @internal
+ */
+export declare function computeAutoFitFontSize(opts: {
+    text: string;
+    font: {
+        family: string;
+        weight: string | number;
+    };
+    maxWidthPx: number;
+    maxHeightPx: number;
+    minPx: number;
+    maxPx: number;
+    measure?: (text: string, cssFont: string) => number;
+    affixes?: readonly AutoFitAffix[];
+}): number;
+/**
+ * Computes a KPI headline's auto-fit font size, re-measuring the `containerRef` element's
+ * box on resize, and once more whenever `text`/`font`/`minPx`/`maxPx` change (even without
+ * a resize).
+ * @param params - Fit parameters.
+ * @param params.containerRef - Ref to the element whose box the text must fit inside.
+ * @param params.text - The text to fit.
+ * @param params.font - Font family and weight used for measurement.
+ * @param params.minPx - Lower bound for the returned font size.
+ * @param params.maxPx - Upper bound for the returned font size.
+ * @param params.measure - Forwarded to {@link computeAutoFitFontSize}; injectable for tests.
+ * @param params.maxHeightPxOverride - When provided, used as the height bound instead of
+ * `containerRef.current.clientHeight`. Needed whenever the container's own box is NOT a safe
+ * (non-circular) height reference -- e.g. a flex row that grows to fill its sibling's leftover
+ * space, whose rendered height would otherwise track the very font size being computed here,
+ * oscillating toward `minPx` instead of the true available height. Width is always measured
+ * from `containerRef.current.clientWidth`, which has no such circularity.
+ * @param params.enabled - Pass `false` when the caller doesn't currently consume the result
+ * (e.g. a KPI subcomponent rendered at its fixed 'compact' scale) to skip the ResizeObserver,
+ * canvas measurement, and font-availability watch entirely. Defaults to `true`. The hook still
+ * runs (rules of hooks); it just returns `minPx` and performs no work.
+ * @param params.affixes - Forwarded to {@link computeAutoFitFontSize}: inline decorations
+ * (icons, arrows) sharing the text's box, budgeted into the fit. Compared by value across
+ * renders -- fresh array literals are fine.
+ * @returns The fitted font size, in CSS pixels. `minPx` until the container is measured.
+ * @internal
+ */
+export declare function useAutoFitFontSize(params: {
+    containerRef: RefObject<HTMLElement | null>;
+    text: string;
+    font: {
+        family: string;
+        weight: string | number;
+    };
+    minPx: number;
+    maxPx: number;
+    measure?: (text: string, cssFont: string) => number;
+    maxHeightPxOverride?: number;
+    enabled?: boolean;
+    affixes?: readonly AutoFitAffix[];
+}): number;