Trazza

Texto del repositorio público, commit 8729248. Fuente: docs/claude/ui-patterns.md.

Patrones de UI: responsive, tiras, widgets y análisis IA de earnings

Detalle movido desde CLAUDE.md el 2026-10-04 para que el fichero que se carga en cada sesión solo lleve el índice y las reglas críticas. Léelo antes de tocar esta zona.

Responsive — tres reglas que se aprendieron midiendo (2026-08-01)

Auditoría de /app/gastos con Playwright a 320/375/414/768 px (modo demo, document.scrollWidth vs clientWidth + getBoundingClientRect de cada nodo). Las tres causaban fallos REALES, no teóricos:

  1. Los items de un grid de widgets necesitan min-w-0 ([&>div]:min-w-0 junto al [&>div]:h-full que ya llevaban). Un grid item trae min-width:auto, así que en la columna ÚNICA de móvil basta con UN hijo indeformable para estirar el track y sacar de pantalla a TODOS los widgets. El culpable medido fue el <input> de búsqueda de la lista de movimientos: un input impone su ancho intrínseco (~20 caracteres = 212 px) como mínimo, y llevaba la columna a 367 px dentro de un contenedor de 343 → los 7 widgets desbordaban 8 px. Para el propio input: size={1} + min-w-0 (sin ambos, w-full no basta dentro de un flex).
  2. DialogContent acota su alto y da margen lateral él solo (w-[calc(100%-2rem)] sm:w-full, max-h-[calc(100dvh-2rem)] overflow-y-auto). Sin el tope, un formulario largo centrado con translate-y(-50%) se sale por ARRIBA y por abajo en un teléfono y no hay forma de llegar al botón de guardar. El margen va sobre w-* y NO sobre max-w-* a propósito: los diálogos pasan su propio max-w-md/max-w-4xl y twMerge descartaría un max-w base. dvh, no vh: el viewport móvil encoge con la barra de URL y el teclado.
  3. Mínimo táctil 40 px hasta lg, no hasta sm: una tablet de 768 px sigue siendo táctil. Patrón para botones de icono: min-w-[40px] min-h-[40px] lg:min-w-0 lg:min-h-0. La auditoría encontró 34 botones por debajo de 36 px (los de editar/borrar meta estaban a 26×26). Para agrandar el área táctil SIN mover el icono: -m-3 p-3 (el margen negativo compensa el padding) — así se arregló la X de cerrar de DialogContent, que medía 16×16.
  1. Los diálogos van por ENCIMA de la cabecera de la app (2026-08-18): DialogOverlay/DialogContent estaban en z-50 y la cabecera de DashboardLayout en z-[70], así que un diálogo alto en móvil —que queda a 16px del borde superior— tenía su título Y su botón de cerrar TAPADOS por la cabecera, sin forma de cerrarlo con la X (medido con elementFromPoint sobre el título: devolvía el svg del logo). Ahora z-[96]/z-[97]: por encima de cabecera (70), sidebar móvil (76) y overlay de búsqueda global (90/95), y por DEBAJO de los toasts (z-[100]) — un guardado hecho desde un diálogo tiene que poder confirmarse por encima de él. Al añadir cualquier overlay nuevo, colócalo en esa escala.

Corolario de método: antes de tocar Tailwind "responsive", mide. El instrumento (script Playwright que recorre viewports y lista los nodos que se salen y los targets pequeños) tarda menos en escribirse que en discutirse.

Tiras horizontales: components/ui/ScrollStrip.jsx

Las pestañas de listas de favoritos (widget del Dashboard y pantalla /app/favorites) van dentro de ScrollStrip. Dos cosas que hace y conviene no deshacer:

Análisis IA de una presentación de resultados (widget Earnings)

Al desplegar una fila del widget "Resultados (Earnings)" aparece "Analizar presentación de resultados" (o "Analizar expectativas" si el trimestre aún no se ha publicado) → POST /api/analyze-earnings (withRateLimit('analysis'), misma cuota que el score de cartera).

Widgets personalizables (Dashboard + Gastos)

Orden inicial: DEFAULT_DASHBOARD_ORDER define lo que ve un usuario NUEVO — no puede salir del registry porque el registry está partido en dos arrays (dashboard + gastos) y el orden deseado los intercala. resolveDashboardLayout(saved, registry, defaultOrder) lo aplica SOLO cuando no hay orden guardado; lo que el usuario reordene manda siempre, así que cambiar este orden NO mueve el dashboard de quien ya tenga un layout guardado (tiene que reordenar o restaurar desde el personalizador).

Colocación vigente (2026-09-10, pedida por el owner) con los widgets de gastos apagados:

| Invertido / Favoritos (1) |      Rendimiento (2)      |
|      Wallet Map (2)       | Quesito / Puntuación (1)  |
| Dividendos (1) | Earnings (1) |     Noticias (1)      |

DEFAULT_PAIRS empareja invested+watchlist y allocation+score — ninguna pareja depende ya de la feature de gastos, así que el layout inicial no cambia al encenderla. Noticias pasó de span: 3 a span: 1 para compartir fila con los dos calendarios (petición del owner): su columna es justo la que rellena el sobrante de las dos parejas, así que el layout vuelve a teselar EXACTO (9 columnas, 3 filas). Ojo: el ancho vive en DOS sitios que hay que mover juntos — el span del registry (que es lo que cuadra la retícula y lo que miden los tests) y la clase lg:col-span-* del bloque JSX en Dashboard.jsx. Con los widgets de gastos encendidos sobra 1 columna al final; lo que fija el test es que ningún widget parta una fila y que el hueco solo pueda estar en la ÚLTIMA — uno en medio de la retícula se lee como un widget que no cargó.

Wallet Map: el texto de cada baldosa lo decide layoutTileText (2026-10-15)

PortfolioTreemap.jsx → layoutTileText(label, w, h), pura y con tests (PortfolioTreemap.layout.test.js, medidas de una cartera real de MyInvestor). Prioridades: (1) el porcentaje se coloca primero, nunca más pequeño que el nombre ni por debajo de 10px, y es lo último que se quita; (2) el nombre se parte en hasta 3 líneas equilibradas y la letra baja hasta 9px antes de recortar con "…". Antes era una sola línea con tope de 15px: los nombres de fondo salían como "ISHARES ES…", las baldosas grandes llevaban letra diminuta y en las bajas desaparecía el porcentaje. SVG no mide texto sin pintarlo: la anchura sale de CHAR_WIDTH (0,62 em, estimación con margen); si se cambia la fuente de las baldosas, revisa esa constante. El tamaño de la baldosa es |variación diaria| (useDashboardData), no el valor: el subtítulo "Tamaño = movimiento" es correcto.

Ninguna baldosa sin nombre (2026-10-17): withMinTileSize sube cada baldosa al menos a un 25 % de la mayor (MIN_TILE_SHARE), sin alterar el orden de tamaños: un BTC-USD a −0,07 % junto a un META a −3,72 % era una franja de pocos píxeles sin texto. El tamaño deja de ser exactamente proporcional en las que apenas se movieron, y se acepta: el % de cada una sigue escrito. Si aun así no caben dos líneas, layoutTileText devuelve inline: true y la baldosa pinta nombre y % en la MISMA línea.

Color en degradado (getTileFill): de suave a intenso según la magnitud, satura en ±3 % (GRADIENT_FULL_AT) con raíz cuadrada para separar las variaciones pequeñas de una cartera de fondos. La leyenda es una barra con la MISMA escala (si cambias GAIN_SCALE/LOSS_SCALE o el umbral, la leyenda los sigue sola). getTileColor (sólido) queda para TEXTO —tooltip, chip "Mejor"—, donde un tono pálido no se leería.

Buscador de activos (barra superior → components/search/GlobalSearchBar.jsx)

Revisado a fondo el 2026-10-15. Vive en su propio componente (salió de DashboardLayout, −270 líneas); la ficha que abre es GlobalSearchOverlay.

Capas — no mezclarlas:

UI: precio de TODAS las filas por runPooledSettled, pintado según llega y cortado al cambiar la búsqueda; mercado legible (exchDisp: NASDAQ / Toronto distingue AAPL de AAPL.TO); combobox ARIA (aria-activedescendant, región status con el nº de resultados); historial navegable con flechas, que guarda el OBJETO (elegir una reciente le borraba el nombre) y se puede vaciar; atajo / y Ctrl/Cmd+K (desactivado con la ficha abierta). En móvil el panel es fixed a todo el ancho bajo la cabecera: el campo mide ~90 px y un panel de su ancho era ilegible (ya pasaba antes de la revisión).

Ficha (GlobalSearchOverlay): Escape la cierra (salvo con el desplegable de watchlists abierto); la pantalla de carga tiene botón de cerrar; si la carga falla hay pantalla de error con "Reintentar" — antes devolvía null y dejaba el ticker "abierto", así que volver a elegir ese activo no hacía nada; el gráfico usa el símbolo RESUELTO (quoteSymbolRef) al cambiar de periodo — con un ISIN sin mapear pedía el histórico del ISIN y salía vacío — y solo pinta la última petición.

Verificación en navegador: guion de Playwright en modo demo (atajo, fondos, "apple", spinner tras borrar, flechas+Enter+Escape, historial, Yahoo caído con page.route → error, símbolo inexistente → "Reintentar" y se puede reabrir, móvil 390 px sin scroll horizontal).

Un widget con lista capada rellena su celda: flex-1 + scroller ABSOLUTO

Patrón compartido por PortfolioNewsWidget y EarningsCalendar (2026-09-20). El problema es el mismo en los dos y volverá en cualquier widget con lista: la celda del grid estira la card con h-full, la fila la marca el widget MÁS ALTO que la comparta, y una card en display:block con la lista clavada en un max-h deja el sobrante en blanco al final — medido en la demo: Noticias 183px de hueco sobre 678, Earnings 175px sobre 693. Y a la vez cortaba la lista a media fila, así que sobraba blanco y faltaba contenido.

La receta, que NO se puede simplificar a "quitar el max-h":

  1. La card es flex flex-col h-full; cabecera y pie, shrink-0.
  2. La lista va en un contenedor relative flex-1 min-h-[N] con el scroller dentro en absolute inset-0 overflow-y-auto overflow-x-hidden.
  3. Lo absoluto no es decorativo: saca el contenido del flujo, así que su alto intrínseco NO cuenta para la fila. Sin eso, una lista larga (6 noticias con miniatura ≈ 530px) estiraría a los vecinos, que es justo lo que el max-h protegía.
  4. El min-h-[N] conserva la contribución que tenía el max-h (380px en Noticias, 420px en Earnings). Sin él la lista colapsa a 0 en móvil, donde la fila mide su contenido y lo absoluto no aporta ninguno.
  5. Un estado de carga con alto FIJO (h-[400px]) pasa a h-full min-h-[400px], o la fila pega un salto al resolverse.

Verificación: el hueco baja a 2px (los bordes) y la fila mantiene su alto — que los vecinos no crezcan es la mitad del arreglo, así que se mide, no se supone.

Como comparte fila con Dividendos y Earnings, la lista de PortfolioNewsWidget no puede estirar la fila: 6 noticias con miniatura miden ~530 px y arrastraban a los dos vecinos. Pero capar su alto con un max-h fijo tampoco vale, y ese fue el bug (2026-09-20): la fila la marca el widget MÁS ALTO que la comparta (Previsión/Calendario, 678 px medidos en la demo) y la card estira con h-full, así que con la lista clavada en 380 px y la card en display:block quedaban 183 px de blanco al final de la card. La solución cumple las dos cosas a la vez: la card es flex flex-col h-full (cabecera y pie shrink-0) y la lista va en un contenedor relative flex-1 min-h-[380px] con el scroller absolute inset-0 — al estar fuera de flujo, su contenido no cuenta para el alto intrínseco de la fila, y el min-h conserva EXACTAMENTE la contribución del max-h anterior (sin él la lista colapsaría a 0 en móvil, donde la fila mide su contenido). El lote inicial es de 8 noticias y no 6 porque, ya rellenando la fila, seis dejaban 36 px sin pintar; a partir de ahí desborda y scrollea. overflow-x-hidden sigue siendo EXPLÍCITO (con overflow-y:auto el eje X computa a auto y pinta una barra horizontal).

Motor único en src/services/dashboardLayout.js (puro, testeado): registries DASHBOARD_WIDGETS, EXPENSES_WIDGETS (widgets de gastos del Dashboard, solo con la feature activa) y EXPENSES_PAGE_WIDGETS (pantalla de Gastos). resolveDashboardLayout(saved, registry) mergea el config guardado con el registry (el registry es la fuente de verdad: widgets nuevos aparecen al final visibles, ids desconocidos se dropean); moveWidget/toggleWidgetVisibility/serializeLayout completan el contrato.

Tailwind 4 (migrado el 2026-10-04) — lo que hay que saber

Migración con @tailwindcss/upgrade y comparación de capturas contra v3 (pantalla a pantalla, al píxel): todas las pantallas revisadas quedaron en 0,00 % salvo variaciones de datos en vivo. Para conseguirlo se añadió en src/index.css:

Y tres diferencias de comportamiento que ya no muerden pero conviene conocer al escribir clases nuevas:

Botón de ampliar, porcentajes, noticias y demo (2026-10-15)

Modo privacidad en el Dashboard: importes Y porcentajes de la cartera (2026-10-15)

Misma regla que Gastos (expenses.md): se ocultan los importes y los porcentajes de TU cartera — variación total del día, % invertido, reparto del quesito, peso en el tooltip del Wallet Map, rendimiento (titular, eje, tooltip, ROI total, "vs S&P 500"). Se siguen viendo las variaciones de cada activo en el mercado (baldosas, Favoritos, movimientos del día): son públicas y no dicen nada de la cartera. En Dashboard.jsx va por formatShare (= formatPercent con privacidad). El tooltip del rendimiento en vista % enseñaba el valor de la cartera en euros aunque la privacidad estuviera activa; ya no.

Wallet Map — value lo pisa Recharts: el Treemap sobrescribe value de cada nodo con su dataKey (size = |variación|). El importe va en marketValue (lo añade PortfolioTreemap) y se formatea con formatMoney que pasa el Dashboard. Antes el tooltip decía "Valor 1" para un BTC de 33.016 €.

Tarjetas de widget: Dividendos y Earnings usan ya el estilo común (rounded-2xl, borde fino, shadow-xs, cabecera px-5 py-3.5 con título text-sm). No vuelvas a meter variantes con rounded-[2.5rem]/degradado/sombra grande: la fila no parecía del mismo panel. Y un título uppercase con truncate necesita leading-tight, no leading-none, o se corta la tilde de las mayúsculas.

Quesito (distribución): sectores, regiones y la etiqueta de cripto se traducen al pintar (sector_names.*, dashboard.region_*); eran literales en español. Las regiones de fondos y acciones usan las MISMAS etiquetas para fundirse en una porción, y REGION_MAP acepta alias de país ("USA", "US", "UK", "Europe"): con solo "United States", la demo pintaba "USA" 35 % y "Norteamérica" 11 % por separado. Las industrias siguen como las da Yahoo (son más de 140).

Dashboard de una cuenta sin posiciones (2026-10-15)

Sin ninguna posición invertida ni liquidez (vista general), el Dashboard pinta EmptyPortfolioHero (qué se verá aquí + "Añadir mi cartera" → /app/brokers?start=import, que abre el importador al llegar) y oculta los widgets que solo dirían "sin datos" con layoutForEmptyPortfolio (services/dashboardLayout, con tests). Se quedan Favoritos y los de gastos. Es el layout que se PINTA (shownLayout): el guardado y el personalizador no cambian, y en cuanto hay posiciones vuelve el del usuario.

Onboarding de una cuenta nueva (2026-10-17) — recorrido verificado con la persona demo vacía y cubierto por npm run test:e2e:onboarding (corre en el CI):

Números según el idioma (2026-10-15)

formatNumber/formatPercent usan appLocale() (lib/formatters), que lee la instancia única de i18next: en-US con la app en inglés, es-ES si no. No escribas 'es-ES' ni toLocaleString() sin locale en una pantalla: el primero ignora el idioma y el segundo sigue al navegador. Excepciones a propósito: panel de admin (interno) y portfolioContextService (texto para la IA).

Pantalla de brokers: importes, textos y tarjetas (2026-10-16)

Privacidad en brokers: usePrivateFormatters (2026-10-16)

Una pantalla que pinta la cartera toma formatMoney/formatNumber/formatPercent/formatMoneyCompact de hooks/usePrivateFormatters (enmascarados en privacidad) en vez de importarlos de lib/formatters: así no hay que acordarse de envolver cada cifra. La tabla de escritorio NUNCA había ocultado nada, y las listas de dividendos/comisiones/liquidez, los gráficos mensuales y las ventas realizadas tampoco (solo las tarjetas de arriba). Se oculta: importes, CANTIDADES (cantidad × precio público = tu valor) y porcentajes de la cartera. Se ve: el precio de mercado (formatPublicMoney) y lo que hace falta para operar (los formularios de alta reciben el formateador sin máscara). El signo va DENTRO del formateador ({ sign: true }): fuera, "+••••%" contaba si ganabas o perdías.