<?php
declare(strict_types=1);

namespace ROITheme\Shared\Domain\Contracts;

/**
 * Interface PostGridShortcodeRendererInterface
 *
 * Contrato para renderizado HTML del shortcode post-grid.
 * Define el comportamiento esperado para generar el HTML del grid
 * sin depender de implementaciones especificas.
 *
 * Responsabilidades:
 * - Generar HTML del grid de posts
 * - Generar CSS inline usando CSSGeneratorInterface
 * - Aplicar clases responsive de Bootstrap
 *
 * NO responsable de:
 * - Construir queries
 * - Obtener settings de BD
 * - Sanitizar atributos del shortcode
 *
 * @package ROITheme\Shared\Domain\Contracts
 */
interface PostGridShortcodeRendererInterface
{
    /**
     * Renderiza el grid de posts como HTML.
     *
     * Ejemplo:
     * ```php
     * $html = $renderer->render($query, $settings, [
     *     'columns' => 3,
     *     'show_thumbnail' => true,
     *     'show_excerpt' => true,
     *     'id' => 'grid-cursos'
     * ]);
     * ```
     *
     * @param \WP_Query $query Query con los posts a mostrar
     * @param array<string, mixed> $settings Settings del componente post-grid desde BD
     * @param array<string, mixed> $options Opciones de visualizacion del shortcode
     *                                      Keys: columns, show_thumbnail, show_excerpt,
     *                                      show_meta, show_categories, excerpt_length,
     *                                      class, id, show_pagination
     *
     * @return string HTML completo del grid incluyendo CSS inline
     */
    public function render(\WP_Query $query, array $settings, array $options): string;
}