plotagents 0.0.0-stage → 0.5.0

package/src/interact.js

@@ -0,0 +1,362 @@
+// Capa de interacción para el navegador: tooltip por marca, crosshair en
+// líneas, leyenda conectada y, en mapas, contorno al pasar, zoom con clic,
+// Ctrl/⌘ + rueda, pellizco y arrastre, con botones +/−/restablecer.
+// Autocontenida (sin imports) para poder incrustarla en HTML.
+
+export function attach(root) {
+  if (!root || root.__pa) return;
+  root.__pa = true;
+  const svg = root.querySelector('svg.pa-chart');
+  if (!svg) return;
+  if (getComputedStyle(root).position === 'static') root.style.position = 'relative';
+  const dark = svg.getAttribute('data-pa-mode') === 'dark';
+  const tipEl = document.createElement('div');
+  tipEl.setAttribute('role', 'tooltip');
+  tipEl.style.cssText = [
+    'position:absolute', 'pointer-events:none', 'z-index:10', 'opacity:0', 'transition:opacity .12s',
+    'padding:8px 10px', 'border-radius:8px', 'font:12.5px/1.45 ' + (svg.getAttribute('font-family') || 'system-ui'),
+    'white-space:nowrap', 'max-width:280px',
+    dark ? 'background:#F2F3FA;color:#141A3F' : 'background:#141A3F;color:#FCFBF9',
+    'box-shadow:0 6px 24px rgba(11,15,43,.18)',
+  ].join(';');
+  root.appendChild(tipEl);
+  const NS = 'http://www.w3.org/2000/svg';
+  const overlay = document.createElementNS(NS, 'g');
+  overlay.setAttribute('pointer-events', 'none');
+  svg.appendChild(overlay);
+  let on = null;
+  let pinned = null;
+
+  const esc = (s) => String(s).replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c]);
+  const show = (html, ev) => {
+    tipEl.innerHTML = html;
+    tipEl.style.opacity = '1';
+    const r = root.getBoundingClientRect();
+    let x = ev.clientX - r.left + 14, y = ev.clientY - r.top + 14;
+    const w = tipEl.offsetWidth, h = tipEl.offsetHeight;
+    if (x + w > r.width) x = ev.clientX - r.left - w - 14;
+    if (y + h > r.height) y = Math.max(0, ev.clientY - r.top - h - 14);
+    tipEl.style.left = x + 'px';
+    tipEl.style.top = y + 'px';
+  };
+  const type = svg.getAttribute('data-pa-type') || '';
+  const isMap = type === 'choropleth' || type === 'symbolmap';
+  const zoomG = svg.querySelector('.pa-zoom');
+  const mapOverlay = document.createElementNS(NS, 'g');
+  mapOverlay.setAttribute('pointer-events', 'none');
+  if (zoomG) zoomG.appendChild(mapOverlay);
+  const hide = () => {
+    tipEl.style.opacity = '0';
+    if (on) on.classList.remove('pa-on');
+    on = null;
+    overlay.innerHTML = '';
+    mapOverlay.innerHTML = '';
+    if (!pinned) svg.classList.remove('pa-focus');
+  };
+  // El título del tooltip hereda el color de la categoría, aclarado u
+  // oscurecido hasta leerse bien sobre el fondo del tooltip; el resto, neutro.
+  const tipBg = dark ? '#F2F3FA' : '#141A3F';
+  const rgb = (h) => { h = String(h).replace('#', ''); if (h.length === 3) h = h.split('').map((c) => c + c).join(''); const n = parseInt(h, 16); return [(n >> 16) & 255, (n >> 8) & 255, n & 255]; };
+  const lum = (c) => { const [r, g, b] = rgb(c).map((v) => { v /= 255; return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; }); return 0.2126 * r + 0.7152 * g + 0.0722 * b; };
+  const ratio = (a, b) => { const [x, y] = [lum(a), lum(b)].sort((m, n) => n - m); return (x + 0.05) / (y + 0.05); };
+  const hex = (a) => '#' + a.map((v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, '0')).join('');
+  const onTip = (c) => {
+    if (!/^#[0-9a-f]{3,6}$/i.test(c || '')) return null;
+    const to = dark ? [20, 26, 63] : [255, 255, 255];
+    const A = rgb(c);
+    for (let t = 0; t <= 1.001; t += 0.05) { const m = hex(A.map((v, i) => v + (to[i] - v) * t)); if (ratio(m, tipBg) >= 4.5) return m; }
+    return null;
+  };
+  const markColor = (node) => {
+    if (!node) return null;
+    const dc = node.getAttribute && (node.getAttribute('data-color') || (node.querySelector('[data-color]') || { getAttribute: () => null }).getAttribute('data-color'));
+    if (dc && /^#/.test(dc)) return dc;
+    const cands = [node, ...node.querySelectorAll('[fill],[stroke]')];
+    for (const n of cands) {
+      const f = n.getAttribute && n.getAttribute('fill');
+      if (f && /^#/.test(f)) return f;
+    }
+    for (const n of cands) {
+      const st = n.getAttribute && n.getAttribute('stroke');
+      if (st && /^#/.test(st) && st.toLowerCase() !== (dark ? '#0b0f2b' : '#fcfbf9')) return st;
+    }
+    return null;
+  };
+  const linesHtml = (txt, color) => {
+    const c = onTip(color);
+    return String(txt).split('\n').map((l, i) => (i === 0
+      ? `<div style="font-weight:600${c ? ';color:' + c : ''}">${c ? `<span style="display:inline-block;width:8px;height:8px;border-radius:2px;background:${color};margin-right:6px;vertical-align:1px"></span>` : ''}${esc(l)}</div>`
+      : `<div style="opacity:.86">${esc(l)}</div>`)).join('');
+  };
+
+  const toSvg = (ev) => {
+    const pt = svg.createSVGPoint();
+    pt.x = ev.clientX; pt.y = ev.clientY;
+    return pt.matrixTransform(svg.getScreenCTM().inverse());
+  };
+
+  svg.addEventListener('pointermove', (ev) => {
+    const t = ev.target;
+    if (t && t.closest && t.closest('.pa-key')) return; // la leyenda maneja su propio foco
+    if (t && t.classList && t.classList.contains('pa-cross')) {
+      const data = JSON.parse(t.getAttribute('data-cross'));
+      const p = toSvg(ev);
+      let best = data[0];
+      for (const d of data) if (Math.abs(d.x - p.x) < Math.abs(best.x - p.x)) best = d;
+      const y0 = +t.getAttribute('data-y0'), y1 = +t.getAttribute('data-y1');
+      overlay.innerHTML =
+        `<line x1="${best.x}" x2="${best.x}" y1="${y0}" y2="${y1}" stroke="${dark ? '#8A90B4' : '#7C819C'}" stroke-width="1"/>` +
+        best.v.map((v) => `<circle cx="${best.x}" cy="${v[2]}" r="4.5" fill="${v[1]}" stroke="${dark ? '#0B0F2B' : '#FCFBF9'}" stroke-width="2"/>`).join('');
+      const rows = [...best.v].sort((a, b) => a[2] - b[2]).map((v) => `<div style="display:flex;gap:8px;align-items:center"><span style="width:8px;height:8px;border-radius:50%;background:${v[1]}"></span><span style="opacity:.86;flex:1">${esc(v[0])}</span><b style="font-weight:600;margin-left:12px">${esc(v[3])}</b></div>`).join('');
+      show(`<div style="font-weight:600;margin-bottom:2px">${esc(best.t)}</div>${rows}`, ev);
+      return;
+    }
+    if (t && t.classList && t.classList.contains('pa-near')) {
+      // Capa densa: busca el punto más cercano (≤ 14 px).
+      const pts = t.__near || (t.__near = JSON.parse(t.getAttribute('data-near')));
+      const p = toSvg(ev);
+      let best = null, bd = 196;
+      for (const q of pts) { const d = (q[0] - p.x) ** 2 + (q[1] - p.y) ** 2; if (d < bd) { bd = d; best = q; } }
+      if (!best) { hide(); return; }
+      overlay.innerHTML = `<circle cx="${best[0]}" cy="${best[1]}" r="6" fill="${best[3]}" stroke="${dark ? '#0B0F2B' : '#FCFBF9'}" stroke-width="2"/>`;
+      if (best[2]) show(linesHtml(best[2], best[3]), ev); else tipEl.style.opacity = '0';
+      return;
+    }
+    const tg = t && t.closest ? t.closest('[data-tip]') : null;
+    if (!tg) { hide(); return; }
+    const mark = tg.classList.contains('pa-m') ? tg : tg.querySelector('.pa-m') && tg.querySelectorAll('.pa-m').length === 1 ? tg.querySelector('.pa-m') : null;
+    if (mark !== on) {
+      if (on) on.classList.remove('pa-on');
+      on = mark;
+      if (isMap) {
+        // Mapas: sin atenuar el resto; un contorno marcado sobre la región (o su círculo).
+        mapOverlay.innerHTML = '';
+        if (on && on.tagName === 'path') mapOverlay.innerHTML = `<path d="${on.getAttribute('d')}" fill="none" stroke="${dark ? '#F2F3FA' : '#141A3F'}" stroke-width="2" stroke-linejoin="round" vector-effect="non-scaling-stroke"/>`;
+        else if (on && on.tagName === 'circle') mapOverlay.innerHTML = `<circle cx="${on.getAttribute('cx')}" cy="${on.getAttribute('cy')}" r="${on.getAttribute('r')}" fill="none" stroke="${dark ? '#F2F3FA' : '#141A3F'}" stroke-width="2" vector-effect="non-scaling-stroke"/>`;
+      } else if (on) { on.classList.add('pa-on'); svg.classList.add('pa-focus'); } else svg.classList.remove('pa-focus');
+    }
+    show(linesHtml(tg.getAttribute('data-tip'), markColor(mark || tg)), ev);
+  });
+  svg.addEventListener('pointerleave', hide);
+
+  // Leyenda conectada: pasar sobre una clave destaca sus marcas (mismo color);
+  // un clic la deja fija, otro clic la suelta.
+  const norm = (c) => String(c || '').trim().toLowerCase();
+  const body = svg.querySelector('.pa-body');
+  const marksOf = (color) => {
+    const c = norm(color);
+    const out = new Set();
+    if (!body) return out;
+    // Clave "punteado": todas las formas marcadas con data-dashed.
+    if (c === 'dashed') { for (const n of body.querySelectorAll('[data-dashed]')) out.add(n.closest('.pa-m') || n); return out; }
+    for (const n of body.querySelectorAll('[fill],[stroke],[data-color]')) {
+      if (n.closest('.pa-legend')) continue;
+      if (norm(n.getAttribute('fill')) === c || norm(n.getAttribute('stroke')) === c || norm(n.getAttribute('data-color')) === c) {
+        const m = n.closest('.pa-m') || n;
+        out.add(m);
+      }
+    }
+    return out;
+  };
+  const focusColor = (color) => {
+    svg.querySelectorAll('.pa-m.pa-on').forEach((n) => n.classList.remove('pa-on'));
+    svg.querySelectorAll('.pa-key').forEach((k) => (k.style.opacity = color && norm(k.getAttribute('data-color')) !== norm(color) ? '0.4' : ''));
+    if (!color) { svg.classList.remove('pa-focus'); return; }
+    const ms = marksOf(color);
+    // Marcas sin clase pa-m (p. ej. etiquetas) no se atenúan: solo las que tienen datos.
+    for (const n of body ? body.querySelectorAll('[fill],[stroke],[data-color]') : []) if (ms.has(n) && !n.classList.contains('pa-m')) n.classList.add('pa-m');
+    ms.forEach((m) => m.classList.add('pa-on'));
+    svg.classList.add('pa-focus');
+  };
+  for (const k of svg.querySelectorAll('.pa-key')) {
+    k.setAttribute('tabindex', '0');
+    k.setAttribute('role', 'button');
+    k.addEventListener('pointerenter', () => { if (!pinned) focusColor(k.getAttribute('data-color')); });
+    k.addEventListener('pointerleave', () => { if (!pinned) focusColor(null); });
+    const toggle = () => { pinned = pinned === k ? null : k; focusColor(pinned ? k.getAttribute('data-color') : null); };
+    k.addEventListener('click', toggle);
+    k.addEventListener('keydown', (e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); toggle(); } });
+  }
+
+  if (zoomG) mapZoom(root, svg, zoomG, { dark, hide });
+}
+
+/**
+ * Zoom y paneo de mapas (buenas prácticas de chartjs-plugin-zoom: la rueda
+ * sola desplaza la página; el zoom pide Ctrl/⌘, para no secuestrar el scroll).
+ * - clic en una región: acerca hasta encuadrarla; otro clic (o Esc, o doble
+ *   clic, o el botón) vuelve a la vista completa.
+ * - Ctrl/⌘ + rueda: zoom alrededor del puntero. Pellizco en pantallas táctiles.
+ * - arrastre con zoom > 1: desplaza. Botones +, − y restablecer (teclado).
+ * El estado sobrevive a los redibujos (slider temporal) en root.__paZoom.
+ */
+function mapZoom(root, svg, z, { dark, hide }) {
+  const [bx, by, bw, bh] = z.getAttribute('data-zoom').split(',').map(Number);
+  const en = svg.getAttribute('data-pa-lang') === 'en';
+  const L = en ? { in: 'Zoom in', out: 'Zoom out', reset: 'Reset zoom', hint: 'Use Ctrl + scroll to zoom the map' } : { in: 'Acercar', out: 'Alejar', reset: 'Restablecer zoom', hint: 'Usa Ctrl + rueda para hacer zoom en el mapa' };
+  const MAX = 14;
+  // El zoom anterior solo vale si el mapa tiene el mismo cuadro (no tras cambiar el ancho).
+  let st = root.__paZoom && root.__paZoom.box === String([bx, by, bw, bh]) ? root.__paZoom : { k: 1, x: 0, y: 0, key: null };
+  let raf = 0;
+  const clamp = (s) => {
+    const k = Math.max(1, Math.min(MAX, s.k));
+    // Sin dejar el mapa fuera del cuadro: el desplazamiento se limita al borde.
+    const minX = bx + bw - (bx + bw) * k, maxX = bx - bx * k;
+    const minY = by + bh - (by + bh) * k, maxY = by - by * k;
+    return { ...s, k, x: Math.min(maxX, Math.max(minX, s.x)), y: Math.min(maxY, Math.max(minY, s.y)) };
+  };
+  const apply = (s) => {
+    z.setAttribute('transform', `translate(${s.x.toFixed(2)},${s.y.toFixed(2)}) scale(${s.k.toFixed(4)})`);
+    svg.classList.toggle('pa-zoomed', s.k > 1.02);
+    svg.style.touchAction = s.k > 1.02 ? 'none' : 'pan-x pan-y';
+    z.style.cursor = s.k > 1.02 ? 'grab' : '';
+    btnReset.hidden = s.k <= 1.02;
+  };
+  const reduced = typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+  const go = (target, animate = true) => {
+    const to = clamp(target);
+    cancelAnimationFrame(raf);
+    const from = { ...st };
+    st = to; root.__paZoom = { ...st, box: String([bx, by, bw, bh]) };
+    if (!animate || reduced) { apply(to); return; }
+    const t0 = performance.now(), D = 520;
+    const step = (now) => {
+      const t = Math.min(1, (now - t0) / D), e = 1 - (1 - t) ** 3;
+      // Interpola en escala logarítmica: el zoom se siente parejo.
+      const k = Math.exp(Math.log(from.k) + (Math.log(to.k) - Math.log(from.k)) * e);
+      const cx = (bx + bw / 2 - from.x) / from.k + ((bx + bw / 2 - to.x) / to.k - (bx + bw / 2 - from.x) / from.k) * e;
+      const cy = (by + bh / 2 - from.y) / from.k + ((by + bh / 2 - to.y) / to.k - (by + bh / 2 - from.y) / from.k) * e;
+      apply({ k, x: bx + bw / 2 - cx * k, y: by + bh / 2 - cy * k });
+      if (t < 1) raf = requestAnimationFrame(step); else apply(to);
+    };
+    raf = requestAnimationFrame(step);
+  };
+  const zoomAt = (k, px, py, animate) => {
+    // Mantiene fijo el punto (px, py) del SVG mientras cambia la escala.
+    const lx = (px - st.x) / st.k, ly = (py - st.y) / st.k;
+    go({ ...st, k, x: px - lx * k, y: py - ly * k, key: null }, animate);
+  };
+  const reset = () => go({ k: 1, x: 0, y: 0, key: null });
+  const toSvg = (cx, cy) => { const p = svg.createSVGPoint(); p.x = cx; p.y = cy; return p.matrixTransform(svg.getScreenCTM().inverse()); };
+
+  // Controles: + / − / restablecer, arriba a la derecha del mapa.
+  const box = document.createElement('div');
+  box.className = 'pa-zoomctl';
+  const fg = dark ? '#F2F3FA' : '#141A3F', bg = dark ? 'rgba(20,26,63,.92)' : 'rgba(252,251,249,.94)', bd = dark ? 'rgba(242,243,250,.22)' : 'rgba(20,26,63,.16)';
+  box.style.cssText = `position:absolute;display:flex;gap:4px;z-index:5;opacity:.0;transition:opacity .15s`;
+  const mk = (label, svgIcon) => {
+    const b = document.createElement('button');
+    b.type = 'button'; b.setAttribute('aria-label', label); b.title = label;
+    // Tamaño fijo en línea: hojas como `figure svg{width:100%}` no deben estirar el ícono.
+    b.innerHTML = svgIcon.replace('<svg ', '<svg style="width:12px;height:12px;display:block;flex:none" ');
+    b.style.cssText = `width:28px;height:28px;display:grid;place-items:center;padding:0;border-radius:7px;border:1px solid ${bd};background:${bg};color:${fg};cursor:pointer;box-shadow:0 1px 3px rgba(11,15,43,.12)`;
+    box.appendChild(b);
+    return b;
+  };
+  const btnIn = mk(L.in, '<svg width="12" height="12" viewBox="0 0 12 12"><path d="M6 2v8M2 6h8" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>');
+  const btnOut = mk(L.out, '<svg width="12" height="12" viewBox="0 0 12 12"><path d="M2 6h8" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>');
+  const btnReset = mk(L.reset, '<svg width="12" height="12" viewBox="0 0 12 12"><path d="M2.5 6a3.5 3.5 0 1 0 1.1-2.55M2.5 1.8v2.2h2.2" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>');
+  const hint = document.createElement('div');
+  hint.style.cssText = `position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);padding:8px 12px;border-radius:8px;background:${dark ? '#F2F3FA' : '#141A3F'};color:${dark ? '#141A3F' : '#FCFBF9'};font:12.5px/1.4 ${svg.getAttribute('font-family') || 'system-ui'};pointer-events:none;opacity:0;transition:opacity .2s;z-index:6`;
+  hint.textContent = L.hint;
+  root.appendChild(box); root.appendChild(hint);
+  svg.style.userSelect = 'none';
+  svg.style.webkitUserSelect = 'none';
+  const place = () => {
+    const r = svg.getBoundingClientRect(), rr = root.getBoundingClientRect();
+    const s = r.width / (svg.viewBox.baseVal.width || r.width);
+    box.style.left = (r.left - rr.left + (bx + bw) * s - 3 * 32) + 'px';
+    box.style.top = (r.top - rr.top + by * s + 4) + 'px';
+  };
+  place();
+  root.addEventListener('pointerenter', () => { place(); box.style.opacity = '1'; });
+  root.addEventListener('pointerleave', () => { box.style.opacity = st.k > 1.02 ? '1' : '0'; });
+  root.addEventListener('focusin', () => { place(); box.style.opacity = '1'; });
+  const center = () => [bx + bw / 2, by + bh / 2];
+  btnIn.addEventListener('click', () => zoomAt(st.k * 1.6, ...center(), true));
+  btnOut.addEventListener('click', () => zoomAt(st.k / 1.6, ...center(), true));
+  btnReset.addEventListener('click', reset);
+  apply(st);
+
+  // Clic en una región: encuadrarla (otro clic en la misma, volver).
+  let moved = false;
+  svg.addEventListener('click', (ev) => {
+    if (moved) { moved = false; return; }
+    if (!(ev.target.closest && ev.target.closest('.pa-zoom'))) return;
+    const m = ev.target.closest && ev.target.closest('.pa-m');
+    if (!m || !m.getBBox) return;
+    const key = m.getAttribute('data-k') || m.getAttribute('d') || m.getAttribute('cx');
+    if (st.key === key) { reset(); return; }
+    const b = m.getBBox();
+    const k = Math.max(1.4, Math.min(MAX, 0.62 * Math.min(bw / Math.max(b.width, 4), bh / Math.max(b.height, 4))));
+    const cx = b.x + b.width / 2, cy = b.y + b.height / 2;
+    hide();
+    go({ k, x: bx + bw / 2 - cx * k, y: by + bh / 2 - cy * k, key });
+  });
+  svg.addEventListener('dblclick', (ev) => { if (ev.target.closest && ev.target.closest('.pa-zoom')) { ev.preventDefault(); reset(); } });
+  const onKey = (e) => { if (e.key === 'Escape' && st.k > 1.02 && root.isConnected) reset(); };
+  if (root.__paKey) document.removeEventListener('keydown', root.__paKey);
+  root.__paKey = onKey;
+  document.addEventListener('keydown', onKey);
+
+  // Ctrl/⌘ + rueda (o gesto de trackpad, que llega con ctrlKey): zoom en el puntero.
+  let hintT = 0;
+  svg.addEventListener('wheel', (ev) => {
+    if (!(ev.target.closest && ev.target.closest('.pa-zoom-clip'))) return;
+    if (!ev.ctrlKey && !ev.metaKey) {
+      if (st.k > 1.02) return;
+      hint.style.opacity = '1'; clearTimeout(hintT); hintT = setTimeout(() => (hint.style.opacity = '0'), 1100);
+      return;
+    }
+    ev.preventDefault();
+    const p = toSvg(ev.clientX, ev.clientY);
+    zoomAt(st.k * Math.exp(-ev.deltaY * 0.004), p.x, p.y, false);
+  }, { passive: false });
+
+  // Arrastre (zoom > 1) y pellizco (dos dedos).
+  const ptrs = new Map();
+  let drag = null, pinch = null;
+  svg.addEventListener('pointerdown', (ev) => {
+    if (!(ev.target.closest && ev.target.closest('.pa-zoom-clip'))) return;
+    moved = false;
+    ptrs.set(ev.pointerId, { x: ev.clientX, y: ev.clientY });
+    if (ptrs.size === 2) {
+      const [a, b] = [...ptrs.values()];
+      const mid = toSvg((a.x + b.x) / 2, (a.y + b.y) / 2);
+      pinch = { d: Math.hypot(a.x - b.x, a.y - b.y), k: st.k, mid };
+      drag = null;
+    } else if (st.k > 1.02) {
+      ev.preventDefault(); // sin selección de texto al arrastrar
+      drag = { x: ev.clientX, y: ev.clientY, sx: st.x, sy: st.y };
+    }
+  });
+  svg.addEventListener('pointermove', (ev) => {
+    if (!ptrs.has(ev.pointerId)) return;
+    ptrs.set(ev.pointerId, { x: ev.clientX, y: ev.clientY });
+    const s = (svg.viewBox.baseVal.width || 1) / svg.getBoundingClientRect().width;
+    if (pinch && ptrs.size === 2) {
+      const [a, b] = [...ptrs.values()];
+      zoomAt(pinch.k * Math.hypot(a.x - b.x, a.y - b.y) / (pinch.d || 1), pinch.mid.x, pinch.mid.y, false);
+      moved = true;
+    } else if (drag) {
+      const dx = (ev.clientX - drag.x) * s, dy = (ev.clientY - drag.y) * s;
+      if (Math.abs(dx) + Math.abs(dy) > 3) {
+        moved = true;
+        z.style.cursor = 'grabbing';
+        if (!svg.hasPointerCapture(ev.pointerId)) svg.setPointerCapture(ev.pointerId);
+        go({ ...st, x: drag.sx + dx, y: drag.sy + dy, key: null }, false);
+        hide();
+      }
+    }
+  });
+  const up = (ev) => {
+    ptrs.delete(ev.pointerId);
+    if (ptrs.size < 2) pinch = null;
+    if (!ptrs.size) { drag = null; z.style.cursor = st.k > 1.02 ? 'grab' : ''; }
+  };
+  svg.addEventListener('pointerup', up);
+  svg.addEventListener('pointercancel', up);
+}
+
+// Fuente autocontenida (toHTML sin bundle): attach más su ayudante de zoom.
+export const attachSource = `(function(){${mapZoom.toString()}\nreturn ${attach.toString()};})()`;

package/src/lint.js

@@ -0,0 +1,137 @@
+// Revisión de un spec ANTES de dibujar: errores que impiden el gráfico y
+// sugerencias de diseño (de los cursos de visualización para la gestión).
+// Pensado para que un agente corrija su propio spec en un segundo intento.
+import { ensureData, fieldsOf, fieldKind, uniq, num, PlotError } from './data.js';
+import { inferType, TYPES, normalizeType } from './infer.js';
+import { validatePalette } from './palette.js';
+import { themeFor } from './theme.js';
+
+/** El índice registra aquí un dibujo de prueba (para revisar coincidencias de mapas). */
+let RENDER_PROBE = null;
+export const _setProbe = (fn) => { RENDER_PROBE = fn; };
+
+export function lint(spec = {}) {
+  const errors = [];
+  const warnings = [];
+  const tips = [];
+  const err = (code, message, fix) => errors.push({ code, message, fix });
+  const warn = (code, message, fix) => warnings.push({ code, message, fix });
+  const sug = (code, message, fix) => tips.push({ code, message, fix });
+
+  let data = [];
+  try { data = spec.type === 'kpi' || spec.items ? [] : ensureData(spec); } catch (e) { err('data', e.message.split('\n')[0], 'Pasa `data` como arreglo de filas: [{ categoria: "A", valor: 10 }]'); }
+  const type = spec.type && spec.type !== 'auto' ? normalizeType(spec.type)[0] : inferType(spec, data);
+  if (!TYPES.includes(type)) err('type', `Tipo "${spec.type}" no soportado.`, `Usa uno de: ${TYPES.join(', ')}`);
+  const fields = fieldsOf(data);
+  const check = (f, role) => {
+    for (const ff of [].concat(f ?? [])) if (ff && !fields.includes(ff)) err('field', `El campo "${ff}" (${role}) no existe.`, `Campos disponibles: ${fields.join(', ')}`);
+  };
+  if (data.length) {
+    check(spec.x, 'x'); check(spec.y, 'y'); check(spec.series ?? spec.color, 'series'); check(spec.size, 'size');
+    check(spec.value, 'value'); check(spec.label, 'label'); if (!['network', 'flowchart'].includes(type)) check(spec.group, 'group'); check(spec.path, 'path');
+    check(spec.from, 'from'); check(spec.to, 'to');
+  } else if (type !== 'kpi' && !errors.length) err('empty', 'No hay filas en `data`.', 'Entrega al menos una fila.');
+
+  if (!spec.title) sug('title', 'Falta el título.', 'Escribe el hallazgo como una frase completa: "Biobío concentra el 32% de las ventas", no "Ventas por región".');
+  else if (!/\d/.test(spec.title) && /^(evoluci[oó]n|distribuci[oó]n|comparaci[oó]n|ranking|gr[aá]fico|ventas|total|resumen)\b|\b(por|seg[uú]n|vs\.?)\s+\w+$/i.test(spec.title.trim())) sug('title-fact', 'El título describe el gráfico pero no dice qué muestra.', 'Un buen título es un hecho, idealmente con la cifra clave.');
+  if (!spec.source) sug('source', 'Falta la fuente de los datos.', 'Agrega `source: "INE, 2025"` (o "datos ilustrativos").');
+
+  const series = spec.series ?? spec.color;
+  const nSeries = series && fields.includes(series) ? uniq(data.map((r) => String(r[series]))).length : Array.isArray(spec.y) ? spec.y.length : 1;
+  if (nSeries > 8) warn('series-max', `${nSeries} series: solo hay 8 colores distinguibles; desde la 9.ª se pintan en gris.`, 'Agrupa la cola en "Otros", usa `highlight` o divide en varios gráficos.');
+
+  if (type === 'bar') {
+    const x = spec.x ?? fields.find((f) => fieldKind(data, f) === 'category');
+    const nCat = x && fields.includes(x) ? uniq(data.map((r) => String(r[x]))).length : 0;
+    if (nCat === 1 && nSeries === 1) sug('one-bar', 'Una sola barra no compara nada.', 'Usa `type: "kpi"` para mostrar el número.');
+    if (nCat > 40 && !spec.top) warn('too-many-bars', `${nCat} categorías: se mostrarán las 25 mayores y el resto como "Otros".`, 'Fija `top: N` para controlar el corte.');
+    if (spec.stack && nSeries > 5) sug('stack-many', 'Apilar más de 5 series dificulta comparar los segmentos del medio.', 'Considera barras agrupadas, `highlight` o `stack: "percent"`.');
+    if (x && fieldKind(data, x) === 'date' && nCat > 24) sug('bar-time', 'Muchos periodos en barras.', 'Para tendencias largas, `type: "line"` se lee mejor.');
+  }
+  if (type === 'line' || type === 'area') {
+    const x = spec.x;
+    if (nSeries > 4 && spec.highlight === undefined) warn('line-many', `${nSeries} líneas: sobre 3-4 el gráfico se vuelve espagueti.`, 'Usa `highlight: "Serie"` para destacar una y atenuar el resto, o separa en varios gráficos.');
+    if (x && fields.includes(x) && fieldKind(data, x) === 'category' && !/^(q|t)\d|^\d/i.test(String(data[0]?.[x]))) sug('line-nominal', 'El eje x tiene categorías sin orden: las líneas sugieren continuidad.', 'Para comparar categorías usa `type: "bar"`.');
+    const pts = x && fields.includes(x) ? uniq(data.map((r) => String(r[x]))).length : 0;
+    if (pts && pts < 3) sug('line-few', 'Menos de 3 puntos en el tiempo.', 'Con 2 periodos, barras agrupadas o un `kpi` con variación comunican mejor.');
+    if (Array.isArray(spec.y) && spec.y.length === 2 && !spec.index) {
+      const [a, b] = spec.y.map((f) => Math.max(...data.map((r) => Math.abs(num(r[f]))).filter(Number.isFinite)));
+      if (a && b && Math.max(a, b) / Math.min(a, b) > 10) warn('dual-scale', 'Las dos medidas tienen escalas muy distintas (no hay doble eje: inventa correlaciones).', 'Usa `index: true` (base 100) o dos gráficos separados.');
+    }
+  }
+  if (type === 'donut') {
+    const lf = spec.label ?? spec.x ?? fields.find((f) => fieldKind(data, f) === 'category');
+    const vf = spec.value ?? spec.y ?? fields.find((f) => fieldKind(data, f) === 'number');
+    const n = lf ? uniq(data.map((r) => String(r[lf]))).length : 0;
+    if (n > 6) warn('donut-slices', `${n} segmentos: sobre 6 la dona no se lee; se agrupan en "Otros".`, 'Usa `type: "bar"` o `type: "treemap"`.');
+    if (n === 2) sug('donut-two', 'Dos segmentos son un solo número.', 'Usa `type: "kpi"` con el porcentaje.');
+    if (vf && n >= 3) {
+      const vals = data.map((r) => num(r[vf])).filter((v) => v > 0).sort((a, b) => b - a);
+      if (vals.length >= 3 && vals[0] / vals[vals.length - 1] < 1.35) sug('donut-close', 'Los valores son muy parecidos: los ángulos no permiten compararlos.', 'Usa `type: "bar"` ordenado.');
+    }
+    if (data.some((r) => num(r[vf]) < 0)) err('negative', 'La dona no admite valores negativos.', 'Usa barras.');
+  }
+  if (type === 'treemap') {
+    const vf = spec.value ?? spec.y ?? fields.find((f) => fieldKind(data, f) === 'number');
+    if (vf && data.some((r) => num(r[vf]) < 0)) warn('negative', 'Los valores negativos se omiten en el treemap.', 'Usa barras para datos con signo.');
+    const gf = spec.group ?? (Array.isArray(spec.path) && spec.path.length > 1 ? spec.path[0] : null);
+    if (gf && fields.includes(gf) && uniq(data.map((r) => String(r[gf]))).length > 8) warn('groups-max', 'Más de 8 grupos: desde el 8.º van en gris "Otros".', 'Agrupa categorías o usa otro nivel de jerarquía.');
+  }
+  if (type === 'scatter' || type === 'bubble') {
+    if (nSeries > 3) warn('scatter-colors', `${nSeries} grupos de color en dispersión: solo los 3 primeros colores son distinguibles entre todos los pares para daltonismo.`, 'Usa `highlight`, agrupa o separa en varios gráficos.');
+    if (data.length > 2000) sug('overplot', `${data.length} puntos: puede haber sobreposición.`, 'Reduce `radius` o usa un mapa de calor.');
+  }
+  // Campos de facetas y tiempo
+  if (data.length) { check(spec.facet ?? spec.col, 'facet'); check(spec.time, 'time'); check(spec.hue, 'hue'); }
+
+  // Paleta propia: se valida con las mismas reglas que la de fábrica.
+  const custom = spec.palette || (spec.theme && typeof spec.theme === 'object' && spec.theme.categorical);
+  if (custom) {
+    const th = themeFor(spec);
+    const n = Math.max(2, Math.min(th.categorical.length, nSeries));
+    const rep = validatePalette(th.categorical.slice(0, n), { mode: th.mode, surface: th.surface, pairs: type === 'scatter' || type === 'bubble' ? 'all' : 'adjacent' });
+    for (const c of rep.checks) if (c.status === 'fail') warn('palette-' + c.name, `Paleta: ${c.detail}`, 'Cambia el orden o los tonos, o usa la paleta de fábrica.');
+  }
+
+  const numericIn = (f) => f && fields.includes(f) && ['number', 'year'].includes(fieldKind(data, f));
+  if (['hist', 'kde', 'ecdf'].includes(type)) {
+    const f = spec.x ?? spec.y;
+    if (f && fields.includes(f) && !numericIn(f)) err('numeric', `"${f}" no es numérico: ${type} necesita una medida.`, 'Para contar categorías usa `type: "countplot"`.');
+    if (data.length < 20) sug('few-obs', `Solo ${data.length} observaciones: la forma de la distribución es poco confiable.`, 'Con pocos datos, `type: "strip"` muestra cada punto.');
+  }
+  if (['regplot', 'residplot', 'jointplot'].includes(type)) {
+    for (const f of [spec.x, spec.y]) if (f && fields.includes(f) && !numericIn(f)) err('numeric', `"${f}" no es numérico: la regresión necesita dos medidas.`, 'Usa `type: "box"` para comparar una medida entre categorías.');
+    if (data.length < 8) warn('few-obs', `Solo ${data.length} puntos: la recta y su intervalo son poco confiables.`, 'Muestra los puntos con `type: "scatter"`.');
+  }
+  if (['box', 'violin'].includes(type) && data.length && spec.x && fields.includes(spec.x)) {
+    const counts = new Map();
+    for (const r of data) counts.set(String(r[spec.x]), (counts.get(String(r[spec.x])) || 0) + 1);
+    const small = [...counts].filter(([, n]) => n < 5).map(([k]) => k);
+    if (small.length) sug('few-per-group', `Grupos con menos de 5 datos: ${small.slice(0, 4).join(', ')}.`, '`type: "strip"` o `points: true` muestran cada observación.');
+  }
+  if (type === 'radar' && nSeries > 4) warn('radar-many', `${nSeries} series en un radar se tapan entre sí.`, 'Usa `highlight`, `facet` o barras agrupadas.');
+  if ((type === 'line' || type === 'area') && spec.yScale === 'log' && data.some((r) => num(r[Array.isArray(spec.y) ? spec.y[0] : spec.y]) <= 0)) warn('log-nonpositive', 'Hay valores ≤ 0: la escala log no los puede mostrar.', 'Quita la escala log o filtra esos valores.');
+
+  if (type === 'choropleth' || type === 'symbolmap') {
+    const _unmatched = [];
+    try { RENDER_PROBE?.({ ...spec, _unmatched }); } catch { /* el error ya se reporta al dibujar */ }
+    if (_unmatched.length) warn('geo-unmatched', `${_unmatched.length} fila(s) no coinciden con el mapa: ${_unmatched.slice(0, 5).join(', ')}.`, 'Revisa los nombres o usa códigos (p. ej. "XIII", "ARG", "TX"), o indica `featureKey`.');
+  }
+  // Formas punteadas: sin explicación, el rayado no se entiende.
+  if ((spec.dashed !== undefined && spec.dashed !== false) || spec.dashedFrom !== undefined) {
+    if (spec.dashedLabel === undefined) sug('dashed-label', 'Hay formas punteadas pero no se dice qué significan (la leyenda dirá "Estimado").', 'Agrega `dashedLabel: "Proyección"`, "Cifra preliminar" o lo que corresponda.');
+    if (spec.dashedFrom !== undefined && !['line', 'area', 'bar', 'column', 'count'].includes(type)) warn('dashed-from-type', '`dashedFrom` solo aplica a líneas, áreas y columnas con eje de tiempo.', 'Usa `dashed` con una lista de categorías o un campo de los datos.');
+  }
+  if (type === 'pyramid') {
+    const sf = spec.sex ?? spec.series ?? spec.hue;
+    if (sf && fields.includes(sf)) { const n = uniq(data.map((r) => String(r[sf]))).length; if (n !== 2) err('pyramid-sides', `La pirámide necesita exactamente 2 grupos en "${sf}" (hay ${n}).`, 'Usa `type: "bar"` con `series` para más grupos.'); }
+  }
+  if (type === 'chord' && data.length && uniq(data.flatMap((r) => [r[spec.from ?? 'from'], r[spec.to ?? 'to']])).length > 16) warn('chord-many', 'Más de 16 grupos en un diagrama de cuerdas: los arcos se vuelven ilegibles.', 'Agrupa los menores en "Otros" o usa `type: "sankey"`.');
+  if (type === 'network' && data.length > 2000) sug('network-big', `${data.length} conexiones: la red puede verse como una mancha.`, 'Filtra las conexiones débiles o usa `layout: "circle"`.');
+
+  if (type === 'kpi' && !(spec.items || spec.data || []).length) err('items', 'El KPI necesita `items`.', 'items: [{ label: "Ventas", value: 1250, delta: 0.12, period: "vs 2025" }]');
+
+  return { ok: errors.length === 0, type, errors, warnings, suggestions: tips };
+}
+
+export { PlotError };

package/src/palette.js

@@ -0,0 +1,59 @@
+// Validador de paletas categóricas: lo mismo que se usó para validar las
+// paletas de fábrica, disponible para que un agente revise la suya.
+// Umbrales: banda de luminosidad OKLCH, croma mínimo, separación ΔE (OKLab×100)
+// entre vecinos bajo protanopía/deuteranopía (Machado 2009) y con visión normal.
+
+const BAND = { light: [0.43, 0.77], dark: [0.48, 0.67] };
+const CHROMA_FLOOR = 0.1;
+const CVD_TARGET = 8, CVD_FLOOR = 6, NORMAL_FLOOR = 15;
+const MACHADO = {
+  protan: [[0.152286, 1.052583, -0.204868], [0.114503, 0.786281, 0.099216], [-0.003882, -0.048116, 1.051998]],
+  deutan: [[0.367322, 0.860646, -0.227968], [0.280085, 0.672501, 0.047413], [-0.01182, 0.04294, 0.968881]],
+};
+
+const lin = (c) => { c /= 255; return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
+const rgbLin = (hex) => { const h = hex.replace('#', ''); const n = parseInt(h.length === 3 ? h.split('').map((c) => c + c).join('') : h.slice(0, 6), 16); return [(n >> 16) & 255, (n >> 8) & 255, n & 255].map(lin); };
+function oklab([r, g, b]) {
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  return [0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s, 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s, 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s];
+}
+const sim = (rgb, M) => M.map((row) => Math.max(0, Math.min(1, row[0] * rgb[0] + row[1] * rgb[1] + row[2] * rgb[2])));
+function dE(a, b, kind) {
+  let A = rgbLin(a), B = rgbLin(b);
+  if (kind) { A = sim(A, MACHADO[kind]); B = sim(B, MACHADO[kind]); }
+  const p = oklab(A), q = oklab(B);
+  return 100 * Math.hypot(p[0] - q[0], p[1] - q[1], p[2] - q[2]);
+}
+const lum = (hex) => { const [r, g, b] = rgbLin(hex); return 0.2126 * r + 0.7152 * g + 0.0722 * b; };
+const contrast = (a, b) => { const [x, y] = [lum(a), lum(b)].sort((m, n) => n - m); return (x + 0.05) / (y + 0.05); };
+
+/**
+ * Revisa una paleta categórica. Devuelve { ok, checks: [{ name, status, detail }] }.
+ * status: 'pass' | 'warn' | 'fail'. `pairs: 'all'` para dispersión y mapas.
+ */
+export function validatePalette(colors, { mode = 'light', surface, pairs = 'adjacent', locale = 'es' } = {}) {
+  const en = String(locale).startsWith('en');
+  const pal = colors.map(String);
+  surface = surface || (mode === 'dark' ? '#0B0F2B' : '#FCFBF9');
+  const checks = [];
+  const [lo, hi] = BAND[mode] || BAND.light;
+  const Ls = pal.map((c) => oklab(rgbLin(c)));
+  const off = pal.filter((c, i) => Ls[i][0] < lo || Ls[i][0] > hi);
+  checks.push({ name: 'lightness', status: off.length ? 'fail' : 'pass', detail: off.length ? (en ? `Outside the lightness band ${lo}–${hi}: ` : `Fuera de la banda de luminosidad ${lo}–${hi}: `) + off.join(', ') : en ? 'All inside the lightness band.' : 'Todos dentro de la banda de luminosidad.' });
+  const gray = pal.filter((c, i) => Math.hypot(Ls[i][1], Ls[i][2]) < CHROMA_FLOOR);
+  checks.push({ name: 'chroma', status: gray.length ? 'fail' : 'pass', detail: gray.length ? (en ? 'Read as gray: ' : 'Se leen como gris: ') + gray.join(', ') : en ? 'All have enough chroma.' : 'Todos con color suficiente.' });
+  const list = pairs === 'all' ? pal.flatMap((_, i) => pal.slice(i + 1).map((__, k) => [i, i + 1 + k])) : pal.slice(1).map((_, i) => [i, i + 1]);
+  let worst = null, nworst = null;
+  for (const [i, j] of list) {
+    for (const k of ['protan', 'deutan']) { const d = dE(pal[i], pal[j], k); if (!worst || d < worst[0]) worst = [d, pal[i], pal[j], k]; }
+    const n = dE(pal[i], pal[j]);
+    if (!nworst || n < nworst[0]) nworst = [n, pal[i], pal[j]];
+  }
+  if (worst) checks.push({ name: 'cvd', status: worst[0] >= CVD_TARGET ? 'pass' : worst[0] >= CVD_FLOOR ? 'warn' : 'fail', detail: en ? `Worst colorblind pair (${worst[3]}): ${worst[1]} ↔ ${worst[2]}, ΔE ${worst[0].toFixed(1)} (target ≥ ${CVD_TARGET}).` : `Peor par para daltonismo (${worst[3]}): ${worst[1]} ↔ ${worst[2]}, ΔE ${worst[0].toFixed(1)} (meta ≥ ${CVD_TARGET}).` });
+  if (nworst) checks.push({ name: 'normal', status: nworst[0] >= NORMAL_FLOOR ? 'pass' : 'fail', detail: en ? `Worst normal-vision pair: ${nworst[1]} ↔ ${nworst[2]}, ΔE ${nworst[0].toFixed(1)} (minimum ${NORMAL_FLOOR}).` : `Peor par con visión normal: ${nworst[1]} ↔ ${nworst[2]}, ΔE ${nworst[0].toFixed(1)} (mínimo ${NORMAL_FLOOR}).` });
+  const low = pal.filter((c) => contrast(c, surface) < 3);
+  checks.push({ name: 'contrast', status: low.length ? 'warn' : 'pass', detail: low.length ? (en ? 'Below 3:1 against the surface (use visible labels): ' : 'Bajo 3:1 contra el fondo (usa etiquetas visibles): ') + low.join(', ') : en ? 'All ≥ 3:1 against the surface.' : 'Todos ≥ 3:1 contra el fondo.' });
+  return { ok: !checks.some((c) => c.status === 'fail'), checks };
+}