roi-theme/openspec/specs/post-grid-shortcode/spec.md

# Especificacion de Shortcode Post Grid

## Purpose

Crear un shortcode `[roi_post_grid]` que permita insertar grids de posts en cualquier pagina o entrada de WordPress, con filtros configurables por categoria, tag, autor y otras opciones. Sigue Clean Architecture delegando logica a Use Cases.

## Context

### Problema Actual
El componente `post-grid` implementado en `templates-unificados` solo funciona en templates de archivo (home.php, archive.php, etc.) porque depende del loop principal de WordPress (`global $wp_query`).

### Solucion
Crear un shortcode que:
1. Siga Clean Architecture (ShortcodeRegistrar → UseCase → Repository)
2. Reutilice estilos del componente `post-grid` existente
3. Permita filtrar posts por categoria, tag, autor
4. No dependa del loop principal de WordPress

### Relacion con templates-unificados
- Este shortcode **complementa** (no reemplaza) el componente post-grid
- El componente post-grid sigue funcionando en templates de archivo
- El shortcode permite insertar grids en contenido arbitrario

### Nota sobre shortcodes legacy
Los shortcodes existentes (`apu_table`, `apu_row`) estan en `Inc/apu-tables.php` (patron legacy). Este nuevo shortcode sigue el patron moderno de Clean Architecture.

---

## Requirements

### Requirement: Arquitectura del Shortcode

The shortcode MUST follow Clean Architecture patterns.

#### Scenario: Ubicacion del ShortcodeRegistrar
- **WHEN** se implementa el shortcode
- **THEN** DEBE estar en `Shared/Infrastructure/Wordpress/PostGridShortcodeRegistrar.php`
- **AND** DEBE usar namespace `ROITheme\Shared\Infrastructure\Wordpress`
- **AND** DEBE registrar el shortcode via add_shortcode

#### Scenario: Delegacion a Use Case
- **WHEN** el shortcode se ejecuta
- **THEN** PostGridShortcodeRegistrar DEBE delegar a RenderPostGridUseCase
- **AND** NO DEBE contener logica de negocio
- **AND** solo sanitiza atributos y pasa al Use Case

#### Scenario: Ubicacion del Use Case
- **WHEN** se implementa la logica del shortcode
- **THEN** DEBE estar en `Shared/Application/UseCases/RenderPostGrid/RenderPostGridUseCase.php`
- **AND** DEBE usar namespace `ROITheme\Shared\Application\UseCases\RenderPostGrid`
- **AND** DEBE orquestar Query, Renderer y Settings

#### Scenario: Ubicacion del QueryBuilder
- **WHEN** se construye el WP_Query
- **THEN** DEBE estar en `Shared/Infrastructure/Query/PostGridQueryBuilder.php`
- **AND** DEBE usar namespace `ROITheme\Shared\Infrastructure\Query`
- **AND** DEBE recibir parametros y retornar WP_Query

#### Scenario: Ubicacion del ShortcodeRenderer
- **WHEN** se genera el HTML del grid
- **THEN** DEBE estar en `Shared/Infrastructure/Ui/PostGridShortcodeRenderer.php`
- **AND** DEBE usar namespace `ROITheme\Shared\Infrastructure\Ui`
- **AND** DEBE inyectar CSSGeneratorInterface

---

### Requirement: Estructura de Clases

Each class MUST have single responsibility following SRP.

#### Scenario: Responsabilidad de PostGridShortcodeRegistrar
- **WHEN** se define PostGridShortcodeRegistrar
- **THEN** DEBE tener metodo estatico `register()` para add_shortcode
- **AND** DEBE tener metodo `handleShortcode(array $atts): string`
- **AND** handleShortcode DEBE sanitizar atributos
- **AND** handleShortcode DEBE obtener UseCase del DIContainer
- **AND** handleShortcode DEBE retornar resultado del UseCase
- **AND** NO DEBE tener mas de 50 lineas

#### Scenario: Responsabilidad de RenderPostGridUseCase
- **WHEN** se define RenderPostGridUseCase
- **THEN** DEBE recibir RenderPostGridRequest como input
- **AND** DEBE inyectar PostGridQueryBuilderInterface via constructor
- **AND** DEBE inyectar PostGridShortcodeRendererInterface via constructor
- **AND** DEBE inyectar ComponentSettingsRepositoryInterface via constructor
- **AND** DEBE orquestar: obtener settings, construir query, renderizar
- **AND** DEBE retornar string HTML
- **AND** NO DEBE tener mas de 80 lineas

#### Scenario: Responsabilidad de PostGridQueryBuilder
- **WHEN** se define PostGridQueryBuilder
- **THEN** DEBE recibir parametros de filtro (category, tag, etc.)
- **AND** DEBE construir array de argumentos WP_Query
- **AND** DEBE retornar WP_Query configurado
- **AND** NO DEBE generar HTML
- **AND** NO DEBE tener mas de 100 lineas

#### Scenario: Responsabilidad de PostGridShortcodeRenderer
- **WHEN** se define PostGridShortcodeRenderer
- **THEN** DEBE recibir WP_Query y configuracion
- **AND** DEBE inyectar CSSGeneratorInterface
- **AND** DEBE generar HTML del grid
- **AND** DEBE generar CSS inline
- **AND** NO DEBE construir queries
- **AND** NO DEBE tener mas de 150 lineas

---

### Requirement: Interfaces en Domain/Application

Interfaces MUST be defined for dependency injection.

#### Scenario: Interface del QueryBuilder
- **WHEN** se define la interface
- **THEN** DEBE estar en `Shared/Domain/Contracts/PostGridQueryBuilderInterface.php`
- **AND** DEBE tener metodo `build(array $params): \WP_Query`

#### Scenario: Interface del Renderer
- **WHEN** se define la interface
- **THEN** DEBE estar en `Shared/Domain/Contracts/PostGridShortcodeRendererInterface.php`
- **AND** DEBE tener metodo `render(\WP_Query $query, array $settings, array $options): string`

#### Scenario: Request DTO
- **WHEN** se define el DTO de entrada
- **THEN** DEBE estar en `Shared/Application/UseCases/RenderPostGrid/RenderPostGridRequest.php`
- **AND** DEBE ser readonly class con propiedades tipadas
- **AND** DEBE contener todos los atributos del shortcode

---

### Requirement: Atributos del Shortcode

The shortcode MUST accept configurable attributes.

#### Scenario: Atributo category
- **WHEN** se usa `[roi_post_grid category="precios-unitarios"]`
- **THEN** DEBE filtrar posts por slug de categoria
- **AND** DEBE aceptar multiples categorias separadas por coma
- **AND** ejemplo: `category="cat1,cat2,cat3"`

#### Scenario: Atributo exclude_category
- **WHEN** se usa `[roi_post_grid exclude_category="noticias"]`
- **THEN** DEBE excluir posts de esas categorias
- **AND** DEBE aceptar multiples categorias separadas por coma

#### Scenario: Atributo tag
- **WHEN** se usa `[roi_post_grid tag="concreto"]`
- **THEN** DEBE filtrar posts por slug de tag
- **AND** DEBE aceptar multiples tags separados por coma

#### Scenario: Atributo author
- **WHEN** se usa `[roi_post_grid author="admin"]`
- **THEN** DEBE filtrar posts por login de autor
- **AND** DEBE aceptar ID numerico o login string

#### Scenario: Atributo posts_per_page
- **WHEN** se usa `[roi_post_grid posts_per_page="6"]`
- **THEN** DEBE limitar cantidad de posts mostrados
- **AND** default DEBE ser 9
- **AND** DEBE aceptar valores entre 1 y 50

#### Scenario: Atributo columns
- **WHEN** se usa `[roi_post_grid columns="4"]`
- **THEN** DEBE definir columnas en desktop
- **AND** default DEBE ser 3
- **AND** DEBE aceptar valores 1, 2, 3 o 4

#### Scenario: Atributo orderby
- **WHEN** se usa `[roi_post_grid orderby="title"]`
- **THEN** DEBE ordenar posts por ese campo
- **AND** default DEBE ser "date"
- **AND** opciones validas: date, title, modified, rand, comment_count

#### Scenario: Atributo order
- **WHEN** se usa `[roi_post_grid order="ASC"]`
- **THEN** DEBE definir direccion del orden
- **AND** default DEBE ser "DESC"
- **AND** opciones validas: ASC, DESC

#### Scenario: Atributo show_pagination
- **WHEN** se usa `[roi_post_grid show_pagination="true"]`
- **THEN** DEBE mostrar paginacion si hay mas posts
- **AND** default DEBE ser false

#### Scenario: Atributo offset
- **WHEN** se usa `[roi_post_grid offset="3"]`
- **THEN** DEBE saltar los primeros N posts
- **AND** default DEBE ser 0

#### Scenario: Atributo exclude_posts
- **WHEN** se usa `[roi_post_grid exclude_posts="123,456"]`
- **THEN** DEBE excluir posts por ID
- **AND** DEBE aceptar IDs separados por coma

#### Scenario: Atributos de visualizacion
- **WHEN** se usan atributos de visualizacion
- **THEN** show_thumbnail default true
- **AND** show_excerpt default true
- **AND** show_meta default true
- **AND** show_categories default true
- **AND** excerpt_length default 20

#### Scenario: Atributo class
- **WHEN** se usa `[roi_post_grid class="my-custom-grid"]`
- **THEN** DEBE agregar clase CSS adicional al contenedor

#### Scenario: Atributo id para paginacion multiple
- **WHEN** se usa `[roi_post_grid id="grid-1" show_pagination="true"]`
- **THEN** DEBE usar query var unico `paged_grid-1`
- **AND** permite multiples shortcodes paginados en misma pagina

---

### Requirement: Obtencion de Settings

The shortcode MUST obtain styles from post-grid component settings.

#### Scenario: Lectura de configuracion
- **WHEN** RenderPostGridUseCase se ejecuta
- **THEN** DEBE usar ComponentSettingsRepositoryInterface
- **AND** DEBE obtener settings de componente 'post-grid'
- **AND** DEBE aplicar colores, spacing, visual_effects del componente

#### Scenario: Settings no encontrados
- **WHEN** no existen settings de post-grid en BD
- **THEN** DEBE usar valores default definidos en VisibilityDefaults
- **AND** NO DEBE fallar con error

---

### Requirement: Renderizado HTML

The shortcode MUST generate valid HTML with proper escaping.

#### Scenario: Estructura HTML del grid
- **WHEN** el shortcode renderiza
- **THEN** DEBE generar contenedor con clase `roi-post-grid-shortcode`
- **AND** DEBE generar row con clase Bootstrap `row`
- **AND** cada card DEBE tener columna responsive

#### Scenario: Clases responsive de columnas
- **WHEN** columns es 3
- **THEN** cada card DEBE tener `col-12 col-md-6 col-lg-4`
- **AND** para columns=4: `col-12 col-md-6 col-lg-3`
- **AND** para columns=2: `col-12 col-md-6`
- **AND** para columns=1: `col-12`

#### Scenario: Sin resultados
- **WHEN** el query no encuentra posts
- **THEN** DEBE mostrar mensaje "No se encontraron publicaciones"
- **AND** NO DEBE romper layout

#### Scenario: Escaping obligatorio
- **WHEN** se genera HTML
- **THEN** DEBE usar esc_html() para textos
- **AND** DEBE usar esc_attr() para atributos
- **AND** DEBE usar esc_url() para URLs
- **AND** DEBE usar wp_kses_post() para excerpts

---

### Requirement: CSS via CSSGenerator

The shortcode MUST use CSSGeneratorInterface for styles.

#### Scenario: Generacion de CSS
- **WHEN** PostGridShortcodeRenderer genera CSS
- **THEN** DEBE inyectar CSSGeneratorInterface
- **AND** DEBE usar settings de post-grid desde BD
- **AND** DEBE generar CSS inline en el shortcode

#### Scenario: Selector unico
- **WHEN** se genera CSS
- **THEN** DEBE usar selector `.roi-post-grid-shortcode`
- **AND** si se especifica id, usar `.roi-post-grid-shortcode-{id}`
- **AND** NO DEBE conflictuar con post-grid del template

---

### Requirement: Registro del Shortcode

The shortcode MUST be registered in WordPress.

#### Scenario: Registro en bootstrap
- **WHEN** WordPress carga el tema
- **THEN** functions-addon.php DEBE llamar PostGridShortcodeRegistrar::register()
- **AND** DEBE estar disponible en editor clasico y Gutenberg

#### Scenario: Metodo register estatico
- **WHEN** se llama PostGridShortcodeRegistrar::register()
- **THEN** DEBE ejecutar add_shortcode('roi_post_grid', ...)
- **AND** DEBE usar DIContainer para obtener dependencias

---

## Implementation Order

### Fase 1: Interfaces y DTOs
1. Crear `Shared/Domain/Contracts/PostGridQueryBuilderInterface.php`
2. Crear `Shared/Domain/Contracts/PostGridShortcodeRendererInterface.php`
3. Crear `Shared/Application/UseCases/RenderPostGrid/RenderPostGridRequest.php`

### Fase 2: Use Case
1. Crear `Shared/Application/UseCases/RenderPostGrid/RenderPostGridUseCase.php`
2. Implementar orquestacion de query, settings, render

### Fase 3: Infrastructure - Query
1. Crear `Shared/Infrastructure/Query/PostGridQueryBuilder.php`
2. Implementar construccion de WP_Query con todos los filtros

### Fase 4: Infrastructure - Renderer
1. Crear `Shared/Infrastructure/Ui/PostGridShortcodeRenderer.php`
2. Implementar generacion HTML y CSS

### Fase 5: Infrastructure - Registrar
1. Crear `Shared/Infrastructure/Wordpress/PostGridShortcodeRegistrar.php`
2. Implementar registro y sanitizacion de atributos

### Fase 6: Registro y DI
1. Registrar en DIContainer las implementaciones
2. Llamar register() en functions-addon.php

### Fase 7: Testing
1. Probar en pagina estatica
2. Verificar filtros por categoria, tag
3. Verificar paginacion con id unico

---

## File Structure

```
Shared/
├── Domain/
│   └── Contracts/
│       ├── PostGridQueryBuilderInterface.php
│       └── PostGridShortcodeRendererInterface.php
├── Application/
│   └── UseCases/
│       └── RenderPostGrid/
│           ├── RenderPostGridRequest.php
│           └── RenderPostGridUseCase.php
└── Infrastructure/
    ├── Query/
    │   └── PostGridQueryBuilder.php
    ├── Ui/
    │   └── PostGridShortcodeRenderer.php
    └── Wordpress/
        └── PostGridShortcodeRegistrar.php
```

---

## Examples

### Ejemplo: Grid basico
```
[roi_post_grid]
```

### Ejemplo: Posts de una categoria
```
[roi_post_grid category="precios-unitarios" posts_per_page="6"]
```

### Ejemplo: Multiples shortcodes con paginacion
```
[roi_post_grid id="grid-cursos" category="cursos" show_pagination="true"]

[roi_post_grid id="grid-tutoriales" category="tutoriales" show_pagination="true"]
```

---

## Dependencies

### Existentes (reutilizar)
- `CSSGeneratorInterface` - Para generar CSS
- `ComponentSettingsRepositoryInterface` - Para leer config de post-grid
- `DIContainer` - Para inyeccion de dependencias
- Bootstrap 5 grid system - Para layout responsive

### Nuevas (crear)
- `PostGridQueryBuilderInterface` - Contrato para query builder
- `PostGridShortcodeRendererInterface` - Contrato para renderer
- `RenderPostGridRequest` - DTO de entrada
- `RenderPostGridUseCase` - Orquestador
- `PostGridQueryBuilder` - Implementacion query
- `PostGridShortcodeRenderer` - Implementacion render
- `PostGridShortcodeRegistrar` - Registro WordPress

---

## Testing Checklist

- [ ] Shortcode renderiza sin atributos
- [ ] Filtro por categoria funciona
- [ ] Filtro por multiples categorias funciona
- [ ] Exclusion de categoria funciona
- [ ] Filtro por tag funciona
- [ ] Columnas 1, 2, 3, 4 funcionan
- [ ] Paginacion con id unico funciona
- [ ] Multiples shortcodes paginados funcionan
- [ ] CSS se aplica desde settings de post-grid
- [ ] Mensaje "sin posts" aparece cuando corresponde
- [ ] Escaping correcto en todo el HTML
- [ ] Funciona en editor clasico
- [ ] Funciona en Gutenberg
- [ ] No hay errores PHP
- [ ] Clases tienen menos de 150 lineas