129 lines
6.6 KiB
Markdown
129 lines
6.6 KiB
Markdown
# 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.
|
|
``` |