Files
localesp/openspec/changes/rediseno-resenas-tarjeta/design.md
T
edgar.friendly 92a13915bc 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).
2026-10-13 23:38:32 +02:00

5.8 KiB

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.