Con las mejoras visuales

sprints/sprint-4/ETAPA_4D_PROMPT.md

@@ -0,0 +1,129 @@
+# ETAPA 4D — Frontend renderer: wizard pregunta-por-pantalla
+
+## 1. Objetivo
+Reemplazar el formulario de una sola página (v2) por un wizard que consume el motor
+de flujo (4C) y muestra una pregunta por pantalla, con layout de altura estable.
+El componente es un RENDERER: dibuja la pantalla que el motor resuelve; no contiene
+lógica de flujo (ADR-005).
+
+## 2. Contexto previo
+- Motor de flujo listo y testeado: `lib/form-engine.ts` (resolveScreens, next, back,
+  resolveVisibility) + `lib/form-engine.types.ts`. 16/16 tests.
+- Widgets de input AISLADOS y reutilizables en `components/widgets/`:
+  `radio-group`, `checkbox-group`, `text-short-field`, `text-area-field`
+  (interfaz genérica value/onChange/error — se reutilizan tal cual).
+- `question-renderer.tsx` despacha por `type` — reutilizable con 2 cambios (ver tareas).
+- `survey-form.tsx` (una sola página, secciones por regex) se REESCRIBE entero.
+- `app/page.tsx` query NO trae `hint`/`instance_generator`/`instance_of` (tarea 4.5 pospuesta de 4C).
+- Gaps detectados: falta widget `yes_no`; hay hardcode A1/A2 en question-renderer a quitar.
+- Comportamiento de referencia (NO de arquitectura): mockup `wizard_formulario_mapeo_v3.html`.
+
+## 3. DECISIONES YA TOMADAS — no consultar de nuevo
+- El componente consume el motor; NO reimplementa visibilidad/navegación/instancias.
+- Una pregunta por pantalla. Secciones = pantallas propias (intro con número + descripción).
+- Reutilizar los widgets de `components/widgets/` existentes.
+- Identificación de pantalla por ID estable (el motor ya lo provee).
+- **Layout de altura estable (UX 1+2+3), parte de esta etapa:**
+  - (1) Viewport de altura estable: el enunciado se ancla en una posición consistente
+    (tercio superior), NO centrado vertical. La caja no crece/encoge con el contenido.
+  - (2) Header y footer FIJOS: progreso arriba, navegación (Anterior/Siguiente) abajo,
+    ambos fuera del área que cambia de tamaño. No "saltan" entre pantallas.
+  - (3) Área de respuesta con altura máxima y SCROLL INTERNO cuando hay muchas opciones,
+    con affordance visual (degradado sutil en borde inferior) que indica "hay más abajo".
+- Usar los tokens de marca existentes (el verde RE, variables CSS/Tailwind del proyecto).
+  NO inventar colores nuevos.
+
+## 4. Tareas
+
+### 4.1 Ampliar la query y construir el FormSchema (app/page.tsx)
+- Agregar `hint, instance_generator, instance_of` al `.select(...)`.
+- Transformar las filas de `questions` (incluidas las `type='section'`) en el `FormSchema`
+  que consume el motor.
+- Pasar el schema al nuevo componente wizard.
+
+### 4.2 Nuevo componente wizard (reemplaza survey-form.tsx)
+- Mantiene el `WizardState` del motor (respuestas con instancias, pantalla actual).
+- En cada render: pide al motor la pantalla actual y la dibuja.
+- Navegación: botones Anterior/Siguiente llaman `next`/`back` del motor.
+- Maneja los tipos de pantalla: sección-intro, pregunta, pregunta-de-instancia, fin.
+- Para pantallas de instancia: muestra el badge de contexto ("Familiar X de N").
+
+### 4.3 Layout de altura estable (UX 1+2+3)
+Implementar el layout descrito en las decisiones. Estructura sugerida:
+```
+[header fijo: logo + progreso]          ← no scrollea
+[viewport estable]
+  [sección-header (si aplica)]
+  [enunciado anclado: código + pregunta + hint]   ← posición consistente
+  [área de respuesta: max-height + scroll interno + fade inferior]
+[footer fijo: Anterior | indicador | Siguiente]    ← no scrollea
+```
+- El enunciado aparece en el mismo lugar pantalla tras pantalla.
+- El área de respuesta scrollea internamente; header/footer nunca se mueven.
+
+### 4.4 question-renderer: ajustes
+- Quitar el hardcode A1/A2 (no aplica a v3; 2.1/2.2 son single_choice genéricos).
+- Agregar el caso `yes_no` (lo usan 1.1/1.2). Crear `widgets/yes-no-field.tsx` si no existe,
+  o resolver yes_no con el RadioGroup existente si es lo más simple — proponé cuál.
+- Migrar las shapes de `lib/types.ts` (v2) a `lib/form-engine.types.ts` (v3) donde el
+  renderer reciba datos del motor.
+
+### 4.5 Progreso
+- La barra/indicador de progreso se calcula desde el motor (pantalla actual / total visible),
+  no desde "preguntas respondidas". Reutilizar `progress-bar.tsx` si encaja.
+
+### 4.6 Consentimiento
+- Reutilizar `consent-screen.tsx` como pantalla 1 (Sección 1), o integrarlo como la primera
+  pantalla del wizard — proponé cuál es más limpio dado que ahora todo es wizard.
+
+## 5. Entregables (DoD)
+- [ ] Wizard funcional una-pregunta-por-pantalla consumiendo el motor.
+- [ ] Layout de altura estable: header/footer fijos, enunciado anclado, scroll interno + fade.
+- [ ] Query ampliada con las 3 columnas; FormSchema construido y pasado al componente.
+- [ ] yes_no renderiza; hardcode A1/A2 removido.
+- [ ] Progreso calculado desde el motor.
+- [ ] Widgets de v2 reutilizados (no reescritos).
+- [ ] **Validación visual del director** contra el mockup + criterios de UX estable.
+- [ ] Build sin errores; sin lógica de flujo en el componente (solo consume el motor).
+
+## 6. Qué reportar
+```
+Verificado:
+- Wizard consume el motor (resolveScreens/next/back) ✓ — sin lógica de flujo propia
+- Layout estable: header/footer fijos ✓, enunciado anclado ✓, scroll interno + fade ✓
+- Query ampliada (hint/instance_generator/instance_of) ✓
+- yes_no resuelto vía [RadioGroup | widget nuevo] ✓
+- Hardcode A1/A2 removido ✓
+- Widgets reutilizados: [lista]
+- Build: [resultado]
+- Capturas/descripción visual de 3 pantallas: pregunta corta, pregunta con muchas opciones
+  (scroll interno), sección-intro
+
+Asumido / Decisiones de diseño:
+- [consentimiento como pantalla / yes_no / etc.]
+
+Hallazgos no esperados:
+- [lo que aparezca]
+```
+Reporte con datos concretos, no "se ve bien" (Patrón C.4). Describí el comportamiento del
+layout estable: ¿el enunciado queda en el mismo lugar entre una pregunta de 3 opciones y
+una de 15? ¿El footer se mantiene fijo?
+
+## 7. Qué NO hacer
+- ❌ No poner lógica de flujo/visibilidad/instancias en el componente (vive en el motor).
+- ❌ No reescribir los widgets de input (reutilizarlos).
+- ❌ No implementar el submit todavía (es 4G) ni la validación server-side.
+- ❌ No implementar el autocomplete de barrios (es 4F) — barrio queda como text_short por ahora.
+- ❌ No inventar colores fuera de los tokens de marca.
+- ❌ No tocar v2.1.0-stable, el motor (4C), ni el seed.
+
+## 8. Versionado
+Commit sugerido:
+```
+feat(wizard): renderer pregunta-por-pantalla con layout estable [4D]
+
+Reemplaza el formulario de una página por wizard que consume el motor (4C).
+Layout de altura estable: header/footer fijos, enunciado anclado, scroll
+interno con affordance. Reutiliza widgets de input. Agrega yes_no, quita
+hardcode A1/A2. Query ampliada con columnas declarativas de v3.
+```