feat(sprint-5/etapa-3): heatmap gradiente 4 stops + modo percentil + localStorage + fix zoom

- colors.ts: gradiente continuo verde→amarillo→naranja→rojo (interpolación N-stops genérica) - Renombra modos: relative→percentile (rank-based), absolute→minmax - Hook useHeatmapMode(): persiste selección en localStorage con clave inq-roi:heatmap-mode - HeatmapLegend: barra de 4 stops, labels P0/P50/P100 en modo percentil - HeatmapModeToggle: etiquetas "Percentil" / "Min-max" - pdf-sections.ts: leyenda PDF con 4 stops interpolados - BpmnCanvas: controles de zoom movidos a esquina inferior izquierda (evita logo bpmn.io) - Tests: 528 unitarios pasan; E2E recalibrados con vecino más cercano (distancia euclidiana) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-19 18:28:10 -03:00
parent 889929329e
commit a65bec45c3
15 changed files with 593 additions and 176 deletions
--- a/src/lib/colors.ts
+++ b/src/lib/colors.ts
@@ -1,73 +1,66 @@
-// Paleta heatmap: verde → amarillo → rojo
-// INVARIANTE: estos valores DEBEN coincidir con tailwind.config.js heatmap.*
-const HEATMAP_LOW = { r: 16, g: 185, b: 129 }   // #10b981
-const HEATMAP_MID = { r: 245, g: 158, b: 11 }   // #f59e0b
-const HEATMAP_HIGH = { r: 239, g: 68, b: 68 }   // #ef4444
-
+// Paleta heatmap: verde → amarillo → naranja → rojo (4 stops, Sprint 5 Etapa 3)
+// INVARIANTE: estos valores DEBEN coincidir con tailwind.config.js heatmap.* y con
+// drawHeatmapLegend() en src/lib/export/pdf-sections.ts
 export const HEATMAP_LOW_HEX = '#10b981'
 export const HEATMAP_MID_HEX = '#f59e0b'
+export const HEATMAP_HIGH_MID_HEX = '#f97316'
 export const HEATMAP_HIGH_HEX = '#ef4444'

+const HEATMAP_STOPS: Array<[number, string]> = [
+  [0.00, HEATMAP_LOW_HEX],
+  [0.33, HEATMAP_MID_HEX],
+  [0.67, HEATMAP_HIGH_MID_HEX],
+  [1.00, HEATMAP_HIGH_HEX],
+]
+
+function hexToRgb(hex: string): { r: number; g: number; b: number } {
+  const v = hex.replace('#', '')
+  return {
+    r: parseInt(v.slice(0, 2), 16),
+    g: parseInt(v.slice(2, 4), 16),
+    b: parseInt(v.slice(4, 6), 16),
+  }
+}
+
 function lerp(a: number, b: number, t: number): number {
  return Math.round(a + (b - a) * t)
 }

-// t en [0, 1]
-export function heatmapColor(t: number): string {
-  const clamped = Math.max(0, Math.min(1, t))
-  let r: number, g: number, b: number
-
-  if (clamped <= 0.5) {
-    const localT = clamped * 2
-    r = lerp(HEATMAP_LOW.r, HEATMAP_MID.r, localT)
-    g = lerp(HEATMAP_LOW.g, HEATMAP_MID.g, localT)
-    b = lerp(HEATMAP_LOW.b, HEATMAP_MID.b, localT)
-  } else {
-    const localT = (clamped - 0.5) * 2
-    r = lerp(HEATMAP_MID.r, HEATMAP_HIGH.r, localT)
-    g = lerp(HEATMAP_MID.g, HEATMAP_HIGH.g, localT)
-    b = lerp(HEATMAP_MID.b, HEATMAP_HIGH.b, localT)
-  }
-
-  return `rgb(${r}, ${g}, ${b})`
+function lerpColor(c0: string, c1: string, t: number): { r: number; g: number; b: number } {
+  const rgb0 = hexToRgb(c0)
+  const rgb1 = hexToRgb(c1)
+  return { r: lerp(rgb0.r, rgb1.r, t), g: lerp(rgb0.g, rgb1.g, t), b: lerp(rgb0.b, rgb1.b, t) }
 }

-export function heatmapColorHex(t: number): string {
+// Interpolación genérica sobre N stops [t, color-hex] ordenados ascendentemente por t.
+// t se clampea a [0, 1] antes de ubicar el segmento correspondiente.
+function interpolateStops(t: number, stops: Array<[number, string]>): { r: number; g: number; b: number } {
  const clamped = Math.max(0, Math.min(1, t))
-  let r: number, g: number, b: number
-
-  if (clamped <= 0.5) {
-    const localT = clamped * 2
-    r = lerp(HEATMAP_LOW.r, HEATMAP_MID.r, localT)
-    g = lerp(HEATMAP_LOW.g, HEATMAP_MID.g, localT)
-    b = lerp(HEATMAP_LOW.b, HEATMAP_MID.b, localT)
-  } else {
-    const localT = (clamped - 0.5) * 2
-    r = lerp(HEATMAP_MID.r, HEATMAP_HIGH.r, localT)
-    g = lerp(HEATMAP_MID.g, HEATMAP_HIGH.g, localT)
-    b = lerp(HEATMAP_MID.b, HEATMAP_HIGH.b, localT)
+  for (let i = 0; i < stops.length - 1; i++) {
+    const [t0, c0] = stops[i]
+    const [t1, c1] = stops[i + 1]
+    if (clamped <= t1) {
+      const localT = t1 === t0 ? 0 : (clamped - t0) / (t1 - t0)
+      return lerpColor(c0, c1, localT)
+    }
  }
+  return hexToRgb(stops[stops.length - 1][1])
+}

+// t en [0, 1] → color hex del gradiente heatmap (verde → amarillo → naranja → rojo)
+export function intensityToColor(t: number): string {
+  const { r, g, b } = interpolateStops(t, HEATMAP_STOPS)
  return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`
 }

-// Retorna opacidad para colores con alpha (útil para overlays sobre bpmn-js)
+export function heatmapColor(t: number): string {
+  const { r, g, b } = interpolateStops(t, HEATMAP_STOPS)
+  return `rgb(${r}, ${g}, ${b})`
+}
+
+// Retorna color con alpha (útil para overlays sobre bpmn-js)
 export function heatmapColorWithAlpha(t: number, alpha = 0.75): string {
-  const clamped = Math.max(0, Math.min(1, t))
-  let r: number, g: number, b: number
-
-  if (clamped <= 0.5) {
-    const localT = clamped * 2
-    r = lerp(HEATMAP_LOW.r, HEATMAP_MID.r, localT)
-    g = lerp(HEATMAP_LOW.g, HEATMAP_MID.g, localT)
-    b = lerp(HEATMAP_LOW.b, HEATMAP_MID.b, localT)
-  } else {
-    const localT = (clamped - 0.5) * 2
-    r = lerp(HEATMAP_MID.r, HEATMAP_HIGH.r, localT)
-    g = lerp(HEATMAP_MID.g, HEATMAP_HIGH.g, localT)
-    b = lerp(HEATMAP_MID.b, HEATMAP_HIGH.b, localT)
-  }
-
+  const { r, g, b } = interpolateStops(t, HEATMAP_STOPS)
  return `rgba(${r}, ${g}, ${b}, ${alpha})`
 }

@@ -78,7 +71,10 @@ export function getContrastText(t: number): 'white' | 'black' {

 // ─── Helpers para el heatmap del reporte ──────────────────────────────────────

-export type HeatmapMode = 'relative' | 'absolute'
+// percentile: posición relativa por rango entre todas las actividades del proceso (no sufre
+//   distorsión por outliers).
+// minmax: (costo - mínimo) / (máximo - mínimo) — refleja valores absolutos, se comprime con outliers.
+export type HeatmapMode = 'percentile' | 'minmax'

 export interface ActivityCostData {
  expectedTotalCost: number
@@ -101,9 +97,20 @@ export function hasSignificantCostVariance(activities: ActivityCostData[]): bool
  return (max - min) / max > VARIANCE_THRESHOLD
 }

+// Normalización por percentil: posición de `current` en el ranking de costos de `all`.
+// rank = cantidad de actividades estrictamente más baratas. Ties reciben el mismo rango
+// (densidad uniforme). No sufre distorsión por outliers, a diferencia de minmax.
+function percentileNorm(current: ActivityCostData, all: ActivityCostData[]): number {
+  const n = all.length
+  if (n <= 1) return 0.5
+  if (current.expectedTotalCost < 0) return 0 // costo negativo = "más barato posible"
+
+  const currentCost = current.expectedTotalCost
+  const rank = all.filter((a) => a.expectedTotalCost < currentCost).length
+  return rank / (n - 1)
+}
+
 // Calcula t ∈ [0,1] para una actividad dada la lista completa y el modo.
-// Modo relativo: normaliza sobre la actividad más costosa (t=1 = la que más pesa).
-// Modo absoluto: normaliza sobre el rango min-max del proceso.
 // Pre-condición: llamar solo cuando hasSignificantCostVariance = true.
 export function computeActivityT(
  activity: ActivityCostData,
@@ -112,9 +119,8 @@ export function computeActivityT(
 ): number {
  if (allActivities.length === 0) return 0

-  if (mode === 'relative') {
-    const maxPercent = Math.max(...allActivities.map((a) => a.percentOfTotal), 0.001)
-    return Math.max(0, Math.min(1, activity.percentOfTotal / maxPercent))
+  if (mode === 'percentile') {
+    return percentileNorm(activity, allActivities)
  }

  const costs = allActivities.map((a) => a.expectedTotalCost)
@@ -132,19 +138,21 @@ export function activityColor(
  mode: HeatmapMode
 ): string {
  if (!hasSignificantCostVariance(allActivities)) return NEUTRAL_HEATMAP_COLOR
-  return heatmapColorHex(computeActivityT(activity, allActivities, mode))
+  return intensityToColor(computeActivityT(activity, allActivities, mode))
 }

-// Valores de los extremos para la leyenda del heatmap
+// Valores de los extremos para la leyenda del heatmap.
+// percentile: los extremos del gradiente representan el rango (0 = más barata, 100 = más cara),
+//   no un costo o porcentaje literal — el rank no es lineal respecto al costo.
+// minmax: los extremos son el costo mínimo y máximo reales del proceso.
 export function heatmapLegendBounds(
  allActivities: ActivityCostData[],
  mode: HeatmapMode
-): { min: number; mid: number; max: number; unit: 'currency' | 'percent' } {
-  if (allActivities.length === 0) return { min: 0, mid: 50, max: 100, unit: 'percent' }
+): { min: number; mid: number; max: number; unit: 'currency' | 'rank' } {
+  if (allActivities.length === 0) return { min: 0, mid: 50, max: 100, unit: 'rank' }

-  if (mode === 'relative') {
-    const maxPercent = Math.max(...allActivities.map((a) => a.percentOfTotal))
-    return { min: 0, mid: maxPercent / 2, max: maxPercent, unit: 'percent' }
+  if (mode === 'percentile') {
+    return { min: 0, mid: 50, max: 100, unit: 'rank' }
  }

  const costs = allActivities.map((a) => a.expectedTotalCost)
--- a/src/lib/export/pdf-sections.ts
+++ b/src/lib/export/pdf-sections.ts
@@ -28,6 +28,7 @@ export const PDF = {
  slate50: [248, 250, 252] as [number, number, number],
  heatLow: [16, 185, 129] as [number, number, number],
  heatMid: [245, 158, 11] as [number, number, number],
+  heatHighMid: [249, 115, 22] as [number, number, number],
  heatHigh: [239, 68, 68] as [number, number, number],
 }

@@ -155,22 +156,31 @@ export function drawHeatmapLegend(doc: DocLike, startY: number): number {
  doc.setTextColor(...PDF.heatLow)
  doc.text('Bajo costo', x, labelY)

-  // Barra de gradiente: dibujada como N segmentos de colores
+  // Barra de gradiente: dibujada como N segmentos de colores, 4 stops
+  // (mismo gradiente que src/lib/colors.ts — verde → amarillo → naranja → rojo)
+  const heatStops: Array<[number, [number, number, number]]> = [
+    [0.00, PDF.heatLow],
+    [0.33, PDF.heatMid],
+    [0.67, PDF.heatHighMid],
+    [1.00, PDF.heatHigh],
+  ]
  const steps = 40
  const segW = barW / steps
  for (let i = 0; i < steps; i++) {
    const t = i / (steps - 1)
-    let r: number, g: number, b: number
-    if (t <= 0.5) {
-      const lt = t * 2
-      r = Math.round(PDF.heatLow[0] + (PDF.heatMid[0] - PDF.heatLow[0]) * lt)
-      g = Math.round(PDF.heatLow[1] + (PDF.heatMid[1] - PDF.heatLow[1]) * lt)
-      b = Math.round(PDF.heatLow[2] + (PDF.heatMid[2] - PDF.heatLow[2]) * lt)
-    } else {
-      const lt = (t - 0.5) * 2
-      r = Math.round(PDF.heatMid[0] + (PDF.heatHigh[0] - PDF.heatMid[0]) * lt)
-      g = Math.round(PDF.heatMid[1] + (PDF.heatHigh[1] - PDF.heatMid[1]) * lt)
-      b = Math.round(PDF.heatMid[2] + (PDF.heatHigh[2] - PDF.heatMid[2]) * lt)
+    let r = heatStops[heatStops.length - 1][1][0]
+    let g = heatStops[heatStops.length - 1][1][1]
+    let b = heatStops[heatStops.length - 1][1][2]
+    for (let s = 0; s < heatStops.length - 1; s++) {
+      const [t0, c0] = heatStops[s]
+      const [t1, c1] = heatStops[s + 1]
+      if (t <= t1) {
+        const lt = t1 === t0 ? 0 : (t - t0) / (t1 - t0)
+        r = Math.round(c0[0] + (c1[0] - c0[0]) * lt)
+        g = Math.round(c0[1] + (c1[1] - c0[1]) * lt)
+        b = Math.round(c0[2] + (c1[2] - c0[2]) * lt)
+        break
+      }
    }
    doc.setFillColor(r, g, b)
    doc.rect(x + i * segW, startY, segW + 0.1, barH, 'F')
--- a/src/lib/hooks/useHeatmapMode.ts
+++ b/src/lib/hooks/useHeatmapMode.ts
@@ -0,0 +1,33 @@
+import { useState } from 'react'
+import type { HeatmapMode } from '@/lib/colors'
+
+const STORAGE_KEY = 'inq-roi:heatmap-mode'
+const DEFAULT_MODE: HeatmapMode = 'percentile'
+
+function isValidMode(value: string | null): value is HeatmapMode {
+  return value === 'percentile' || value === 'minmax'
+}
+
+// Persiste la preferencia de modo de heatmap en localStorage. Nunca confía en el string
+// crudo leído de localStorage sin validarlo contra los modos válidos.
+export function useHeatmapMode(): [HeatmapMode, (mode: HeatmapMode) => void] {
+  const [mode, setModeState] = useState<HeatmapMode>(() => {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY)
+      return isValidMode(stored) ? stored : DEFAULT_MODE
+    } catch {
+      return DEFAULT_MODE
+    }
+  })
+
+  function setMode(newMode: HeatmapMode) {
+    try {
+      localStorage.setItem(STORAGE_KEY, newMode)
+    } catch {
+      // localStorage no disponible (modo privado, cuota excedida) — continuar sin persistir
+    }
+    setModeState(newMode)
+  }
+
+  return [mode, setMode]
+}