<?php

declare(strict_types=1);

namespace ROITheme\Shared\Domain\Contracts;

/**
 * Interface para el repositorio de configuraciones de componentes
 *
 * Domain Layer - Define el contrato para acceso a datos de configuración
 * Trabaja con la tabla wp_roi_theme_component_settings (normalizada)
 *
 * Esta interfaz es genérica y funciona para todos los componentes del tema.
 *
 * @package ROITheme\Shared\Domain\Contracts
 */
interface ComponentSettingsRepositoryInterface
{
    /**
     * Obtiene todas las configuraciones de un componente agrupadas por grupo
     *
     * @param string $componentName Nombre del componente (ej: 'top-notification-bar')
     * @return array<string, array<string, mixed>> Configuraciones agrupadas
     *               Ejemplo: [
     *                   'visibility' => ['enabled' => true, 'show_on_mobile' => true, ...],
     *                   'content' => ['icon_class' => 'bi-star', 'label_text' => 'Nuevo', ...],
     *                   'styles' => ['background_color' => '#0E2337', ...]
     *               ]
     */
    public function getComponentSettings(string $componentName): array;

    /**
     * Guarda las configuraciones de un componente
     *
     * @param string $componentName Nombre del componente
     * @param array<string, array<string, mixed>> $settings Configuraciones agrupadas
     *                                                       Ejemplo: [
     *                                                           'visibility' => ['enabled' => true],
     *                                                           'content' => ['icon_class' => 'bi-star']
     *                                                       ]
     * @return int Número de campos actualizados
     */
    public function saveComponentSettings(string $componentName, array $settings): int;

    /**
     * Obtiene el valor de un campo específico
     *
     * @param string $componentName Nombre del componente
     * @param string $groupName Nombre del grupo
     * @param string $attributeName Nombre del atributo
     * @return mixed|null Valor del campo o null si no existe
     */
    public function getFieldValue(string $componentName, string $groupName, string $attributeName): mixed;

    /**
     * Guarda el valor de un campo específico
     *
     * @param string $componentName Nombre del componente
     * @param string $groupName Nombre del grupo
     * @param string $attributeName Nombre del atributo
     * @param mixed $value Valor a guardar
     * @return bool True si se guardó correctamente
     */
    public function saveFieldValue(string $componentName, string $groupName, string $attributeName, mixed $value): bool;

    /**
     * Restaura un componente a sus valores por defecto desde el schema JSON
     *
     * @param string $componentName Nombre del componente
     * @param string $schemaPath Ruta al archivo schema JSON
     * @return int Número de campos restaurados
     */
    public function resetToDefaults(string $componentName, string $schemaPath): int;
}