plotagents 0.0.0-stage → 0.5.0

package/src/charts/scatter.js

@@ -0,0 +1,136 @@
+// 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 } from '../data.js';
+import { gridY, gridX, ticksWidth, refLinesY, refLinesX, yAxisMargin, yAxisTop, yGrid, yTickLabels, quietCorner } from '../axes.js';
+import { createFrame, SIZES } from '../frame.js';
+
+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 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);
+  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 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));
+  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 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))];
+  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 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 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));
+
+  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' }));
+
+  // 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);
+    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)' }));
+    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);
+    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);
+  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) };
+  });
+  body.push(dotLayer(circles));
+
+  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 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.`;
+  return frame.finish(g({}, body), { desc, type: size ? 'bubble' : 'scatter' });
+}

package/src/charts/sunburst.js

@@ -0,0 +1,135 @@
+// 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 = 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 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 = top.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,194 @@
+// 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.
+  const divRamp = [...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: [...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' });
+  }
+
+  // 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;
+}

package/src/context.js

@@ -0,0 +1,10 @@
+// Contexto de dibujo: valores globales que plot() fija mientras dibuja un
+// gráfico (todo es sincrónico, así que no hay mezcla entre gráficos).
+export const ctx = { textScale: 1 };
+
+/** Ejecuta fn con un contexto temporal y lo restaura después. */
+export function withContext(values, fn) {
+  const prev = { ...ctx };
+  Object.assign(ctx, values);
+  try { return fn(); } finally { Object.assign(ctx, prev); }
+}

package/src/dashed.js

@@ -0,0 +1,90 @@
+// Formas "punteadas" (`dashed`): para marcar lo que no es un dato firme —
+// estimaciones, proyecciones, cifras provisorias, territorios en disputa—
+// sin inventar otro color. La forma conserva su tono, pero con un relleno
+// rayado (franjas del color sobre una versión clara del mismo) y un contorno
+// discontinuo. En líneas, el trazo se vuelve discontinuo (`dashedFrom` corta
+// una serie en el punto donde empieza la proyección).
+//
+//   dashed: "Texas"                     → una categoría, serie o región
+//   dashed: ["Texas", "Ohio"]           → varias
+//   dashed: "provisional"               → un campo de los datos (filas con valor verdadero)
+//   dashed: { field: "estado", equals: "estimado" }
+//   dashedFrom: "2025"                  → desde ese x en adelante (líneas, áreas y columnas)
+//   dashedLabel: "Estimación"           → entrada de leyenda y línea en el tooltip
+import { el } from './svg.js';
+import { ramp, readable } from './theme.js';
+
+/** Trazos discontinuos: contornos cortos y finos; líneas algo más largas. */
+export const DASH = { outline: '4 2.5', line: '5 6', legend: '3.5 2.5' };
+
+const TRUE = /^(true|1|s[ií]|yes|y|x|✓)$/i;
+const truthy = (v) => v === true || v === 1 || (typeof v === 'string' && TRUE.test(v.trim()));
+
+/**
+ * Devuelve una función (clave, serie?) → boolean, o null si no hay `dashed`.
+ * `keyField` y `seriesField` dicen qué campos identifican cada forma.
+ */
+export function dashedMatcher(spec, data, keyField, seriesField, norm = String) {
+  const d = spec.dashed;
+  if (d === undefined || d === null || d === false) return null;
+  if (d === true) return () => true;
+  const row0 = data && data[0];
+  const field = typeof d === 'object' && !Array.isArray(d) ? d.field : typeof d === 'string' && row0 && d in row0 ? d : null;
+  if (field) {
+    const eq = typeof d === 'object' ? d.equals ?? d.value : undefined;
+    const pairs = new Set();
+    for (const r of data) {
+      const hit = eq !== undefined ? [].concat(eq).map(String).includes(String(r[field])) : truthy(r[field]);
+      if (hit) pairs.add(norm(r[keyField]) + '\u0000' + (seriesField ? norm(r[seriesField]) : ''));
+    }
+    return (k, s) => pairs.has(norm(k) + '\u0000' + (seriesField ? norm(s ?? '') : ''));
+  }
+  const keys = new Set([].concat(d).map(norm));
+  return (k, s) => keys.has(norm(k)) || (s !== undefined && s !== null && keys.has(norm(s)));
+}
+
+/** ¿El valor x está en el tramo proyectado (x ≥ dashedFrom)? */
+export function fromTest(spec, toNum) {
+  if (spec.dashedFrom === undefined || spec.dashedFrom === null) return null;
+  const t = toNum(spec.dashedFrom);
+  return Number.isFinite(t) ? (x) => Number.isFinite(x) && x >= t : null;
+}
+
+const isHex = (c) => /^#[0-9a-f]{3}([0-9a-f]{3})?$/i.test(String(c || ''));
+
+/**
+ * Fábrica de rellenos rayados, uno por color. `fill(c)` da el url(#…) y
+ * `defs()` los <pattern> que hay que poner en el SVG.
+ */
+export function hatcher(theme, id) {
+  const pats = new Map();
+  return {
+    fill(color) {
+      if (!pats.has(color)) pats.set(color, `${id}-h${pats.size}`);
+      return `url(#${pats.get(color)})`;
+    },
+    /** Contorno: el mismo tono, con al menos 3:1 contra el fondo (WCAG, gráficos). */
+    stroke(color) { return isHex(color) ? readable(color, theme, 3) : color; },
+    defs() {
+      return [...pats].map(([c, pid]) => pattern(pid, c, theme)).join('');
+    },
+    get size() { return pats.size; },
+  };
+}
+
+function pattern(pid, color, theme) {
+  const bg = isHex(color) && isHex(theme.surface) ? ramp([theme.surface, color], theme.mode === 'dark' ? 0.3 : 0.22) : null;
+  return el('pattern', { id: pid, width: 6, height: 6, patternUnits: 'userSpaceOnUse', patternTransform: 'rotate(45)' }, [
+    bg ? el('rect', { width: 6, height: 6, fill: bg }) : el('rect', { width: 6, height: 6, fill: color, fillOpacity: 0.22 }),
+    el('rect', { width: 2.6, height: 6, fill: color }),
+  ]);
+}
+
+/** Atributos de una forma punteada: relleno rayado + contorno discontinuo. */
+export function dashedAttrs(H, color, { width = 1.25 } = {}) {
+  return { fill: H.fill(color), stroke: H.stroke(color), strokeWidth: width, strokeDasharray: DASH.outline, 'data-dashed': '1', 'data-color': color };
+}
+
+const T = (locale, es, en) => (String(locale || 'es').startsWith('en') ? en : es);
+/** Texto por defecto para la leyenda cuando el agente no da `dashedLabel`. */
+export const dashedDefaultLabel = (locale) => T(locale, 'Estimado', 'Estimate');