roi-theme/openspec/specs/flujo-componentes/spec.md

Especificacion de Flujo de Componentes

Purpose

Define el flujo de trabajo de 5 fases para crear componentes en ROITheme, incluyendo convenciones de nomenclatura, estructura de archivos y validacion.

Requirements

Requirement: Nomenclatura NO NEGOCIABLE

The system MUST follow strict naming conventions that are NON-NEGOTIABLE.

Scenario: Nomenclatura de component_name en JSON y BD

• WHEN se define el nombre del componente en JSON o base de datos
• THEN DEBE usar kebab-case
• AND ejemplo: featured-image, hero-section, top-bar

Scenario: Nomenclatura de archivo schema JSON

• WHEN se crea un archivo de schema JSON
• THEN el nombre DEBE ser kebab-case
• AND ejemplo: featured-image.json, hero-section.json

Scenario: Nomenclatura de carpeta de modulo

• WHEN se crea la carpeta del modulo
• THEN DEBE usar PascalCase
• AND ejemplo: FeaturedImage/, HeroSection/, TopBar/

Scenario: Nomenclatura de namespace PHP

• WHEN se define el namespace PHP
• THEN DEBE usar PascalCase
• AND patron: ROITheme[Contexto][Componente][Capa]

Scenario: Nomenclatura de clases Renderer y FormBuilder

• WHEN se nombran las clases Renderer o FormBuilder
• THEN DEBEN usar PascalCase
• AND ejemplo: FeaturedImageRenderer, HeroSectionFormBuilder

Scenario: Conversion kebab-case a PascalCase

• WHEN se convierte de kebab-case a PascalCase
• THEN se eliminan los guiones
• AND se capitaliza cada palabra
• AND ejemplo: featured-image se convierte en FeaturedImage

---

Requirement: Fase 1 - Creacion de Schema JSON

The first step MUST be creating the component JSON schema.

Scenario: Ubicacion del schema

• WHEN se crea un schema JSON
• THEN DEBE colocarse en Schemas/[nombre-en-kebab-case].json
• AND ejemplo: Schemas/featured-image.json

Scenario: Campo component_name en schema

• WHEN se define component_name en el schema
• THEN DEBE usar kebab-case
• AND ejemplo: component_name con valor featured-image

Scenario: Fuente del schema

• WHEN se extrae informacion para el schema
• THEN DEBE basarse en _planeacion/roi-theme/roi-theme-template/index.html
• AND DEBEN extraerse TODOS los campos CSS y textos del HTML

Scenario: Campos obligatorios de visibilidad

• WHEN se crea un schema
• THEN DEBE incluir is_enabled como boolean
• AND DEBE incluir show_on_desktop como boolean
• AND DEBE incluir show_on_mobile como boolean

Scenario: Grupos JSON estandar con priorities

• WHEN se estructura un schema JSON
• THEN DEBE organizar campos en los 12 grupos estandar con priorities fijas
• AND VISIBILITY DEBE tener priority 10
• AND CONTENT DEBE tener priority 20
• AND TYPOGRAPHY DEBE tener priority 30
• AND COLORS DEBE tener priority 40
• AND SPACING DEBE tener priority 50
• AND VISUAL_EFFECTS DEBE tener priority 60
• AND BEHAVIOR DEBE tener priority 70
• AND LAYOUT DEBE tener priority 80
• AND LINKS, ICONS, MEDIA, FORMS DEBEN tener priority 90

Scenario: Tipos de campo validos en schema

• WHEN se define un campo en el schema JSON
• THEN el type DEBE ser uno de: boolean, text, textarea, url, select, color
• AND si type es select DEBE incluir array de options
• AND si type es boolean el default DEBE ser true o false
• AND si type es color el default DEBE ser formato hexadecimal (#RRGGBB)

Scenario: Campo heading_level para semantica HTML

• WHEN un componente tiene titulo principal
• THEN el grupo TYPOGRAPHY DEBE incluir campo heading_level
• AND heading_level DEBE ser tipo select con options h1, h2, h3, h4, h5, h6
• AND heading_level es critico para jerarquia semantica y SEO

Scenario: Campos de accesibilidad en MEDIA

• WHEN un componente tiene imagenes
• THEN el grupo MEDIA DEBE incluir campo image_alt
• AND image_alt es obligatorio para accesibilidad (WCAG)
• WHEN la imagen puede compartirse en redes sociales
• THEN DEBE incluir campo is_og_image como boolean

Scenario: Campos tipicos del grupo BEHAVIOR

• WHEN un componente tiene comportamiento interactivo
• THEN el grupo BEHAVIOR puede incluir is_sticky, sticky_offset, collapse_on_mobile
• AND para Table of Contents puede incluir generate_jump_links, enable_scrollspy
• AND para animaciones puede incluir animation_type

---

Requirement: Fase 2 - Sincronizacion JSON a BD

The second step MUST synchronize the JSON schema with the database.

Scenario: Comando de sincronizacion

• WHEN se necesita sincronizar un componente
• THEN ejecutar wp roi-theme sync-component [nombre]
• AND ejemplo: wp roi-theme sync-component featured-image

Scenario: Tabla destino

• WHEN se sincroniza
• THEN los datos van a la tabla wp_roi_theme_component_settings

Scenario: Preservacion de valores

• WHEN se sincroniza un schema actualizado
• THEN los valores existentes del usuario DEBEN preservarse
• AND solo se agregan campos nuevos

Scenario: Conversion de valores para almacenamiento

• WHEN se sincroniza un campo a BD
• THEN arrays y objects DEBEN convertirse con json_encode()
• AND booleans DEBEN convertirse a '1' o '0'
• AND otros tipos DEBEN convertirse a string con cast

---

Requirement: Fase 3 - Creacion del Renderer

The third step MUST create the Renderer that converts DB data to HTML + CSS.

Scenario: Ubicacion del Renderer

• WHEN se crea un Renderer
• THEN DEBE colocarse en Public/[PascalCase]/Infrastructure/Ui/[PascalCase]Renderer.php
• AND ejemplo: Public/FeaturedImage/Infrastructure/Ui/FeaturedImageRenderer.php

Scenario: Inyeccion de CSSGeneratorInterface

• WHEN se implementa un Renderer
• THEN DEBE inyectar CSSGeneratorInterface via constructor
• AND NO DEBE tener CSS hardcodeado

Scenario: Generacion de CSS

• WHEN se genera CSS en el Renderer
• THEN DEBE usar $this->cssGenerator->generate()
• AND CERO CSS hardcodeado en el codigo PHP

Scenario: Validacion de visibilidad

• WHEN el Renderer procesa un componente
• THEN DEBE validar is_enabled, show_on_desktop, show_on_mobile
• AND NO renderizar si no cumple condiciones de visibilidad

Scenario: Clases responsive Bootstrap para visibilidad

• WHEN el Renderer genera HTML para show_on_desktop y show_on_mobile
• THEN DEBE usar clases Bootstrap d-none, d-lg-block, d-lg-none
• AND NO DEBE usar CSS custom para visibilidad responsive
• AND el breakpoint principal es lg (992px)

Scenario: Tabla de decision para visibilidad responsive

• GIVEN campos show_on_desktop y show_on_mobile del componente
• WHEN show_on_desktop es false AND show_on_mobile es true
• THEN aplicar clase d-lg-none (solo visible en mobile)
• WHEN show_on_desktop es true AND show_on_mobile es false
• THEN aplicar clases d-none d-lg-block (solo visible en desktop)
• WHEN show_on_desktop es false AND show_on_mobile es false
• THEN NO renderizar componente y retornar string vacio
• WHEN show_on_desktop es true AND show_on_mobile es true
• THEN NO aplicar clases de visibilidad (visible en ambos)

Scenario: Metodo supports

• WHEN se implementa el metodo supports()
• THEN DEBE retornar el nombre en kebab-case
• AND ejemplo: return 'featured-image'

---

Requirement: Contrato de CSSGeneratorInterface

The CSS generation service MUST follow a specific contract defined in Shared.

Scenario: Ubicacion de CSSGeneratorInterface

• WHEN se necesita la interface de generacion CSS
• THEN DEBE estar en Shared/Domain/Contracts/CSSGeneratorInterface.php

Scenario: Firma del metodo generate

• WHEN se implementa CSSGeneratorInterface
• THEN DEBE tener metodo generate(string $selector, array $styles): string
• AND $selector es el selector CSS (ej: '.navbar')
• AND $styles es array asociativo de propiedades CSS
• AND retorna string CSS formateado

Scenario: Conversion de propiedades CSS

• WHEN CSSGeneratorService procesa array de estilos
• THEN DEBE convertir snake_case a kebab-case
• AND ejemplo: background_color se convierte en background-color

---

Requirement: Fase 4 - Creacion del FormBuilder

The fourth step MUST create the FormBuilder for the admin panel.

Scenario: Ubicacion del FormBuilder

• WHEN se crea un FormBuilder
• THEN DEBE colocarse en Admin/[PascalCase]/Infrastructure/Ui/[PascalCase]FormBuilder.php
• AND ejemplo: Admin/FeaturedImage/Infrastructure/Ui/FeaturedImageFormBuilder.php

Scenario: Inyeccion de AdminDashboardRenderer

• WHEN se implementa un FormBuilder
• THEN DEBE inyectar AdminDashboardRenderer

---

Requirement: Contrato de AdminDashboardRenderer

The admin panel rendering service MUST follow a specific contract.

Scenario: Ubicacion de AdminDashboardRenderer

• WHEN se necesita el renderer del panel admin
• THEN DEBE estar en Admin/Shared/Infrastructure/Ui/AdminDashboardRenderer.php

Scenario: Responsabilidad de AdminDashboardRenderer

• WHEN se usa AdminDashboardRenderer
• THEN DEBE generar el HTML de controles de formulario
• AND DEBE aplicar el Design System del admin (gradiente, bordes)
• AND DEBE usar Bootstrap 5 form controls

Scenario: Design System del admin

• WHEN se implementa la UI del admin
• THEN DEBE usar gradiente #0E2337 a #1e3a5f
• AND borde naranja #FF8600
• AND Bootstrap 5 form controls

Scenario: Registro en getComponents

• WHEN se registra el FormBuilder
• THEN DEBE registrarse en getComponents() con ID en kebab-case
• AND ejemplo: 'featured-image'

---

Requirement: Fase 5 - Validacion de Arquitectura

The fifth and final step MUST validate the component architecture.

Scenario: Comando de validacion

• WHEN se necesita validar un componente
• THEN ejecutar php Shared/Infrastructure/Scripts/validate-architecture.php [nombre]
• AND ejemplo: php Shared/Infrastructure/Scripts/validate-architecture.php featured-image

Scenario: Elementos validados

• WHEN se ejecuta la validacion
• THEN DEBE validar estructura de carpetas
• AND DEBE validar schema JSON
• AND DEBE validar datos en BD
• AND DEBE validar Renderer
• AND DEBE validar FormBuilder
• AND DEBE validar cumplimiento SOLID

---

Requirement: Estructura de Archivos por Componente

A complete component MUST have a specific file structure.

Scenario: Estructura de componente en Public

• GIVEN un componente FeaturedImage en Public
• WHEN esta completo
• THEN DEBE existir Public/FeaturedImage/Infrastructure/Ui/FeaturedImageRenderer.php

Scenario: Estructura de componente en Admin

• GIVEN un componente FeaturedImage en Admin
• WHEN esta completo
• THEN DEBE existir Admin/FeaturedImage/Infrastructure/Ui/FeaturedImageFormBuilder.php

Scenario: Archivo schema

• GIVEN un componente FeaturedImage
• WHEN se necesita el schema
• THEN DEBE existir en Schemas/featured-image.json

---

Requirement: Variables CSS del Tema

Code MUST use the theme CSS variables.

Scenario: Variables de color disponibles

• WHEN se necesitan colores
• THEN DEBEN usarse las variables como --color-navy-dark y --color-orange-primary

Scenario: Prohibicion de CSS hardcodeado

• WHEN se genera CSS
• THEN NO DEBE haber colores hardcodeados en PHP
• AND DEBE usarse CSSGeneratorService

---

Requirement: Reglas NO Negociables del Flujo

These rules MUST always be followed, without exceptions.

Scenario: Creacion de archivos

• WHEN se van a crear archivos para un componente
• THEN DEBE leerse primero el template HTML
• AND NO crear archivos sin esa referencia

Scenario: Campos de visibilidad

• WHEN se crea un schema
• THEN NO DEBE omitirse ninguno de los 3 campos obligatorios de visibilidad

Scenario: CSS en Renderers

• WHEN se implementa un Renderer
• THEN NO DEBE haber CSS inline
• AND todo via CSSGeneratorService

Scenario: Instanciacion de servicios

• WHEN se necesita un servicio
• THEN NO instanciar directamente con new Service()
• AND DEBE usarse Inyeccion de Dependencias

Scenario: Modificacion de campos en BD

• WHEN se necesita modificar campos
• THEN NO modificar campos en BD manualmente
• AND modificar el schema JSON y sincronizar

Scenario: Validacion de arquitectura

• WHEN se completa un componente
• THEN NO saltarse la validacion de arquitectura
• AND ejecutar validate-architecture.php

Scenario: Fases completas

• WHEN se crea un componente
• THEN NO crear componentes sin completar las 5 fases
• AND cada fase es obligatoria

---

Requirement: Comandos WP-CLI

WP-CLI commands MUST be executed with the correct configuration.

Scenario: Ubicacion de WP-CLI

• WHEN se necesita ejecutar WP-CLI
• THEN usar C:\xampp\php_8.0.30_backup\wp-cli.phar

Scenario: Sincronizar un componente

• WHEN se sincroniza un componente especifico
• THEN ejecutar powershell -Command "php 'C:\xampp\php_8.0.30_backup\wp-cli.phar' roi-theme sync-component [nombre]"

Scenario: Sincronizar todos los componentes

• WHEN se sincroniza todo
• THEN ejecutar powershell -Command "php 'C:\xampp\php_8.0.30_backup\wp-cli.phar' roi-theme sync-all-components"

---

Requirement: Flujo de 5 Fases Secuencial

Component creation MUST follow the exact sequence.

Scenario: Flujo completo de 5 fases

• WHEN se crea un nuevo componente
• THEN Fase 1 es crear Schema JSON en Schemas/[nombre].json
• AND Fase 2 es sincronizar con wp roi-theme sync-component [nombre]
• AND Fase 3 es crear Renderer en Public/[Nombre]/Infrastructure/Ui/[Nombre]Renderer.php
• AND Fase 4 es crear FormBuilder en Admin/[Nombre]/Infrastructure/Ui/[Nombre]FormBuilder.php
• AND Fase 5 es validar con validate-architecture.php [nombre]

Scenario: No saltar fases

• WHEN se desarrolla un componente
• THEN NO se DEBE saltar ninguna fase
• AND cada fase depende de la anterior
• AND la validacion final es obligatoria

---

Requirement: Checklist de Componente Completo

A component MUST pass the checklist to be considered complete.

Scenario: Checklist de archivos

• WHEN se verifica un componente
• THEN DEBE existir Schemas/[nombre-kebab].json
• AND DEBE existir Public/[NombrePascal]/Infrastructure/Ui/[NombrePascal]Renderer.php
• AND DEBE existir Admin/[NombrePascal]/Infrastructure/Ui/[NombrePascal]FormBuilder.php

Scenario: Checklist de codigo

• WHEN se verifica el codigo
• THEN schema tiene los 3 campos de visibilidad
• AND Renderer inyecta CSSGeneratorInterface
• AND Renderer no tiene CSS hardcodeado
• AND supports() retorna kebab-case
• AND FormBuilder registrado con ID kebab-case
• AND validacion de arquitectura pasa

Scenario: Checklist de BD

• WHEN se verifica la base de datos
• THEN datos sincronizados en wp_roi_theme_component_settings
• AND component_name en kebab-case