Chart Type Utility Library

/**
 * Enum representing abstract chart type categories.
 */
export enum ChartType {
    CARTESIAN = 'cartesian',
    TABLE = 'table',
    BIG_NUMBER = 'big_number',
    PIE = 'pie',
    FUNNEL = 'funnel',
}

/**
 * Enum representing concrete chart kind variations.
 */
export enum ChartKind {
    LINE = 'line',
    HORIZONTAL_BAR = 'horizontal_bar',
    VERTICAL_BAR = 'vertical_bar',
    AREA = 'area',
    SCATTER = 'scatter',
    MIXED = 'mixed',
    PIE = 'pie',
    TABLE = 'table',
    BIG_NUMBER = 'big_number',
    FUNNEL = 'funnel',
}

/**
 * Enum for Cartesian series types used in ECharts.
 */
export enum CartesianSeriesType {
    LINE = 'line',
    BAR = 'bar',
    SCATTER = 'scatter',
    AREA = 'area',
}

/**
 * Series configuration for Cartesian charts.
 */
export type Series = {
    type: CartesianSeriesType;
    areaStyle?: Record<string, unknown>;
};

/**
 * ECharts configuration with series array.
 */
export type EChartsConfig = {
    series?: Series[];
};

/**
 * Layout configuration for Cartesian charts.
 */
export type CartesianChartLayout = {
    flipAxes?: boolean;
};

/**
 * Cartesian chart configuration.
 */
export type CartesianChart = {
    layout: CartesianChartLayout;
    eChartsConfig: EChartsConfig;
};

/**
 * Pie chart configuration.
 */
export type PieChart = {
    groupFieldIds?: string[];
    metricId?: string;
};

/**
 * Table chart configuration.
 */
export type TableChart = {
    columns?: Record<string, unknown>;
};

/**
 * Discriminated union type for all chart configurations.
 */
export type ChartConfig =
    | { type: ChartType.CARTESIAN; config?: CartesianChart }
    | { type: ChartType.PIE; config?: PieChart }
    | { type: ChartType.TABLE; config?: TableChart }
    | { type: ChartType.BIG_NUMBER; config?: Record<string, unknown> }
    | { type: ChartType.FUNNEL; config?: Record<string, unknown> };

/**
 * Converts a ChartKind to its corresponding abstract ChartType.
 * Returns CARTESIAN type if chartKind is undefined.
 *
 * @param chartKind - The concrete chart kind to convert
 * @returns The abstract chart type
 */
export function getChartType(chartKind: ChartKind | undefined): ChartType;

/**
 * Converts an abstract ChartType to a concrete ChartKind by examining the chart configuration.
 * For CARTESIAN charts, inspects series configuration to determine specific kind.
 * Returns undefined if chart kind cannot be determined.
 *
 * @param chartType - The abstract chart type
 * @param config - The chart configuration
 * @returns The concrete chart kind or undefined
 */
export function getChartKind(
    chartType: ChartType,
    config: ChartConfig['config']
): ChartKind | undefined;

/**
 * Type guard to check if a configuration is a Cartesian chart.
 * Checks for presence of layout and eChartsConfig properties.
 *
 * @param config - The configuration to check
 * @returns True if configuration is a Cartesian chart
 */
export function isCartesianChartConfig(
    config: ChartConfig['config']
): config is CartesianChart;

/**
 * Type guard to check if a configuration is a Pie chart.
 * Checks for presence of groupFieldIds property.
 *
 * @param config - The configuration to check
 * @returns True if configuration is a Pie chart
 */
export function isPieChartConfig(
    config: ChartConfig['config']
): config is PieChart;

/**
 * Type guard to check if a configuration is a Table chart.
 * Checks for presence of columns property.
 *
 * @param config - The configuration to check
 * @returns True if configuration is a Table chart
 */
export function isTableChartConfig(
    config: ChartConfig['config']
): config is TableChart;

/**
 * Detects if a series array contains mixed chart types.
 * Considers LINE charts with area styling as different from LINE charts without.
 * Returns true if 2 or more distinct series types are present.
 *
 * @param series - Array of series configurations
 * @returns True if series contains mixed chart types
 */
export function isSeriesWithMixedChartTypes(
    series: Series[] | undefined
): boolean;