plotagents 0.0.0-stage → 0.5.0

package/src/charts/choropleth.js

@@ -0,0 +1,559 @@
+// Mapas: coroplético (color por valor) y de símbolos (círculos proporcionales).
+// Geometrías por nombre registrado ('chile', 'usa', 'world') o GeoJSON propio.
+// Países alargados como Chile se dibujan a la izquierda con una columna de
+// etiquetas (nombre, barra y valor) ordenada de norte a sur; mapas anchos
+// usan todo el ancho con etiquetas solo donde importan. Los estados de EE. UU.
+// llevan su sigla (y el valor, si cabe); los chicos del noreste, afuera con
+// línea guía. En el navegador: zoom con clic, rueda (+ Ctrl/⌘) o pellizco.
+import { el, g, text } from '../svg.js';
+import { measure, truncate } from '../text.js';
+import { makeFormat } from '../format.js';
+import { ramp, textOn } from '../theme.js';
+import { ensureData, requireField, num, fieldsOf, fieldKind, humanize, aggregate } from '../data.js';
+import { createFrame, hash } from '../frame.js';
+import { niceStep } from '../scale.js';
+import { getGeo } from '../geo/registry.js';
+import { mercator, equalEarth, projections, fit, aspectOf, pathD, centroid, rings } from '../geo/projection.js';
+import { dashedMatcher, hatcher, dashedAttrs, dashedDefaultLabel, DASH } from '../dashed.js';
+
+const T = (locale, es, en) => (String(locale || 'es').startsWith('en') ? en : es);
+
+/** Normaliza nombres para que "Región del Bío-Bío", "Biobio" y "BIOBÍO" coincidan. */
+export function normKey(s) {
+  return String(s ?? '')
+    .normalize('NFD').replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/^\s*(region|provincia|comuna)\s+(metropolitana\s+de\s+)?(de\s+la\s+|del\s+|de\s+los\s+|de\s+las\s+|de\s+)?/, (m, a, metro) => (metro ? 'metropolitana' : ''))
+    .replace(/[^a-z0-9]/g, '');
+}
+
+function featureIndex(features, featureKey) {
+  const idx = new Map();
+  const add = (k, f) => { const n = normKey(k); if (n && !idx.has(n)) idx.set(n, f); };
+  for (const f of features) {
+    const p = f.properties || {};
+    if (featureKey) { add(p[featureKey], f); continue; }
+    for (const k of ['code', 'num', 'id', 'iso3', 'iso_a3', 'name', 'nameEn', 'NAME', 'nombre']) if (p[k] !== undefined && p[k] !== null) add(p[k], f);
+    for (const a of p.aliases || []) add(a, f);
+  }
+  return idx;
+}
+
+const nameOf = (f, locale) => {
+  const p = f.properties || {};
+  return (String(locale).startsWith('en') ? p.nameEn || p.name : p.name || p.nameEn) || p.NAME || p.nombre || String(p.code ?? p.id ?? '');
+};
+
+/** Redondeo "bonito" de un corte de clase (2 cifras relativas al rango). */
+function niceRound(v, range) {
+  if (!range) return v;
+  const step = 10 ** (Math.floor(Math.log10(range)) - 1);
+  return Math.round(v / step) * step;
+}
+
+function quantile(sorted, p) {
+  const h = (sorted.length - 1) * p, lo = Math.floor(h), hi = Math.ceil(h);
+  return sorted[lo] + (sorted[hi] - sorted[lo]) * (h - lo);
+}
+
+/** Escala de color: clases (cuantiles, intervalos iguales o cortes dados) o continua. */
+export function colorScale(values, spec, theme) {
+  const v = values.filter(Number.isFinite).sort((a, b) => a - b);
+  const min = v[0], max = v[v.length - 1], range = max - min;
+  const mid = spec.midpoint ?? (spec.diverging ? 0 : undefined);
+  const mode = Array.isArray(spec.scale) || Array.isArray(spec.thresholds) ? 'thresholds' : spec.scale || 'quantile';
+  if (mid !== undefined) {
+    const stops = theme.diverging;
+    const dev = Math.max(Math.abs(max - mid), Math.abs(min - mid)) || 1;
+    if (mode === 'continuous') return { mode, min: mid - dev, max: mid + dev, mid, color: (x) => ramp(stops, 0.5 + (x - mid) / dev / 2), stops };
+    // Clases simétricas: el paso "bonito" más chico que cubre la desviación
+    // con a lo más `classes/2` clases por lado (sin cortes fuera de los datos).
+    const perSide = Math.max(2, Math.floor((spec.classes ?? 6) / 2));
+    const mag = 10 ** Math.floor(Math.log10(dev / perSide));
+    const step = [1, 2, 2.5, 5, 10].map((k) => k * mag).find((st) => Math.ceil(dev / st - 1e-9) <= perSide) || 10 * mag;
+    const k = Math.max(1, Math.ceil(dev / step - 1e-9));
+    const breaks = Array.from({ length: 2 * k - 1 }, (_, j) => +(mid + step * (j + 1 - k)).toPrecision(12));
+    const n = 2 * k;
+    const colors = Array.from({ length: n }, (_, i) => ramp(stops, 0.5 + ((i + 0.5 - k) / k) * 0.5));
+    // Extremos simétricos (mid ± k·paso): la leyenda se lee igual hacia ambos lados.
+    return { ...classed(breaks, colors, Math.min(min, +(mid - k * step).toPrecision(12)), Math.max(max, +(mid + k * step).toPrecision(12))), mid };
+  }
+  const stops = theme.sequential;
+  if (mode === 'continuous') return { mode, min, max, color: (x) => ramp(stops.slice(1), (x - min) / (range || 1)), stops: stops.slice(1) };
+  let breaks;
+  if (mode === 'thresholds') breaks = [...(Array.isArray(spec.scale) ? spec.scale : spec.thresholds)].map(Number).sort((a, b) => a - b);
+  else {
+    const n = Math.max(2, Math.min(9, spec.classes ?? Math.min(5, v.length)));
+    if (mode === 'equal') breaks = Array.from({ length: n - 1 }, (_, k) => niceRound(min + (range * (k + 1)) / n, range));
+    else breaks = Array.from({ length: n - 1 }, (_, k) => niceRound(quantile(v, (k + 1) / n), range));
+    breaks = [...new Set(breaks)].filter((b) => b > min && b <= max);
+  }
+  const n = breaks.length + 1;
+  const t0 = theme.mode === 'dark' ? 0.26 : 0.16;
+  const colors = Array.from({ length: n }, (_, i) => ramp(stops, n === 1 ? 0.6 : t0 + ((1 - t0) * i) / (n - 1)));
+  return classed(breaks, colors, min, max);
+}
+
+function classed(breaks, colors, min, max) {
+  const cls = (x) => { let i = 0; while (i < breaks.length && x >= breaks[i]) i++; return i; };
+  return { mode: 'classes', breaks, colors, min, max, cls, color: (x) => colors[cls(x)] };
+}
+
+/** Leyenda escalonada (o degradado), pegada al mapa. Devuelve { svg, h }. */
+function legendBar(sc, x, y, maxW, theme, fmt, { title, missing, locale, gid, dashed }) {
+  const out = [];
+  let lx = x;
+  const size = theme.type?.axis ?? 11.5;
+  if (title) {
+    const tw = Math.min(measure(title, 12, 500), maxW * 0.4);
+    out.push(text(lx, y + 13, truncate(title, tw, 12, 500), { fill: theme.lede, fontSize: 12, fontWeight: 500 }));
+    lx += tw + 12;
+  }
+  // Anchos con su separación: cuadro + texto (+ espacio hasta la siguiente clave).
+  const missW = missing ? measure(T(locale, 'Sin dato', 'No data'), size) + 14 + (dashed ? 14 : 0) : 0;
+  const dashW = dashed ? measure(dashed.label, size) + 16 : 0;
+  // Si "Sin dato" y la clave punteada no caben junto a la escala, bajan a una segunda fila.
+  const extra = missW + dashW ? 14 + missW + dashW : 0;
+  const wrapX = 140 + extra > x + maxW - lx;
+  const barW = Math.max(120, Math.min(360, x + maxW - lx - (wrapX ? 0 : extra)));
+  const by = y + 4;
+  if (sc.mode === 'classes') {
+    const n = sc.colors.length, gap = 2;
+    const sw = (barW - gap * (n - 1)) / n;
+    // Cada clase es una clave conectada: al pasar encima se destacan sus regiones.
+    sc.colors.forEach((c, i) => out.push(g({ class: 'pa-key', 'data-color': c, style: 'cursor:pointer' }, [
+      el('rect', { x: lx + i * (sw + gap), y: by - 4, width: sw + gap, height: 18, fill: 'transparent' }),
+      el('rect', { x: lx + i * (sw + gap), y: by, width: sw, height: 10, rx: i === 0 || i === n - 1 ? 3 : 1, fill: c }),
+    ])));
+    // Etiquetas en los cortes; los extremos (mín. y máx.) en las puntas.
+    // Los extremos solo se rotulan si caen fuera de los cortes (con cortes fijos, un año puede no llegar a la última clase).
+    const labels = [
+      ...(sc.min < sc.breaks[0] || !sc.breaks.length ? [{ x: lx, v: sc.min, anchor: 'start' }] : []),
+      ...sc.breaks.map((b, i) => ({ x: lx + (i + 1) * (sw + gap) - gap / 2, v: b, anchor: 'middle' })),
+      ...(sc.max >= sc.breaks[sc.breaks.length - 1] || !sc.breaks.length ? [{ x: lx + barW, v: sc.max, anchor: 'end' }] : []),
+    ];
+    let last = -Infinity;
+    for (const L of labels) {
+      const s = fmt(L.v), w = measure(s, size);
+      const left = L.anchor === 'start' ? L.x : L.anchor === 'end' ? L.x - w : L.x - w / 2;
+      if (left < last + 6) continue;
+      out.push(text(L.x, by + 24, s, { fill: theme.muted, fontSize: size, textAnchor: L.anchor }));
+      last = left + w;
+    }
+  } else {
+    const id = gid + '-grad';
+    const stops = Array.from({ length: 9 }, (_, i) => el('stop', { offset: `${i * 12.5}%`, stopColor: sc.color(sc.min + ((sc.max - sc.min) * i) / 8) }));
+    out.push(el('defs', {}, el('linearGradient', { id }, stops)));
+    out.push(el('rect', { x: lx, y: by, width: barW, height: 10, rx: 3, fill: `url(#${id})` }));
+    out.push(text(lx, by + 24, fmt(sc.min), { fill: theme.muted, fontSize: size }));
+    if (sc.mid !== undefined) out.push(text(lx + barW / 2, by + 24, fmt(sc.mid), { fill: theme.muted, fontSize: size, textAnchor: 'middle' }));
+    out.push(text(lx + barW, by + 24, fmt(sc.max), { fill: theme.muted, fontSize: size, textAnchor: 'end' }));
+  }
+  let mx = wrapX ? x : lx + barW + 14;
+  const ey = wrapX ? by + 32 : by;
+  if (missing) {
+    out.push(g({ class: 'pa-key', 'data-color': `url(#${gid}-nd)`, style: 'cursor:pointer' }, [
+      el('rect', { x: mx, y: ey, width: 10, height: 10, rx: 2, fill: `url(#${gid}-nd)`, stroke: theme.axis, strokeWidth: 0.5 }),
+      text(mx + 14, ey + 9, T(locale, 'Sin dato', 'No data'), { fill: theme.muted, fontSize: size }),
+    ]));
+    mx += missW;
+  }
+  if (dashed) {
+    out.push(g({ class: 'pa-key', 'data-color': 'dashed', style: 'cursor:pointer' }, [
+      el('rect', { x: mx + 0.6, y: ey + 0.6, width: 9.8, height: 9.8, rx: 2, fill: dashed.fill, stroke: dashed.stroke, strokeWidth: 1.1, strokeDasharray: DASH.legend }),
+      text(mx + 15, ey + 9, dashed.label, { fill: theme.lede, fontSize: size }),
+    ]));
+  }
+  return { svg: g({ class: 'pa-legend pa-map-legend' }, out), h: wrapX && (missing || dashed) ? 50 : 34 };
+}
+
+/** Patrón rayado para regiones sin dato. */
+const noDataPattern = (id, theme) =>
+  `<pattern id="${id}" width="5" height="5" patternUnits="userSpaceOnUse" patternTransform="rotate(45)"><rect width="5" height="5" fill="${theme.tint}"/><line x1="0" y1="0" x2="0" y2="5" stroke="${theme.muted}" stroke-width="1" stroke-opacity="0.35"/></pattern>`;
+
+/** Datos + geometría emparejados. */
+function prepare(spec, locale) {
+  const fc = getGeo(spec.geo ?? 'chile');
+  const data = ensureData(spec);
+  const fields = fieldsOf(data);
+  const key = spec.key ?? spec.region ?? spec.x ?? spec.label ?? fields.find((f) => fieldKind(data, f) === 'category');
+  const valueF = spec.value ?? spec.y ?? (typeof spec.size === 'string' ? spec.size : null) ?? fields.find((f) => f !== key && fieldKind(data, f) === 'number');
+  requireField(data, key, 'key');
+  requireField(data, valueF, 'value');
+  let features = fc.features.filter((f) => f.geometry && rings(f.geometry).length);
+  if (!spec.antarctica) features = features.filter((f) => (f.properties || {}).iso3 !== 'ATA');
+  let idx = featureIndex(features, spec.featureKey);
+  // Territorios opcionales (Puerto Rico en 'usa'): solo se dibujan si hay datos para ellos.
+  if (features.some((f) => f.properties?.optional)) {
+    const used = new Set(data.map((r) => idx.get(normKey(r[key]))).filter(Boolean));
+    features = features.filter((f) => !f.properties?.optional || used.has(f) || spec.territories === true);
+    idx = featureIndex(features, spec.featureKey);
+  }
+  const buckets = new Map();
+  const unmatched = [];
+  for (const r of data) {
+    const f = idx.get(normKey(r[key]));
+    if (!f) { if (r[key] !== undefined && r[key] !== null && r[key] !== '') unmatched.push(String(r[key])); continue; }
+    if (!buckets.has(f)) buckets.set(f, []);
+    buckets.get(f).push(num(r[valueF]));
+  }
+  const values = new Map();
+  for (const [f, vs] of buckets) { const v = aggregate(vs, spec.aggregate || 'mean'); if (Number.isFinite(v)) values.set(f, v); }
+  if (Array.isArray(spec._unmatched)) spec._unmatched.push(...new Set(unmatched));
+  const ranked = [...values.entries()].sort((a, b) => b[1] - a[1]);
+  const rank = new Map(ranked.map(([f], i) => [f, i + 1]));
+  const projName = spec.projection ?? fc.projection ?? (/^(world|mundo|countries|paises|países)$/i.test(String(spec.geo)) ? 'equalEarth' : null);
+  const lonSpan = (() => { let a = Infinity, b = -Infinity; for (const f of features) for (const r of rings(f.geometry)) for (const p of r) { if (p[0] < a) a = p[0]; if (p[0] > b) b = p[0]; } return b - a; })();
+  const raw = (projName && projections[projName] ? projections[projName] : lonSpan > 100 ? equalEarth : mercator)();
+  // `dashed`: por nombre de región (con los mismos alias) o por un campo de los datos.
+  const dm = dashedMatcher(spec, data, key, null, normKey);
+  const dashed = new Set(dm ? features.filter((f) => featureKeys(f).some((k) => dm(k))) : []);
+  return { fc, features, values, rank, ranked, unmatched: [...new Set(unmatched)], key, valueF, raw, data, dashed };
+}
+
+/**
+ * Columna de etiquetas para mapas altos: una fila por región a la altura de
+ * su centroide (separadas si chocan), con línea guía, barra y valor.
+ */
+function labelColumn(items, x, y0, y1, w, theme, fmt, { bars = true, maxV }) {
+  const out = [];
+  const n = items.length;
+  const rowH = Math.max(12.5, Math.min(18, (y1 - y0) / Math.max(1, n)));
+  const fs = rowH < 14 ? 10.5 : 11.5;
+  // Separación vertical (orden norte → sur se conserva).
+  const rows = items.map((it) => ({ ...it, y: it.cy })).sort((a, b) => a.cy - b.cy);
+  for (let i = 0; i < rows.length; i++) rows[i].y = Math.max(rows[i].y, i ? rows[i - 1].y + rowH : y0 + rowH / 2);
+  for (let i = rows.length - 1; i >= 0; i--) { const lim = i === rows.length - 1 ? y1 - rowH / 2 : rows[i + 1].y - rowH; if (rows[i].y > lim) rows[i].y = lim; }
+  for (let i = 0; i < rows.length; i++) if (rows[i].y < y0 + rowH / 2 + i * rowH) rows[i].y = y0 + rowH / 2 + i * rowH;
+  const nameW = Math.min(w * (bars ? 0.46 : 0.68), Math.max(...rows.map((r) => measure(r.name, fs))));
+  const valW = Math.max(...rows.map((r) => measure(r.label, fs, 600)));
+  const barX = x + nameW + 8;
+  const diverging = rows.some((r) => r.v < 0);
+  const barMax = Math.max(0, w - nameW - valW * (diverging ? 2 : 1) - (diverging ? 26 : 18));
+  const showBars = bars && barMax >= 36;
+  const negMax = diverging ? Math.max(0, ...rows.filter((r) => r.v < 0).map((r) => -r.v)) : 0;
+  const posMax = Math.max(0, ...rows.filter((r) => r.v > 0).map((r) => r.v));
+  // Con valores negativos, eje en cero y barras hacia ambos lados.
+  const zeroX = diverging ? barX + valW + 6 + (barMax * negMax) / (negMax + posMax || 1) : barX;
+  const scaleW = diverging ? barMax / (negMax + posMax || 1) : barMax / (maxV || 1);
+  if (showBars && diverging) out.push(el('line', { x1: zeroX, x2: zeroX, y1: y0, y2: y1, stroke: theme.axis, strokeWidth: 1 }));
+  for (const r of rows) {
+    const parts = [];
+    // Línea guía: horizontal desde el centroide y quiebre suave a la fila.
+    parts.push(el('path', { d: `M${r.cx.toFixed(1)},${r.cy.toFixed(1)}L${(x - 14).toFixed(1)},${r.cy.toFixed(1)}L${(x - 4).toFixed(1)},${r.y.toFixed(1)}`, fill: 'none', stroke: theme.muted, strokeWidth: 0.6, opacity: 0.55 }));
+    parts.push(el('circle', { cx: r.cx, cy: r.cy, r: 1.8, fill: theme.ink, opacity: 0.7 }));
+    parts.push(text(x, r.y + fs * 0.36, truncate(r.name, nameW, fs), { fill: r.missing ? theme.muted : theme.lede, fontSize: fs }));
+    if (r.missing) parts.push(text(showBars ? barX : x + nameW + 8, r.y + fs * 0.36, r.label, { fill: theme.muted, fontSize: fs }));
+    else if (showBars) {
+      const bw = Math.max(2, Math.abs(r.v) * scaleW);
+      const bx = r.v < 0 ? zeroX - bw : zeroX;
+      parts.push(el('rect', { x: bx, y: r.y - 3.5, width: bw, height: 7, rx: 2, fill: r.barColor || r.color }));
+      parts.push(text(r.v < 0 ? bx - 6 : bx + bw + 6, r.y + fs * 0.36, r.label, { fill: theme.ink, fontSize: fs, fontWeight: 600, textAnchor: r.v < 0 ? 'end' : 'start' }));
+    } else parts.push(text(x + nameW + 8, r.y + fs * 0.36, r.label, { fill: theme.ink, fontSize: fs, fontWeight: 600 }));
+    out.push(g({ class: 'pa-m', 'data-tip': r.tip }, parts));
+  }
+  return out;
+}
+
+/** Etiquetas sobre el mapa (mapas anchos): solo las elegidas y sin choques. */
+function mapLabels(items, theme, placedBoxes = []) {
+  const out = [];
+  for (const it of items) {
+    const w = Math.max(measure(it.name, 11, 600), measure(it.label, 11));
+    const box = [it.cx - w / 2 - 2, it.cy - 13, it.cx + w / 2 + 2, it.cy + 13];
+    if (placedBoxes.some((b) => !(box[2] < b[0] || box[0] > b[2] || box[3] < b[1] || box[1] > b[3]))) continue;
+    placedBoxes.push(box);
+    const halo = { stroke: theme.surface, strokeWidth: 3, paintOrder: 'stroke', strokeLinejoin: 'round', textAnchor: 'middle' };
+    out.push(g({ class: 'pa-map-label', 'pointer-events': 'none' }, [
+      text(it.cx, it.cy - 2, it.name, { fill: theme.ink, fontSize: 11, fontWeight: 600, ...halo }),
+      text(it.cx, it.cy + 11, it.label, { fill: theme.lede, fontSize: 11, ...halo }),
+    ]));
+  }
+  return out;
+}
+
+function chooseLabeled(m, spec, locale, defaultN) {
+  const hl = spec.highlight === undefined ? [] : [].concat(spec.highlight).map(normKey);
+  const isHl = (f) => hl.length && featureIndexHas(f, hl);
+  if (Array.isArray(spec.labels)) { const want = spec.labels.map(normKey); return m.features.filter((f) => featureIndexHas(f, want)); }
+  const n = typeof spec.labels === 'number' ? spec.labels : spec.labels === false ? 0 : defaultN;
+  const top = m.ranked.slice(0, n).map(([f]) => f);
+  return [...new Set([...m.features.filter(isHl), ...top])];
+}
+function featureKeys(f) {
+  const p = f.properties || {};
+  return [p.code, p.num, p.id, p.iso3, p.fips, p.name, p.nameEn, ...(p.aliases || [])].filter((v) => v !== undefined && v !== null).map(normKey);
+}
+function featureIndexHas(f, keys) {
+  const own = featureKeys(f);
+  return keys.some((k) => own.includes(k));
+}
+
+/**
+ * Siglas sobre el mapa (estados de EE. UU. u otra geometría con `abbr`): la
+ * sigla va dentro si cabe, con el valor debajo cuando hay espacio. Las
+ * marcadas `callout` (estados chicos) van en una columna a la derecha con
+ * línea guía, ordenadas por altura.
+ */
+function abbrLabels(items, proj, theme, { calloutX, showValues, top, bottom }) {
+  const inside = [], callouts = [];
+  const fs = Math.max(8.5, Math.min(11, proj.bounds.w / 62));
+  for (const it of items) {
+    const p = it.f.properties || {};
+    if (!p.abbr) continue;
+    const at = p.labelAt ? proj(p.labelAt) : [it.cx, it.cy];
+    if (p.callout && calloutX) { callouts.push({ ...it, ax: it.cx, ay: it.cy }); continue; }
+    const s = Math.sqrt(it.area);
+    const aw = measure(p.abbr, fs, 600);
+    if (aw + 3 > s * 0.95) {
+      // Islas chicas (Hawái, Puerto Rico): la sigla al lado, fuera de la forma.
+      if (!proj.inset || !proj.inset(p.labelAt || it.f.geometry && rings(it.f.geometry)[0][0])) continue;
+      let x1 = -Infinity;
+      for (const r of rings(it.f.geometry)) for (const pt of r) x1 = Math.max(x1, proj(pt)[0]);
+      inside.push(text(x1 + 5, at[1] + fs * 0.36, p.abbr, { fill: theme.lede, fontSize: fs, fontWeight: 600 }));
+      continue;
+    }
+    const ink = it.dashedShape ? theme.ink : textOn(it.color, theme);
+    const val = showValues && !it.missing && s > fs * 3.4 && measure(it.label, fs - 1) + 4 < s * 0.92;
+    const y0 = at[1] + (val ? -1 : fs * 0.36);
+    const halo = it.dashedShape ? { stroke: theme.surface, strokeWidth: 2.5, paintOrder: 'stroke', strokeLinejoin: 'round' } : {};
+    inside.push(text(at[0], y0, p.abbr, { fill: ink, fontSize: fs, fontWeight: 600, textAnchor: 'middle', ...halo }));
+    if (val) inside.push(text(at[0], y0 + fs + 0.5, it.label, { fill: ink, fontSize: fs - 1, textAnchor: 'middle', opacity: 0.88, ...halo }));
+  }
+  const out = [g({ class: 'pa-map-label pa-zoom-hide', 'pointer-events': 'none' }, inside)];
+  if (callouts.length) {
+    const rowH = fs + 5.5;
+    const rows = callouts.sort((a, b) => a.ay - b.ay).map((c) => ({ ...c, y: c.ay }));
+    for (let i = 0; i < rows.length; i++) rows[i].y = Math.max(rows[i].y, i ? rows[i - 1].y + rowH : top + rowH / 2);
+    for (let i = rows.length - 1; i >= 0; i--) { const lim = i === rows.length - 1 ? bottom - rowH / 2 : rows[i + 1].y - rowH; if (rows[i].y > lim) rows[i].y = lim; }
+    const parts = rows.map((r) => {
+      const p = r.f.properties;
+      const ax = r.ax.toFixed(1), ay = r.ay.toFixed(1);
+      return g({ class: 'pa-m', 'data-tip': r.tip, 'data-color': r.color }, [
+        el('path', { d: `M${ax},${ay}L${(calloutX - 12).toFixed(1)},${r.y.toFixed(1)}L${(calloutX - 3).toFixed(1)},${r.y.toFixed(1)}`, fill: 'none', stroke: theme.muted, strokeWidth: 0.6, opacity: 0.7 }),
+        el('circle', { cx: ax, cy: ay, r: 1.6, fill: theme.ink, opacity: 0.75 }),
+        el('rect', { x: calloutX, y: r.y - 4.5, width: 9, height: 9, rx: 2, ...(r.dashedShape ? { fill: r.fill, stroke: r.stroke, strokeWidth: 1, strokeDasharray: DASH.legend } : { fill: r.missing ? r.fill : r.color }) }),
+        text(calloutX + 13, r.y + fs * 0.36, p.abbr, { fill: theme.ink, fontSize: fs, fontWeight: 600 }),
+        showValues ? text(calloutX + 18 + measure(p.abbr, fs, 600), r.y + fs * 0.36, r.label, { fill: theme.lede, fontSize: fs }) : '',
+      ]);
+    });
+    out.push(g({ class: 'pa-callouts pa-zoom-hide' }, parts));
+  }
+  return out;
+}
+
+/** Recuadros (Alaska, Hawái, Puerto Rico): un marco fino y discontinuo. */
+function insetFrames(features, proj, theme) {
+  if (!proj.inset) return '';
+  const boxes = new Map();
+  for (const f of features) for (const r of rings(f.geometry)) {
+    const k = proj.inset(r[0]);
+    if (!k) continue;
+    const b = boxes.get(k) || [Infinity, Infinity, -Infinity, -Infinity];
+    for (const pt of r) { const [x, y] = proj(pt); b[0] = Math.min(b[0], x); b[1] = Math.min(b[1], y); b[2] = Math.max(b[2], x); b[3] = Math.max(b[3], y); }
+    boxes.set(k, b);
+  }
+  const pad = 7;
+  return g({ class: 'pa-insets', 'pointer-events': 'none' }, [...boxes.values()].map((b) => el('rect', { x: b[0] - pad, y: b[1] - pad, width: b[2] - b[0] + 2 * pad, height: b[3] - b[1] + 2 * pad, rx: 6, fill: 'none', stroke: theme.axis, strokeWidth: 0.8, strokeDasharray: '2 3' })));
+}
+
+function baseChart(spec, theme, kind) {
+  const locale = spec.locale || 'es';
+  const m = prepare(spec, locale);
+  const vals = [...m.values.values()];
+  const fmt = makeFormat(spec.format, locale, vals);
+  const W = spec.width || 720;
+  const aspect = aspectOf(m.features, m.raw);
+  const tall = aspect > 1.6 && m.features.length <= 40;
+  // Alto por defecto según la forma del territorio.
+  const defH = tall ? (W < 560 ? 660 : 740) : Math.round(W * Math.min(1.1, aspect) + 150);
+  const frame = createFrame(spec, theme, { height: defH });
+  let area = frame.layout([]);
+  const gid = 'pa-map-' + Math.abs(hash(String(spec.title) + kind + W)).toString(36);
+  const missingAny = spec.missing !== 'plain' && m.features.some((f) => !m.values.has(f));
+  const body = [];
+  let sc = null;
+  const H = hatcher(theme, gid);
+  const dashedLabel = spec.dashedLabel ?? dashedDefaultLabel(locale);
+  const dashedKey = m.dashed.size && spec.legend !== false ? { label: dashedLabel, fill: H.fill(theme.muted), stroke: H.stroke(theme.muted) } : null;
+  if (kind === 'choropleth' && vals.length) {
+    sc = colorScale(vals, spec, theme);
+    const lg = legendBar(sc, area.x, area.y, area.w, theme, fmt.tick ? (v) => fmt(v) : fmt, { title: spec.legendTitle ?? humanize(m.valueF), missing: missingAny, locale, gid, dashed: dashedKey });
+    body.push(lg.svg);
+    area = { ...area, y: area.y + lg.h + 8, h: area.h - lg.h - 8 };
+  }
+  // Mapa de símbolos ancho: la leyenda de tamaños va arriba, en fila (abajo chocaría con Alaska o la Antártida).
+  let rMax = null;
+  if (kind === 'symbol') {
+    const N = m.values.size;
+    const wEst = area.w, hEst = wEst * Math.min(1.1, aspect);
+    rMax = spec.maxRadius ?? Math.max(8, Math.min(30, Math.sqrt(tall ? (area.h / aspect) * area.h : wEst * hEst) / (tall ? 9 : N > 30 ? 22 : 16)));
+  }
+  let lx = area.x;
+  const rowItems = [];
+  if (kind === 'symbol' && !tall && vals.length) {
+    const maxV = Math.max(...vals.map(Math.abs), 0) || 1;
+    const size = theme.type?.axis ?? 11.5;
+    const base = area.y + 2 * rMax + 2;
+    for (const v of [maxV / 16, maxV / 4, maxV]) {
+      const r = Math.sqrt(v / maxV) * rMax;
+      rowItems.push(el('circle', { cx: lx + r, cy: base - r, r, fill: 'none', stroke: theme.muted, strokeWidth: 0.8 }));
+      rowItems.push(text(lx + 2 * r + 5, base - 1, fmt(v), { fill: theme.muted, fontSize: size }));
+      lx += 2 * r + 12 + measure(fmt(v), size);
+    }
+    lx += 10;
+  }
+  if (dashedKey && !(kind === 'choropleth' && vals.length)) {
+    const size = theme.type?.axis ?? 11.5;
+    const ky = rowItems.length ? area.y + 2 * rMax - 9 : area.y + 4.6;
+    rowItems.push(g({ class: 'pa-key', 'data-color': 'dashed', style: 'cursor:pointer' }, [
+      el('rect', { x: lx + 0.6, y: ky, width: 9.8, height: 9.8, rx: 2, fill: dashedKey.fill, stroke: dashedKey.stroke, strokeWidth: 1.1, strokeDasharray: DASH.legend }),
+      text(lx + 15, ky + 8.4, dashedLabel, { fill: theme.lede, fontSize: size }),
+    ]));
+  }
+  if (rowItems.length) {
+    const h = kind === 'symbol' && !tall ? 2 * rMax + 12 : 26;
+    body.push(g({ class: 'pa-legend pa-size-legend' }, rowItems));
+    area = { ...area, y: area.y + h, h: area.h - h };
+  }
+  // Columna de siglas para estados chicos (EE. UU.): se reserva a la derecha.
+  const callouts = kind === 'choropleth' && !tall && spec.labels !== false ? m.features.filter((f) => f.properties?.callout && f.properties?.abbr) : [];
+  const fsC = Math.max(8.5, Math.min(11, (area.w * 0.9) / 62));
+  const calloutW = callouts.length
+    ? 18 + Math.max(...callouts.map((f) => measure(f.properties.abbr, fsC, 600) + (kind === 'choropleth' && m.values.has(f) ? measure(fmt(m.values.get(f)), fsC) + 4 : 0)))
+    : 0;
+  // Mapa ancho: el alto se ajusta al ancho si el agente no fijó `height`.
+  if (!tall && spec.height === undefined) {
+    const mapH = (area.w - calloutW) * Math.min(1.1, aspect);
+    frame.setHeight(area.y + mapH + frame.chrome);
+    area = { ...area, h: frame.bottom - area.y };
+  }
+  let box;
+  if (tall) {
+    const colMin = W < 480 ? 0.56 : 0.5;
+    let mapW = Math.min(area.w * (1 - colMin), area.h / aspect);
+    box = [area.x, area.y, area.x + mapW, area.y + area.h];
+  } else box = [area.x, area.y, area.x + area.w - calloutW, area.y + area.h];
+  const proj = fit(m.features, m.raw, box, { align: tall ? 'left' : 'center' });
+  const calloutX = calloutW ? proj.bounds.x + proj.bounds.w + 14 : 0;
+  return { locale, m, vals, fmt, frame, area, gid, missingAny, body, sc, proj, tall, H, dashedLabel, calloutX, rMax };
+}
+
+const rankText = (r, n, locale) => (String(locale).startsWith('en') ? `#${r} of ${n}` : `${r}.º de ${n}`);
+
+/** Capa del mapa con recorte: el navegador la escala y desplaza (zoom). */
+function zoomLayer(B, children) {
+  const { area, gid } = B;
+  const box = [area.x, area.y, area.w, area.h].map((v) => Math.round(v * 10) / 10);
+  return [
+    el('clipPath', { id: `${gid}-clip` }, el('rect', { x: box[0], y: box[1] - 2, width: box[2], height: box[3] + 4 })),
+    // Fondo transparente: la rueda, el arrastre y el pellizco funcionan también sobre el mar.
+    g({ class: 'pa-zoom-clip', 'clip-path': `url(#${gid}-clip)` }, [el('rect', { x: box[0], y: box[1], width: box[2], height: box[3], fill: 'transparent' }), g({ class: 'pa-zoom', 'data-zoom': box.join(',') }, children)]),
+  ];
+}
+
+export function choropleth(spec, theme) {
+  const B = baseChart(spec, theme, 'choropleth');
+  const { locale, m, fmt, frame, area, gid, body, sc, proj, tall, H, dashedLabel, calloutX } = B;
+  const hl = spec.highlight === undefined ? null : [].concat(spec.highlight).map(normKey);
+  const isHl = (f) => hl && featureIndexHas(f, hl);
+  const N = m.values.size;
+  const regions = [], dashedRegions = [], outlines = [];
+  const items = [];
+  for (const f of m.features) {
+    const v = m.values.get(f);
+    const has = v !== undefined;
+    const base = has ? sc.color(v) : null;
+    const isDashed = m.dashed.has(f);
+    const name = nameOf(f, locale);
+    const tipTxt = (has ? `${name}\n${fmt(v)} · ${rankText(m.rank.get(f), N, locale)}` : `${name}\n${T(locale, 'Sin dato', 'No data')}`) + (isDashed ? `\n${dashedLabel}` : '');
+    const d = pathD(f.geometry, proj);
+    const common = { class: 'pa-m', d, strokeLinejoin: 'round', opacity: hl && !isHl(f) ? 0.5 : null, 'data-tip': tipTxt, 'data-k': normKey(f.properties?.code ?? f.properties?.iso3 ?? name) };
+    let fill = has ? base : spec.missing === 'plain' ? theme.tint : `url(#${gid}-nd)`;
+    let stroke = null;
+    if (isDashed && has) {
+      // Rayado del color de su clase + borde discontinuo: se lee igual en la escala.
+      const a = dashedAttrs(H, base, { width: 1.2 });
+      fill = a.fill; stroke = a.stroke;
+      dashedRegions.push(el('path', { ...common, ...a }));
+    } else if (isDashed) {
+      stroke = theme.muted;
+      dashedRegions.push(el('path', { ...common, fill, stroke, strokeWidth: 1.1, strokeDasharray: DASH.outline, 'data-dashed': '1', 'data-color': fill }));
+    } else regions.push(el('path', { ...common, fill, stroke: theme.surface, strokeWidth: 0.75, 'data-color': fill }));
+    if (isHl(f)) outlines.push(el('path', { d, fill: 'none', stroke: theme.ink, strokeWidth: 1.5, strokeLinejoin: 'round', 'pointer-events': 'none' }));
+    const c = centroid(f.geometry, proj);
+    items.push({ f, name, v, cx: c.x, cy: c.y, area: c.area, label: has ? fmt(v) : '—', color: has ? base : theme.tint, fill, stroke, dashedShape: isDashed, missing: !has, tip: tipTxt });
+  }
+  const layer = [g({ class: 'pa-regions' }, regions), dashedRegions.length ? g({ class: 'pa-regions pa-dashed' }, dashedRegions) : '', g({ class: 'pa-outlines' }, outlines), insetFrames(m.features, proj, theme)];
+  const after = [];
+  if (tall && spec.labels !== false) {
+    const x = proj.bounds.x + proj.bounds.w + 26;
+    const maxV = Math.max(...[...m.values.values()].map(Math.abs));
+    after.push(...labelColumn(items, x, area.y, area.y + area.h, area.x + area.w - x, theme, fmt, { bars: spec.bars !== false, maxV }));
+  } else if (spec.labels !== false && m.features.some((f) => f.properties?.abbr) && !Array.isArray(spec.labels) && typeof spec.labels !== 'number') {
+    const [lab, ...rest] = abbrLabels(items, proj, theme, { calloutX, showValues: spec.values !== false, top: area.y, bottom: area.y + area.h });
+    layer.push(lab);
+    after.push(...rest);
+  } else {
+    const chosen = new Set(chooseLabeled(m, spec, locale, m.features.length <= 30 ? m.features.length : 0));
+    const ordered = items.filter((it) => chosen.has(it.f) && !it.missing).sort((a, b) => b.area - a.area);
+    layer.push(g({ class: 'pa-zoom-hide' }, mapLabels(ordered, theme)));
+  }
+  body.push(...(tall ? layer : zoomLayer(B, layer)), ...after);
+  const desc = describeMap(m, fmt, locale, T(locale, 'Mapa coroplético', 'Choropleth map'));
+  return frame.finish(body, { desc, type: 'choropleth', defs: noDataPattern(`${gid}-nd`, theme) + H.defs() });
+}
+
+/** Mapa de símbolos: círculos de área proporcional en el centroide. */
+export function symbolMap(spec, theme) {
+  const B = baseChart(spec, theme, 'symbol');
+  const { locale, m, fmt, frame, area, body, proj, tall, gid, H, dashedLabel, rMax } = B;
+  const N = m.values.size;
+  const maxV = Math.max(...[...m.values.values()].map(Math.abs), 0) || 1;
+  const color = (spec.colors && Object.values(spec.colors)[0]) || theme.categorical[0];
+  const layer = [g({ class: 'pa-regions pa-base' }, m.features.map((f) => el('path', { d: pathD(f.geometry, proj), fill: theme.tint, stroke: theme.surface, strokeWidth: 0.75, strokeLinejoin: 'round', 'data-k': normKey(f.properties?.code ?? f.properties?.iso3 ?? nameOf(f, locale)) }))), insetFrames(m.features, proj, theme)];
+  const items = m.features.map((f) => {
+    const c = centroid(f.geometry, proj);
+    const v = m.values.get(f);
+    const name = nameOf(f, locale);
+    const isDashed = m.dashed.has(f);
+    const at = f.properties?.labelAt ? proj(f.properties.labelAt) : [c.x, c.y];
+    return { f, name, v, cx: at[0], cy: at[1], area: c.area, r: v === undefined ? 0 : Math.sqrt(Math.abs(v) / maxV) * rMax, label: v === undefined ? '—' : fmt(v), color, missing: v === undefined, dashedShape: isDashed,
+      tip: (v === undefined ? `${name}\n${T(locale, 'Sin dato', 'No data')}` : `${name}\n${fmt(v)} · ${rankText(m.rank.get(f), N, locale)}`) + (isDashed ? `\n${dashedLabel}` : '') };
+  });
+  const circles = items.filter((it) => !it.missing).sort((a, b) => b.r - a.r)
+    .map((it) => el('circle', { class: 'pa-m', cx: it.cx, cy: it.cy, r: Math.max(1.5, it.r), 'data-tip': it.tip, 'data-color': color,
+      ...(it.dashedShape ? { ...dashedAttrs(H, color, { width: 1.3 }) } : { fill: color, fillOpacity: 0.75, stroke: theme.surface, strokeWidth: 1.5 }) }));
+  layer.push(g({ class: 'pa-symbols' }, circles));
+  // Leyenda de tamaños (tres círculos anidados) en la esquina libre.
+  const sizes = [maxV, maxV / 4, maxV / 16].map((v) => ({ v, r: Math.sqrt(v / maxV) * rMax }));
+  const lx = tall ? proj.bounds.x + proj.bounds.w + 26 : area.x + 4, ly = tall ? area.y + area.h - 4 : area.y + area.h - 4;
+  const leg = sizes.map((s) => [
+    el('circle', { cx: lx + rMax, cy: ly - s.r, r: s.r, fill: 'none', stroke: theme.muted, strokeWidth: 0.75 }),
+    el('line', { x1: lx + rMax, x2: lx + rMax * 2 + 8, y1: ly - 2 * s.r, y2: ly - 2 * s.r, stroke: theme.muted, strokeWidth: 0.5 }),
+    text(lx + rMax * 2 + 11, ly - 2 * s.r + 3.5, fmt(s.v), { fill: theme.muted, fontSize: 10.5 }),
+  ]);
+  if (tall && spec.labels !== false) {
+    const x = proj.bounds.x + proj.bounds.w + 26;
+    const legH = rMax * 2 + 12;
+    body.push(...layer, ...labelColumn(items.map((it) => ({ ...it, barColor: color })), x, area.y, area.y + area.h - legH, area.x + area.w - x, theme, fmt, { bars: spec.bars !== false, maxV }));
+  } else {
+    const chosen = new Set(chooseLabeled(m, spec, locale, Math.min(5, m.values.size)));
+    layer.push(g({ class: 'pa-zoom-hide' }, mapLabels(items.filter((it) => chosen.has(it.f) && !it.missing).sort((a, b) => b.v - a.v).map((it) => ({ ...it, cy: it.cy - it.r - 10 })), theme)));
+    body.push(...zoomLayer(B, layer));
+  }
+  if (tall) body.push(g({ class: 'pa-legend pa-size-legend' }, leg));
+  const desc = describeMap(m, fmt, locale, T(locale, 'Mapa de símbolos', 'Proportional symbol map'));
+  return frame.finish(body, { desc, type: 'symbolmap', defs: H.defs() });
+}
+
+function describeMap(m, fmt, locale, what) {
+  const en = String(locale).startsWith('en');
+  if (!m.ranked.length) return `${what}.`;
+  const [hiF, hiV] = m.ranked[0], [loF, loV] = m.ranked[m.ranked.length - 1];
+  let s = en
+    ? `${what} of ${humanize(m.valueF)} across ${m.values.size} areas. Highest: ${nameOf(hiF, locale)} (${fmt(hiV)}). Lowest: ${nameOf(loF, locale)} (${fmt(loV)}).`
+    : `${what} de ${humanize(m.valueF).toLowerCase()} en ${m.values.size} territorios. Mayor: ${nameOf(hiF, locale)} (${fmt(hiV)}). Menor: ${nameOf(loF, locale)} (${fmt(loV)}).`;
+  if (m.unmatched.length) s += en ? ` Unmatched: ${m.unmatched.slice(0, 8).join(', ')}.` : ` Sin coincidencia: ${m.unmatched.slice(0, 8).join(', ')}.`;
+  return s;
+}