openspec(resenas): cambio rediseno-resenas-tarjeta

Deltas de tarjeta-local (media en la cabecera, formulario de reseña bajo
la barra de acciones, respuesta visual de los botones) y de
resenas-por-local (la sección pierde media y formulario, expande solo
reseñas y su control pasa a ancho completo bajo ellas).
This commit is contained in:
2026-10-13 23:38:32 +02:00
parent 8a7c755ace
commit 92a13915bc
6 changed files with 202 additions and 0 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-13
@@ -0,0 +1,56 @@
# Design: rediseno-resenas-tarjeta
## Context
`LocalCard.jsx` monta la tarjeta del local: cabecera (nombre/provincia), categoría, dirección, enlaces, descripción, `ResenasLocal` (sección de reseñas) y pie con la barra de acciones (Comentar · Reportar · Marcar · Compartir). `ResenasLocal.jsx` es hoy el dueño de todo el estado de reseñas (lista, media, total, formulario, envío, borrado, reporte) y expone `comentar()` por ref para que la barra abra/cierre la sección; su cajón animado contiene el resto de reseñas **y** el formulario. `StarRating.jsx` se usa con tamaños 12 (tarjetas de reseña), 14 (media) y 20 (input). Los estilos son inline; el único CSS global vive en `<style>` de `index.html`.
Consecuencia de la estructura actual: no es posible colocar el formulario debajo de la barra (el formulario vive en el subárbol de `ResenasLocal`) ni mostrar la media en la cabecera (la media vive en `ResenasLocal`) sin reorganizar la propiedad del estado.
## Goals / Non-Goals
**Goals:**
- Media en la cabecera de la tarjeta, arriba a la derecha, a la altura del título.
- Formulario bajo la barra de acciones, visible solo con «Comentar», con ese botón en estado activo mientras está abierto.
- Expandir reseñas amplía solo reseñas, con control de ancho completo debajo de ellas.
- Paddings uniformes en las tarjetas de comentario, tamaño único de estrellas y hover/activo de botones a superficie completa.
- Mantener intacto el contrato con la API (`listarResenas`, `enviarResena`, `borrarResena`, `reportarLocal`) y la identidad anónima.
**Non-Goals:**
- No cambiar el contrato de la API ni el cálculo de la media (servidor).
- No tocar la barra de filtros (cambio `unificar-filtros-iu`) ni la pasarela de propuesta.
- No reordenar el resto de bloques de la tarjeta (descripción, aviso de confirmación, fecha).
## Decisions
### D1 — Un dueño único del estado de reseñas: hook `useResenas(localId, { totalInicial, mediaInicial })`
El estado y las acciones de reseñas (lista, cargando, total, media, reseña propia y valores del formulario, enviando, error, reportada) pasan a un hook. `LocalCard` lo consume y reparte datos a dos componentes presentacionales: `ResenasLocal` (lista + expansión) y `FormularioResena` (formulario). *Alternativas descartadas*: (a) portal del formulario al pie de la tarjeta — mantendría el estado en `ResenasLocal` a costa de un patrón poco habitual en el repo; (b) elevar el estado directamente a `LocalCard` — funciona, pero engorda el contenedor y el hook es la convención ya usada (`useFavoritos`, `useUbicacion`, `useToast`). El hook elimina la necesidad del `ref` imperativo `comentar()`, que desaparece.
### D2 — El formulario se controla desde el hook y se monta bajo la barra
`FormularioResena` es presentacional y controlado (`puntuacion`, `comentario`, `tienePropia`, `enviando`, `error` + callbacks). `LocalCard` guarda `comentando` (solo UI) y lo monta como último hijo de la tarjeta, debajo de la barra. Tras enviar, el hook refresca la lista y actualiza media/total, así que el formulario queda en modo «Actualizar» sin lógica extra.
### D3 — Cajón: solo el resto de reseñas y control de ancho completo
`ResenasLocal` conserva su estado local `abierto` y la animación `grid-template-rows 0fr→1fr`. El contenido del cajón pasa a ser únicamente el resto de reseñas; el control de ampliar/plegar es un botón de ancho completo situado **después** del cajón («Ver las N reseñas ▾» / «Ver menos ▴»), con `aria-expanded`. La cabecera «Reseñas (N)» sigue alternando (sin estrellas, que se mueven a la tarjeta).
### D4 — Un único tamaño de estrellas
`StarRating.jsx` exporta `TAMANO_ESTRELLAS` (14) y ese valor lo usan la media de la cabecera, las tarjetas de reseña y el input de valoración. *Alternativa descartada*: dejar el input a 20 — es lo que hoy provoca la inconsistencia señalada; 14 mantiene el input usable (los botones de estrella conservan su padding).
### D5 — Hover y estado activo por clase CSS (no inline)
Con estilos inline no se pueden expresar `:hover`/`:active`, y un `background` inline anularía la regla de hover. Se añaden clases en el `<style>` de `index.html` (`.btn-hover`, `.btn-hover.activo`) que pintan **el fondo completo del botón** (no solo el icono) en hover, pulsado y estado activo. Las acciones de la barra dejan de fijar `background` inline fuera del estado activo.
### D6 — Padding uniforme en las tarjetas de comentario
La tarjeta de reseña queda con `padding: 12` y el párrafo del comentario con `margin: 0` (hoy tiene `margin: 10`, que desplaza el texto respecto a las estrellas y al pie de la tarjeta).
## Risks / Trade-offs
- [Mover estado y formulario rompe las pruebas existentes de `ResenasLocal`] → la prueba pasa a ser de presentación y la lógica (envío, borrado, reporte, errores) se cubre en `useResenas.spec.js` y `LocalCard.spec.jsx`.
- [Reasignar el tamaño de estrellas cambia el aspecto de las tarjetas de reseña (12→14)] → es el objetivo de «igualar tamaños»; si se prefiere otro valor, se cambia en una constante.
- [El hover por CSS depende de que no quede `background` inline] → se retiran explícitamente de los botones afectados y se comprueba en el navegador.
- [Con el formulario abierto y el cajón plegado, el usuario podría no ver la lista completa] → el formulario es independiente del cajón por diseño (petición explícita).
## Migration Plan
1. Hook `useResenas` + `StarRating.TAMANO_ESTRELLAS` + clases CSS de botones.
2. `ResenasLocal` presentacional (cajón solo con reseñas, control ancho completo, paddings y estrellas).
3. `FormularioResena` y montaje en `LocalCard` bajo la barra, con media en la cabecera y estado activo de «Comentar».
4. Pruebas y verificación en el navegador (servidor local en marcha con datos de ejemplo).
Rollback: revertir los commits del cambio; sin migración de datos.
@@ -0,0 +1,26 @@
# Proposal: rediseno-resenas-tarjeta
## Why
Al usar el prototipo aparecen inconsistencias de usabilidad en la tarjeta del local y su sección de reseñas: la media vive dentro de la sección de reseñas (escondida), el formulario de reseña está dentro del cajón desplegable (así que «ver más reseñas» abre también el formulario), el control de expansión es un enlace pequeño a la izquierda, las tarjetas de comentario tienen el texto con un margen interno asimétrico, hay tres tamaños de estrellas distintos y los botones no responden al pasar el ratón (el sombreado de los estados activos solo tiñe el icono, no la superficie del botón).
## What Changes
- **Cabecera de la tarjeta**: las estrellas de la media pasan a la esquina superior derecha, a la altura del título.
- **Formulario de reseña**: sale del cajón de reseñas y aparece **debajo de la barra de acciones**, solo al pulsar «Comentar»; mientras está abierto, el botón «Comentar» queda en estado activo.
- **Cajón de reseñas**: expandir amplía **solo las reseñas** (el formulario ya no está dentro); el botón de ampliar/plegar pasa a **ancho completo** y se coloca **debajo de las reseñas**.
- **Tarjetas de comentario**: padding uniforme (se elimina el margen interno asimétrico del texto).
- **Estrellas**: un solo tamaño para media, tarjetas de reseña e input de valoración.
- **Botones**: efecto *hover* y estados activos con fondo que cubre **toda la superficie** del botón, no solo el icono.
## Capabilities
### Modified Capabilities
- `tarjeta-local`: la cabecera incorpora la media; la tarjeta aloja el formulario de reseña bajo la barra de acciones; se añade la respuesta visual de los botones (hover y estado activo).
- `resenas-por-local`: la sección desplegable pierde la media y el formulario (se mueven a la tarjeta), expande solo las reseñas y su control de expansión pasa a ancho completo bajo las reseñas.
## Impact
- **Código**: `src/components/LocalCard.jsx`, `src/components/ResenasLocal.jsx`, nuevo `src/components/FormularioResena.jsx`, nuevo `src/hooks/useResenas.js` (dueño único del estado de reseñas), `src/components/StarRating.jsx` (exporta el tamaño único), `index.html` (reglas de hover en los botones).
- **Tests**: `ResenasLocal.spec.jsx` pasa a prueba de presentación; nuevos `FormularioResena.spec.jsx` y `useResenas.spec.js`; `LocalCard.spec.jsx` cubre la cabecera con media, el formulario bajo la barra y la expansión de solo reseñas.
- **Sin cambios** de API, contrato de datos ni moderación.
@@ -0,0 +1,34 @@
# Spec Delta: resenas-por-local
## MODIFIED Requirements
### Requirement: Sección de reseñas desplegable en la tarjeta del local
La tarjeta de cada local SHALL incluir una sección «Reseñas (N)» que carga sus reseñas al montar la tarjeta y muestra las 3 primeras en una fila de tarjetas que ocupa toda la anchura de la tarjeta. Al expandirla, una animación amplía la sección revelando SOLO el resto de reseñas en el mismo grid; el formulario de reseña NO SHALL formar parte de esta sección (vive bajo la barra de acciones de la tarjeta). El control de ampliar/plegar SHALL ser un botón de ancho completo situado debajo de las reseñas («Ver las N reseñas» / «Ver menos»), y la cabecera SHALL seguir alternando el plegado. La media del local NO SHALL mostrarse en esta sección: se muestra en la cabecera de la tarjeta. Cada tarjeta de reseña SHALL incluir un botón «Borrar» cuando sea propia del dispositivo y un botón «Reportar» cuando sea ajena.
#### Scenario: Vista previa sin expandir
- **WHEN** se muestra la tarjeta de un local con reseñas
- **THEN** la sección presenta el total y las 3 reseñas más recientes en fila ocupando toda la anchura, sin interacción y sin estrellas de media
#### Scenario: Expansión solo de reseñas
- **WHEN** el usuario expande la sección de reseñas
- **THEN** la animación revela el resto de reseñas y no aparece ningún formulario
#### Scenario: Control de expansión a ancho completo
- **WHEN** el local tiene más reseñas que la vista previa
- **THEN** el botón «Ver las N reseñas» se muestra debajo de las reseñas ocupando todo el ancho de la tarjeta, y al expandir pasa a «Ver menos»
#### Scenario: Cierre desde la cabecera
- **WHEN** la sección está expandida y el usuario pulsa la cabecera «Reseñas (N)»
- **THEN** la sección se pliega
#### Scenario: Publicar desde el formulario de la tarjeta
- **WHEN** el usuario envía su reseña desde el formulario situado bajo la barra de acciones
- **THEN** su reseña aparece en la lista y el total de la sección se actualiza
#### Scenario: La propia reseña es editable y borrable desde su tarjeta
- **WHEN** el dispositivo ya tiene reseña en ese local
- **THEN** el formulario aparece precargado (Actualizar) y su tarjeta de reseña incluye un botón «Borrar»
#### Scenario: Reportar una reseña ajena
- **WHEN** el usuario pulsa «Reportar» en una tarjeta de reseña ajena
- **THEN** se envía el reporte de esa reseña y la tarjeta lo refleja
@@ -0,0 +1,58 @@
# Spec Delta: tarjeta-local
## MODIFIED Requirements
### Requirement: Estructura de la tarjeta de local
La tarjeta de cada local SHALL presentar sus bloques en este orden: cabecera con el nombre, la provincia y las estrellas de la media arriba a la derecha a la altura del título; 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; barra inferior de acciones y, debajo de ésta, el formulario de reseña cuando esté abierto.
#### 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
#### Scenario: Media en la cabecera
- **WHEN** se muestra la tarjeta de un local con reseñas
- **THEN** las estrellas de la media aparecen en la esquina superior derecha de la cabecera, alineadas con la línea del título
#### Scenario: Formulario bajo la barra de acciones
- **WHEN** el usuario pulsa «Comentar»
- **THEN** el formulario de reseña se muestra como último bloque de la tarjeta, debajo de la barra de acciones
### 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. «Comentar» SHALL alternar el formulario de reseña y SHALL reflejar su estado activo mientras el formulario permanezca abierto.
#### Scenario: Comentar abre el formulario
- **WHEN** el usuario pulsa «Comentar»
- **THEN** el formulario de reseña aparece debajo de la barra de acciones y el botón «Comentar» queda en estado activo (`aria-pressed`)
#### Scenario: Comentar cierra el formulario
- **WHEN** el formulario está abierto y el usuario vuelve a pulsar «Comentar» o usa «Cerrar» del formulario
- **THEN** el formulario desaparece y el botón «Comentar» vuelve a su estado inactivo
#### 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)
## ADDED Requirements
### Requirement: Respuesta visual de los botones
Los botones de la tarjeta y de la sección de reseñas SHALL ofrecer respuesta visual al pasar el puntero y al pulsarlos, y el fondo SHALL cubrir toda la superficie del botón (no solo el icono); los botones con estado activo (Marcar, Comentar) SHALL teñir también su superficie completa.
#### Scenario: Hover sobre un botón
- **WHEN** el puntero pasa por encima de un botón de la tarjeta o de la sección de reseñas
- **THEN** el fondo de todo el botón cambia, no solo el del icono
#### Scenario: Estado activo a superficie completa
- **WHEN** un botón está activo (p. ej. «Marcar» en un local favorito o «Comentar» con el formulario abierto)
- **THEN** el tinte de fondo cubre toda la superficie del botón
@@ -0,0 +1,26 @@
# Tasks: rediseno-resenas-tarjeta
## 1. Base: estrellas, hook y estilos de botón
- [x] 1.1 Exportar `TAMANO_ESTRELLAS` en `StarRating.jsx` y unificar el tamaño de media, tarjetas de reseña e input
- [x] 1.2 Crear `src/hooks/useResenas.js`: dueño único del estado de reseñas (lista, total, media, reseña propia, formulario, enviar, borrar, reportar, error)
- [x] 1.3 Añadir en `index.html` las clases `.btn-hover` / `.btn-hover.activo` con fondo a superficie completa (hover, pulsado y activo)
## 2. Sección de reseñas
- [x] 2.1 `ResenasLocal` presentacional: recibe datos y callbacks, cajón animado solo con el resto de reseñas, control de ampliar/plegar de ancho completo debajo de las reseñas, cabecera sin estrellas
- [x] 2.2 Tarjetas de comentario: padding uniforme (párrafo sin margen interno) y estrellas al tamaño único
## 3. Tarjeta y formulario
- [x] 3.1 Crear `FormularioResena.jsx` (controlado): estrellas 1–5, comentario opcional, Publicar/Actualizar, error y Cerrar
- [x] 3.2 `LocalCard`: media en la esquina superior derecha de la cabecera a la altura del título
- [x] 3.3 `LocalCard`: montar el formulario debajo de la barra de acciones, visible solo con «Comentar», con el botón en estado activo mientras está abierto
- [x] 3.4 Aplicar hover y estado activo (superficie completa) a los botones de la tarjeta, la barra, las tarjetas de reseña y el formulario
## 4. Verificación
- [x] 4.1 `tests/unit/useResenas.spec.js`: carga y precarga de la propia, enviar (media/total y refresco), borrar, reportar y error del servidor
- [x] 4.2 `tests/component/ResenasLocal.spec.jsx` y `tests/component/FormularioResena.spec.jsx`: pruebas de presentación (vista previa, expansión solo de reseñas, control de ancho completo, precarga, aviso de error, Cerrar)
- [x] 4.3 `tests/component/LocalCard.spec.jsx`: media en la cabecera, «Comentar» abre el formulario bajo la barra con estado activo, expandir reseñas no muestra formulario, hover presente en los botones
- [x] 4.4 Suite completa y build en verde, y comprobación en el navegador con los datos de ejemplo