Files
localesp/openspec/changes/rediseno-resenas-tarjeta/design.md
T
edgar.friendly 24cce5dbb9
deploy-branch / deploy (push) Failing after 2s
deploy-branch / teardown (push) Skipped
tests / Unitarias + componente + build (pull_request) Successful in 3m12s
tests / Integración (Nominatim real, opt-in) (pull_request) Skipped
tests / Unitarias + componente + build (push) Successful in 3m9s
tests / Integración (Nominatim real, opt-in) (push) Skipped
fix(resenas,portada): quita el recuento de reseñas y los tres contadores
- ResenasLocal: desaparece la cabecera «Reseñas (N)» que iba encima de
  las tarjetas; el único control de expansión es el botón de ancho
  completo bajo las reseñas («Ver las N reseñas» / «Ver menos»).
- Tarjetas de reseña: las estrellas llevan soporte de línea y padding
  superior para que el hueco de arriba iguale al del resto del contenido.
- App: se eliminan los tres contadores del principio de la página
  (Locales · Provincias · Media ★) y las variables que solo los
  alimentaban (issue #4).

CI: en .gitea/workflows/tests.yml el build de producción pasa a correr
ANTES de las pruebas. La suite incluye un smoke de la SPA servida
(GET / → dist/index.html) y `dist/` está gitignored, así que sin build
previo esa prueba recibía 404 en el runner (hasta ahora el artefacto lo
generaba el job de deploy, que en esta rama falla por no tener entrada
en scripts/entornos.env).

164/164 tests y build en verde.
2026-10-14 00:37:18 +02:00

6.1 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 es únicamente el resto de reseñas; se elimina la cabecera «Reseñas (N)» que vivía encima de las tarjetas (el recuento solo aparece en la etiqueta del botón «Ver las N reseñas» cuando hay más que la vista previa). El único control de ampliar/plegar es ese botón, de ancho completo y situado después del cajón, con aria-expanded.

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). Las estrellas, que usan lineHeight: 0, se envuelven en un contenedor con soporte de línea y paddingTop: 2 para que el hueco superior iguale al del resto del contenido (mismo tratamiento que en el formulario).

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.