plotagents 0.0.0-stage → 0.7.0

package/src/charts/scatter.js

@@ -0,0 +1,214 @@
+// Dispersión y burbujas: relación entre dos variables numéricas, con tamaño
+// opcional (área proporcional), escalas log y línea de tendencia.
+import { el, g, text, tip, dotLayer } from '../svg.js';
+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, 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 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) => 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) && (!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));
+  const focus = (p) => !hl || hl.has(p.name) || hl.has(p.k);
+  const colorOf = (p) => (!focus(p) ? theme.dim : series ? cmap.get(p.k) : theme.categorical[0]);
+
+  const fx = makeFormat(spec.xFormat, locale, pts.map((p) => p.x));
+  const fy = makeFormat(spec.yFormat ?? spec.format, locale, pts.map((p) => p.y));
+  const fs = size ? makeFormat(spec.sizeFormat, locale, pts.map((p) => p.s)) : null;
+
+  const legend = series && keys.length > 1 && spec.legend !== false ? keys.map((k) => ({ label: k, color: cmap.get(k) })) : [];
+  const frame = createFrame(spec, theme, { height: 460 });
+  const area = frame.layout(legend);
+
+  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 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 = 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 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 }));
+  body.push(gridX(xS.ticks(dx.step), xS, inner, theme, xtf, { baseline: NaN }));
+  body.push(el('line', { x1: inner.x, x2: inner.x + inner.w, y1: inner.y + inner.h + 0.5, y2: inner.y + inner.h + 0.5, stroke: theme.axis }));
+  // Títulos de ejes: horizontales, nunca rotados.
+  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));
+    const n = tx.length, mx = tx.reduce((a, b) => a + b, 0) / n, my = ty.reduce((a, b) => a + b, 0) / n;
+    let sxy = 0, sxx = 0, syy = 0;
+    for (let i = 0; i < n; i++) { sxy += (tx[i] - mx) * (ty[i] - my); sxx += (tx[i] - mx) ** 2; syy += (ty[i] - my) ** 2; }
+    const b = sxy / (sxx || 1), a = my - b * mx;
+    const r2v = sxx && syy ? (sxy * sxy) / (sxx * syy) : 0;
+    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);
+    // 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));
+  body.push(refLinesX(spec.refLines || [], xS, inner, theme, fx));
+
+  // Burbujas grandes debajo, chicas arriba; anillo del color de fondo.
+  const sorted = [...pts].sort((a, b) => (focus(a) - focus(b)) || b.s - a.s);
+  // 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, { 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));
+
+  // Etiquetas selectivas: las que pide el agente o las N mayores.
+  if (labelF && spec.labels !== false) {
+    let chosen;
+    if (Array.isArray(spec.labels)) chosen = pts.filter((p) => spec.labels.map(String).includes(p.name));
+    else {
+      const n = typeof spec.labels === 'number' ? spec.labels : hl ? 0 : Math.min(6, pts.length);
+      chosen = [...pts].sort((a, b) => (size ? b.s - a.s : b.y - a.y)).slice(0, n);
+      if (hl) chosen = chosen.concat(pts.filter((p) => hl.has(p.name)));
+    }
+    const placed = [];
+    for (const p of chosen) {
+      if (!p.name) continue;
+      const w = measure(p.name, 12, 500);
+      const r = rOf(p);
+      let lx = xS(p.x) + r + 4, ly = yS(p.y) + 4, anchor = 'start';
+      if (lx + w > inner.x + inner.w) { lx = xS(p.x) - r - 4; anchor = 'end'; }
+      const box = anchor === 'start' ? [lx, ly - 11, lx + w, ly + 3] : [lx - w, ly - 11, lx, ly + 3];
+      if (placed.some((b) => !(box[2] < b[0] || box[0] > b[2] || box[3] < b[1] || box[1] > b[3]))) continue;
+      placed.push(box);
+      body.push(el('text', { x: lx, y: ly, fill: theme.ink, fontSize: 12, fontWeight: 500, textAnchor: anchor, stroke: theme.surface, strokeWidth: 3, paintOrder: 'stroke', strokeLinejoin: 'round' }, p.name.replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c])));
+    }
+  }
+
+  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.`;
+  return frame.finish(g({}, body), { desc, type: size ? 'bubble' : 'scatter' });
+}

package/src/charts/sunburst.js

@@ -0,0 +1,136 @@
+// Sunburst: la misma jerarquía que el treemap, en anillos concéntricos. El
+// anillo interior es el primer nivel (color por categoría); los exteriores
+// heredan el color con pasos sutiles de luminosidad. Total al centro.
+import { el, g, text, tip } from '../svg.js';
+import { measure } from '../text.js';
+import { makeFormat } from '../format.js';
+import { textOn } from '../theme.js';
+import { humanize } from '../data.js';
+import { createFrame } from '../frame.js';
+import { buildHierarchy, findNode, assignColors, shareFmt, breadcrumb, height, SEP } from '../hierarchy.js';
+
+const TAU = Math.PI * 2;
+const f = (n) => n.toFixed(2);
+
+function arcPath(cx, cy, r0, r1, a0, a1) {
+  if (a1 - a0 >= TAU - 1e-6) a1 = a0 + TAU - 1e-4;
+  const large = a1 - a0 > Math.PI ? 1 : 0;
+  const p = (r, a) => `${f(cx + r * Math.cos(a))},${f(cy + r * Math.sin(a))}`;
+  if (r0 <= 0.01) return `M${f(cx)},${f(cy)}L${p(r1, a0)}A${f(r1)},${f(r1)} 0 ${large} 1 ${p(r1, a1)}Z`;
+  return `M${p(r1, a0)}A${f(r1)},${f(r1)} 0 ${large} 1 ${p(r1, a1)}L${p(r0, a1)}A${f(r0)},${f(r0)} 0 ${large} 0 ${p(r0, a0)}Z`;
+}
+
+export function sunburst(spec, theme) {
+  const locale = spec.locale || 'es';
+  const en = String(locale).startsWith('en');
+  const { root, fields, valueField } = buildHierarchy(spec);
+  const focus = findNode(root, spec.focus);
+  const levels = Math.max(1, height(focus));
+  assignColors(root, theme, spec); // colores estables al navegar
+  const vals = [];
+  (function walk(n) { vals.push(n.value); n.children.forEach(walk); })(root);
+  const fmt = makeFormat(spec.format, locale, vals);
+  const share = shareFmt(locale);
+  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 = 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)) });
+  let area = frame.layout(legend);
+  const body = [];
+  const bc = breadcrumb(focus, area.x, area.y, area.w, theme, locale);
+  if (bc.h) { body.push(bc.svg); area = { ...area, y: area.y + bc.h, h: area.h - bc.h }; }
+
+  const R = Math.max(40, Math.min(area.w, area.h) / 2 - 2);
+  const cx = area.x + area.w / 2, cy = area.y + area.h / 2;
+  const r0 = R * (spec.hole ?? 0.3);
+  // Anillos: el exterior más delgado cuando hay muchos niveles.
+  const weights = Array.from({ length: levels }, (_, i) => (levels >= 3 && i === levels - 1 ? 0.62 : 1));
+  const wsum = weights.reduce((a, b) => a + b, 0);
+  const radii = [r0];
+  weights.forEach((w) => radii.push(radii[radii.length - 1] + ((R - r0) * w) / wsum));
+
+  const total = focus.value, grand = root.value;
+  const sep = theme.marks?.gap ?? 2;
+  const arcs = [];
+  const labels = [];
+  (function layout(n, a0, a1, d) {
+    let a = a0;
+    for (const c of n.children) {
+      const span = ((a1 - a0) * c.value) / (n.value || 1);
+      if (d < levels) {
+        arcs.push({ n: c, a0: a, a1: a + span, r0: radii[d], r1: radii[d + 1], d: d + 1 });
+        layout(c, a, a + span, d + 1);
+      }
+      a += span;
+    }
+  })(focus, -Math.PI / 2, (3 * Math.PI) / 2, 0);
+
+  for (const a of arcs) {
+    const n = a.n;
+    const fill = dim(n) ? theme.dim : n.color;
+    const parent = n.parent && n.parent.depth > 0 ? n.parent : null;
+    const t = tip(n.path.join(SEP), `${fmt(n.value)} · ${share(n.value, grand)} ${en ? 'of total' : 'del total'}`, parent ? `${share(n.value, parent.value)} ${en ? 'of' : 'de'} ${parent.name}` : '');
+    const drill = n.children.length ? JSON.stringify(n.path) : undefined;
+    body.push(el('path', {
+      class: 'pa-m', d: arcPath(cx, cy, a.r0, a.r1, a.a0, a.a1), fill,
+      stroke: theme.surface, strokeWidth: Math.min(sep, 1.75), strokeLinejoin: 'round',
+      'data-tip': t, 'data-drill': drill, style: drill ? 'cursor:pointer' : undefined,
+    }));
+    // Etiqueta: tangencial si cabe a lo largo del arco; si no, radial; si no, nada.
+    const mid = (a.a0 + a.a1) / 2;
+    const rm = (a.r0 + a.r1) / 2;
+    const thick = a.r1 - a.r0;
+    const ink = textOn(fill, theme);
+    for (const size of [12, 11, 10]) {
+      const w = measure(n.name, size, 600);
+      const deg = (mid * 180) / Math.PI;
+      const half = (a.a1 - a.a0) / 2;
+      // Tangencial: texto recto sobre un arco. Se busca un radio donde el
+      // borde interior no cruce r0 y las puntas no salgan por r1.
+      const rt = a.r0 + 2 + size / 2;
+      const reach = Math.sqrt((rt + size / 2) ** 2 + (w / 2 + 3) ** 2);
+      const angOk = half < Math.PI / 2 && w / 2 + 4 <= (rt - size / 2) * Math.tan(half);
+      if (reach <= a.r1 - 2 && angOk) {
+        const lo = rt, hi = Math.sqrt(Math.max(0, (a.r1 - 2) ** 2 - (w / 2 + 3) ** 2)) - size / 2;
+        const rr = Math.max(lo, Math.min(hi, (lo + hi) / 2));
+        let rot = deg + 90;
+        if (Math.sin(mid) > 0) rot -= 180;
+        labels.push(text(0, 0, n.name, { transform: `translate(${f(cx + rr * Math.cos(mid))},${f(cy + rr * Math.sin(mid))}) rotate(${f(rot)})`, textAnchor: 'middle', dy: size * 0.35, fill: ink, fontSize: size, fontWeight: 600, pointerEvents: 'none' }));
+        break;
+      }
+      // Radial: a lo largo del radio, si el anillo es largo y el arco ancho.
+      if (w + 10 <= thick && 2 * a.r0 * Math.sin(Math.min(half, Math.PI / 2)) >= size + 3) {
+        let rot = deg;
+        if (Math.cos(mid) < 0) rot += 180;
+        labels.push(text(0, 0, n.name, { transform: `translate(${f(cx + rm * Math.cos(mid))},${f(cy + rm * Math.sin(mid))}) rotate(${f(rot)})`, textAnchor: 'middle', dy: size * 0.35, fill: ink, fontSize: size, fontWeight: 600, pointerEvents: 'none' }));
+        break;
+      }
+    }
+  }
+  body.push(g({ class: 'pa-labels' }, labels));
+
+  // Centro: total (o el nodo en foco). Clic en el centro sube un nivel.
+  const big = spec.centerValue ?? fmt(total);
+  let bigSize = Math.min(30, r0 * 0.46);
+  while (bigSize > 12 && measure(big, bigSize, 600) > r0 * 1.7) bigSize -= 1;
+  const small = spec.centerLabel ?? (focus.path.length ? focus.name : en ? 'Total' : 'Total');
+  const up = focus.path.length ? JSON.stringify(focus.path.slice(0, -1)) : undefined;
+  body.push(g({ class: 'pa-center', 'data-drill': up, style: up ? 'cursor:pointer' : undefined }, [
+    el('circle', { cx, cy, r: Math.max(0, r0 - 2), fill: theme.surface }),
+    text(cx, cy + bigSize * 0.3, big, { fill: theme.ink, fontSize: bigSize, fontWeight: 600, textAnchor: 'middle' }),
+    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 = 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}.`
+    : `Sunburst de ${what.toLowerCase()} en ${fields.length} niveles, total ${fmt(total)}. Mayores grupos: ${top3}.`;
+  return frame.finish(body, { desc, type: 'sunburst' });
+}

package/src/charts/treemap.js

@@ -0,0 +1,197 @@
+// Treemap de varios niveles (estilo Atlas de Complejidad Económica / d3plus).
+// Color por grupo de primer nivel, variación sutil de luminosidad en niveles
+// más profundos, encabezados de grupo cuando hay espacio y etiquetas que solo
+// aparecen si caben. Drill-down: data-drill + spec.focus.
+import { el, g, text, tip, esc } from '../svg.js';
+import { measure, wrap } from '../text.js';
+import { makeFormat } from '../format.js';
+import { textOn, ramp } from '../theme.js';
+import { formatNumber } from '../format.js';
+import { humanize } from '../data.js';
+import { createFrame } from '../frame.js';
+import { ctx } from '../context.js';
+import { buildHierarchy, findNode, assignColors, shareFmt, breadcrumb, height, SEP } from '../hierarchy.js';
+
+/** Algoritmo squarified (Bruls, Huizing & van Wijk, 2000). */
+export function squarify(items, x, y, w, h) {
+  const out = [];
+  const total = items.reduce((a, b) => a + b.value, 0);
+  if (total <= 0 || w <= 0 || h <= 0) return out;
+  const scale = (w * h) / total;
+  const nodes = items.map((it) => ({ it, area: it.value * scale })).filter((n) => n.area > 0);
+  let rect = { x, y, w, h };
+  let row = [];
+  const worst = (r, side) => {
+    const s = r.reduce((a, b) => a + b.area, 0);
+    const mx = Math.max(...r.map((n) => n.area)), mn = Math.min(...r.map((n) => n.area));
+    return Math.max((side * side * mx) / (s * s), (s * s) / (side * side * mn));
+  };
+  const layoutRow = (r, last) => {
+    const s = r.reduce((a, b) => a + b.area, 0);
+    if (rect.w >= rect.h) {
+      const cw = last ? rect.w : s / rect.h;
+      let cy = rect.y;
+      r.forEach((n, i) => { const ch = i === r.length - 1 ? rect.y + rect.h - cy : n.area / cw; out.push({ ...n.it, x: rect.x, y: cy, w: cw, h: ch }); cy += ch; });
+      rect = { x: rect.x + cw, y: rect.y, w: rect.w - cw, h: rect.h };
+    } else {
+      const ch = last ? rect.h : s / rect.w;
+      let cx = rect.x;
+      r.forEach((n, i) => { const cw = i === r.length - 1 ? rect.x + rect.w - cx : n.area / ch; out.push({ ...n.it, x: cx, y: rect.y, w: cw, h: ch }); cx += cw; });
+      rect = { x: rect.x, y: rect.y + ch, w: rect.w, h: rect.h - ch };
+    }
+  };
+  nodes.forEach((n, idx) => {
+    const side = Math.min(rect.w, rect.h);
+    if (!row.length || worst([...row, n], side) <= worst(row, side)) row.push(n);
+    else { layoutRow(row, false); row = [n]; }
+    if (idx === nodes.length - 1) layoutRow(row, true);
+  });
+  return out;
+}
+
+// Separación entre hermanos según la profundidad visible (1 = primer nivel).
+// Separación por nivel: más aire entre categorías, menos dentro de ellas.
+const GAP = (d) => (d <= 1 ? 4 : d === 2 ? 2 : 1);
+
+export function treemap(spec, theme) {
+  const locale = spec.locale || 'es';
+  const en = String(locale).startsWith('en');
+  const { root, fields, valueField } = buildHierarchy(spec);
+  const focus = findNode(root, spec.focus);
+  const levels = height(focus);
+  // El color sigue a la entidad: se asigna sobre el árbol completo, así al
+  // entrar a un grupo sus elementos conservan la familia de color del padre.
+  const single = height(root) <= 1 && spec.colorBy !== 'label';
+  assignColors(root, theme, spec, { single });
+  const allValues = [];
+  (function walk(n) { allValues.push(n.value); n.children.forEach(walk); })(root);
+  const fmt = makeFormat(spec.format, locale, allValues);
+  const share = shareFmt(locale);
+  const hl = spec.highlight === undefined ? null : new Set([].concat(spec.highlight).map(String));
+
+  // Variación vs. el periodo anterior (con `time`) o vs. `compareData`.
+  const prevRows = spec.compareData ?? spec._prev?.data;
+  const prevLabel = spec.compareLabel ?? spec._prev?.label;
+  const prevMap = new Map();
+  if (prevRows && prevRows.length) {
+    const pr = buildHierarchy({ ...spec, data: prevRows, time: undefined }).root;
+    (function walk(n) { prevMap.set(n.path.join('\u0000'), n.value); n.children.forEach(walk); })(pr);
+  }
+  const changeOf = (n) => { const pv = prevMap.get(n.path.join('\u0000')); return pv > 0 ? n.value / pv - 1 : null; };
+  const showChange = prevMap.size > 0 && spec.change !== false;
+  const byChange = showChange && spec.colorBy === 'change';
+  const pctTxt = (c) => (c === null ? '' : `${c > 0 ? '▲' : c < 0 ? '▼' : '■'} ${formatNumber(Math.abs(c) * 100, Math.abs(c) < 0.1 ? 1 : 0, locale, true)}%`);
+  let cMax = 0;
+  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.
+  // 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.
+  const top = focus.children;
+  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: 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.
+  const W = spec.width || 720;
+  const frame = createFrame(spec, theme, { height: W < 560 ? Math.round(Math.min(780, W * 1.15 + 170)) : Math.round(Math.max(440, Math.min(620, W * 0.62))) });
+  let area = frame.layout(legend);
+  const body = [];
+  const bc = breadcrumb(focus, area.x, area.y, area.w, theme, locale);
+  if (bc.h) { body.push(bc.svg); area = { ...area, y: area.y + bc.h, h: area.h - bc.h }; }
+
+  const total = focus.value;
+  const grand = root.value;
+  const R = theme.marks?.barRadius ?? 4;
+
+  const tipFor = (n) => {
+    const parentShare = n.parent && n.parent.value ? share(n.value, n.parent.value) : '';
+    const ch = showChange ? changeOf(n) : null;
+    return tip(
+      n.path.join(SEP),
+      `${fmt(n.value)} · ${share(n.value, grand)} ${en ? 'of total' : 'del total'}`,
+      n.parent && n.parent.depth > 0 ? `${parentShare} ${en ? 'of' : 'de'} ${n.parent.name}` : '',
+      ch !== null ? `${pctTxt(ch)} ${prevLabel ? 'vs ' + prevLabel : ''}`.trim() : ''
+    );
+  };
+  const dim = (n) => hl && !n.path.some((p) => hl.has(p));
+
+  function drawLeaf(n, x, y, w, h, relDepth) {
+    if (w < 0.6 || h < 0.6) return '';
+    const ch = showChange ? changeOf(n) : null;
+    const fill = dim(n) ? theme.dim : byChange ? changeColor(ch) : n.color;
+    const rx = Math.max(0, Math.min(R - 1, w / 6, h / 6));
+    const parts = [el('rect', { x, y, width: w, height: h, rx, fill })];
+    const extra = [spec.showValues ? fmt(n.value) : null, ch !== null ? pctTxt(ch) : null].filter(Boolean).join(' · ');
+    parts.push(...tileLabel(n.name, share(n.value, total), x, y, w, h, textOn(fill, theme), extra || null, relDepth));
+    const drill = relDepth === 1 && n.children.length ? JSON.stringify(n.path) : undefined;
+    return g({ class: 'pa-m', 'data-tip': tipFor(n), 'data-drill': drill, style: drill ? 'cursor:pointer' : undefined }, parts);
+  }
+
+  function drawNode(n, x, y, w, h, relDepth) {
+    // Hoja visible (sin hijos o al fondo de la jerarquía mostrada).
+    if (!n.children.length) return drawLeaf(n, x, y, w, h, relDepth);
+    // Sin bandas de encabezado: el área de cada grupo es exactamente su valor.
+    // La categoría se reconoce por su color sólido, el espacio entre grupos y la leyenda.
+    const parts = [];
+    const iy = y, ih = h;
+    const gap = GAP(relDepth + 1);
+    const rects = squarify(n.children, x, iy, w, ih);
+    for (const c of rects) parts.push(drawNode(c, c.x + gap / 2, c.y + gap / 2, c.w - gap, c.h - gap, relDepth + 1));
+    const drill = relDepth === 1 ? JSON.stringify(n.path) : undefined;
+    return g({ class: relDepth === 1 ? 'pa-group' : undefined, 'data-tip': relDepth === 1 ? tipFor(n) : undefined, 'data-drill': drill, style: drill ? 'cursor:pointer' : undefined }, parts);
+  }
+
+  const g1 = GAP(1);
+  const rects = squarify(focus.children, area.x - g1 / 2, area.y - g1 / 2, area.w + g1, area.h + g1);
+  for (const r of rects) body.push(drawNode(r, r.x + g1 / 2, r.y + g1 / 2, r.w - g1, r.h - g1, 1));
+
+  const leaves = [];
+  (function walk(n) { if (!n.children.length) leaves.push(n); n.children.forEach(walk); })(focus);
+  const top3 = leaves.sort((a, b) => b.value - a.value).slice(0, 3).map((l) => `${l.name} ${share(l.value, total)}`).join(', ');
+  const what = humanize(valueField);
+  const where = focus.path.length ? ` (${focus.path.join(SEP)})` : '';
+  const desc = en
+    ? `Treemap of ${what}${where} across ${fields.length} level${fields.length > 1 ? 's' : ''}, total ${fmt(total)}. Largest: ${top3}.`
+    : `Treemap de ${what.toLowerCase()}${where} en ${fields.length} nivel${fields.length > 1 ? 'es' : ''}, total ${fmt(total)}. Mayores: ${top3}.`;
+  return frame.finish(body, { desc, type: 'treemap' });
+}
+
+/** Etiqueta dentro del rectángulo solo si cabe; tamaño según el área. */
+function tileLabel(name, pct, x, y, w, h, fill, value, depth) {
+  const out = [];
+  const pad = w < 60 || h < 40 ? 5 : 8;
+  const maxSize = depth <= 1 ? 24 : depth === 2 ? 18 : 15;
+  for (let size = Math.min(maxSize, Math.max(10, Math.sqrt(w * h) / 8.5)); size >= 9.5; size -= 1) {
+    const lines = wrap(name, w - pad * 2, size, 600, 3);
+    const X = ctx.textScale;
+    const lh = size * X * 1.14;
+    const pctSize = Math.max(9.5, size * 0.78);
+    const sub = value ? `${pct} · ${value}` : pct;
+    const need = pad + lines.length * lh + 3 + pctSize * X + pad * 0.5;
+    const widest = Math.max(...lines.map((l) => measure(l, size, 600)), measure(sub, pctSize));
+    const fitsW = lines.every((l) => measure(l, size, 600) <= w - pad * 2) && !/…$/.test(lines[lines.length - 1]);
+    if (fitsW && widest <= w - pad * 2 && need <= h) {
+      lines.forEach((l, i) => out.push(text(x + pad, y + pad + size * X * 0.88 + i * lh, l, { fill, fontSize: size, fontWeight: 600 })));
+      out.push(text(x + pad, y + pad + size * X * 0.88 + (lines.length - 1) * lh + pctSize * X + 4, sub, { fill, fontSize: pctSize, opacity: 0.86 }));
+      return out;
+    }
+    if (lines.length === 1 && fitsW && pad + lh <= h) {
+      out.push(text(x + pad, y + pad + size * X * 0.88, lines[0], { fill, fontSize: size, fontWeight: 600 }));
+      return out;
+    }
+  }
+  return out;
+}