<?php

declare(strict_types=1);

namespace App\Framework\LiveComponents\Attributes;

use Attribute;

/**
 * DataProvider Attribute - Marks a class as a data provider implementation
 *
 * Enables automatic discovery and injection of data providers based on interface and name.
 * The interface is automatically detected from the class's implemented interfaces.
 * The framework will resolve the correct provider instance when reconstructing components
 * from state (e.g., after LiveComponent actions).
 *
 * Example:
 * ```php
 * #[DataProvider(name: 'demo')]
 * final readonly class DemoChartDataProvider implements ChartDataProvider
 * {
 *     // Interface ChartDataProvider is automatically detected
 * }
 *
 * #[DataProvider(name: 'database')]
 * final readonly class DatabaseChartDataProvider implements ChartDataProvider
 * {
 *     // Interface ChartDataProvider is automatically detected
 * }
 * ```
 *
 * Discovery Process:
 * - Framework scans for classes with #[DataProvider] attribute
 * - Automatically detects implemented interfaces via reflection
 * - Builds registry: Interface + Name → Provider Class
 * - Example: ChartDataProvider + 'demo' → DemoChartDataProvider
 *
 * Usage in Component:
 * ```php
 * final readonly class ChartComponent
 * {
 *     public function __construct(
 *         ComponentId $id,
 *         ?ComponentData $initialData = null,
 *         ?ChartDataProvider $dataProvider = null,  // Injected by Controller
 *         // ... other parameters
 *     ) {
 *         if ($initialData !== null) {
 *             // Restore state and resolve provider from stored name
 *             $this->state = ChartState::fromComponentData($initialData);
 *             $this->dataProvider = $this->resolveProvider(
 *                 ChartDataProvider::class,
 *                 $this->state->dataProviderName
 *             );
 *         }
 *     }
 * }
 * ```
 */
#[Attribute(Attribute::TARGET_CLASS)]
final readonly class DataProvider
{
    /**
     * @param string $name Provider name/identifier (e.g., 'demo', 'database', 'api')
     */
    public function __construct(
        public string $name = 'default'
    ) {
    }
}