Chart Tooltip Formatter

Build a simple chart visualization system that formats tooltip data for user-friendly display. The system should handle multiple data series, format values appropriately, and generate HTML tooltips for chart visualization libraries.

Capabilities

Format tooltip for single series

• Given chart data with one series containing a label "Sales" and value 1234.56, the tooltip displays the formatted output with the label and value @test
• Given chart data with an empty label string and value 0, the tooltip displays the formatted value correctly @test

Format tooltip for multiple series

• Given chart data with three series (Revenue: 5000, Costs: 3000, Profit: 2000), the tooltip displays all series in the correct order with proper formatting @test
• Given chart data with multiple series where some values are negative (-500), the tooltip correctly formats and displays negative values @test

Apply field-specific formatting

• Given an ItemsMap with a currency format configuration (USD) for a "revenue" field, the tooltip formats the value with the dollar sign and two decimal places @test
• Given an ItemsMap with a percentage format configuration for a "growth_rate" field, the tooltip formats the value with a percent symbol @test

Handle missing or null data

• Given chart data where one series has a null value, the tooltip displays a dash or appropriate placeholder instead of the value @test
• Given chart data with undefined series data, the tooltip handles it gracefully without crashing @test

Implementation

@generates

API

/**
 * Represents formatting configuration for a specific field
 */
export interface FieldFormat {
  type: 'currency' | 'percentage' | 'number' | 'default';
  currency?: string;
  decimalPlaces?: number;
}

/**
 * Map of field names to their formatting configurations
 */
export interface ItemsMap {
  [fieldName: string]: FieldFormat;
}

/**
 * Represents a single data series in the tooltip
 */
export interface TooltipSeries {
  seriesName: string;
  value: number | null | undefined;
  color?: string;
}

/**
 * Parameters passed to the tooltip formatter
 */
export interface TooltipParams {
  axisValue?: string;
  series: TooltipSeries[];
}

/**
 * Formats tooltip content for chart visualization with field-specific formatting
 *
 * @param params - The tooltip parameters containing series data
 * @param itemsMap - Optional map of field formatting configurations
 * @returns HTML string for tooltip display
 */
export function formatTooltip(
  params: TooltipParams,
  itemsMap?: ItemsMap
): string;

/**
 * Formats a single value according to the specified format configuration
 *
 * @param value - The numeric value to format
 * @param format - The format configuration to apply
 * @returns Formatted string representation of the value
 */
export function formatValue(
  value: number | null | undefined,
  format?: FieldFormat
): string;

Dependencies { .dependencies }

@lightdash/common { .dependency }

Provides tooltip formatting utilities and field formatting support for chart visualizations.

@satisfied-by