<?php
declare(strict_types=1);

namespace ROITheme\Shared\Domain\Contracts;

use ROITheme\Shared\Domain\Entities\Component;
use ROITheme\Shared\Domain\ValueObjects\ComponentName;
use ROITheme\Shared\Domain\ValueObjects\ComponentConfiguration;

/**
 * ComponentDefaultsRepositoryInterface - Contrato para valores por defecto de componentes
 *
 * RESPONSABILIDAD: Definir contrato para gestión de configuración por defecto de componentes
 *
 * PROPÓSITO:
 * - Almacenar configuración "factory" de cada tipo de componente
 * - Permitir resetear componentes a valores por defecto
 * - Proporcionar plantillas para nuevos componentes
 *
 * CASO DE USO:
 * ```php
 * // Crear nuevo componente top_bar con valores por defecto
 * $defaults = $defaultsRepo->getByName(ComponentName::fromString('top_bar'));
 * $component = new Component(
 *     ComponentName::fromString('top_bar'),
 *     $defaults // configuración por defecto
 * );
 *
 * // Resetear componente a valores por defecto
 * $component = $component->updateConfiguration($defaults);
 * ```
 *
 * @package ROITheme\Shared\Domain\Contracts
 */
interface ComponentDefaultsRepositoryInterface
{
    /**
     * Obtener configuración por defecto de un componente
     *
     * @param ComponentName $name Nombre del componente
     * @return ComponentConfiguration Configuración por defecto
     */
    public function getByName(ComponentName $name): ComponentConfiguration;

    /**
     * Guardar configuración por defecto para un componente
     *
     * @param ComponentName $name Nombre del componente
     * @param ComponentConfiguration $configuration Configuración por defecto
     * @return void
     */
    public function save(ComponentName $name, ComponentConfiguration $configuration): void;

    /**
     * Verificar si existen defaults para un componente
     *
     * @param ComponentName $name
     * @return bool
     */
    public function exists(ComponentName $name): bool;

    /**
     * Obtener todos los defaults
     *
     * @return array<string, ComponentConfiguration> Array asociativo nombre => configuración
     */
    public function findAll(): array;

    /**
     * Eliminar defaults de un componente
     *
     * @param ComponentName $name
     * @return bool True si se eliminó, false si no existía
     */
    public function delete(ComponentName $name): bool;
}