Sales Metrics Comparison Tool

Overview

Build a sales metrics comparison tool that displays period-over-period comparisons with configurable time granularity in chart tooltips.

Background

You are building a Business Intelligence dashboard that shows sales metrics over time. When users hover over data points, they need to see not just the current value, but also how it compares to a previous period (e.g., previous month, same month last year). The comparison should adapt to different time granularities (daily, weekly, monthly, quarterly, yearly).

Requirements

Implement a tooltip formatter for chart visualizations that:

1. Accept comparison configuration including:

   • Time granularity level (day, week, month, quarter, or year)
   • Current period data (value and timestamp)
   • Comparison period data (value and timestamp)

2. Generate formatted tooltip content that displays:

   • Current period value with appropriate formatting
   • Comparison period value
   • Percentage change between periods (with + or - sign)
   • Time period labels based on the granularity

3. Handle edge cases including:

   • Missing comparison data
   • Zero values in the comparison period
   • Negative values
   • Very large percentage changes

Dependencies { .dependencies }

@lightdash/common { .dependency }

Provides Business Intelligence utilities including chart data models, tooltip formatters, and query result handling.

Test Cases

Create a test file named comparison.test.ts with the following test cases:

Test 1: Basic Monthly Comparison { @test }

Input:

• Current period: January 2024 revenue = $50,000
• Previous period: December 2023 revenue = $40,000
• Granularity: MONTH

Expected Output:

• Percentage change: +25%
• Tooltip should display both values and the increase

Test 2: Year-over-Year Comparison { @test }

Input:

• Current period: Q1 2024 sales = 1,000 units
• Previous period: Q1 2023 sales = 1,200 units
• Granularity: QUARTER

Expected Output:

• Percentage change: -16.67%
• Tooltip should display both values and the decrease

Test 3: Missing Comparison Data { @test }

Input:

• Current period: February 2024 customers = 500
• Previous period: No data available
• Granularity: MONTH

Expected Output:

• System should handle gracefully without errors
• Tooltip should show current value only

Test 4: Weekly Comparison with Zero Previous Value { @test }

Input:

• Current period: Week 12, 2024 new signups = 50
• Previous period: Week 11, 2024 new signups = 0
• Granularity: WEEK

Expected Output:

• Percentage change: +100% (or display as "new" or "N/A")
• System should handle division by zero appropriately

Constraints

• Use TypeScript with proper type definitions
• Handle timezone conversions where applicable
• Ensure calculations are accurate for financial data
• Format percentages to 2 decimal places
• Support both positive and negative percentage changes

Deliverables

1. src/comparison.ts - Main implementation file with period comparison logic
2. src/comparison.test.ts - Test file with all test cases passing
3. Proper type definitions for all functions and data structures