docs: add templates-unificados openspec specification

Defines unified listing templates architecture.

Key additions:
- Two new components: archive-header, post-grid
- 10-phase implementation sequence
- _page_visibility group pattern
- Graceful handling of missing content
- CSS pagination via CSSGeneratorService

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

openspec/specs/templates-unificados/spec.md

@@ -0,0 +1,417 @@
+# Especificacion de Templates Unificados para Blog/Archive
+
+## Purpose
+
+Define la arquitectura para unificar todos los templates de listados (blog, categorias, tags, archives) usando la misma estructura que `single.php`, aprovechando el sistema de visibilidad existente para controlar que componentes mostrar en cada contexto. Incluye la creacion de dos nuevos componentes: `archive-header` y `post-grid`.
+
+## Requirements
+
+### Requirement: Template Unificado para Listados
+
+All listing templates MUST use the same structure as single.php.
+
+#### Scenario: Estructura base de templates de listado
+- **WHEN** se implementa home.php, archive.php, category.php o tag.php
+- **THEN** DEBE usar la misma estructura que single.php
+- **AND** DEBE llamar a roi_render_component() para cada componente
+- **AND** la visibilidad se controla via PageVisibilityHelper::shouldShow()
+
+#### Scenario: Componentes que se llaman en templates de listado
+- **WHEN** se renderiza un template de listado
+- **THEN** DEBE llamar a roi_render_component('hero')
+- **AND** DEBE llamar a roi_render_component('archive-header')
+- **AND** DEBE llamar a roi_render_component('post-grid')
+- **AND** DEBE llamar a roi_render_component('table-of-contents') en sidebar
+- **AND** DEBE llamar a roi_render_component('cta-box-sidebar') en sidebar
+- **AND** DEBE llamar a roi_render_component('contact-form')
+- **AND** cada componente decide si renderiza segun show_on_archives
+
+#### Scenario: Determinacion de sidebar en listados
+- **WHEN** se determina si mostrar sidebar en un listado
+- **THEN** DEBE usar roi_should_render_any_wrapper(['table-of-contents', 'cta-box-sidebar'])
+- **AND** si retorna true usar col-lg-9 para contenido principal
+- **AND** si retorna false usar col-lg-12 para contenido principal
+
+#### Scenario: Paginacion en templates de listado
+- **WHEN** se muestra paginacion en un listado
+- **THEN** DEBE usar the_posts_pagination() de WordPress
+- **AND** DEBE aplicar estilos Bootstrap via CSS del componente post-grid
+
+#### Scenario: CSS de paginacion generado por post-grid
+- **WHEN** PostGridRenderer renderiza la paginacion
+- **THEN** el CSS de paginacion DEBE generarse via CSSGeneratorService
+- **AND** DEBE aplicar estilos Bootstrap (nav-links, page-numbers)
+- **AND** los colores DEBEN ser configurables via grupo colors del schema
+
+---
+
+### Requirement: Componente archive-header
+
+The archive-header component MUST display dynamic title and description for archive pages.
+
+#### Scenario: Ubicacion de archivos archive-header
+- **WHEN** se crea el componente archive-header
+- **THEN** schema DEBE estar en Schemas/archive-header.json
+- **AND** Renderer DEBE estar en Public/ArchiveHeader/Infrastructure/Ui/ArchiveHeaderRenderer.php
+- **AND** FormBuilder DEBE estar en Admin/ArchiveHeader/Infrastructure/Ui/ArchiveHeaderFormBuilder.php
+- **AND** FieldMapper DEBE estar en Admin/ArchiveHeader/Infrastructure/FieldMapping/ArchiveHeaderFieldMapper.php
+
+#### Scenario: Namespaces PHP de archive-header
+- **WHEN** se definen los namespaces para archive-header
+- **THEN** Renderer DEBE usar namespace `ROITheme\Public\ArchiveHeader\Infrastructure\Ui`
+- **AND** FormBuilder DEBE usar namespace `ROITheme\Admin\ArchiveHeader\Infrastructure\Ui`
+- **AND** FieldMapper DEBE usar namespace `ROITheme\Admin\ArchiveHeader\Infrastructure\FieldMapping`
+
+#### Scenario: Deteccion automatica de tipo de archivo
+- **WHEN** ArchiveHeaderRenderer detecta el tipo de pagina
+- **THEN** para categoria DEBE mostrar "Categoria: [nombre]"
+- **AND** para tag DEBE mostrar "Etiqueta: [nombre]"
+- **AND** para autor DEBE mostrar "Articulos de: [nombre]"
+- **AND** para fecha DEBE mostrar "Archivo: [Mes Ano]"
+- **AND** para busqueda DEBE mostrar "Resultados para: [termino]"
+- **AND** para blog home DEBE mostrar el valor de blog_title del schema
+
+#### Scenario: Grupos del schema archive-header
+- **WHEN** se define el schema archive-header.json
+- **THEN** DEBE incluir grupo visibility con priority 10
+- **AND** DEBE incluir grupo content con priority 20
+- **AND** DEBE incluir grupo typography con priority 30
+- **AND** DEBE incluir grupo colors con priority 40
+- **AND** DEBE incluir grupo spacing con priority 50
+- **AND** DEBE incluir grupo behavior con priority 70
+- **NOTE** archive-header NO incluye visual_effects (priority 60) porque es un componente de texto simple sin sombras, bordes redondeados ni transiciones hover
+
+#### Scenario: Campos obligatorios de visibility en archive-header
+- **WHEN** se define grupo visibility en schema
+- **THEN** DEBE incluir is_enabled como boolean con default true
+- **AND** DEBE incluir show_on_desktop como boolean con default true
+- **AND** DEBE incluir show_on_mobile como boolean con default true
+
+#### Scenario: Campos de _page_visibility en archive-header
+- **WHEN** se configura visibilidad por tipo de pagina en FieldMapper
+- **THEN** DEBE mapear campo show_on_home en grupo _page_visibility con default false
+- **AND** DEBE mapear campo show_on_posts en grupo _page_visibility con default false
+- **AND** DEBE mapear campo show_on_pages en grupo _page_visibility con default false
+- **AND** DEBE mapear campo show_on_archives en grupo _page_visibility con default true
+- **AND** DEBE mapear campo show_on_search en grupo _page_visibility con default false
+- **NOTE** Los campos _page_visibility NO van en el schema JSON, se manejan via FieldMapper y VisibilityDefaults
+- **NOTE** show_on_archives en true porque este componente solo tiene sentido en archives
+
+#### Scenario: Campos de content en archive-header
+- **WHEN** se define grupo content
+- **THEN** DEBE incluir blog_title como text con default "Blog"
+- **AND** DEBE incluir show_post_count como boolean con default true
+- **AND** DEBE incluir show_description como boolean con default true
+
+#### Scenario: Campos de typography en archive-header
+- **WHEN** se define grupo typography
+- **THEN** DEBE incluir heading_level como select con options ["h1", "h2", "h3", "h4", "h5", "h6"] y default "h1"
+- **AND** DEBE incluir title_size como text con default "2rem"
+- **AND** DEBE incluir title_weight como text con default "700"
+- **AND** DEBE incluir description_size como text con default "1rem"
+
+#### Scenario: Campos de colors en archive-header
+- **WHEN** se define grupo colors
+- **THEN** DEBE incluir title_color como color con default "#0E2337"
+- **AND** DEBE incluir description_color como color con default "#6b7280"
+- **AND** DEBE incluir count_bg_color como color con default "#FF8600"
+- **AND** DEBE incluir count_text_color como color con default "#ffffff"
+
+#### Scenario: Campos de spacing en archive-header
+- **WHEN** se define grupo spacing
+- **THEN** DEBE incluir margin_top como text con default "2rem"
+- **AND** DEBE incluir margin_bottom como text con default "2rem"
+- **AND** DEBE incluir padding como text con default "1.5rem"
+
+#### Scenario: Campos de behavior en archive-header
+- **WHEN** se define grupo behavior
+- **THEN** DEBE incluir is_sticky como boolean con default false
+- **AND** DEBE incluir sticky_offset como text con default "0"
+
+---
+
+### Requirement: Componente post-grid
+
+The post-grid component MUST display posts from the main WordPress loop in a grid layout.
+
+#### Scenario: Ubicacion de archivos post-grid
+- **WHEN** se crea el componente post-grid
+- **THEN** schema DEBE estar en Schemas/post-grid.json
+- **AND** Renderer DEBE estar en Public/PostGrid/Infrastructure/Ui/PostGridRenderer.php
+- **AND** FormBuilder DEBE estar en Admin/PostGrid/Infrastructure/Ui/PostGridFormBuilder.php
+- **AND** FieldMapper DEBE estar en Admin/PostGrid/Infrastructure/FieldMapping/PostGridFieldMapper.php
+
+#### Scenario: Namespaces PHP de post-grid
+- **WHEN** se definen los namespaces para post-grid
+- **THEN** Renderer DEBE usar namespace `ROITheme\Public\PostGrid\Infrastructure\Ui`
+- **AND** FormBuilder DEBE usar namespace `ROITheme\Admin\PostGrid\Infrastructure\Ui`
+- **AND** FieldMapper DEBE usar namespace `ROITheme\Admin\PostGrid\Infrastructure\FieldMapping`
+
+#### Scenario: Diferencia entre post-grid y related-post
+- **WHEN** PostGridRenderer obtiene los posts
+- **THEN** DEBE usar global $wp_query para obtener posts del loop principal
+- **AND** NO DEBE crear su propio WP_Query como hace RelatedPostRenderer
+- **AND** DEBE llamar wp_reset_postdata() al finalizar si modifica el loop
+
+#### Scenario: Grupos del schema post-grid
+- **WHEN** se define el schema post-grid.json
+- **THEN** DEBE incluir grupo visibility con priority 10
+- **AND** DEBE incluir grupo content con priority 20
+- **AND** DEBE incluir grupo typography con priority 30
+- **AND** DEBE incluir grupo colors con priority 40
+- **AND** DEBE incluir grupo spacing con priority 50
+- **AND** DEBE incluir grupo visual_effects con priority 60
+- **AND** DEBE incluir grupo layout con priority 80
+- **AND** DEBE incluir grupo media con priority 90
+
+#### Scenario: Campos obligatorios de visibility en post-grid
+- **WHEN** se define grupo visibility en schema
+- **THEN** DEBE incluir is_enabled como boolean con default true
+- **AND** DEBE incluir show_on_desktop como boolean con default true
+- **AND** DEBE incluir show_on_mobile como boolean con default true
+
+#### Scenario: Campos de _page_visibility en post-grid
+- **WHEN** se configura visibilidad por tipo de pagina en FieldMapper
+- **THEN** DEBE mapear campo show_on_home en grupo _page_visibility con default true
+- **AND** DEBE mapear campo show_on_posts en grupo _page_visibility con default false
+- **AND** DEBE mapear campo show_on_pages en grupo _page_visibility con default false
+- **AND** DEBE mapear campo show_on_archives en grupo _page_visibility con default true
+- **AND** DEBE mapear campo show_on_search en grupo _page_visibility con default true
+- **NOTE** Los campos _page_visibility NO van en el schema JSON, se manejan via FieldMapper y VisibilityDefaults
+- **NOTE** show_on_home en true para mostrar grid en pagina de blog principal
+- **NOTE** show_on_archives en true porque este componente es para listados
+- **NOTE** show_on_search en true para mostrar resultados de busqueda
+
+#### Scenario: Campos de content en post-grid
+- **WHEN** se define grupo content
+- **THEN** DEBE incluir show_thumbnail como boolean con default true
+- **AND** DEBE incluir show_excerpt como boolean con default true
+- **AND** DEBE incluir show_meta como boolean con default true
+- **AND** DEBE incluir show_categories como boolean con default true
+- **AND** DEBE incluir excerpt_length como select con options ["10", "15", "20", "25", "30"] y default "20"
+- **AND** DEBE incluir read_more_text como text con default "Leer mas"
+- **AND** DEBE incluir no_posts_message como text con default "No se encontraron publicaciones"
+
+#### Scenario: Campos de media en post-grid
+- **WHEN** se define grupo media
+- **THEN** DEBE incluir fallback_image como url con default ""
+- **AND** DEBE incluir fallback_image_alt como text con default "Imagen por defecto"
+- **AND** fallback_image_alt es obligatorio para accesibilidad WCAG
+
+#### Scenario: Campos de typography en post-grid
+- **WHEN** se define grupo typography
+- **THEN** DEBE incluir heading_level como select con options ["h2", "h3", "h4", "h5", "h6"] y default "h3"
+- **AND** DEBE incluir card_title_size como text con default "1.1rem"
+- **AND** DEBE incluir card_title_weight como text con default "600"
+- **AND** DEBE incluir excerpt_size como text con default "0.9rem"
+- **AND** DEBE incluir meta_size como text con default "0.8rem"
+
+#### Scenario: Campos de colors en post-grid
+- **WHEN** se define grupo colors
+- **THEN** DEBE incluir card_bg_color como color con default "#ffffff"
+- **AND** DEBE incluir card_title_color como color con default "#0E2337"
+- **AND** DEBE incluir card_hover_bg_color como color con default "#f9fafb"
+- **AND** DEBE incluir card_border_color como color con default "#e5e7eb"
+- **AND** DEBE incluir card_hover_border_color como color con default "#FF8600"
+- **AND** DEBE incluir excerpt_color como color con default "#6b7280"
+- **AND** DEBE incluir meta_color como color con default "#9ca3af"
+- **AND** DEBE incluir category_bg_color como color con default "#FFF5EB"
+- **AND** DEBE incluir category_text_color como color con default "#FF8600"
+
+#### Scenario: Campos de spacing en post-grid
+- **WHEN** se define grupo spacing
+- **THEN** DEBE incluir grid_gap como text con default "1.5rem"
+- **AND** DEBE incluir card_padding como text con default "1.25rem"
+- **AND** DEBE incluir section_margin_top como text con default "0"
+- **AND** DEBE incluir section_margin_bottom como text con default "2rem"
+
+#### Scenario: Campos de visual_effects en post-grid
+- **WHEN** se define grupo visual_effects
+- **THEN** DEBE incluir card_border_radius como text con default "0.5rem"
+- **AND** DEBE incluir card_shadow como text con default "0 1px 3px rgba(0,0,0,0.1)"
+- **AND** DEBE incluir card_hover_shadow como text con default "0 4px 12px rgba(0,0,0,0.15)"
+- **AND** DEBE incluir card_transition como text con default "all 0.3s ease"
+- **AND** DEBE incluir image_border_radius como text con default "0.375rem"
+
+#### Scenario: Campos de layout en post-grid
+- **WHEN** se define grupo layout
+- **THEN** DEBE incluir columns_desktop como select con options ["2", "3", "4"] y default "3"
+- **AND** DEBE incluir columns_tablet como select con options ["1", "2", "3"] y default "2"
+- **AND** DEBE incluir columns_mobile como select con options ["1", "2"] y default "1"
+- **AND** DEBE incluir image_position como select con options ["top", "left", "none"] y default "top"
+
+---
+
+### Requirement: Manejo Graceful de Contenido Faltante
+
+The post-grid component MUST handle missing content gracefully.
+
+#### Scenario: Post sin imagen destacada
+- **WHEN** un post no tiene thumbnail y show_thumbnail es true
+- **THEN** si fallback_image tiene valor DEBE mostrar esa imagen con fallback_image_alt
+- **AND** si fallback_image esta vacio DEBE omitir la imagen sin romper el layout
+- **AND** NO DEBE mostrar imagen rota o placeholder generico
+
+#### Scenario: Post sin excerpt
+- **WHEN** un post no tiene excerpt y show_excerpt es true
+- **THEN** DEBE generar excerpt automatico desde post_content
+- **AND** DEBE respetar excerpt_length del schema
+- **AND** DEBE usar wp_trim_words() para truncar
+
+#### Scenario: Post sin categorias
+- **WHEN** un post no tiene categorias y show_categories es true
+- **THEN** DEBE omitir la seccion de categorias
+- **AND** NO DEBE mostrar "Sin categoria" u otro texto placeholder
+
+#### Scenario: No posts found - Query vacia
+- **WHEN** have_posts() retorna false en un template de listado
+- **THEN** post-grid DEBE mostrar mensaje configurable de "no hay posts"
+- **AND** el mensaje DEBE usar campo no_posts_message del schema con default "No se encontraron publicaciones"
+- **AND** DEBE aplicar estilos consistentes con el design system
+- **AND** NO DEBE romper el layout de la pagina
+
+---
+
+### Requirement: Visibilidad por Tipo de Pagina
+
+Components MUST respect the show_on_archives setting in _page_visibility group.
+
+#### Scenario: Patron de visibilidad por tipo de pagina
+- **WHEN** se implementa visibilidad por tipo de pagina
+- **THEN** los campos show_on_home, show_on_posts, show_on_pages, show_on_archives, show_on_search
+- **AND** DEBEN estar en grupo _page_visibility (NO en visibility)
+- **AND** DEBEN mapearse via FieldMapper del componente
+- **AND** DEBEN evaluarse via PageVisibilityHelper::shouldShow()
+
+#### Scenario: Configuracion por defecto de show_on_archives para nuevos componentes
+- **WHEN** se configura _page_visibility para componentes nuevos
+- **THEN** archive-header DEBE tener show_on_archives true en _page_visibility
+- **AND** post-grid DEBE tener show_on_archives true en _page_visibility
+
+#### Scenario: Componentes existentes en archives
+- **WHEN** se evalua que componentes mostrar en archives via _page_visibility
+- **THEN** hero DEBE tener show_on_archives false por defecto (configurable)
+- **AND** table-of-contents DEBE tener show_on_archives false
+- **AND** featured-image DEBE tener show_on_archives false
+- **AND** social-share DEBE tener show_on_archives false
+- **AND** related-post DEBE tener show_on_archives false
+- **AND** cta-box-sidebar DEBE tener show_on_archives true
+- **AND** contact-form DEBE tener show_on_archives configurable
+
+#### Scenario: Llamada a componente con visibilidad deshabilitada (Patron Template Unificado)
+- **GIVEN** el template unificado llama a TODOS los componentes para mantener consistencia
+- **WHEN** un template llama roi_render_component() para un componente
+- **AND** ese componente tiene show_on_archives false
+- **THEN** el componente NO DEBE renderizarse (retorna string vacio)
+- **AND** esto es comportamiento correcto y esperado, NO un error
+- **AND** permite que el admin habilite/deshabilite componentes sin modificar templates
+- **NOTE** Por ejemplo: table-of-contents se llama en sidebar pero no renderiza en archives porque show_on_archives=false
+
+---
+
+### Requirement: Templates a Modernizar
+
+These templates MUST be updated to use the unified structure.
+
+#### Scenario: Modernizar home.php
+- **WHEN** se actualiza home.php
+- **THEN** DEBE reemplazar get_template_part() con roi_render_component()
+- **AND** DEBE eliminar referencia a TemplateParts/content.php
+- **AND** DEBE usar estructura unificada con hero, archive-header, post-grid
+
+#### Scenario: Modernizar archive.php
+- **WHEN** se actualiza archive.php
+- **THEN** DEBE reemplazar get_template_part() con roi_render_component()
+- **AND** DEBE eliminar referencia a TemplateParts/content.php
+- **AND** DEBE usar estructura unificada
+
+#### Scenario: Modernizar category.php
+- **GIVEN** category.php existe en roi-theme/ (verificado)
+- **WHEN** se actualiza category.php
+- **THEN** DEBE reemplazar get_template_part() con roi_render_component()
+- **AND** DEBE eliminar referencia a TemplateParts/content.php
+- **AND** DEBE usar estructura unificada
+
+#### Scenario: Modernizar tag.php
+- **GIVEN** tag.php existe en roi-theme/ (verificado)
+- **WHEN** se actualiza tag.php
+- **THEN** DEBE reemplazar get_template_part() con roi_render_component()
+- **AND** DEBE eliminar referencia a TemplateParts/content.php
+- **AND** DEBE usar estructura unificada
+
+#### Scenario: Modernizar author.php
+- **GIVEN** author.php existe en roi-theme/ (verificado)
+- **WHEN** se actualiza author.php
+- **THEN** DEBE reemplazar get_template_part() con roi_render_component()
+- **AND** DEBE eliminar referencia a TemplateParts/content.php
+- **AND** DEBE usar estructura unificada
+- **AND** archive-header detectara automaticamente contexto de autor
+
+#### Scenario: Modernizar date.php
+- **GIVEN** date.php existe en roi-theme/ (verificado)
+- **WHEN** se actualiza date.php
+- **THEN** DEBE reemplazar get_template_part() con roi_render_component()
+- **AND** DEBE eliminar referencia a TemplateParts/content.php
+- **AND** DEBE usar estructura unificada
+- **AND** archive-header detectara automaticamente contexto de fecha
+
+#### Scenario: Modernizar search.php
+- **GIVEN** search.php existe en roi-theme/ (verificado)
+- **WHEN** se actualiza search.php
+- **THEN** DEBE reemplazar get_template_part() con roi_render_component()
+- **AND** DEBE eliminar referencia a TemplateParts/content.php
+- **AND** DEBE usar estructura unificada con post-grid
+- **AND** archive-header detectara automaticamente contexto de busqueda mostrando "Resultados: [termino]"
+
+---
+
+### Requirement: Orden de Implementacion
+
+Components and templates MUST be implemented in a specific order.
+
+#### Scenario: Secuencia de implementacion
+- **WHEN** se implementa esta especificacion
+- **THEN** Fase 1 es crear componente archive-header (5 pasos del flujo)
+- **AND** Fase 2 es crear componente post-grid (5 pasos del flujo)
+- **AND** Fase 3 es modernizar home.php
+- **AND** Fase 4 es modernizar archive.php
+- **AND** Fase 5 es modernizar category.php
+- **AND** Fase 6 es modernizar tag.php
+- **AND** Fase 7 es modernizar author.php
+- **AND** Fase 8 es modernizar date.php
+- **AND** Fase 9 es modernizar search.php
+- **AND** Fase 10 es configurar visibilidad de componentes existentes
+
+#### Scenario: Cada componente sigue flujo de 5 fases
+- **WHEN** se crea archive-header o post-grid
+- **THEN** DEBE seguir Fase 1: Schema JSON
+- **AND** DEBE seguir Fase 2: Sincronizacion wp roi-theme sync-component
+- **AND** DEBE seguir Fase 3: Renderer
+- **AND** DEBE seguir Fase 4: FormBuilder
+- **AND** DEBE seguir Fase 5: Validacion validate-architecture.php
+
+---
+
+### Requirement: Dependencias Existentes
+
+The implementation MUST use existing infrastructure.
+
+#### Scenario: Uso de PageVisibilityHelper
+- **WHEN** un Renderer verifica visibilidad
+- **THEN** DEBE usar PageVisibilityHelper::shouldShow(componentName)
+- **AND** esta en Shared/Infrastructure/Services/PageVisibilityHelper.php
+
+#### Scenario: Uso de CSSGeneratorInterface
+- **WHEN** un Renderer genera CSS
+- **THEN** DEBE inyectar CSSGeneratorInterface via constructor
+- **AND** DEBE usar $this->cssGenerator->generate()
+
+#### Scenario: Uso de roi_should_render_any_wrapper
+- **WHEN** un template determina si mostrar sidebar
+- **THEN** DEBE usar roi_should_render_any_wrapper()
+- **AND** esta definida en functions-addon.php linea 423
+
+#### Scenario: Uso de DIContainer
+- **WHEN** se instancian servicios
+- **THEN** DEBE usar DIContainer::getInstance()
+- **AND** NO DEBE instanciar servicios con new directamente