feat(tarjeta): rediseño de usabilidad — descripción arriba, vista previa de reseñas y barra de acciones
deploy-branch / deploy (push) Successful in 2m45s
deploy-branch / teardown (push) Skipped
tests / Unitarias + componente + build (push) Failing after 3m3s
tests / Integración (Nominatim real, opt-in) (push) Skipped
tests / Unitarias + componente + build (pull_request) Failing after 2m59s
tests / Integración (Nominatim real, opt-in) (pull_request) Skipped

- La descripción del local pasa a bloque propio ENCIMA de las reseñas
- Reseñas: carga al montar con 2 visibles sin expandir; expansión con
  animación (grid-template-rows 0fr→1fr, 350ms) que revela todas + el
  formulario; pista "Ver las N reseñas" cuando hay más de 2
- Barra inferior a ancho completo: Comentar (expande+enfoca) · Reportar
  (formulario controlado) · Marcar (favorito, corazón fuera de cabecera,
  aria-pressed) · Compartir (antes en cabecera); fecha pequeñita encima
- openspec: archiva resenas-por-local (spec principal creado por sync) y
  abre tarjeta-local-rediseno (specs de tarjeta-local + resenas modificada)

Suite: 138/138 (+6 netos).
This commit is contained in:
2026-10-11 23:21:22 +02:00
parent 478943c58a
commit ebbd7b696e
17 changed files with 724 additions and 188 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-11
@@ -0,0 +1,84 @@
# Design: Rediseño de la tarjeta de local
## Context
Decisiones de entrevista (2026-10-11): Marcar = favorito **solo** en la barra
(el corazón sale de la cabecera); **2 reseñas** visibles en primera vista;
"Comentar" **expande y enfoca** el formulario inline (no modal); barra de
**4 botones** (Comentar · Reportar · Marcar · Compartir) con la fecha en
pequeñito encima y el banner "Sigue aquí" cuando toque. Sin cambios de
backend: es un redisefo de `LocalCard` + `ResenasLocal` + `ReportarLocal`.
## Goals / Non-Goals
**Goals:**
- Jerarquía clara: descripción (datos del local) encima; reseñas (contenido
vivo) debajo, con 2 visibles sin interacción.
- Expansión animada que amplíe la tarjeta revelando todo + formulario.
- Acciones primarias siempre visibles en una barra inferior a ancho completo.
**Non-Goals:**
- Cambios de API/BD (la carga es la misma de `GET …/resenas`, solo cambia
cuándo se dispara).
- Paginación/límite de reseñas por local (futuro si hay locales muy reseñados).
- Virtualización del listado de tarjetas (cada tarjeta hace 1 fetch de
reseñas al montar; con pocos locales es irrelevante).
## Decisions
1. **Carga de reseñas al montar** (`useEffect` en `ResenasLocal`) en vez de
al expandir: la vista previa debe existir sin interacción. Se refresca al
expandir y tras cada escritura. El polling general de locales (5 s) no
refresca reseñas (no hace falta).
2. **Vista previa = 2 reseñas más recientes** (`slice(0, 2)`), la lista
completa vive dentro de la zona animada. Cabecera: `★ media · Reseñas (N)`
+ chevron con `aria-expanded`. Si hay más de 2, una pista "Ver las N
reseñas ▾" bajo la vista previa también expande (área de toque generosa).
3. **Animación con `grid-template-rows: 0fr → 1fr`** (contenedor
`display: grid`, hijo `overflow: hidden`, `transition` 350 ms). Mejor que
`max-height` fijado a ojo (no hay que estimar altura ni recortar contenido
largo) y soportada por todos los navegadores actuales. Con estilos inline,
sin tocar CSS global.
4. **`comentar()` imperativo vía `forwardRef` + `useImperativeHandle`** en
`ResenasLocal`: la barra de `LocalCard` llama al ref → `setAbierto(true)`
→ tras ~360 ms (fin de la transición) `scrollIntoView({ behavior:
"smooth", block: "nearest" })` del formulario y foco en la primera
estrella. `scrollIntoView` se llama con encadenamiento opcional (jsdom no
lo implementa y los tests no deben romperse).
5. **`ReportarLocal` controlado:** props `{ localId, onCerrar,
inicialAbierto }`; la barra lo monta con `inicialAbierto` y `onCerrar` lo
desmonta. Se mantiene autónomo en su lógica de envío (motivo, comentario,
estado enviado). Se renderiza justo encima de la barra, donde vivía el
enlace "Reportar".
6. **Barra inferior = 4 botones iguales** (`flex: 1`, icono Tabler encima y
etiqueta debajo, ~11 px), separada por borde superior; "Marcar" usa
`aria-pressed` + corazón relleno rojizo cuando es favorito. En móvil los 4
caben en un tercio de ancho cada uno sin wrap; si algún día crece, se
permite `flexWrap`.
7. **Cabecera limpia:** salen el corazón y compartir; queda nombre +
provincia. `CategoriaBadge`, dirección y enlaces Maps/Waze no cambian.
## Risks / Trade-offs
- [Un fetch de reseñas por tarjeta al montar] → aceptable con pocos locales
(prod tiene 3); si crece, batch endpoint (`?ids=`) como endurecimiento.
- [Animación `grid-template-rows` en navegadores viejos] → degrada a salto
seco sin romper nada (la propiedad anima o ignora).
- [Vista previa + zona animada duplican render de tarjetas de reseña] → las
2 primeras se renderizan una vez (fuera de la zona animada); dentro solo
van de la 3ª en adelante. Sin duplicación real.
## Migration Plan
Puro frontend, desplegar y ya. Rollback = revert.
## Open Questions
(nada bloqueante; el número mágico 2 de la vista previa y los 350 ms de la
transición son fácilmente ajustables)
@@ -0,0 +1,59 @@
# Proposal: Rediseño de la tarjeta de local (usabilidad)
## Why
La sección de reseñas actual (fila plegable donde antes estaban las estrellas)
esconde todo el contenido tras un clic y mezcla jerarquías: la descripción del
local queda debajo de las reseñas y las acciones están dispersas (corazón y
compartir en la cabecera, reportar abajo en pequeñito). La tarjeta necesita
una jerarquía clara: la descripción del local es del local; las reseñas son
contenido vivo que debe verse sin fricción; y las acciones primarias merecen
una barra propia y visible.
## What Changes
- **Descripción separada y encima:** `local.descripcion` deja de convivir con
las reseñas y se muestra en su propio bloque, encima de la sección de
reseñas.
- **Reseñas con vista previa:** la sección de reseñas carga al montar la
tarjeta y muestra **2 reseñas visibles en la primera vista** (las más
recientes) con la cabecera "★ media · Reseñas (N)".
- **Expansión animada:** al expandir, una animación (transición CSS) amplía la
tarjeta revelando **todas** las reseñas y el formulario inline.
- **Barra inferior de acciones a ancho completo:** el pie de la tarjeta queda
cubierto por cuatro botones — **Comentar · Reportar · Marcar · Compartir**:
- *Comentar*: expande la sección de reseñas (si estaba plegada), hace
scroll suave hasta el formulario y enfoca las estrellas.
- *Reportar*: abre el formulario de reporte del local (antes era un
textuelo "Reportar").
- *Marcar*: favorito (el corazón desaparece de la cabecera; estado activo
visible en la barra).
- *Compartir*: el share se muda de la cabecera a la barra.
- La fecha ("Publicado …") queda en pequeñito justo encima de la barra; el
aviso "Sigue aquí ✅" se mantiene como banner cuando corresponde, encima de
la barra.
## Capabilities
### New Capabilities
- `tarjeta-local`: estructura y acciones de la tarjeta de local — orden de
bloques (descripción sobre reseñas), barra inferior de acciones y sus
comportamientos.
### Modified Capabilities
- `resenas-por-local`: el requisito "Sección de reseñas desplegable en la
tarjeta del local" cambia de carga perezosa tras clic a **carga en la
primera vista con 2 reseñas visibles** y expansión **animada** que revela
todas + formulario, abrible también desde "Comentar".
## Impact
- **Frontend:** `LocalCard.jsx` (reestructura + barra), `ResenasLocal.jsx`
(carga al montar, vista previa de 2, animación, `comentar()` imperativo),
`ReportarLocal.jsx` (controlado: se abre desde la barra).
- **Tests:** rework de `ResenasLocal.spec.jsx` (carga temprana, 2 visibles,
expansión, comentar) y nuevo `LocalCard.spec.jsx` (barra de 4, descripción
encima, Marcar activo).
- **Sin cambios** de backend, BD ni API.
@@ -0,0 +1,22 @@
# Delta: resenas-por-local (UI de la sección de reseñas)
## MODIFIED Requirements
### Requirement: Sección de reseñas desplegable en la tarjeta del local
La tarjeta de cada local SHALL incluir una sección "★ media · Reseñas (N)" que carga sus reseñas al montar la tarjeta y muestra las 2 más recientes visibles en la primera vista; al expandirla, una animación amplía la tarjeta revelando todas las reseñas y el formulario inline (estrellas interactivas 1–5 y comentario opcional de 500 caracteres), con las acciones de publicar/actualizar y borrar para la reseña del propio dispositivo. La expansión también puede dispararse desde el botón "Comentar" de la barra inferior.
#### Scenario: Vista previa sin expandir
- **WHEN** se muestra la tarjeta de un local con reseñas
- **THEN** la sección de reseñas presenta la media, el total y las 2 reseñas más recientes visibles sin interacción
#### Scenario: Expansión animada
- **WHEN** el usuario expande la sección de reseñas
- **THEN** la tarjeta se amplía con una animación de transición que revela todas las reseñas y el formulario
#### Scenario: Expandir y reseñar
- **WHEN** el usuario expande la sección de reseñas y envía estrellas (y opcionalmente comentario)
- **THEN** su reseña aparece en la lista y la cabecera actualiza número y media
#### Scenario: La propia reseña es editable
- **WHEN** el dispositivo ya tiene reseña en ese local y expande la sección
- **THEN** el formulario aparece precargado con su reseña y ofrece actualizar o borrar
@@ -0,0 +1,33 @@
# Delta Spec: tarjeta-local (nueva capacidad)
## ADDED Requirements
### Requirement: Estructura de la tarjeta de local
La tarjeta de cada local SHALL presentar sus bloques en este orden: nombre y provincia en la cabecera, categoría, dirección, enlaces de navegación, descripción del local (si existe), sección de reseñas, aviso de confirmación (cuando corresponda), fecha de publicación y, como pie, la barra inferior de acciones.
#### Scenario: La descripción va encima de las reseñas
- **WHEN** un local tiene descripción y reseñas
- **THEN** la descripción se muestra como bloque propio, inmediatamente encima de la sección de reseñas y sin mezclarse con ella
#### Scenario: Local sin descripción
- **WHEN** un local no tiene descripción
- **THEN** la tarjeta pasa de los enlaces de navegación directamente a la sección de reseñas
### Requirement: Barra inferior de acciones
El pie de la tarjeta SHALL estar ocupado por una barra de botones a ancho completo con, de momento, cuatro acciones: Comentar, Reportar, Marcar y Compartir. La fecha de publicación SHALL quedar como texto secundario justo encima de la barra, y el aviso de confirmación ("Sigue aquí") SHALL mostrarse como banner encima de la barra cuando corresponda.
#### Scenario: Comentar
- **WHEN** el usuario pulsa "Comentar"
- **THEN** la sección de reseñas se expande si estaba plegada, la tarjeta se desplaza suavemente hasta el formulario y el foco pasa a la valoración por estrellas
#### Scenario: Reportar
- **WHEN** el usuario pulsa "Reportar"
- **THEN** se abre el formulario de reporte del local encima de la barra, sin salir de la tarjeta
#### Scenario: Marcar
- **WHEN** el usuario pulsa "Marcar" en un local no marcado
- **THEN** el local pasa a ser favorito y el botón refleja el estado activo (y viceversa al pulsar de nuevo)
#### Scenario: Compartir
- **WHEN** el usuario pulsa "Compartir"
- **THEN** se abre el flujo de compartir del local (nativo del dispositivo o WhatsApp con enlace copiado)
@@ -0,0 +1,42 @@
# Tasks: Rediseño de la tarjeta de local (usabilidad)
> **Estado:** implementado y verificado. `./node_modules/.bin/vitest run` →
> **138/138 en verde** (20 ficheros): rework de `ResenasLocal.spec.jsx`
> (7 tests: carga al montar, vista previa de 2 con la tercera oculta por
> aria-hidden, expansión, comentar() con foco, envío, propia precargada,
> reporte y error) y nuevo `LocalCard.spec.jsx` (5 tests: descripción encima
> por orden DOM, barra de 4, Marcar aria-pressed + persistencia, reporte
> controlado, Comentar expande y enfoca).
> Decisiones de entrevista (2026-10-11): Marcar = favorito solo en la barra,
> 2 reseñas visibles plegada, "Comentar" expande + enfoca el formulario, barra
> de 4 (Comentar · Reportar · Marcar · Compartir), fecha pequeñita encima y
> banner "Sigue aquí" cuando toque. Sin cambios de backend.
## 1. ResenasLocal (vista previa + animación + comentar)
- [x] 1.1 Cargar las reseñas al montar (`useEffect`) en vez de al expandir; refrescar al expandir y tras cada escritura
- [x] 1.2 Vista previa: mostrar las 2 reseñas más recientes sin expandir; cabecera "★ media · Reseñas (N)" + chevron `aria-expanded`; pista "Ver las N reseñas ▾" cuando haya más de 2
- [x] 1.3 Zona animada `grid-template-rows: 0fr → 1fr` (350 ms, hijo `overflow: hidden`) que contiene el resto de reseñas y el formulario
- [x] 1.4 `comentar()` imperativo (`forwardRef` + `useImperativeHandle`): expande, scroll suave hasta el formulario (`scrollIntoView` opcional-safe) y foco en la primera estrella tras la transición
## 2. ReportarLocal controlado
- [x] 2.1 Props `{ localId, onCerrar, inicialAbierto }`: montar ya abierto desde la barra; "Cancelar" desmonta vía `onCerrar` (mantener el flujo motivo/comentario/enviado intacto)
## 3. LocalCard (reestructura + barra de acciones)
- [x] 3.1 Cabecera limpia: fuera corazón y compartir; queda nombre + provincia (CategoriaBadge, dirección y enlaces sin cambios)
- [x] 3.2 Descripción del local en bloque propio ENCIMA de la sección de reseñas
- [x] 3.3 Barra inferior a ancho completo con 4 botones (icono + etiqueta): Comentar (→ `resenasRef.comentar()`), Reportar (monta el formulario encima de la barra), Marcar (`aria-pressed`, corazón relleno en activo) y Compartir (flujo existente)
- [x] 3.4 Fecha "Publicado …" en pequeñito justo encima de la barra; banner "Sigue aquí" y mensaje de confirmado encima de la barra cuando corresponda
## 4. Tests
- [x] 4.1 Rework de `tests/component/ResenasLocal.spec.jsx`: carga al montar sin expandir, vista previa de 2 (y pista "Ver las N"), expansión muestra todas + formulario, `comentar()` via ref expande y enfoca, propia precargada (Actualizar/Borrar), reporte de ajena, error de servidor
- [x] 4.2 Nuevo `tests/component/LocalCard.spec.jsx`: descripción encima de la sección de reseñas, barra con los 4 botones, "Marcar" alterna `aria-pressed`, "Reportar" abre el formulario controlado
- [x] 4.3 Suite completa en verde: `./node_modules/.bin/vitest run`
## 5. Cierre
- [x] 5.1 Commit + push y verificación del despliegue en prototipo-yb01.localesp.es