<?php
declare(strict_types=1);

namespace ROITheme\Shared\Domain\Contracts;

/**
 * Interface CSSGeneratorInterface
 *
 * Contrato para servicios que generan CSS a partir de configuraciones de componentes.
 * Define el comportamiento esperado para la generación de reglas CSS sin depender
 * de implementaciones específicas o frameworks.
 *
 * Responsabilidades:
 * - Generar CSS válido a partir de un selector y estilos
 * - Formatear reglas CSS correctamente
 * - Convertir nombres de propiedades (snake_case → kebab-case)
 *
 * NO responsable de:
 * - Media queries (manejado por Renderer con clases Bootstrap)
 * - Visibilidad responsive (manejado por Renderer)
 * - Persistencia o caché de CSS
 *
 * @package ROITheme\Shared\Domain\Contracts
 */
interface CSSGeneratorInterface
{
    /**
     * Genera una regla CSS completa a partir de un selector y sus estilos.
     *
     * Convierte un array de estilos en una regla CSS válida y formateada.
     * Los nombres de propiedades en snake_case se convierten automáticamente
     * a kebab-case según el estándar CSS.
     *
     * Ejemplo:
     * ```php
     * $styles = [
     *     'background_color' => '#FF8600',
     *     'text_color' => '#FFFFFF',
     *     'font_size' => '1rem',
     *     'padding' => '1rem 0'
     * ];
     *
     * $css = $generator->generate('.navbar', $styles);
     *
     * // Resultado:
     * // .navbar {
     * //     background-color: #FF8600;
     * //     color: #FFFFFF;
     * //     font-size: 1rem;
     * //     padding: 1rem 0;
     * // }
     * ```
     *
     * @param string $selector Selector CSS (ej: '.navbar', '#header', 'body')
     * @param array<string, string> $styles Array asociativo de propiedades CSS y sus valores
     *                                      Formato: ['property_name' => 'value']
     *
     * @return string Regla CSS completa y formateada, o string vacío si no hay estilos
     */
    public function generate(string $selector, array $styles): string;
}