plotagents 0.5.0 → 0.7.0

package/src/charts/sankey.js

@@ -3,7 +3,7 @@
 import { el, g, text, tip } from '../svg.js';
 import { measure, truncate } from '../text.js';
 import { makeFormat } from '../format.js';
-import { ensureData, requireField, num, fieldsOf, fieldKind } from '../data.js';
+import { ensureData, requireField, num, fieldsOf, fieldKind, PlotError } from '../data.js';
 import { createFrame } from '../frame.js';
 
 export function sankey(spec, theme) {
@@ -16,24 +16,39 @@ export function sankey(spec, theme) {
   requireField(data, to, 'to');
   requireField(data, valueF, 'value');
   const locale = spec.locale || 'es';
+  const en = String(locale).startsWith('en');
 
-  // Enlaces agregados
+  // Enlaces agregados (valores no finitos o ≤ 0 se ignoran).
   const lmap = new Map();
   for (const r of data) {
     const v = num(r[valueF]);
-    if (!(v > 0)) continue;
+    if (!(v > 0) || !Number.isFinite(v)) continue;
     const s = String(r[from]), t = String(r[to]);
     if (s === t) continue;
     const k = s + '\u0000' + t;
     lmap.set(k, (lmap.get(k) || 0) + v);
   }
   const links = [...lmap.entries()].map(([k, v]) => { const [s, t] = k.split('\u0000'); return { s, t, v }; });
+  if (!links.length) {
+    throw en
+      ? new PlotError('The sankey has no positive flows between different nodes.', `Check \`${valueF}\`: it needs values > 0, and \`${from}\` must differ from \`${to}\` (self-loops are dropped).`)
+      : new PlotError('El sankey no tiene flujos positivos entre nodos distintos.', `Revisa \`${valueF}\`: necesita valores > 0, y \`${from}\` debe ser distinto de \`${to}\` (los bucles se omiten).`);
+  }
   const names = [...new Set(links.flatMap((l) => [l.s, l.t]))];
   const nodes = new Map(names.map((n) => [n, { name: n, in: [], out: [], depth: 0 }]));
   for (const l of links) { l.sn = nodes.get(l.s); l.tn = nodes.get(l.t); l.sn.out.push(l); l.tn.in.push(l); }
   for (const n of nodes.values()) n.value = Math.max(sum(n.in), sum(n.out));
 
-  // Profundidad = camino más largo desde un origen (con tope por si hay ciclos).
+  // Un sankey fluye en una dirección: un ciclo (a → b → a) no tiene etapas.
+  const cycle = findCycle(nodes);
+  if (cycle) {
+    const path = cycle.join(' → ');
+    throw en
+      ? new PlotError(`The sankey has a cycle (${path}): flows must go one way, stage by stage.`, 'Name each stage apart ("Chile (origin)" → "Chile (destination)"), drop the return flows, or use `type: "chord"` for two-way exchanges.')
+      : new PlotError(`El sankey tiene un ciclo (${path}): los flujos deben ir en una sola dirección, etapa por etapa.`, 'Distingue las etapas ("Chile (origen)" → "Chile (destino)"), quita los flujos de vuelta o usa `type: "chord"` para intercambios en ambos sentidos.');
+  }
+
+  // Profundidad = camino más largo desde un origen.
   for (let it = 0; it < names.length; it++) {
     let changed = false;
     for (const l of links) if (l.tn.depth < l.sn.depth + 1) { l.tn.depth = l.sn.depth + 1; changed = true; }
@@ -124,10 +139,31 @@ export function sankey(spec, theme) {
     }
     body.push(g({ 'data-tip': `${n.name}\n${fmt(n.value)}` }, parts));
   }
-  const en = String(locale).startsWith('en');
   const top = [...links].sort((a, b) => b.v - a.v).slice(0, 3).map((l) => `${l.s} → ${l.t} (${fmt(l.v)})`).join('; ');
   const desc = en ? `Sankey diagram with ${nodes.size} nodes and ${links.length} flows. Largest flows: ${top}.` : `Diagrama de Sankey con ${nodes.size} nodos y ${links.length} flujos. Mayores flujos: ${top}.`;
   return frame.finish(body, { desc, type: 'sankey' });
 }
 
 const sum = (ls) => ls.reduce((a, l) => a + l.v, 0);
+
+/** Primer ciclo encontrado (lista de nombres, cerrada) o null. DFS iterativo. */
+function findCycle(nodes) {
+  const state = new Map(); // 1 = en la pila, 2 = terminado
+  for (const start of nodes.values()) {
+    if (state.has(start)) continue;
+    const stack = [[start, 0]];
+    const trail = [start];
+    state.set(start, 1);
+    while (stack.length) {
+      const top = stack[stack.length - 1];
+      const [n, i] = top;
+      if (i < n.out.length) {
+        top[1]++;
+        const m = n.out[i].tn;
+        if (state.get(m) === 1) return [...trail.slice(trail.indexOf(m)), m].map((x) => x.name);
+        if (!state.has(m)) { state.set(m, 1); stack.push([m, 0]); trail.push(m); }
+      } else { state.set(n, 2); stack.pop(); trail.pop(); }
+    }
+  }
+  return null;
+}

package/src/charts/scatter.js

@@ -5,28 +5,47 @@ import { measure } from '../text.js';
 import { makeFormat } from '../format.js';
 import { niceDomain, niceStep, linear, log, logDomain } from '../scale.js';
 import { colorMap } from '../theme.js';
-import { ensureData, requireField, uniq, num, fieldsOf, fieldKind, humanize } from '../data.js';
-import { gridY, gridX, ticksWidth, refLinesY, refLinesX, yAxisMargin, yAxisTop, yGrid, yTickLabels, quietCorner } from '../axes.js';
-import { createFrame, SIZES } from '../frame.js';
+import { ensureData, requireField, uniq, num, fieldsOf, fieldKind, humanize, PlotError } from '../data.js';
+import { gridY, gridX, ticksWidth, refLinesY, refLinesX, yAxisMargin, yAxisTop, yGrid, yTickLabels, quietCorner, isInside } from '../axes.js';
+import { createFrame, SIZES, hash } from '../frame.js';
+import { extent } from '../stats.js';
+import { ctx } from '../context.js';
+
+/** Muestra pareja de ~n filas (inferir tipos de campo sin recorrer 50 mil filas). */
+const sampleRows = (data, n = 200) => (data.length <= n ? data : Array.from({ length: n }, (_, i) => data[Math.floor((i * (data.length - 1)) / (n - 1))]));
 
 export function scatter(spec, theme) {
   const data = ensureData(spec);
   const fields = fieldsOf(data);
-  const numeric = fields.filter((f) => fieldKind(data, f) === 'number' || fieldKind(data, f) === 'year');
+  const sample = sampleRows(data);
+  const kinds = new Map();
+  const kindOf = (f) => { if (!kinds.has(f)) kinds.set(f, fieldKind(sample, f)); return kinds.get(f); };
+  const numeric = spec.x && spec.y ? [] : fields.filter((f) => kindOf(f) === 'number' || kindOf(f) === 'year');
   const x = spec.x || numeric[0];
   const y = spec.y || numeric.find((f) => f !== x);
   const size = spec.size;
   const series = spec.series ?? spec.hue ?? spec.color;
-  const labelF = spec.label ?? fields.find((f) => fieldKind(data, f) === 'category' && f !== series);
+  const labelF = spec.label ?? fields.find((f) => kindOf(f) === 'category' && f !== series);
   requireField(data, x, 'x');
   requireField(data, y, 'y');
   if (size) requireField(data, size, 'size');
   if (series) requireField(data, series, 'series');
   const locale = spec.locale || 'es';
+  const en = String(locale).startsWith('en');
+  const xLog = spec.xScale === 'log', yLog = spec.yScale === 'log';
 
+  // En escala log, los valores ≤ 0 no tienen posición: se omiten.
   const pts = data
     .map((r) => ({ r, x: num(r[x]), y: num(r[y]), s: size ? num(r[size]) : 1, k: series ? String(r[series]) : '', name: labelF ? String(r[labelF] ?? '') : '' }))
-    .filter((p) => Number.isFinite(p.x) && Number.isFinite(p.y));
+    .filter((p) => Number.isFinite(p.x) && Number.isFinite(p.y) && (!xLog || p.x > 0) && (!yLog || p.y > 0));
+  if (!pts.length) {
+    const which = !data.some((r) => Number.isFinite(num(r[x]))) ? x : y;
+    const logNote = xLog || yLog ? (en ? ' (on a log scale only values > 0 count)' : ' (en escala log solo cuentan valores > 0)') : '';
+    throw new PlotError(
+      en ? `No points to plot: \`${which}\` has no numeric values${logNote}.` : `No hay puntos para graficar: \`${which}\` no tiene valores numéricos${logNote}.`,
+      en ? `Use numeric fields for x and y, e.g. x: "gdp", y: "life_expectancy". Fields: ${fields.join(', ')}.` : `Usa campos numéricos en x e y, p. ej. x: "pib", y: "esperanza_vida". Campos: ${fields.join(', ')}.`
+    );
+  }
   const keys = series ? uniq(pts.map((p) => p.k)) : [''];
   const cmap = colorMap(keys, theme, spec.colors);
   const hl = spec.highlight === undefined ? null : new Set([].concat(spec.highlight).map(String));
@@ -41,27 +60,43 @@ export function scatter(spec, theme) {
   const frame = createFrame(spec, theme, { height: 460 });
   const area = frame.layout(legend);
 
-  const xLog = spec.xScale === 'log', yLog = spec.yScale === 'log';
-  const ex = [Math.min(...pts.map((p) => p.x)), Math.max(...pts.map((p) => p.x))];
-  const ey = [Math.min(...pts.map((p) => p.y)), Math.max(...pts.map((p) => p.y))];
+  const ex = extent(pts.map((p) => p.x));
+  const ey = extent(pts.map((p) => p.y));
   if (spec.xDomain) ex.splice(0, 2, ...spec.xDomain);
   if (spec.yDomain) ey.splice(0, 2, ...spec.yDomain);
   const dx = xLog ? logDomain(...ex) : spec.xDomain ? { min: ex[0], max: ex[1], step: niceStep(ex[1] - ex[0], Math.max(3, Math.round(area.w / 110))) } : niceDomain(ex[0], ex[1], Math.max(3, Math.round(area.w / 110)));
   const dy = yLog ? logDomain(...ey) : spec.yDomain ? { min: ey[0], max: ey[1], step: niceStep(ey[1] - ey[0], Math.max(3, Math.round(area.h / 70))) } : niceDomain(ey[0], ey[1], Math.max(3, Math.round(area.h / 70)));
   if (spec._domains) { spec._domains.x = [dx.min, dx.max]; spec._domains.y = [dy.min, dy.max]; }
-  const ytf = yLog ? fy : fy.tick(dy.step);
-  const xtf = xLog ? fx : fx.tick(dx.step);
   const yTicks = (yLog ? log(dy.min, dy.max, 0, 1) : linear(dy.min, dy.max, 0, 1)).ticks(dy.step);
+  const ytf = yLog ? fy : fy.tick(dy.step, yTicks);
+  const xtf = xLog ? fx : fx.tick(dx.step, linear(dx.min, dx.max, 0, 1).ticks(dx.step));
   const leftM = yAxisMargin(yTicks, ytf, theme);
   const top = area.y + 18 + yAxisTop(theme);
   const inner = { x: area.x + leftM, y: top, w: area.w - leftM - 8, h: area.y + area.h - top - 44 };
-  const maxS = Math.max(...pts.map((p) => p.s));
+  const maxS = extent(pts.map((p) => p.s))[1];
   const rMax = spec.maxRadius ?? Math.min(30, Math.max(12, Math.sqrt((inner.w * inner.h) / Math.max(1, pts.length)) / 3));
   // Las burbujas no se salen del área: margen interno del radio máximo.
   const bp = size ? rMax * 0.75 : 6;
-  const xS = (xLog ? log : linear)(dx.min, dx.max, inner.x + bp, inner.x + inner.w - bp);
   const yS = (yLog ? log : linear)(dy.min, dy.max, inner.y + inner.h - bp, inner.y + bp);
   const rOf = (p) => (size ? Math.max(2.5, Math.sqrt(Math.max(0, p.s) / (maxS || 1)) * rMax) : spec.radius ?? (pts.length > 300 ? 3 : 5));
+  // Eje y por dentro: si un punto pegado a la izquierda choca con una etiqueta
+  // de marca, el rango x arranca pasado la etiqueta más ancha.
+  let xPad = 0;
+  if (isInside(theme, undefined) && !spec.xDomain) {
+    const axisSize = SIZES.axis;
+    const kk = 5 * Math.max(1, ctx.textScale * 0.8);
+    const yT = yS.ticks(dy.step);
+    const boxes = yT.map((t) => { const base = Math.round(yS(t)) + 0.5 - kk; return { w: ticksWidth([t], ytf, theme.type?.axis ?? axisSize), y0: base - (theme.type?.axis ?? axisSize) * 0.75, y1: base + 1 }; });
+    const xS0 = (xLog ? log : linear)(dx.min, dx.max, inner.x + bp, inner.x + inner.w - bp);
+    const wMax = Math.max(0, ...boxes.map((b) => b.w));
+    for (const p of pts) {
+      const r = rOf(p), px = xS0(p.x);
+      if (px - r > inner.x + wMax + 1) continue;
+      const py = yS(p.y);
+      if (boxes.some((b) => px - r < inner.x + b.w + 1 && py + r > b.y0 && py - r < b.y1)) { xPad = Math.min(Math.max(0, wMax + 6 - bp + r), inner.w * 0.2); if (xPad >= inner.w * 0.2) break; }
+    }
+  }
+  const xS = (xLog ? log : linear)(dx.min, dx.max, inner.x + bp + xPad, inner.x + inner.w - bp);
 
   const body = [];
   body.push(yGrid(yS.ticks(dy.step), yS, inner, theme, { baseline: NaN }));
@@ -71,6 +106,7 @@ export function scatter(spec, theme) {
   body.push(text(area.x, area.y + 10, spec.yLabel ?? humanize(y), { fill: theme.lede, fontSize: SIZES.axis, fontWeight: 500 }));
   body.push(text(inner.x + inner.w, inner.y + inner.h + 40, spec.xLabel ?? humanize(x), { fill: theme.lede, fontSize: SIZES.axis, fontWeight: 500, textAnchor: 'end' }));
 
+  const taken = []; // zonas ocupadas por rótulos (R²), para la clave de tamaños
   // Tendencia lineal (mínimos cuadrados)
   if (spec.trend) {
     const tx = pts.map((p) => (xLog ? Math.log10(p.x) : p.x)), ty = pts.map((p) => (yLog ? Math.log10(p.y) : p.y));
@@ -82,12 +118,16 @@ export function scatter(spec, theme) {
     const lx0 = xLog ? Math.log10(dx.min) : dx.min, lx1 = xLog ? Math.log10(dx.max) : dx.max;
     const P = (lx) => [xS(xLog ? 10 ** lx : lx), yS(yLog ? 10 ** (a + b * lx) : a + b * lx)];
     const [ax, ay] = P(lx0), [bx, by] = P(lx1);
-    body.push(el('clipPath', { id: 'pa-clip-trend' }, el('rect', { x: inner.x, y: inner.y, width: inner.w, height: inner.h })));
-    body.push(el('line', { x1: ax, y1: ay, x2: bx, y2: by, stroke: theme.ink, strokeWidth: 1.5, opacity: 0.55, clipPath: 'url(#pa-clip-trend)' }));
+    // id único por gráfico: varios SVG en una página no comparten el recorte.
+    const clipId = 'pa-clip-trend-' + Math.abs(hash(String(spec.title) + x + y + inner.w + pts.length)).toString(36);
+    body.push(el('clipPath', { id: clipId }, el('rect', { x: inner.x, y: inner.y, width: inner.w, height: inner.h })));
+    body.push(el('line', { x1: ax, y1: ay, x2: bx, y2: by, stroke: theme.ink, strokeWidth: 1.5, opacity: 0.55, clipPath: `url(#${clipId})` }));
     const r2s = `R² = ${r2v.toFixed(2).replace('.', String(locale).startsWith('en') ? '.' : ',')}`;
     const occ = pts.map((p) => [xS(p.x), yS(p.y)]);
     for (let i = 0; i <= 24; i++) occ.push([ax + ((bx - ax) * i) / 24, ay + ((by - ay) * i) / 24]);
     const qc = quietCorner(occ, inner, measure(r2s, 11.5) + 4, 16);
+    const r2w = measure(r2s, 11.5) + 4, r2x0 = qc.anchor === 'end' ? qc.x - r2w : qc.x;
+    for (let i = 0; i <= 8; i++) for (const dy of [-12, -6, 0]) taken.push([r2x0 + (r2w * i) / 8, qc.y + dy]);
     body.push(text(qc.x, qc.y, r2s, { fill: theme.lede, fontSize: 11.5, textAnchor: qc.anchor, stroke: theme.surface, strokeWidth: 3, paintOrder: 'stroke' }));
   }
   body.push(refLinesY(spec.refLines || [], yS, inner, theme, fy));
@@ -95,13 +135,52 @@ export function scatter(spec, theme) {
 
   // Burbujas grandes debajo, chicas arriba; anillo del color de fondo.
   const sorted = [...pts].sort((a, b) => (focus(a) - focus(b)) || b.s - a.s);
-  const circles = sorted.map((p) => {
-    const lines = [p.name || '', `${humanize(x)}: ${fx(p.x)}`, `${humanize(y)}: ${fy(p.y)}`];
-    if (size) lines.push(`${humanize(size)}: ${fs(p.s)}`);
-    if (series) lines.splice(1, 0, p.k);
-    return { class: 'pa-m', cx: xS(p.x), cy: yS(p.y), r: rOf(p), fill: colorOf(p), fillOpacity: size ? 0.78 : 0.9, stroke: theme.surface, strokeWidth: size ? 1.5 : pts.length > 400 ? 1 : 2, 'data-tip': tip(...lines) };
+  // Tooltips: la capa densa guarda a lo más MAX_TIPS; no se arman los que se descartan.
+  const MAX_TIPS = 20000;
+  const hx = humanize(x), hy = humanize(y), hs = size ? humanize(size) : '';
+  const circles = sorted.map((p, i) => {
+    let t = '';
+    if (i < MAX_TIPS || sorted.length <= 1500) {
+      const lines = [p.name || '', `${hx}: ${fx(p.x)}`, `${hy}: ${fy(p.y)}`];
+      if (size) lines.push(`${hs}: ${fs(p.s)}`);
+      if (series) lines.splice(1, 0, p.k);
+      t = tip(...lines);
+    }
+    return { class: 'pa-m', cx: xS(p.x), cy: yS(p.y), r: rOf(p), fill: colorOf(p), fillOpacity: size ? 0.78 : 0.9, stroke: theme.surface, strokeWidth: size ? 1.5 : pts.length > 400 ? 1 : 2, 'data-tip': t };
   });
-  body.push(dotLayer(circles));
+  body.push(dotLayer(circles, { maxTips: MAX_TIPS }));
+
+  // Clave de tamaños (burbujas): 2–3 círculos de referencia anidados en una esquina libre.
+  if (size && spec.sizeKey !== false && maxS > 0) {
+    const nice = (v) => { const e = 10 ** Math.floor(Math.log10(v)); const m = v / e; return (m >= 5 ? 5 : m >= 2 ? 2 : 1) * e; };
+    const v1 = nice(maxS);
+    const vals = [v1, nice(v1 / 4), nice(v1 / 16)].filter((v, i, a) => a.indexOf(v) === i && Math.sqrt(v / maxS) * rMax >= 4);
+    if (vals.length >= 2) {
+      const radii = vals.map((v) => Math.sqrt(v / maxS) * rMax);
+      const R = radii[0];
+      const labs = vals.map((v) => fs(v));
+      const lw = Math.max(...labs.map((l) => measure(l, 10.5)));
+      const kw = 2 * R + 8 + lw, kh = 2 * R + 16;
+      const occ = sorted.map((p) => [xS(p.x), yS(p.y)]);
+      // Lo ya ocupado (R²) pesa como muchos puntos: la clave nunca lo tapa.
+      for (const q of taken) for (let i = 0; i < 50; i++) occ.push(q);
+      const qc = quietCorner(occ, inner, kw, kh);
+      const left = qc.anchor === 'end' ? qc.x - kw : qc.x;
+      const y0 = qc.y - kh + 3; // borde superior de la caja elegida
+      const cx = left + R, cy0 = y0 + kh - 1;
+      const parts = [text(left, y0 + 10, hs, { fill: theme.muted, fontSize: 10.5, fontWeight: 500 })];
+      let prevY = -Infinity;
+      radii.forEach((r, i) => {
+        const top = cy0 - 2 * r;
+        const ly = Math.max(top, prevY + 11); // rótulos separados aunque los círculos se acerquen
+        prevY = ly;
+        parts.push(el('circle', { cx, cy: cy0 - r, r, fill: 'none', stroke: theme.muted, strokeWidth: 1, opacity: 0.8 }));
+        parts.push(el('path', { d: `M${cx.toFixed(1)},${top.toFixed(1)}H${(cx + R + 1).toFixed(1)}L${(cx + R + 4).toFixed(1)},${ly.toFixed(1)}`, fill: 'none', stroke: theme.muted, strokeWidth: 0.75, opacity: 0.6 }));
+        parts.push(text(cx + R + 6, ly + 3.5, labs[i], { fill: theme.muted, fontSize: 10.5 }));
+      });
+      body.push(g({ class: 'pa-sizekey' }, parts));
+    }
+  }
 
   body.push(yTickLabels(yS.ticks(dy.step), yS, inner, theme, ytf));
 
@@ -128,7 +207,6 @@ export function scatter(spec, theme) {
     }
   }
 
-  const en = String(locale).startsWith('en');
   const desc = en
     ? `Scatter plot of ${humanize(y)} vs ${humanize(x)} with ${pts.length} points.`
     : `Gráfico de dispersión de ${humanize(y)} versus ${humanize(x)} con ${pts.length} puntos.`;

package/src/charts/sunburst.js

@@ -34,9 +34,10 @@ export function sunburst(spec, theme) {
   const hl = spec.highlight === undefined ? null : new Set([].concat(spec.highlight).map(String));
   const dim = (n) => hl && !n.path.some((p) => hl.has(p));
 
-  const top = focus.children;
-  const legend = top.length > 1 && spec.legend !== false && !focus.path.length
-    ? [...top.filter((c) => !c.folded).map((c) => ({ label: c.name, color: c.color, shape: 'square' })), ...(top.some((c) => c.folded) ? [{ label: en ? 'Other' : 'Otros', color: theme.other, shape: 'square' }] : [])]
+  const top = root.children;
+  const active = focus.path[0];
+  const legend = top.length > 1 && spec.legend !== false
+    ? [...top.filter((c) => !c.folded).map((c) => ({ label: c.name, value: c.name, color: c.color, shape: 'square', active: active === undefined ? undefined : active === c.name })), ...(top.some((c) => c.folded) ? [{ label: en ? 'Other' : 'Otros', color: theme.other, shape: 'square' }] : [])]
     : [];
 
   const frame = createFrame(spec, theme, { height: (spec.width || 720) < 560 ? Math.round((spec.width || 720) + 190) : Math.min(560, Math.max(380, (spec.width || 720) * 0.7)) });
@@ -126,7 +127,7 @@ export function sunburst(spec, theme) {
     measure(small, 11.5) <= r0 * 1.7 ? text(cx, cy + bigSize * 0.3 + 16, small, { fill: theme.lede, fontSize: 11.5, textAnchor: 'middle' }) : '',
   ]));
 
-  const top3 = top.slice(0, 3).map((c) => `${c.name} ${share(c.value, total)}`).join(', ');
+  const top3 = focus.children.slice(0, 3).map((c) => `${c.name} ${share(c.value, total)}`).join(', ');
   const what = humanize(valueField);
   const desc = en
     ? `Sunburst of ${what} in ${fields.length} levels, total ${fmt(total)}. Largest groups: ${top3}.`

package/src/charts/treemap.js

@@ -85,7 +85,8 @@ export function treemap(spec, theme) {
   if (byChange) (function walk(n) { if (!n.children.length) { const c = changeOf(n); if (c !== null) cMax = Math.max(cMax, Math.abs(c)); } n.children.forEach(walk); })(focus);
   cMax = spec.changeDomain ?? (Math.ceil(Math.min(1, cMax || 0.1) * 20) / 20);
   // Crecimiento en el tono frío, caída en el cálido; gris neutro sin cambio.
-  const divRamp = [...theme.diverging].reverse();
+  // Con una colormap propia (cmap) se respeta su orientación: bajo → alto.
+  const divRamp = theme.cmap ? [...theme.diverging] : [...theme.diverging].reverse();
   const changeColor = (c) => (c === null ? theme.tint : ramp(divRamp, 0.5 + Math.max(-1, Math.min(1, c / cMax)) / 2));
 
   // Leyenda del primer nivel visible, con su participación: la leyenda también informa.
@@ -93,12 +94,14 @@ export function treemap(spec, theme) {
   let legend = [];
   if (byChange && spec.legend !== false) {
     const lab = (v) => `${v > 0 ? '+' : v < 0 ? '−' : ''}${formatNumber(Math.abs(v) * 100, 0, locale)}%`;
-    legend = [{ type: 'ramp', stops: [...theme.diverging].reverse(), min: lab(-cMax), max: lab(cMax), title: (en ? 'Change' : 'Variación') + (prevLabel ? (en ? ' vs ' : ' vs ') + prevLabel : '') }];
-  } else if (levels > 1 && top.length > 1 && spec.legend !== false && !focus.path.length) {
-    const shown = top.filter((c) => !c.folded);
-    const sh0 = shareFmt(locale);
-    legend = shown.map((c) => ({ label: `${c.name} ${sh0(c.value, focus.value)}`, color: c.color, shape: 'square' }));
-    if (top.some((c) => c.folded)) legend.push({ label: en ? 'Other' : 'Otros', color: theme.other, shape: 'square' });
+    legend = [{ type: 'ramp', stops: divRamp, min: lab(-cMax), max: lab(cMax), title: (en ? 'Change' : 'Variación') + (prevLabel ? (en ? ' vs ' : ' vs ') + prevLabel : '') }];
+  } else if (height(root) > 1 && root.children.length > 1 && spec.legend !== false) {
+    // Leyenda del primer nivel, también al entrar a un grupo: clic = ver solo
+    // esa categoría en todo el plano; shift + clic = quitarla (en el navegador).
+    const tops = root.children;
+    const active = focus.path[0];
+    legend = tops.filter((c) => !c.folded).map((c) => ({ label: `${c.name} ${share(c.value, root.value)}`, value: c.name, color: c.color, shape: 'square', active: active === undefined ? undefined : active === c.name }));
+    if (tops.some((c) => c.folded)) legend.push({ label: en ? 'Other' : 'Otros', color: theme.other, shape: 'square' });
   }
 
   // En pantallas angostas el treemap crece hacia abajo: rectángulos legibles.

package/src/charts/wordcloud.js

@@ -0,0 +1,163 @@
+// Nube de palabras, hecha con cuidado.
+//
+//   plot({ type: 'wordcloud', data, text: 'palabra', value: 'menciones' })
+//   plot({ type: 'wordcloud', text: 'respuestas abiertas de una encuesta…' })
+//
+// Decisiones de diseño (lo que suele salir mal en una nube):
+// · Todas las palabras horizontales: girarlas obliga a torcer el cuello.
+// · El tamaño de letra crece con la raíz de la frecuencia, para que el ÁREA
+//   de la palabra (no su altura) sea proporcional al conteo.
+// · Colocación determinista en espiral desde el centro, la más frecuente
+//   primero; sin choques, con aire entre palabras. Mismo spec, misma nube.
+// · Color con significado: por grupo (`series`) con leyenda, o un solo tono
+//   que se oscurece con la frecuencia. Nunca colores al azar.
+// · Si una palabra no cabe, se achica toda la nube; las que igual no caben
+//   se informan en la descripción, nunca se cortan.
+// · Con texto crudo, cuenta palabras quitando las vacías (es/en).
+import { g, text, tip } from '../svg.js';
+import { measure } from '../text.js';
+import { makeFormat, formatNumber } from '../format.js';
+import { colorMap, ramp } from '../theme.js';
+import { ensureData, requireField, num, fieldsOf, fieldKind, humanize, PlotError } from '../data.js';
+import { createFrame } from '../frame.js';
+import { ctx } from '../context.js';
+
+const T = (locale, es, en) => (String(locale || 'es').startsWith('en') ? en : es);
+
+const STOP = new Set((
+  // Español
+  'a al algo algún alguna algunas alguno algunos ante antes aquel aquella aquellas aquellos aquí así aun aún bajo bien cada casi como cómo con contra cual cuál cuales cuando cuándo de del desde donde dónde dos el él ella ellas ellos en entre era eran es esa esas ese eso esos esta está están estar este esto estos fue fueron ha había han hasta hay la las le les lo los más me mi mis mismo mucho muy nada ni no nos nosotros nuestra nuestro o os otra otras otro otros para pero poco por porque qué que quien quién se sea ser si sí sin sobre son su sus también tan tanto te tiene tienen todo todos tu tus un una uno unos usted ustedes ya yo estoy estamos fue sido ser hacer hace cosa cosas solo sólo vez veces etc pues entonces luego'
+  // English
+  + ' a about above after again all am an and any are as at be because been before being below between both but by can could did do does doing down during each few for from further had has have having he her here hers him his how i if in into is it its itself just me more most my no nor not now of off on once only or other our ours out over own same she should so some such than that the their them then there these they this those through to too under until up very was we were what when where which while who whom why will with would you your yours also get got really much many one two'
+).split(/\s+/));
+
+/** Texto crudo → [{ text, value }] por frecuencia. */
+export function countWords(input, { locale, minLength = 3, stopwords = [] } = {}) {
+  const extra = new Set([].concat(stopwords).map((w) => String(w).toLowerCase()));
+  const counts = new Map(), shown = new Map();
+  const docs = [].concat(input).filter((d) => typeof d === 'string');
+  for (const d of docs) for (const m of d.matchAll(/[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu)) {
+    const raw = m[0].replace(/['’-]+$/, '');
+    const k = raw.toLowerCase();
+    if (k.length < minLength || STOP.has(k) || extra.has(k) || /^\d+$/.test(k)) continue;
+    counts.set(k, (counts.get(k) || 0) + 1);
+    // Se muestra la forma más común (respeta "Biobío", "IA", "ChatGPT").
+    const f = shown.get(k) || new Map();
+    f.set(raw, (f.get(raw) || 0) + 1);
+    shown.set(k, f);
+  }
+  return [...counts].map(([k, v]) => ({ text: [...shown.get(k)].sort((a, b) => b[1] - a[1])[0][0], value: v }));
+}
+
+export function wordcloud(spec, theme) {
+  const locale = spec.locale || 'es';
+  const en = String(locale).startsWith('en');
+  // ── Palabras ────────────────────────────────────────────────────────────
+  let words, groupF = null, valueF = 'value';
+  // `text` es un campo de los datos, o el texto mismo a contar (string o lista de strings).
+  const isField = typeof spec.text === 'string' && Array.isArray(spec.data) && spec.data.length > 0 && fieldsOf(spec.data).includes(spec.text);
+  const rawText = !isField && (typeof spec.text === 'string' || (Array.isArray(spec.text) && spec.text.length > 0 && spec.text.every((t) => typeof t === 'string')));
+  if (rawText || (spec.textField && spec.data)) {
+    const docs = rawText ? spec.text : ensureData(spec).map((r) => r[spec.textField]);
+    words = countWords(docs, { locale, minLength: spec.minLength ?? 3, stopwords: spec.stopwords });
+    valueF = T(locale, 'menciones', 'mentions');
+  } else {
+    const data = ensureData(spec);
+    const fields = fieldsOf(data);
+    const textF = spec.text ?? spec.word ?? spec.label ?? spec.x ?? fields.find((f) => /^(word|palabra|term|término|termino|text|texto|tag|keyword)$/i.test(f)) ?? fields.find((f) => fieldKind(data, f) === 'category');
+    valueF = spec.value ?? spec.size ?? spec.y ?? fields.find((f) => f !== textF && fieldKind(data, f) === 'number');
+    groupF = spec.series ?? spec.hue ?? spec.group ?? (typeof spec.color === 'string' && !spec.color.startsWith('#') ? spec.color : null);
+    requireField(data, textF, 'text');
+    if (valueF) requireField(data, valueF, 'value');
+    if (groupF) requireField(data, groupF, 'series');
+    const acc = new Map();
+    for (const r of data) {
+      const t = String(r[textF] ?? '').trim();
+      if (!t) continue;
+      const v = valueF ? num(r[valueF]) : 1;
+      if (!Number.isFinite(v) || v <= 0) continue;
+      const e = acc.get(t) || { text: t, value: 0, group: groupF ? String(r[groupF]) : null };
+      e.value += v;
+      acc.set(t, e);
+    }
+    words = [...acc.values()];
+  }
+  if (!words.length) throw new PlotError(T(locale, 'La nube no tiene palabras.', 'The word cloud has no words.'), T(locale, 'Pasa filas { palabra, valor } o `text: "…"` con el texto a contar.', 'Pass rows { word, value } or `text: "…"` with the text to count.'));
+  words.sort((a, b) => b.value - a.value || a.text.localeCompare(b.text));
+  const total = words.reduce((a, w) => a + w.value, 0);
+  const top = spec.top ?? 80;
+  const dropped = Math.max(0, words.length - top);
+  words = words.slice(0, top);
+
+  // ── Marco y color ───────────────────────────────────────────────────────
+  const groups = groupF ? [...new Set(words.map((w) => w.group))] : [];
+  const cmap = groups.length ? colorMap(groups, theme, spec.colors) : null;
+  const legend = groups.map((gname) => ({ label: gname, color: cmap.get(gname), shape: 'square' }));
+  const frame = createFrame(spec, theme, { height: 460 });
+  const area = frame.layout(legend);
+  const vmax = words[0].value, vmin = words[words.length - 1].value;
+  const hl = spec.highlight === undefined ? null : new Set([].concat(spec.highlight).map((s) => String(s).toLowerCase()));
+  const colorOf = (w, t) => {
+    if (cmap) return cmap.get(w.group);
+    if (spec.colors && spec.colors[w.text]) return spec.colors[w.text];
+    // Un solo tono: más frecuente, más oscuro (en tema oscuro, más claro).
+    return ramp(theme.sequential, 0.5 + 0.5 * t);
+  };
+
+  // ── Colocación: espiral, de la más frecuente a la menos ─────────────────
+  const XS = ctx.textScale;
+  const minF = spec.minFont ?? 11;
+  const maxF0 = spec.maxFont ?? Math.max(26, Math.min(80, Math.sqrt(area.w * area.h) / 6.2));
+  const cx = area.x + area.w / 2, cy = area.y + area.h / 2;
+  const pad = 3;
+  const tryLayout = (k) => {
+    const maxF = Math.max(minF + 4, maxF0 * k);
+    const placed = [], miss = [];
+    const cell = 40, grid = new Map();
+    const keyOf = (i, j) => i * 100003 + j;
+    const cellsOf = (b) => { const out = []; for (let i = Math.floor(b[0] / cell); i <= Math.floor(b[2] / cell); i++) for (let j = Math.floor(b[1] / cell); j <= Math.floor(b[3] / cell); j++) out.push(keyOf(i, j)); return out; };
+    const hit = (b) => { for (const c of cellsOf(b)) for (const o of grid.get(c) || []) if (!(b[2] <= o[0] || b[0] >= o[2] || b[3] <= o[1] || b[1] >= o[3])) return true; return false; };
+    const add = (b) => { for (const c of cellsOf(b)) { if (!grid.has(c)) grid.set(c, []); grid.get(c).push(b); } };
+    const ratio = area.w / Math.max(1, area.h);
+    for (const [idx, w] of words.entries()) {
+      const t = vmax === vmin ? 0.6 : Math.sqrt((w.value - vmin) / (vmax - vmin));
+      const size = Math.max(minF, minF + (maxF - minF) * t);
+      const weight = t > 0.55 ? 600 : t > 0.2 ? 500 : 400;
+      const bw = measure(w.text, size, weight), bh = size * XS * 1.02;
+      if (bw > area.w || bh > area.h) { miss.push(w); continue; }
+      let ok = null;
+      // Espiral de Arquímedes, achatada según la forma del panel.
+      for (let s = 0, r = 0; r < Math.hypot(area.w, area.h); s += 0.12) {
+        r = 1.6 * s;
+        const x = cx + r * Math.cos(s + idx * 0.7) * Math.sqrt(ratio), y = cy + r * Math.sin(s + idx * 0.7) / Math.sqrt(ratio);
+        const b = [x - bw / 2 - pad, y - bh / 2 - pad, x + bw / 2 + pad, y + bh / 2 + pad];
+        if (b[0] < area.x || b[2] > area.x + area.w || b[1] < area.y || b[3] > area.y + area.h) continue;
+        if (!hit(b)) { ok = { x, y, b }; break; }
+      }
+      if (!ok) { miss.push(w); continue; }
+      add(ok.b);
+      placed.push({ ...w, x: ok.x, y: ok.y, size, weight, t, bh });
+    }
+    return { placed, miss };
+  };
+  let L = tryLayout(1);
+  // Si no caben las importantes (el primer cuarto), se achica la nube entera.
+  for (let k = 0.88, n = 0; n < 7 && L.miss.some((w) => words.indexOf(w) < Math.max(5, words.length / 4)); k *= 0.88, n++) L = tryLayout(k);
+  const fmt = makeFormat(spec.format, locale, words.map((w) => w.value));
+  const body = L.placed.map((w) => {
+    const color = colorOf(w, w.t);
+    const dim = hl && !hl.has(w.text.toLowerCase());
+    const share = total ? ` · ${formatNumber((100 * w.value) / total, (100 * w.value) / total < 10 ? 1 : 0, locale)}%` : '';
+    return text(w.x, w.y + w.bh * 0.3, w.text, {
+      class: 'pa-m', fill: dim ? theme.dim : hl ? theme.categorical[1] : color, fontSize: w.size, fontWeight: w.weight, textAnchor: 'middle',
+      letterSpacing: w.size > 30 ? '-0.02em' : null, 'data-color': color, 'data-tip': tip(w.text, `${fmt(w.value)} ${valueF ? humanize(valueF).toLowerCase() : ''}${share}`.trim(), w.group),
+    });
+  });
+  // ── Descripción ─────────────────────────────────────────────────────────
+  const head = words.slice(0, 5).map((w) => `${w.text} (${fmt(w.value)})`).join(', ');
+  let desc = en ? `Word cloud of ${L.placed.length} words, sized by ${valueF ? humanize(valueF).toLowerCase() : 'frequency'}. Most frequent: ${head}.` : `Nube de ${L.placed.length} palabras, con tamaño según ${valueF ? humanize(valueF).toLowerCase() : 'frecuencia'}. Más frecuentes: ${head}.`;
+  const lost = L.miss.length + dropped;
+  if (lost) desc += en ? ` ${lost} less frequent words are not shown.` : ` No se muestran ${lost} palabras menos frecuentes.`;
+  return frame.finish([g({ class: 'pa-words' }, body)], { desc, type: 'wordcloud' });
+}
+