<?php
declare(strict_types=1);

namespace ROITheme\Shared\Domain\Contracts;

/**
 * Interface PostGridQueryBuilderInterface
 *
 * Contrato para construccion de queries de posts para el shortcode post-grid.
 * Define el comportamiento esperado para construir WP_Query sin depender
 * de implementaciones especificas.
 *
 * Responsabilidades:
 * - Construir WP_Query a partir de parametros de filtro
 * - Aplicar filtros por categoria, tag, autor
 * - Configurar paginacion y ordenamiento
 *
 * NO responsable de:
 * - Generar HTML
 * - Generar CSS
 * - Obtener settings de BD
 *
 * @package ROITheme\Shared\Domain\Contracts
 */
interface PostGridQueryBuilderInterface
{
    /**
     * Construye un WP_Query configurado con los parametros proporcionados.
     *
     * Ejemplo:
     * ```php
     * $params = [
     *     'category' => 'precios-unitarios',
     *     'tag' => 'concreto',
     *     'posts_per_page' => 6,
     *     'orderby' => 'date',
     *     'order' => 'DESC'
     * ];
     *
     * $query = $builder->build($params);
     * ```
     *
     * @param array<string, mixed> $params Parametros de filtro y configuracion
     *                                     Keys soportadas: category, exclude_category, tag,
     *                                     author, posts_per_page, orderby, order, offset,
     *                                     exclude_posts, paged
     *
     * @return \WP_Query Query configurado listo para iterar
     */
    public function build(array $params): \WP_Query;
}