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