drizzle-cube 0.5.7 → 0.6.0

package/dist/client/components/charts/FunnelChart.helpers.d.ts

@@ -0,0 +1,25 @@
+import { ChartDisplayConfig } from '../../types';
+import { FunnelChartData } from '../../types/funnel';
+/** Check if data is already in funnel data format. */
+export declare function isFunnelData(data: unknown[]): data is FunnelChartData[];
+/**
+ * Render time metrics based on config options - returns array of lines for
+ * vertical stacking.
+ */
+export declare function getTimeMetricsLines(step: FunnelChartData, showAvg: boolean, showMedian: boolean, showP90: boolean): string[];
+/** Coerce arbitrary query rows into FunnelChartData by probing field names. */
+export declare function toFunnelData(data: unknown[]): FunnelChartData[];
+export interface FunnelDisplayOptions {
+    customStepLabels?: string[];
+    isVertical: boolean;
+    funnelStyle: NonNullable<ChartDisplayConfig['funnelStyle']>;
+    showConversion: boolean;
+    showAvgTime: boolean;
+    showMedianTime: boolean;
+    showP90Time: boolean;
+    hideSummaryFooter: boolean;
+}
+/** Resolve every funnel display option (with backward-compat for time metrics). */
+export declare function resolveFunnelDisplayOptions(displayConfig: ChartDisplayConfig | undefined): FunnelDisplayOptions;
+/** Color for a funnel step (cyclic over the palette or the default funnel gradient). */
+export declare function getStepColor(index: number, colorPalette: string[]): string;

package/dist/client/components/charts/FunnelViews.d.ts

@@ -0,0 +1,16 @@
+import { FunnelChartData } from '../../types/funnel';
+import { FunnelDisplayOptions } from './FunnelChart.helpers';
+interface FunnelViewProps {
+    funnelData: FunnelChartData[];
+    firstStepValue: number;
+    paletteColors: string[];
+    options: FunnelDisplayOptions;
+    height: string | number;
+}
+/** Recharts trapezoid funnel style. */
+export declare function FunnelShapeView({ funnelData, firstStepValue, paletteColors, options, height }: FunnelViewProps): import("react").JSX.Element;
+/** Vertical bars (steps laid out horizontally, bars grow bottom-to-top). */
+export declare function FunnelVerticalView({ funnelData, firstStepValue, paletteColors, options, height }: FunnelViewProps): import("react").JSX.Element;
+/** Horizontal bars (default - steps stacked vertically, bars grow left-to-right). */
+export declare function FunnelHorizontalView({ funnelData, firstStepValue, paletteColors, options, height }: FunnelViewProps): import("react").JSX.Element;
+export {};

package/dist/client/components/charts/HeatMapCanvas.d.ts

@@ -0,0 +1,25 @@
+import { HeatMapDisplayOptions } from './HeatMapChart.helpers';
+interface HeatMapDatum {
+    x: string;
+    y: number | null;
+}
+interface HeatMapSerie {
+    id: string;
+    data: HeatMapDatum[];
+}
+interface HeatMapCanvasProps {
+    data: HeatMapSerie[];
+    truncated: boolean;
+    colors: string[];
+    options: HeatMapDisplayOptions;
+    xAxisField: string;
+    yAxisField: string;
+    valueField: string;
+}
+/**
+ * The nivo `<ResponsiveHeatMap>` for HeatMapChart, with all axis/legend/colour
+ * config resolved from helpers. Extracted so the chart component stays a thin
+ * orchestrator. Behaviour matches the original inline JSX.
+ */
+export declare function HeatMapCanvas({ data, truncated, colors, options, xAxisField, yAxisField, valueField, }: HeatMapCanvasProps): import("react").JSX.Element;
+export {};

package/dist/client/components/charts/HeatMapChart.helpers.d.ts

@@ -0,0 +1,64 @@
+import { AxisFormatConfig, ChartDisplayConfig } from '../../types';
+/**
+ * Maximum dimensions for heatmap to prevent browser lockup. 50x50 = 2500 cells.
+ */
+export declare const MAX_HEATMAP_ROWS = 50;
+export declare const MAX_HEATMAP_COLS = 50;
+/** Parse color string (hex or rgb) to RGB values. */
+export declare function parseColor(color: string): {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/** Relative luminance of a color (0 black .. 1 white) per WCAG. */
+export declare function getLuminance(color: string): number;
+/** Contrasting text color (white or dark) based on a background color. */
+export declare function getContrastingTextColor(bgColor: string): string;
+interface HeatMapDatum {
+    x: string;
+    y: number | null;
+}
+interface HeatMapSerie {
+    id: string;
+    data: HeatMapDatum[];
+}
+export interface HeatMapTransformResult {
+    data: HeatMapSerie[];
+    truncated: boolean;
+    originalRows: number;
+    originalCols: number;
+}
+/**
+ * Transform drizzle-cube flat query results to nivo heatmap format.
+ *
+ * Groups rows by the Y dimension, sorts X chronologically when possible, and
+ * truncates to MAX_HEATMAP_ROWS x MAX_HEATMAP_COLS to prevent browser lockup.
+ */
+export declare function transformToHeatMapFormat(data: Record<string, unknown>[], xAxisField: string | undefined, yAxisField: string | undefined, valueField: string | undefined, xGranularity?: string, yGranularity?: string): HeatMapTransformResult;
+/** Coerce an axis config value (string | array | undefined) to a single field. */
+export declare function firstField(value: string | string[] | undefined): string | undefined;
+export interface HeatMapDisplayOptions {
+    showLabels: boolean;
+    cellShape: 'rect' | 'circle';
+    showLegend: boolean;
+    xAxisFormat?: AxisFormatConfig;
+    yAxisFormat?: AxisFormatConfig;
+    valueFormat?: AxisFormatConfig;
+}
+/** Resolve heatmap display options from the (loosely-typed) display config. */
+export declare function resolveHeatMapDisplayOptions(displayConfig: ChartDisplayConfig | undefined): HeatMapDisplayOptions;
+/** Build an axis `format` fn that applies the given axis format config (or none). */
+export declare function makeAxisFormatter(format: AxisFormatConfig | undefined): ((v: string | number) => string) | undefined;
+/** Resolve the heatmap value formatter (custom format or nivo default). */
+export declare function makeValueFormatter(valueFormat: AxisFormatConfig | undefined): ((v: number) => string) | string;
+/** Sequential colours config for nivo; falls back to a built-in scheme. */
+export declare function resolveHeatMapColors(colors: string[]): {
+    type: 'sequential';
+    colors: [string, string];
+} | {
+    type: 'sequential';
+    scheme: 'greens';
+};
+/** Default sequential blue gradient when no palette gradient is supplied. */
+export declare const DEFAULT_HEATMAP_COLORS: string[];
+export {};

package/dist/client/components/charts/KpiDelta.helpers.d.ts

@@ -0,0 +1,20 @@
+import { ChartAxisConfig } from '../../types';
+/** Coerce a config axis value (string | array | undefined) to a field list. */
+export declare function toFieldList(axis: ChartAxisConfig['yAxis']): string[];
+/** Sort rows ascending by the dimension field (stable when absent). */
+export declare function sortByDimension<T extends Record<string, any>>(data: T[], dimensionField: string | undefined): T[];
+/** Extract finite numeric values for a field. */
+export declare function extractNumericValues(rows: Record<string, any>[], valueField: string): number[];
+export interface DeltaStats {
+    lastValue: number;
+    absoluteChange: number;
+    percentageChange: number;
+    isPositiveChange: boolean;
+}
+/** Compute last value + delta vs the previous value. Requires >= 2 values. */
+export declare function computeDelta(values: number[]): DeltaStats;
+/**
+ * Resolve a palette colour by index, falling back to a default. Used for both
+ * the positive and negative delta colours.
+ */
+export declare function resolvePaletteColor(colorIndex: number | undefined, colors: string[] | undefined, fallback: string): string;

package/dist/client/components/charts/KpiNumber.helpers.d.ts

@@ -0,0 +1,30 @@
+import { ChartAxisConfig, ChartDisplayConfig } from '../../types';
+/** Extract the value field list from chart config (string | array | undefined). */
+export declare function getKpiValueFields(yAxis: ChartAxisConfig['yAxis']): string[];
+/** Sort rows ascending by the time-dimension field (stable when absent). */
+export declare function sortKpiData<T extends Record<string, any>>(data: T[] | undefined, timeDimensionField: string | undefined): T[];
+/**
+ * Extract numeric values for the configured field, falling back to the first
+ * numeric field on each row when the configured field is absent.
+ */
+export declare function extractKpiValues(dataToUse: Record<string, any>[], valueField: string): number[];
+/** Compute avg/min/max over a numeric series (0s when empty). */
+export declare function computeKpiStats(values: number[]): {
+    avg: number;
+    min: number;
+    max: number;
+};
+/**
+ * Format a numeric KPI value with thousands/millions/billions suffixes,
+ * honouring a custom `formatValue`, `decimals` and `prefix` from displayConfig.
+ */
+export declare function formatKpiNumber(value: number | null | undefined, displayConfig: ChartDisplayConfig): string;
+/**
+ * Resolve the label to display for a KPI field: prefer the resolved field label,
+ * but fall back to the raw field name when the label looks empty/too short.
+ */
+export declare function resolveDisplayLabel(label: string | undefined, fieldName: string): string;
+/** Resolve the main value colour from the palette / displayConfig overrides. */
+export declare function resolveValueColor(valueColorIndex: number | undefined, colors: string[] | undefined): string;
+/** Resolve the variance colour (green/red based on sign), with palette overrides. */
+export declare function resolveVarianceColor(variance: number | null, positiveColorIndex: number | undefined, negativeColorIndex: number | undefined, colors: string[] | undefined): string;

package/dist/client/components/charts/KpiStates.d.ts

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+type KpiStateVariant = 'muted' | 'danger' | 'warning';
+/** Resolve the shared `height`/`minHeight` style used by every KPI card state. */
+export declare function kpiHeightStyle(height: string | number): React.CSSProperties;
+/**
+ * Centred KPI state card (no-data / config-error / insufficient-data).
+ *
+ * Owns the duplicated centred flex wrapper shared by KpiNumber and KpiDelta.
+ * Callers supply already-resolved title/hint text (i18n resolved at the call
+ * site) plus an optional colour variant and extra children.
+ */
+export declare function KpiCenteredState({ height, title, hint, variant, children }: {
+    height: string | number;
+    title: React.ReactNode;
+    hint?: React.ReactNode;
+    variant?: KpiStateVariant;
+    children?: React.ReactNode;
+}): React.JSX.Element;
+export {};

package/dist/client/components/charts/MissingDependencyFallback.d.ts

@@ -8,5 +8,5 @@ interface MissingDependencyFallbackProps {
  * Fallback component shown when a chart's optional dependency is not installed.
  * Provides clear instructions on how to install the missing package.
  */
-export declare function MissingDependencyFallback({ chartType, packageName, installCommand, height }: MissingDependencyFallbackProps): import("react/jsx-runtime").JSX.Element;
+export declare function MissingDependencyFallback({ chartType, packageName, installCommand, height }: MissingDependencyFallbackProps): import("react").JSX.Element;
 export {};

package/dist/client/components/charts/ScatterChart.helpers.d.ts

@@ -0,0 +1,43 @@
+import { CHART_MARGINS } from '../../utils/chartConstants';
+import { AxisFormatConfig, ChartAxisConfig, ChartDisplayConfig, CubeQuery } from '../../types';
+export interface ScatterRenderState {
+    showLegend: boolean;
+    showGrid: boolean;
+    showTooltip: boolean;
+    /** Whether to render one Scatter per series group vs a single series. */
+    hasSeries: boolean;
+    xAxisFormat?: AxisFormatConfig;
+    /** For scatter charts the y-axis uses the left-axis format config. */
+    yAxisFormat?: AxisFormatConfig;
+    chartMargins: typeof CHART_MARGINS;
+}
+/**
+ * Resolve all render-time display flags, axis formats and margins for the
+ * scatter chart from the display config and the transformed series keys.
+ */
+export declare function resolveScatterRenderState(displayConfig: ChartDisplayConfig | undefined, seriesKeys: string[]): ScatterRenderState;
+export interface ScatterAxisFields {
+    xAxisField: string;
+    yAxisField: string;
+    seriesFields: string[];
+    /** Set when the config is invalid (no usable axis fields). */
+    errorCode?: 'axisInvalid' | 'axisFields';
+}
+/** Resolve x/y/series fields supporting both the new and legacy config shapes. */
+export declare function resolveScatterAxisFields(chartConfig: ChartAxisConfig | undefined): ScatterAxisFields;
+export interface ScatterPoint {
+    x: number;
+    y: number;
+    name: string;
+    timeValues: Record<string, string>;
+    originalItem: Record<string, any>;
+}
+export interface ScatterTransform {
+    scatterData: ScatterPoint[];
+    seriesGroups: Record<string, ScatterPoint[]>;
+}
+/**
+ * Transform rows into scatter points, grouping by series when configured.
+ * Null x/y coordinates are filtered out. Mirrors the original two-branch logic.
+ */
+export declare function transformScatterData(data: Record<string, any>[], xAxisField: string, yAxisField: string, seriesFields: string[], timeDimensionFields: string[], queryObject: CubeQuery | undefined): ScatterTransform;

package/dist/client/components/charts/ScatterSeries.d.ts

@@ -0,0 +1,17 @@
+import { ColorPalette } from '../../types';
+import { ScatterPoint } from './ScatterChart.helpers';
+interface ScatterSeriesProps {
+    hasSeries: boolean;
+    seriesKeys: string[];
+    seriesGroups: Record<string, ScatterPoint[]>;
+    scatterData: ScatterPoint[];
+    colorPalette?: ColorPalette;
+    hoveredLegend: string | null;
+}
+/**
+ * Renders the `<Scatter>` series for ScatterChart — one per series group when
+ * `hasSeries`, otherwise a single series. Returned as a fragment so it composes
+ * inside the Recharts chart children. Behaviour matches the original inline JSX.
+ */
+export declare function ScatterSeries({ hasSeries, seriesKeys, seriesGroups, scatterData, colorPalette, hoveredLegend }: ScatterSeriesProps): import("react").JSX.Element;
+export {};

package/dist/client/components/charts/ScatterTooltip.d.ts

@@ -0,0 +1,21 @@
+import { AxisFormatConfig } from '../../types';
+import { ScatterPoint } from './ScatterChart.helpers';
+interface ScatterTooltipProps {
+    active?: boolean;
+    payload?: Array<{
+        payload?: ScatterPoint;
+    }>;
+    xAxisField: string;
+    yAxisField: string;
+    xAxisFormat?: AxisFormatConfig;
+    yAxisFormat?: AxisFormatConfig;
+    getFieldLabel: (field: string) => string;
+}
+/**
+ * Custom Recharts tooltip content for ScatterChart.
+ *
+ * Extracted from the inline `content` render prop to keep the chart body lean.
+ * Renders the point name, any time-dimension values, and the formatted x/y.
+ */
+export declare function ScatterTooltip({ active, payload, xAxisField, yAxisField, xAxisFormat, yAxisFormat, getFieldLabel }: ScatterTooltipProps): import("react").JSX.Element | null;
+export {};

package/dist/client/components/charts/TreeMapChart.helpers.d.ts

@@ -0,0 +1,37 @@
+import { AxisFormatConfig, ChartAxisConfig, ColorPalette, CubeQuery } from '../../types';
+export interface TreemapDatum {
+    name: string;
+    size: number;
+    fill?: string;
+    series?: string;
+    [key: string]: unknown;
+}
+export interface TreemapBuildResult {
+    treemapData: TreemapDatum[];
+    isNumericSeries: boolean;
+    seriesField?: string;
+}
+/**
+ * Build treemap data (config or auto-detect), then drop non-positive sizes.
+ * Returns `null` when the legacy path can't find a usable size field.
+ */
+export declare function buildTreemapData(data: Record<string, any>[], chartConfig: ChartAxisConfig | undefined, queryObject: CubeQuery | undefined, colorPalette: ColorPalette | undefined): TreemapBuildResult | null;
+/** Min/max of the (numeric) series field across the raw rows. */
+export declare function seriesMinMax(data: Record<string, any>[], seriesField: string): {
+    min: number;
+    max: number;
+};
+/** Format a numeric value with the optional axis format (or `.toFixed(2)`). */
+export declare function formatSeriesValue(value: number, format: AxisFormatConfig | undefined): string;
+export interface LegendEntry {
+    value: string;
+    type: 'rect';
+    color: string;
+}
+/**
+ * Build the legend entries for the treemap: a gradient ramp for numeric series,
+ * or discrete swatches for categorical series. Empty when not applicable.
+ */
+export declare function buildTreemapLegend(data: Record<string, any>[], treemapData: TreemapDatum[], showLegend: boolean, seriesField: string | undefined, isNumericSeries: boolean, leftYAxisFormat: AxisFormatConfig | undefined): LegendEntry[];
+/** Adjust the outer container height to make room for a legend, if present. */
+export declare function adjustHeightForLegend(height: string | number, hasLegend: boolean): string | number;

package/dist/client/components/charts/TreeMapContent.d.ts

@@ -0,0 +1,24 @@
+import { default as React } from 'react';
+import { AxisFormatConfig, ChartAxisConfig, ColorPalette, CubeQuery } from '../../types';
+import { ChartDataPointClickEvent } from '../../types/drill';
+import { TreemapDatum } from './TreeMapChart.helpers';
+interface TreeMapContentOptions {
+    treemapData: TreemapDatum[];
+    colorPalette?: ColorPalette;
+    hoveredIndex: number | null;
+    setHoveredIndex: (index: number | null) => void;
+    leftYAxisFormat?: AxisFormatConfig;
+    drillEnabled?: boolean;
+    onDataPointClick?: (event: ChartDataPointClickEvent) => void;
+    queryObject?: CubeQuery;
+    chartConfig?: ChartAxisConfig;
+}
+/**
+ * Build the Recharts `content` renderer for treemap cells.
+ *
+ * Encapsulates the per-cell rect + foreignObject overlay, hover state and drill
+ * click handler that previously lived inline in TreeMapChart (the highest-
+ * complexity hot spots). Behaviour is identical to the original.
+ */
+export declare function makeTreeMapContent({ treemapData, colorPalette, hoveredIndex, setHoveredIndex, leftYAxisFormat, drillEnabled, onDataPointClick, queryObject, chartConfig, }: TreeMapContentOptions): (props: any) => React.JSX.Element | null;
+export {};

package/dist/client/components/charts/TreeMapLegend.d.ts

@@ -0,0 +1,13 @@
+import { AxisFormatConfig } from '../../types';
+import { LegendEntry } from './TreeMapChart.helpers';
+interface TreeMapLegendProps {
+    isNumericSeries: boolean;
+    seriesField?: string;
+    seriesLabel: string;
+    legendPayload: LegendEntry[];
+    data: Record<string, any>[];
+    leftYAxisFormat?: AxisFormatConfig;
+}
+/** Treemap legend wrapper — gradient for numeric series, swatches otherwise. */
+export declare function TreeMapLegend({ isNumericSeries, seriesField, seriesLabel, legendPayload, data, leftYAxisFormat, }: TreeMapLegendProps): import("react").JSX.Element;
+export {};

package/dist/client/components/charts/cartesianChartHelpers.d.ts

@@ -0,0 +1,126 @@
+import { default as React } from 'react';
+import { ColorPalette } from '../../types';
+/**
+ * Co-located helpers shared by the Cartesian time-series charts (Line, Area).
+ *
+ * These extract the heavier inline logic that previously lived inside the chart
+ * components — the clickable/drill dot renderer, the comparison-mode tick and
+ * label formatters, and the series-key → measure-field resolution — so the
+ * component bodies stay focused on chart composition. Pure extraction: no
+ * behaviour change.
+ */
+export interface DataPointClickPayload {
+    dataPoint: any;
+    clickedField: string;
+    xValue: any;
+    position: {
+        x: number;
+        y: number;
+    };
+    nativeEvent: React.MouseEvent;
+}
+interface DrillDotOptions {
+    /** Recharts dot props (cx, cy, payload, key). */
+    props: any;
+    color: string;
+    drillEnabled?: boolean;
+    originalField?: string;
+    seriesKey: string;
+    onDataPointClick?: (payload: DataPointClickPayload) => void;
+}
+/**
+ * Render a single data-point dot. When drill is enabled and a click handler is
+ * present, renders a larger clickable dot with a surface-coloured backing
+ * circle to mask grid lines; otherwise a small plain dot. Returns null when the
+ * point has no coordinates.
+ *
+ * `renderPlain` controls whether a small non-interactive dot is drawn when
+ * drill is disabled (Line draws one; Area returns nothing).
+ */
+export declare function renderDrillDot({ props, color, drillEnabled, originalField, seriesKey, onDataPointClick, renderPlain }: DrillDotOptions & {
+    renderPlain: boolean;
+}): React.ReactElement | null;
+/**
+ * Build the comparison-mode X-axis tick formatter for time-series charts.
+ * Returns undefined when not in comparison mode (no custom formatting).
+ */
+export declare function makeComparisonTickFormatter(hasComparisonData: boolean, chartData: any[], queryObject: any, xAxisField: string): ((value: string | number, index: number) => string) | undefined;
+/**
+ * Build the comparison-mode tooltip label formatter for time-series charts.
+ * Returns undefined when not in comparison mode (no custom formatting).
+ */
+export declare function makeComparisonLabelFormatter(hasComparisonData: boolean, queryObject: any, xAxisField: string): ((label: any, payload: any) => string) | undefined;
+/**
+ * Resolve effective stacking for the Area chart from `stackType` (new) /
+ * `stacked` (legacy), disabling stacking when a right axis is present (areas on
+ * different axes can't be stacked).
+ */
+export declare function resolveAreaStacking(displayConfig: {
+    stackType?: string;
+    stacked?: boolean;
+} | undefined, hasRightAxis: boolean): {
+    effectiveShouldStack: boolean;
+    effectiveIsPercentStack: boolean;
+    stackOffset: 'expand' | undefined;
+};
+/** Build a map from series display label to original measure field name. */
+export declare function buildSeriesKeyToFieldMap(yAxisFields: string[], getFieldLabel: (field: string) => string): Record<string, string>;
+/**
+ * Resolve a series key back to its original measure field, handling comparison
+ * suffixes like "(Current)" / "(Prior)" and dimension prefixes ("Dim - Label").
+ */
+export declare function makeSeriesKeyResolver(seriesKeyToField: Record<string, string>): (seriesKey: string) => string | undefined;
+/** Pick a series colour by index, preferring the palette then the defaults. */
+export declare function getSeriesColor(colorPalette: ColorPalette | undefined, index: number): string;
+interface LineSeriesOptions {
+    seriesKeys: string[];
+    colorPalette?: ColorPalette;
+    resolveField: (seriesKey: string) => string | undefined;
+    yAxisAssignment: Record<string, 'left' | 'right'>;
+    hoveredLegend: string | null;
+    connectNulls: boolean;
+    drillEnabled?: boolean;
+    onDataPointClick?: (payload: DataPointClickPayload) => void;
+    /** Comparison styling (omit/false → standard series). */
+    hasComparisonData?: boolean;
+    periodLabels?: string[];
+    priorPeriodStyle?: 'solid' | 'dashed' | 'dotted';
+    priorPeriodOpacity?: number;
+}
+/** Render all line series for the Line chart. */
+export declare function renderLineSeries(opts: LineSeriesOptions): React.ReactElement[];
+interface AreaSeriesOptions {
+    seriesKeys: string[];
+    colorPalette?: ColorPalette;
+    seriesKeyToField: Record<string, string>;
+    yAxisAssignment: Record<string, 'left' | 'right'>;
+    hoveredLegend: string | null;
+    connectNulls: boolean;
+    shouldStack: boolean;
+    drillEnabled?: boolean;
+    onDataPointClick?: (payload: DataPointClickPayload) => void;
+}
+/** Render all area series for the Area chart. */
+export declare function renderAreaSeries(opts: AreaSeriesOptions): React.ReactElement[];
+export interface TimeSeriesShape {
+    chartData: any[];
+    seriesKeys: string[];
+    effectiveXAxisKey: string;
+    hasComparisonData: boolean;
+    periodLabels: string[];
+}
+/**
+ * Shape raw rows for a Cartesian time-series chart. In comparison mode this
+ * uses the overlay transform (aligned by period day index); otherwise the
+ * standard series transform. Centralises the branch so the chart body stays
+ * flat.
+ */
+export declare function buildTimeSeriesData(args: {
+    data: any[];
+    xAxisField: string;
+    yAxisFields: string[];
+    seriesFields: string[];
+    queryObject: any;
+    getFieldLabel: (field: string) => string;
+}): TimeSeriesShape;
+export {};

package/dist/client/components/charts/chartAxisResolution.d.ts

@@ -0,0 +1,32 @@
+import { ChartAxisConfig } from '../../types';
+/**
+ * Discriminated error code returned by {@link resolveChartAxisFields} when the
+ * chart configuration is invalid. Each chart maps these codes to its own i18n
+ * hint key (e.g. pie charts surface a pie-specific message for `axisInvalid`).
+ */
+export type ChartAxisErrorCode = 'axisInvalid' | 'axisFields';
+/**
+ * Result of resolving X/Y/series fields from a {@link ChartAxisConfig}.
+ * When `errorCode` is non-null the field values are not usable and the chart
+ * should render a configuration-error state instead.
+ */
+export interface ResolvedChartAxisFields {
+    /** Resolved X-axis field (category), or undefined when the config is invalid */
+    xAxisField?: string;
+    /** Resolved Y-axis (value/measure) fields */
+    yAxisFields: string[];
+    /** Optional series/grouping fields (only present in the new config format) */
+    seriesFields: string[];
+    /** Non-null when the configuration cannot produce a renderable axis setup */
+    errorCode: ChartAxisErrorCode | null;
+}
+/**
+ * Pure resolver for the X/Y/series field extraction that Cartesian charts
+ * (bar, line, area, pie) all duplicated inline.
+ *
+ * Supports both the new format (`xAxis` / `yAxis` / `series` arrays) and the
+ * legacy format (`x` / `y`). Returns a discriminated `errorCode` rather than
+ * JSX so each chart can map it to its own i18n hint key and render its own
+ * guard component.
+ */
+export declare function resolveChartAxisFields(chartConfig?: ChartAxisConfig): ResolvedChartAxisFields;

package/dist/client/components/charts/chartScaffolding.d.ts

@@ -0,0 +1,77 @@
+import { AxisFormatConfig } from '../../types';
+/**
+ * Shared scaffolding for the Cartesian recharts charts (bar, line, area).
+ *
+ * These charts duplicated the same dual-Y-axis derivation, chart margins,
+ * target-line overlay, and the left/right `<YAxis>` JSX. The pure helpers and
+ * recharts render-helpers here own that shared setup. Render-helpers return
+ * recharts elements (inside a fragment) and are embedded directly in the chart
+ * children — recharts flattens fragments when discovering axes/series, exactly
+ * as it already does for the inline target-line fragment.
+ */
+export interface DualAxisInfo {
+    /** True when at least one measure is assigned to the right axis */
+    hasRightAxis: boolean;
+    /** Measure fields rendered against the left axis */
+    leftAxisFields: string[];
+    /** Measure fields rendered against the right axis */
+    rightAxisFields: string[];
+}
+/** Derive left/right axis membership from per-measure axis assignments. */
+export declare function getDualAxisInfo(yAxisFields: string[], yAxisAssignment: Record<string, 'left' | 'right'>): DualAxisInfo;
+/** Chart margins with extra room for the Y-axis label(s). */
+export declare function getYAxisChartMargins(hasRightAxis: boolean): {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+};
+/**
+ * Apply target values (single or comma-separated spread) onto chart data,
+ * returning the spread targets plus data enhanced with a `__target` key.
+ */
+export declare function withTargetData<T extends Record<string, any>>(chartData: T[], target: string | undefined): {
+    spreadTargets: number[];
+    enhancedChartData: T[];
+};
+/**
+ * Render the left + optional right `<YAxis>`. Returns recharts elements in a
+ * fragment for embedding directly in the chart children. Positional args keep
+ * the (otherwise identical) call sites in each chart down to a single line.
+ *
+ * @param isPercentStack when true (area/bar percent stacking) the left axis shows 0–100%
+ */
+export declare function renderDualYAxes({ hasRightAxis, leftAxisFields, rightAxisFields }: DualAxisInfo, getFieldLabel: (field: string) => string, leftYAxisFormat?: AxisFormatConfig, rightYAxisFormat?: AxisFormatConfig, isPercentStack?: boolean): import("react").JSX.Element;
+/**
+ * Render the target overlay: a white backing line plus a purple dashed line
+ * on top (shared by bar, line, area). Returns null when there are no targets.
+ */
+export declare function renderChartTargetLines(spreadTargets: number[]): import("react").JSX.Element | null;
+interface CartesianTooltipOptions {
+    leftYAxisFormat?: AxisFormatConfig;
+    rightYAxisFormat?: AxisFormatConfig;
+    yAxisAssignment: Record<string, 'left' | 'right'>;
+    /** Maps a series key (display label) back to its original measure field. */
+    resolveField: (name: string) => string | undefined;
+    /** When true, values render as percentages (area/bar percent stacking). */
+    isPercentStack?: boolean;
+}
+/**
+ * Build the value/name tooltip formatter shared by the Cartesian charts.
+ * Handles null values, the target series, percent stacking, and per-series
+ * left/right axis format selection.
+ */
+export declare function makeCartesianTooltipFormatter({ leftYAxisFormat, rightYAxisFormat, yAxisAssignment, resolveField, isPercentStack }: CartesianTooltipOptions): (value: any, name: any) => [any, any];
+/**
+ * Render the hover-aware bottom legend shared by the Cartesian charts.
+ * Returns null when the legend is hidden. `iconType` / `paddingTop` differ
+ * per chart (rect+10 for area, rect+25 for bar, line+25 for line).
+ */
+export declare function renderHoverLegend({ show, iconType, paddingTop, onHover, onLeave }: {
+    show: boolean;
+    iconType: 'rect' | 'line' | 'circle';
+    paddingTop: number;
+    onHover: (dataKey: string) => void;
+    onLeave: () => void;
+}): import("react").JSX.Element | null;
+export {};

package/dist/client/components/charts/gaugeChartHelpers.d.ts

@@ -0,0 +1,36 @@
+import { AxisFormatConfig, ThresholdBand } from '../../types';
+/**
+ * Co-located helpers for GaugeChart: pure geometry/value math and threshold
+ * parsing extracted from the component so the render body stays flat. Pure
+ * extraction — no behaviour change.
+ */
+export declare const START_ANGLE: number;
+export declare const END_ANGLE: number;
+export declare const TRACK_COLOR = "#e2e8f0";
+export declare const DEFAULT_FILL = "#6366f1";
+export declare function parseNum(v: unknown): number | null;
+export declare function clamp(v: number, lo: number, hi: number): number;
+export declare function valueToAngle(value: number, min: number, max: number): number;
+export declare function resolveColor(fraction: number, thresholds: ThresholdBand[]): string;
+export declare function buildArcPath(innerRadius: number, outerRadius: number, startAngle: number, endAngle: number): string;
+/** Parse the displayConfig.thresholds value (array or JSON string) into bands. */
+export declare function parseThresholds(raw: unknown): ThresholdBand[];
+export interface ThresholdArcBand {
+    color: string;
+    start: number;
+    end: number;
+}
+/** Build the outer-ring threshold arc bands (in fraction space 0..1). */
+export declare function buildThresholdBands(thresholds: ThresholdBand[]): ThresholdArcBand[];
+export interface GaugeGeometry {
+    effectiveMax: number;
+    clampedValue: number;
+    fraction: number;
+    fillColor: string;
+    fillAngle: number;
+    needleAngle: number;
+}
+/** Compute the gauge's clamped value, fraction, fill colour, and angles. */
+export declare function computeGaugeGeometry(rawValue: number, minValue: number, maxValue: number, thresholds: ThresholdBand[]): GaugeGeometry;
+/** Format a gauge value with the optional axis format, else locale string. */
+export declare function formatGaugeValue(value: number, yAxisFormat?: AxisFormatConfig): string;