<?php

declare(strict_types=1);

namespace App\Application\LiveComponents\Services;

use App\Application\LiveComponents\ValueObjects\ChartData;
use App\Application\LiveComponents\ValueObjects\ChartType;
use App\Application\LiveComponents\ValueObjects\DataRange;
use App\Application\LiveComponents\ValueObjects\DataSource;

/**
 * ChartDataProvider - Interface for loading chart data
 *
 * Implementations receive DataSource via constructor to determine which data to load:
 * - new DemoChartDataProvider(DataSource::demo())
 * - new DatabaseChartDataProvider(DataSource::fromString('sales'))
 * - new DatabaseChartDataProvider(DataSource::fromString('traffic'))
 */
interface ChartDataProvider
{
    /**
     * Get chart data for a specific type and range
     *
     * @param ChartType $chartType
     * @param DataRange $dataRange
     * @return ChartData
     */
    public function getChartData(ChartType $chartType, DataRange $dataRange): ChartData;

    /**
     * Get updated data point for real-time refresh
     *
     * @param ChartType $chartType
     * @return array New data point values
     */
    public function getNewDataPoint(ChartType $chartType): array;

    /**
     * Get all available chart types
     *
     * @return array<ChartType>
     */
    public function getAvailableChartTypes(): array;

    /**
     * Get all available data ranges
     *
     * @return array<DataRange>
     */
    public function getAvailableDataRanges(): array;
}
