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.

6.6 KiB Raw Blame History