plotagents 0.5.0 → 0.7.0

package/src/charts/choropleth.js

@@ -8,12 +8,12 @@
 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 { ramp, textOn, colorMap } from '../theme.js';
+import { ensureData, requireField, num, fieldsOf, fieldKind, humanize, aggregate, PlotError } 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 { mercator, equalEarth, planar, projections, makeProjection, fit, aspectOf, pathD, centroid, rings, isPointGeom, isLineGeom } 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);
@@ -32,7 +32,8 @@ function featureIndex(features, featureKey) {
   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; }
+    if (featureKey) { add(featureKey === 'id' && p.id === undefined ? f.id : p[featureKey], f); continue; }
+    if (f.id !== undefined && f.id !== null) add(f.id, f);
     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);
   }
@@ -41,9 +42,42 @@ function featureIndex(features, featureKey) {
 
 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 ?? '');
+  return (String(locale).startsWith('en') ? p.nameEn || p.name : p.name || p.nameEn) || p.NAME || p.nombre || String(p.code ?? p.id ?? f.id ?? '');
 };
 
+// Propiedades que suelen traer el nombre en GeoJSON de otras fuentes (INE, IGM, Natural Earth, GADM, censos).
+const NAME_PROPS = ['name', 'nameEn', 'NAME', 'nombre', 'Nombre', 'NOMBRE', 'name_en', 'NAME_EN', 'NAME_1', 'NAME_2', 'NAME_3', 'ADMIN', 'admin', 'NOM_REG', 'NOM_REGION', 'Region', 'REGION', 'region', 'NOM_PROV', 'NOM_COM', 'NOM_COMUNA', 'COMUNA', 'Comuna', 'comuna', 'provincia', 'PROVINCIA', 'label', 'title', 'NAMELSAD', 'GEN', 'NUTS_NAME', 'shapeName'];
+const primitive = (v) => typeof v === 'string' || typeof v === 'number';
+
+/**
+ * GeoJSON ajeno: busca la propiedad cuyos valores calzan con más filas de
+ * los datos (p. ej. "CUT_REG", "NOM_COM" o "GEOID"). Devuelve null si
+ * ninguna mejora lo que ya calzaba.
+ */
+function bestProperty(features, keys, already) {
+  const want = new Set(keys.map(normKey).filter(Boolean));
+  if (!want.size) return null;
+  const props = new Set();
+  for (const f of features.slice(0, 80)) for (const [k, v] of Object.entries(f.properties || {})) if (primitive(v)) props.add(k);
+  let best = null, bestN = already;
+  for (const k of props) {
+    let n = 0;
+    const seen = new Set(features.map((f) => normKey(f.properties?.[k])));
+    for (const w of want) if (seen.has(w)) n++;
+    if (n > bestN) { best = k; bestN = n; }
+  }
+  return best;
+}
+
+/** Copia las features con `name` resuelto (nameKey explícito o adivinado). */
+function withNames(features, nameKey) {
+  return features.map((f) => {
+    const p = f.properties || {};
+    const v = p[nameKey];
+    return primitive(v) && p.name !== v ? { ...f, properties: { ...p, name: String(v) } } : f;
+  });
+}
+
 /** Redondeo "bonito" de un corte de clase (2 cifras relativas al rango). */
 function niceRound(v, range) {
   if (!range) return v;
@@ -89,7 +123,7 @@ export function colorScale(values, spec, theme) {
     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 t0 = theme.cmap ? 0 : 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);
 }
@@ -173,21 +207,40 @@ const noDataPattern = (id, theme) =>
 
 /** Datos + geometría emparejados. */
 function prepare(spec, locale) {
-  const fc = getGeo(spec.geo ?? 'chile');
+  const fc = getGeo(spec.geo ?? 'chile', spec.geoObject);
   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);
+  // Valores de texto ("Izquierda", "Derecha"…): un color por categoría.
+  const categorical = spec.scale === 'categorical' || (data.length > 0 && fieldKind(data, valueF) === 'category');
+  let features = fc.features.filter((f) => f && f.geometry && rings(f.geometry).length);
   if (!spec.antarctica) features = features.filter((f) => (f.properties || {}).iso3 !== 'ATA');
+  // Nombres: `nameKey` o la primera propiedad conocida (NOMBRE, NAME_1, ADMIN…).
+  const hasName = (f) => { const p = f.properties || {}; return primitive(p.name) || primitive(p.nameEn) || primitive(p.NAME) || primitive(p.nombre); };
+  const firstText = () => { for (const f of features.slice(0, 20)) for (const [k, v] of Object.entries(f.properties || {})) if (typeof v === 'string' && v.trim()) return k; return null; };
+  const nameKey = spec.nameKey ?? (features.length && !features.some(hasName) ? NAME_PROPS.find((k) => features.some((f) => primitive(f.properties?.[k]))) ?? spec.featureKey ?? firstText() : null);
+  if (nameKey) features = withNames(features, nameKey);
   let idx = featureIndex(features, spec.featureKey);
+  // Sin `featureKey`: si las filas no calzan con las claves de siempre, se busca la propiedad que sí calza.
+  let autoKey = null;
+  if (!spec.featureKey && data.length) {
+    const keys = data.map((r) => r[key]).filter(primitive);
+    const matched = keys.filter((k) => idx.has(normKey(k))).length;
+    if (matched < new Set(keys.map(normKey)).size) {
+      autoKey = bestProperty(features, keys, new Set(keys.filter((k) => idx.has(normKey(k))).map(normKey)).size);
+      if (autoKey) for (const [k, f] of featureIndex(features, autoKey)) if (!idx.has(k)) idx.set(k, f);
+      if (autoKey && !nameKey && !features.some(hasName)) features = withNames(features, autoKey), idx = new Map([...featureIndex(features, null), ...featureIndex(features, autoKey)]);
+    }
+  }
   // 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);
+    idx = featureIndex(features, spec.featureKey ?? autoKey);
+    if (!spec.featureKey && autoKey) for (const [k, f] of featureIndex(features, null)) if (!idx.has(k)) idx.set(k, f);
   }
   const buckets = new Map();
   const unmatched = [];
@@ -195,20 +248,129 @@ function prepare(spec, locale) {
     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]));
+    buckets.get(f).push(categorical ? r[valueF] : 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); }
+  const mode = (vs) => { const c = new Map(); for (const v of vs) if (primitive(v) && v !== '') c.set(String(v), (c.get(String(v)) || 0) + 1); return [...c].sort((a, b) => b[1] - a[1])[0]?.[0]; };
+  for (const [f, vs] of buckets) {
+    const v = categorical ? mode(vs) : aggregate(vs, spec.aggregate || 'mean');
+    if (categorical ? v !== undefined : 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]);
+  // Categorías ordenadas por cuántas áreas cubren (o el orden dado en `order`).
+  const count = new Map();
+  for (const v of values.values()) count.set(v, (count.get(v) || 0) + 1);
+  const categories = categorical ? (Array.isArray(spec.order) ? spec.order.map(String).filter((c) => count.has(c)).concat([...count.keys()].filter((c) => !spec.order.map(String).includes(c))) : [...count.keys()].sort((a, b) => count.get(b) - count.get(a))) : null;
+  const ranked = categorical ? [] : [...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)();
+  // Proyección: la pedida; si no, una según la geometría (coordenadas fuera de
+  // lon/lat → plano cartesiano, p. ej. UTM; mundo → Equal Earth; resto → Mercator).
+  const projName = typeof spec.projection === 'string' ? spec.projection : fc.projection ?? (/^(world|mundo|countries|paises|países)$/i.test(String(spec.geo)) ? 'equalEarth' : null);
+  let lon0 = Infinity, lon1 = -Infinity, latMax = 0;
+  for (const f of features) for (const r of rings(f.geometry)) for (const p of r) { if (p[0] < lon0) lon0 = p[0]; if (p[0] > lon1) lon1 = p[0]; if (Math.abs(p[1]) > latMax) latMax = Math.abs(p[1]); }
+  const projected = Math.max(Math.abs(lon0), Math.abs(lon1)) > 180.5 || latMax > 90.5;
+  const raw = makeProjection(spec.projection) ?? (projName && projections[projName] ? projections[projName]() : projected ? planar() : lon1 - lon0 > 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 };
+  return { fc, features, values, rank, ranked, unmatched: [...new Set(unmatched)], key, valueF, raw, data, dashed, categorical, categories };
+}
+
+// ── Capas extra: marcadores (lon/lat) y GeoJSON superpuesto ─────────────────
+const pickF = (fields, names) => names.find((n) => fields.includes(n));
+
+/** `markers`: [{ lon, lat, label, value }] o { data, lon, lat, label, size, color, legend }. */
+function markerList(spec, theme) {
+  const mk = spec.markers;
+  if (!mk) return null;
+  const o = Array.isArray(mk) ? {} : mk;
+  const rows = ensureData({ data: Array.isArray(mk) ? mk : mk.data || [] });
+  const fields = fieldsOf(rows);
+  const lonF = o.lon ?? pickF(fields, ['lon', 'lng', 'long', 'longitude', 'longitud', 'x']);
+  const latF = o.lat ?? pickF(fields, ['lat', 'latitude', 'latitud', 'y']);
+  const labelF = o.label ?? pickF(fields, ['label', 'name', 'nombre', 'city', 'ciudad', 'title']);
+  const sizeF = o.size ?? pickF(fields, ['size', 'value', 'valor']);
+  const colorF = typeof o.color === 'string' && fields.includes(o.color) ? o.color : pickF(fields, ['color']);
+  if (!lonF || !latF) throw new PlotError('Los marcadores necesitan longitud y latitud.', 'markers: [{ lon: -73.05, lat: -36.82, label: "Concepción" }]');
+  const items = rows.map((r) => ({ lon: num(r[lonF]), lat: num(r[latF]), label: labelF ? r[labelF] : undefined, size: sizeF ? num(r[sizeF]) : NaN, color: (colorF && r[colorF]) || (typeof o.color === 'string' && !fields.includes(o.color) ? o.color : null), row: r }))
+    .filter((m) => Number.isFinite(m.lon) && Number.isFinite(m.lat));
+  const maxS = Math.max(0, ...items.map((m) => Math.abs(m.size)).filter(Number.isFinite));
+  for (const m of items) m.r = Number.isFinite(m.size) && maxS ? Math.max(3, Math.sqrt(Math.abs(m.size) / maxS) * (o.maxRadius ?? 14)) : o.radius ?? 4.5;
+  return { items, color: (typeof o.color === 'string' && !fields.includes(o.color) && o.color) || theme.ink, legend: o.legend ?? o.title ?? null, labels: o.labels !== false, sizeF };
+}
+
+/** `layers`: [{ geo, stroke, fill, width, dash, opacity, label, below }]. */
+function layerList(spec, theme) {
+  return [].concat(spec.layers || []).filter(Boolean).map((L, i) => {
+    const fc = getGeo(L.geo ?? L.data, L.object ?? L.geoObject);
+    const fs = fc.features.filter((f) => f && f.geometry && rings(f.geometry).length);
+    const lines = fs.every((f) => isLineGeom(f.geometry));
+    return { ...L, features: fs, i, stroke: L.stroke ?? L.color ?? (lines ? theme.ink : theme.lede), width: L.width ?? L.strokeWidth ?? (lines ? 1.5 : 1), fill: L.fill ?? 'none' };
+  });
+}
+
+function drawLayer(L, proj, theme, locale) {
+  return g({ class: 'pa-layer', 'pointer-events': L.label || L.tooltip !== false ? null : 'none' }, L.features.map((f) => {
+    const pt = isPointGeom(f.geometry);
+    const nm = nameOf(f, locale);
+    const tipT = [L.label, nm && nm !== String(f.id ?? '') ? nm : null].filter(Boolean).join('\n');
+    return el('path', {
+      class: tipT ? 'pa-m' : null, 'data-tip': tipT || null, d: pathD(f.geometry, proj, { r: L.radius ?? 3 }),
+      fill: pt ? (L.fill !== 'none' ? L.fill : L.stroke) : L.fill, fillOpacity: L.fillOpacity ?? null,
+      stroke: pt ? theme.surface : L.stroke, strokeWidth: pt ? 1 : L.width, strokeDasharray: L.dash === true ? '5 4' : L.dash || null,
+      strokeLinejoin: 'round', strokeLinecap: 'round', opacity: L.opacity ?? null, 'data-color': L.stroke,
+    });
+  }));
+}
+
+function drawMarkers(mk, proj, theme, fmt, placed) {
+  const dots = [], labs = [];
+  const halo = { stroke: theme.surface, strokeWidth: 3, paintOrder: 'stroke', strokeLinejoin: 'round' };
+  for (const m of [...mk.items].sort((a, b) => b.r - a.r)) {
+    const [x, y] = proj([m.lon, m.lat]);
+    m.x = x; m.y = y;
+    const c = m.color || mk.color;
+    const tipT = [m.label, Number.isFinite(m.size) && mk.sizeF ? fmt(m.size) : null].filter((v) => v !== undefined && v !== null && v !== '').join('\n');
+    dots.push(el('circle', { class: 'pa-m', cx: x, cy: y, r: m.r, fill: c, fillOpacity: m.r > 6 ? 0.8 : 1, stroke: theme.surface, strokeWidth: 1.5, 'data-tip': tipT || null, 'data-color': c }));
+  }
+  for (const m of mk.items) placed.push([m.x - m.r - 2, m.y - m.r - 2, m.x + m.r + 2, m.y + m.r + 2]);
+  if (mk.labels) for (const m of mk.items) {
+    if (m.label === undefined || m.label === null || m.label === '') continue;
+    const w = measure(String(m.label), 11, 600);
+    const hit = (box) => placed.some((b) => !(box[2] < b[0] || box[0] > b[2] || box[3] < b[1] || box[1] > b[3]));
+    // A la derecha del punto; si choca, a la izquierda; si no, encima.
+    const cands = [
+      { box: [m.x + m.r + 3, m.y - 8, m.x + m.r + 6 + w, m.y + 8], x: m.x + m.r + 4, y: m.y + 4, anchor: 'start' },
+      { box: [m.x - m.r - 6 - w, m.y - 8, m.x - m.r - 3, m.y + 8], x: m.x - m.r - 4, y: m.y + 4, anchor: 'end' },
+      { box: [m.x - w / 2 - 2, m.y - m.r - 20, m.x + w / 2 + 2, m.y - m.r - 3], x: m.x, y: m.y - m.r - 7, anchor: 'middle' },
+    ];
+    const c = cands.find((k) => !hit(k.box));
+    if (!c) continue;
+    placed.push(c.box);
+    labs.push(text(c.x, c.y, String(m.label), { fill: theme.ink, fontSize: 11, fontWeight: 600, textAnchor: c.anchor, ...halo }));
+  }
+  return [g({ class: 'pa-markers' }, dots), g({ class: 'pa-map-label pa-marker-labels', 'pointer-events': 'none' }, labs)];
+}
+
+/** Leyenda de categorías (mapas con valores de texto): cuadros enlazados con las regiones. */
+function catLegend(sc, x, y, maxW, theme, { title, missing, locale, gid, dashed }) {
+  const out = [];
+  const size = theme.type?.axis ?? 11.5;
+  let lx = x, ly = y, rows = 1;
+  if (title) { out.push(text(lx, ly + 9.5, title, { fill: theme.lede, fontSize: 12, fontWeight: 500 })); lx += measure(title, 12, 500) + 14; }
+  const item = (label, attrs, key) => {
+    const w = 14 + measure(label, size) + 16;
+    if (lx + w > x + maxW && lx > x) { lx = x; ly += 20; rows++; }
+    out.push(g({ class: 'pa-key', 'data-color': key, style: 'cursor:pointer' }, [
+      el('rect', { x: lx, y: ly, width: 10, height: 10, rx: 2, ...attrs }),
+      text(lx + 14, ly + 9, label, { fill: theme.lede, fontSize: size }),
+    ]));
+    lx += w;
+  };
+  for (const c of sc.cats) item(c, { fill: sc.color(c) }, sc.color(c));
+  if (missing) item(T(locale, 'Sin dato', 'No data'), { fill: `url(#${gid}-nd)`, stroke: theme.axis, strokeWidth: 0.5 }, `url(#${gid}-nd)`);
+  if (dashed) item(dashed.label, { fill: dashed.fill, stroke: dashed.stroke, strokeWidth: 1.1, strokeDasharray: DASH.legend }, 'dashed');
+  return { svg: g({ class: 'pa-legend pa-map-legend' }, out), h: rows * 20 + 2 };
 }
 
 /**
@@ -360,11 +522,37 @@ function insetFrames(features, proj, theme) {
 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);
+  if (m.categorical && kind === 'symbol') throw new PlotError(T(locale, `"${m.valueF}" tiene texto, no números: un mapa de símbolos necesita cantidades.`, `"${m.valueF}" holds text, not numbers: a symbol map needs quantities.`), T(locale, 'Usa type: "choropleth" para colorear por categoría.', 'Use type: "choropleth" to color by category.'));
+  const vals = m.categorical ? [] : [...m.values.values()];
+  const numFmt = makeFormat(spec.format, locale, vals);
+  const fmt = m.categorical ? (v) => (typeof v === 'number' ? numFmt(v) : String(v ?? '')) : numFmt;
   const W = spec.width || 720;
-  const aspect = aspectOf(m.features, m.raw);
-  const tall = aspect > 1.6 && m.features.length <= 40;
+  const layers = layerList(spec, theme);
+  const markers = markerList(spec, theme);
+  // `fitTo`: encuadra unas regiones (nombres o códigos), una caja [lon0, lat0, lon1, lat1] o "markers".
+  let fitFeats = m.features;
+  if (spec.fitTo !== undefined && spec.fitTo !== null) {
+    const ft = spec.fitTo;
+    if (Array.isArray(ft) && ft.length === 4 && ft.every((v) => typeof v === 'number')) {
+      const [a, b, c, d] = ft;
+      fitFeats = [{ type: 'Feature', properties: {}, geometry: { type: 'Polygon', coordinates: [[[a, b], [c, b], [c, d], [a, d], [a, b]]] } }];
+    } else if (ft === 'markers' && markers?.items.length) {
+      fitFeats = [{ type: 'Feature', properties: {}, geometry: { type: 'MultiPoint', coordinates: markers.items.map((x) => [x.lon, x.lat]) } }];
+    } else {
+      const want = [].concat(ft).map(normKey);
+      const hit = m.features.filter((f) => featureIndexHas(f, want));
+      if (hit.length) fitFeats = hit;
+    }
+    // Un margen del 6 % para que lo encuadrado no toque el borde.
+    if (fitFeats !== m.features) {
+      let a = Infinity, b = Infinity, c = -Infinity, d = -Infinity;
+      for (const f of fitFeats) for (const r of rings(f.geometry)) for (const p of r) { a = Math.min(a, p[0]); b = Math.min(b, p[1]); c = Math.max(c, p[0]); d = Math.max(d, p[1]); }
+      const px = (c - a) * 0.06 || 0.5, py = (d - b) * 0.06 || 0.5;
+      fitFeats = [{ type: 'Feature', properties: {}, geometry: { type: 'MultiPoint', coordinates: [[a - px, b - py], [c + px, d + py], [a - px, d + py], [c + px, b - py]] } }];
+    }
+  }
+  const aspect = aspectOf(fitFeats, m.raw);
+  const tall = aspect > 1.6 && m.features.length <= 40 && fitFeats === m.features && spec.tall !== false;
   // 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 });
@@ -376,7 +564,13 @@ function baseChart(spec, theme, kind) {
   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) {
+  if (kind === 'choropleth' && m.categorical && m.values.size) {
+    const cmap = colorMap(m.categories, theme, spec.colors);
+    sc = { mode: 'categories', cats: m.categories, color: (v) => cmap.get(String(v)) || theme.other };
+    const lg = spec.legend === false ? { svg: '', h: 0 } : catLegend(sc, area.x, area.y, area.w, theme, { title: spec.legendTitle ?? null, missing: missingAny, locale, gid, dashed: dashedKey });
+    body.push(lg.svg);
+    area = { ...area, y: area.y + lg.h + 8, h: area.h - lg.h - 8 };
+  } else 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);
@@ -403,7 +597,30 @@ function baseChart(spec, theme, kind) {
     }
     lx += 10;
   }
-  if (dashedKey && !(kind === 'choropleth' && vals.length)) {
+  // Claves de las capas y marcadores con nombre (`label` / `legend`).
+  {
+    const size = theme.type?.axis ?? 11.5;
+    const ky = rowItems.length ? area.y + 2 * (rMax || 0) - 9 : area.y + 4.6;
+    for (const L of layers) {
+      if (!L.label) continue;
+      const pts = L.features.every((f) => isPointGeom(f.geometry)), poly = !pts && !L.features.every((f) => isLineGeom(f.geometry));
+      rowItems.push(g({ class: 'pa-key', 'data-color': L.stroke, style: 'cursor:pointer' }, [
+        pts ? el('circle', { cx: lx + 5, cy: ky + 4.9, r: 3.5, fill: L.fill !== 'none' ? L.fill : L.stroke })
+          : poly ? el('rect', { x: lx + 0.5, y: ky + 0.5, width: 9.5, height: 9.5, rx: 2, fill: L.fill === 'none' ? 'none' : L.fill, stroke: L.stroke, strokeWidth: 1.2, strokeDasharray: L.dash === true ? '3 2' : L.dash || null })
+            : el('line', { x1: lx, x2: lx + 14, y1: ky + 4.9, y2: ky + 4.9, stroke: L.stroke, strokeWidth: Math.min(3, L.width + 0.5), strokeDasharray: L.dash === true ? '4 3' : L.dash || null, strokeLinecap: 'round' }),
+        text(lx + (pts || poly ? 15 : 19), ky + 8.4, L.label, { fill: theme.lede, fontSize: size }),
+      ]));
+      lx += (pts || poly ? 15 : 19) + measure(L.label, size) + 16;
+    }
+    if (markers?.legend) {
+      rowItems.push(g({ class: 'pa-key', 'data-color': markers.color, style: 'cursor:pointer' }, [
+        el('circle', { cx: lx + 5, cy: ky + 4.9, r: 4.5, fill: markers.color, stroke: theme.surface, strokeWidth: 1 }),
+        text(lx + 15, ky + 8.4, markers.legend, { fill: theme.lede, fontSize: size }),
+      ]));
+      lx += 15 + measure(markers.legend, size) + 16;
+    }
+  }
+  if (dashedKey && !(kind === 'choropleth' && (vals.length || m.categorical))) {
     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' }, [
@@ -434,9 +651,13 @@ function baseChart(spec, theme, kind) {
     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' });
+  // Puntos y marcadores en el borde: margen para el círculo y su etiqueta.
+  const inset = m.features.some((f) => isPointGeom(f.geometry)) ? (spec.pointRadius ?? 5) + 18 : markers?.items.length ? 12 : 0;
+  const pts = m.features.some((f) => isPointGeom(f.geometry));
+  if (inset) box = [box[0] + inset * (tall ? 0 : 1), box[1] + inset + (pts ? 12 : 0), box[2] - inset, box[3] - Math.min(inset, 10)];
+  const proj = fit(fitFeats, 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 };
+  return { locale, m, vals, fmt, frame, area, gid, missingAny, body, sc, proj, tall, H, dashedLabel, calloutX, rMax, layers, markers };
 }
 
 const rankText = (r, n, locale) => (String(locale).startsWith('en') ? `#${r} of ${n}` : `${r}.º de ${n}`);
@@ -454,7 +675,9 @@ function zoomLayer(B, 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 { locale, m, fmt, frame, area, gid, body, sc, proj, tall, H, dashedLabel, calloutX, layers, markers } = B;
+  const borderC = spec.borderColor ?? theme.surface, borderW = spec.borderWidth ?? 0.75;
+  const ptR = spec.pointRadius ?? 5;
   const hl = spec.highlight === undefined ? null : [].concat(spec.highlight).map(normKey);
   const isHl = (f) => hl && featureIndexHas(f, hl);
   const N = m.values.size;
@@ -466,8 +689,9 @@ export function choropleth(spec, theme) {
     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 tipTxt = (has ? `${name}\n${fmt(v)}${m.categorical ? '' : ' · ' + rankText(m.rank.get(f), N, locale)}` : `${name}\n${T(locale, 'Sin dato', 'No data')}`) + (isDashed ? `\n${dashedLabel}` : '');
+    const d = pathD(f.geometry, proj, { r: ptR });
+    const isLine = isLineGeom(f.geometry);
     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;
@@ -479,39 +703,45 @@ export function choropleth(spec, theme) {
     } 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 }));
+    } else if (isLine) regions.push(el('path', { ...common, fill: 'none', stroke: has ? base : theme.muted, strokeWidth: spec.lineWidth ?? 2.5, strokeLinecap: 'round', 'data-color': has ? base : fill }));
+    else regions.push(el('path', { ...common, fill, stroke: isPointGeom(f.geometry) ? theme.surface : borderC, strokeWidth: isPointGeom(f.geometry) ? 1.2 : borderW, '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 layer = [...layers.filter((L) => L.below).map((L) => drawLayer(L, proj, theme, locale)), g({ class: 'pa-regions' }, regions), dashedRegions.length ? g({ class: 'pa-regions pa-dashed' }, dashedRegions) : '', g({ class: 'pa-outlines' }, outlines), insetFrames(m.features, proj, theme),
+    ...layers.filter((L) => !L.below).map((L) => drawLayer(L, proj, theme, locale))];
+  const placed = [];
+  if (markers) layer.push(...drawMarkers(markers, proj, theme, fmt, placed));
   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 }));
+    after.push(...labelColumn(items, x, area.y, area.y + area.h, area.x + area.w - x, theme, fmt, { bars: spec.bars !== false && !m.categorical, 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)));
+    const ordered = items.filter((it) => chosen.has(it.f) && !it.missing).sort((a, b) => b.area - a.area)
+      .map((it) => (isPointGeom(it.f.geometry) ? { ...it, cy: it.cy - ptR - 12 } : it));
+    layer.push(g({ class: 'pa-zoom-hide' }, mapLabels(ordered, theme, placed)));
   }
   body.push(...(tall ? layer : zoomLayer(B, layer)), ...after);
-  const desc = describeMap(m, fmt, locale, T(locale, 'Mapa coroplético', 'Choropleth map'));
+  const desc = describeMap(m, fmt, locale, T(locale, 'Mapa coroplético', 'Choropleth map')) + describeExtras(markers, layers, locale);
   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 { locale, m, fmt, frame, area, body, proj, tall, gid, H, dashedLabel, rMax, layers, markers } = 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 layer = [...layers.filter((L) => L.below).map((L) => drawLayer(L, proj, theme, locale)), g({ class: 'pa-regions pa-base' }, m.features.map((f) => el('path', { d: pathD(f.geometry, proj, { r: 2.5 }), fill: isLineGeom(f.geometry) ? 'none' : theme.tint, stroke: isLineGeom(f.geometry) ? theme.axis : spec.borderColor ?? theme.surface, strokeWidth: isLineGeom(f.geometry) ? 1.5 : spec.borderWidth ?? 0.75, strokeLinejoin: 'round', 'data-k': normKey(f.properties?.code ?? f.properties?.iso3 ?? nameOf(f, locale)) }))), insetFrames(m.features, proj, theme),
+    ...layers.filter((L) => !L.below).map((L) => drawLayer(L, proj, theme, locale))];
   const items = m.features.map((f) => {
     const c = centroid(f.geometry, proj);
     const v = m.values.get(f);
@@ -525,6 +755,7 @@ export function symbolMap(spec, theme) {
     .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));
+  if (markers) layer.push(...drawMarkers(markers, proj, theme, fmt, []));
   // 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;
@@ -543,12 +774,29 @@ export function symbolMap(spec, 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'));
+  const desc = describeMap(m, fmt, locale, T(locale, 'Mapa de símbolos', 'Proportional symbol map')) + describeExtras(markers, layers, locale);
   return frame.finish(body, { desc, type: 'symbolmap', defs: H.defs() });
 }
 
+function describeExtras(markers, layers, locale) {
+  const en = String(locale).startsWith('en');
+  let s = '';
+  if (markers?.items.length) s += en ? ` ${markers.items.length} markers${markers.legend ? ` (${markers.legend})` : ''}.` : ` ${markers.items.length} marcadores${markers.legend ? ` (${markers.legend})` : ''}.`;
+  const named = layers.filter((L) => L.label).map((L) => L.label);
+  if (named.length) s += en ? ` Layers: ${named.join(', ')}.` : ` Capas: ${named.join(', ')}.`;
+  return s;
+}
+
 function describeMap(m, fmt, locale, what) {
   const en = String(locale).startsWith('en');
+  if (m.categorical) {
+    const cnt = new Map();
+    for (const v of m.values.values()) cnt.set(v, (cnt.get(v) || 0) + 1);
+    const parts = m.categories.map((c) => `${c} (${cnt.get(c)})`).join(', ');
+    let s = en ? `${what} of ${humanize(m.valueF)} across ${m.values.size} areas: ${parts}.` : `${what} de ${humanize(m.valueF).toLowerCase()} en ${m.values.size} territorios: ${parts}.`;
+    if (m.unmatched.length) s += en ? ` Unmatched: ${m.unmatched.slice(0, 8).join(', ')}.` : ` Sin coincidencia: ${m.unmatched.slice(0, 8).join(', ')}.`;
+    return s;
+  }
   if (!m.ranked.length) return `${what}.`;
   const [hiF, hiV] = m.ranked[0], [loF, loV] = m.ranked[m.ranked.length - 1];
   let s = en