plotagents 0.0.0-stage → 0.7.0

package/src/data.js

@@ -0,0 +1,137 @@
+// Preparación de datos: validación con mensajes útiles para agentes,
+// inferencia de campos, formato ancho → largo y agregación.
+import { isDateLike, parseDate } from './format.js';
+
+export class PlotError extends Error {
+  constructor(message, hint) {
+    super(hint ? `${message}\n→ ${hint}` : message);
+    this.name = 'PlotError';
+    this.hint = hint;
+  }
+}
+
+/** Convierte a número de forma tolerante ("1.234,5", "12%", "$ 3.000"). */
+export function num(v) {
+  if (typeof v === 'number') return v;
+  if (v === null || v === undefined || v === '' || typeof v === 'boolean') return NaN;
+  let s = String(v).trim().replace(/[\s$€£%]|US\$|CLP|UF/g, '').replace('−', '-');
+  const hasC = s.includes(','), hasD = s.includes('.');
+  if (hasC && hasD) s = s.lastIndexOf(',') > s.lastIndexOf('.') ? s.replace(/\./g, '').replace(',', '.') : s.replace(/,/g, '');
+  else if (hasC) s = /,\d{3}(?!\d)/.test(s) && !/,\d{1,2}$/.test(s) ? s.replace(/,/g, '') : s.replace(',', '.');
+  else if (hasD && /^\-?\d{1,3}(\.\d{3})+$/.test(s)) s = s.replace(/\./g, '');
+  const n = Number(s);
+  return Number.isFinite(n) ? n : NaN;
+}
+
+export function fieldsOf(data) {
+  const set = new Set();
+  for (const row of data.slice(0, 50)) if (row && typeof row === 'object') Object.keys(row).forEach((k) => set.add(k));
+  return [...set];
+}
+
+export function ensureData(spec) {
+  let data = spec.data;
+  if (!Array.isArray(data)) {
+    if (data && typeof data === 'object') {
+      // { "Biobío": 10, "Ñuble": 5 } → filas
+      data = Object.entries(data).map(([k, v]) => ({ label: k, value: v }));
+    } else throw new PlotError('`data` debe ser un arreglo de objetos (filas).', 'Ejemplo: data: [{ region: "Biobío", ventas: 120 }]');
+  }
+  if (data.length && typeof data[0] !== 'object') {
+    data = data.map((v, i) => ({ index: i + 1, value: v }));
+  }
+  return data.filter((r) => r && typeof r === 'object');
+}
+
+export function requireField(data, field, role) {
+  if (field === undefined || field === null) return;
+  const fields = fieldsOf(data);
+  if (!fields.includes(field)) {
+    throw new PlotError(
+      `El campo "${field}" (${role}) no existe en los datos.`,
+      `Campos disponibles: ${fields.map((f) => `"${f}"`).join(', ') || '(ninguno)'}`
+    );
+  }
+}
+
+const isNumericField = (data, f) => {
+  let n = 0, ok = 0;
+  for (const r of data.slice(0, 200)) {
+    const v = r[f];
+    if (v === null || v === undefined || v === '') continue;
+    n++;
+    if (typeof v === 'number' || (typeof v === 'string' && !isDateLike(v) && Number.isFinite(num(v)))) ok++;
+  }
+  return n > 0 && ok / n > 0.9;
+};
+
+export const fieldKind = (data, f) => {
+  const vals = data.map((r) => r[f]).filter((v) => v !== null && v !== undefined && v !== '');
+  if (!vals.length) return 'empty';
+  if (vals.every((v) => isDateLike(v))) return 'date';
+  if (isNumericField(data, f)) {
+    const ns = vals.map(num);
+    if (ns.every((v) => Number.isInteger(v) && v >= 1000 && v <= 2999)) return 'year';
+    return 'number';
+  }
+  return 'category';
+};
+
+/** Elige x / y si el agente no los indicó. */
+export function inferXY(spec, data) {
+  const fields = fieldsOf(data);
+  const kinds = Object.fromEntries(fields.map((f) => [f, fieldKind(data, f)]));
+  let { x, y } = spec;
+  const nums = fields.filter((f) => kinds[f] === 'number');
+  if (!x) x = fields.find((f) => kinds[f] === 'date' || kinds[f] === 'year') || fields.find((f) => kinds[f] === 'category') || fields.find((f) => f !== y);
+  if (!y) y = nums.find((f) => f !== x) || fields.find((f) => f !== x);
+  return { x, y, kinds };
+}
+
+/**
+ * y: ['ventas', 'costos'] → formato largo con un campo de serie.
+ * Así los agentes pueden pasar tablas anchas sin transformarlas.
+ */
+export function melt(data, x, ys, seriesName = '__series', valueName = '__value', labels = {}) {
+  const out = [];
+  for (const r of data) for (const f of ys) out.push({ ...r, [x]: r[x], [seriesName]: labels[f] || humanize(f), [valueName]: r[f] });
+  return out;
+}
+
+export function uniq(arr) {
+  const seen = new Set();
+  const out = [];
+  for (const v of arr) {
+    const k = v instanceof Date ? v.getTime() : v;
+    if (!seen.has(k)) { seen.add(k); out.push(v); }
+  }
+  return out;
+}
+
+export function aggregate(values, how = 'sum') {
+  const v = values.filter((n) => Number.isFinite(n));
+  if (!v.length) return NaN;
+  switch (how) {
+    case 'mean': case 'avg': return v.reduce((a, b) => a + b, 0) / v.length;
+    case 'max': return v.reduce((a, b) => (b > a ? b : a), -Infinity); // sin spread: no desborda con 150 mil filas
+    case 'min': return v.reduce((a, b) => (b < a ? b : a), Infinity);
+    case 'count': return v.length;
+    case 'last': return v[v.length - 1];
+    case 'first': return v[0];
+    default: return v.reduce((a, b) => a + b, 0);
+  }
+}
+
+/** Valor de x normalizado: fecha → ms, año → número, si no, texto. */
+export function xValue(v, kind) {
+  if (kind === 'date') return parseDate(v);
+  if (kind === 'year' || kind === 'number') return num(v);
+  return v === null || v === undefined ? '' : String(v);
+}
+
+export const humanize = (f) =>
+  String(f ?? '')
+    .replace(/^__.*/, '')
+    .replace(/[_-]+/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/^\w/, (c) => c.toUpperCase());

package/src/facet.js

@@ -0,0 +1,84 @@
+// Small multiples (seaborn: col / col_wrap): un panel por valor de `facet`,
+// con escalas y colores compartidos y una sola leyenda. Es la alternativa
+// correcta a 8 líneas enredadas o a un doble eje.
+import { el, g } from './svg.js';
+import { createFrame } from './frame.js';
+import { colorMap } from './theme.js';
+import { ensureData, requireField, uniq, fieldKind, num } from './data.js';
+import { niceDomain } from './scale.js';
+
+const LINE_LIKE = new Set(['line', 'area', 'kde', 'ecdf', 'point', 'regplot', 'residplot']);
+
+export function facet(spec, theme, renderOne) {
+  const data = ensureData(spec);
+  const f = spec.facet ?? spec.col;
+  requireField(data, f, 'facet');
+  let keys = uniq(data.map((r) => String(r[f])));
+  const fk = fieldKind(data, f);
+  if (fk === 'year' || fk === 'number') keys.sort((a, b) => num(a) - num(b));
+  if (spec.facetOrder) keys = [...spec.facetOrder.map(String).filter((k) => keys.includes(k)), ...keys.filter((k) => !spec.facetOrder.map(String).includes(k))];
+
+  // Colores globales: la misma serie tiene el mismo color en todos los paneles.
+  const sf = spec.series ?? spec.hue ?? (typeof spec.color === 'string' && !spec.color.startsWith('#') ? spec.color : null);
+  const colors = { ...(spec.colors || {}) };
+  let legend = [];
+  if (sf && data.length && Object.prototype.hasOwnProperty.call(data[0], sf)) {
+    const sk = uniq(data.map((r) => String(r[sf])));
+    const cm = colorMap(sk, theme, spec.colors);
+    for (const k of sk) colors[k] = cm.get(k);
+    if (sk.length > 1) legend = sk.map((k) => ({ label: k, color: cm.get(k), shape: LINE_LIKE.has(spec.type) ? 'line' : 'square' }));
+  }
+
+  const frame = createFrame({ ...spec, height: 200 }, theme, { width: 720 });
+  const area = frame.layout(legend);
+  const gap = spec.panelGap ?? 14;
+  // Columnas pedidas, pero nunca paneles de menos de ~150 px (en móvil se apilan).
+  const fit = Math.max(1, Math.floor((area.w + gap) / 150));
+  const want = spec.columns ?? spec.colWrap ?? spec.col_wrap ?? Math.max(1, Math.floor((area.w + gap) / 230));
+  const cols = Math.max(1, Math.min(keys.length, want, fit));
+  const pw = (area.w - gap * (cols - 1)) / cols;
+  const ph = spec.panelHeight ?? Math.round(Math.min(300, Math.max(160, pw * 0.66)));
+  const rows = Math.ceil(keys.length / cols);
+  frame.setHeight(area.y + rows * ph + (rows - 1) * gap + frame.chrome);
+
+  const panelTheme = { ...theme, type: { ...(theme.type || {}), title: Math.min(13.5, theme.type?.title ?? 13.5), titleWeight: 600 } };
+  const multiSeries = legend.length > 1;
+  const base = {
+    ...spec, facet: undefined, col: undefined, title: undefined, subtitle: undefined, source: undefined, refLines: spec.refLines,
+    width: Math.floor(pw), height: ph, padding: 0, colors, legend: false, theme: panelTheme, palette: undefined,
+    labels: spec.panelLabels ?? (multiSeries && LINE_LIKE.has(spec.type) ? false : spec.labels),
+  };
+  const subsets = keys.map((k) => data.filter((r) => String(r[f]) === k));
+
+  // Escalas compartidas: primera pasada para conocer el dominio de cada panel.
+  const shareY = spec.sharey ?? spec.shareY ?? true;
+  const shareX = spec.sharex ?? spec.shareX ?? true;
+  let yDomain = spec.yDomain, xDomain = spec.xDomain;
+  if ((shareY && !yDomain) || (shareX && !xDomain)) {
+    const ds = subsets.map((d, i) => { const _domains = {}; try { renderOne({ ...base, data: d, title: keys[i], _domains }); } catch { /* panel vacío */ } return _domains; });
+    const ys = ds.filter((d) => d.y).map((d) => d.y), xs = ds.filter((d) => d.x).map((d) => d.x);
+    if (shareY && !yDomain && ys.length) {
+      const lo = Math.min(...ys.map((d) => d[0])), hi = Math.max(...ys.map((d) => d[1]));
+      yDomain = spec.yScale === 'log' ? [lo, hi] : (({ min, max }) => [min, max])(niceDomain(lo, hi, 4));
+    }
+    if (shareX && !xDomain && xs.length) xDomain = [Math.min(...xs.map((d) => d[0])), Math.max(...xs.map((d) => d[1]))];
+  }
+
+  const body = [];
+  keys.forEach((k, i) => {
+    const c = i % cols, r = Math.floor(i / cols);
+    const px = area.x + c * (pw + gap), py = area.y + r * (ph + gap);
+    let svg;
+    try {
+      svg = renderOne({ ...base, data: subsets[i], title: k, yDomain, xDomain });
+    } catch (e) {
+      svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${pw}" height="${ph}"></svg>`;
+    }
+    // Panel anidado: se quita el estilo responsivo del SVG raíz del panel.
+    svg = svg.replace(/^<svg /, `<svg x="${px.toFixed(1)}" y="${py.toFixed(1)}" `).replace(/ style="[^"]*"/, '');
+    body.push(svg);
+  });
+  const en = String(spec.locale || 'es').startsWith('en');
+  const desc = (en ? `Small multiples by ${f}: ` : `Paneles por ${f}: `) + keys.join(', ') + '.';
+  return frame.finish(g({ class: 'pa-facets' }, body), { desc, type: 'facet' });
+}

package/src/format.js

@@ -0,0 +1,203 @@
+// Formato de números y fechas. Por defecto en español de Chile:
+// punto de miles, coma decimal y porcentaje pegado al número (56,1%).
+
+const SEP = {
+  es: { group: '.', dec: ',' },
+  en: { group: ',', dec: '.' },
+};
+
+const COMPACT = {
+  es: [[1e12, ' B'], [1e6, ' M'], [1e3, ' mil']],
+  en: [[1e12, 'T'], [1e9, 'B'], [1e6, 'M'], [1e3, 'K']],
+};
+
+export const MONTHS = {
+  es: ['ene', 'feb', 'mar', 'abr', 'may', 'jun', 'jul', 'ago', 'sep', 'oct', 'nov', 'dic'],
+  en: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
+};
+
+const loc = (l) => (l && String(l).toLowerCase().startsWith('en') ? 'en' : 'es');
+
+/** Número con separadores. `decimals` fijo; `trim` quita ceros finales. */
+export function formatNumber(v, decimals = 0, locale = 'es', trim = false) {
+  if (v === null || v === undefined || Number.isNaN(v)) return '';
+  if (!Number.isFinite(v)) return v > 0 ? '∞' : '-∞';
+  const { group, dec } = SEP[loc(locale)];
+  const neg = v < 0;
+  let [int, frac = ''] = Math.abs(v).toFixed(Math.max(0, Math.min(20, Math.round(+decimals) || 0))).split('.');
+  int = int.replace(/\B(?=(\d{3})+(?!\d))/g, group);
+  if (trim) frac = frac.replace(/0+$/, '');
+  const out = frac ? int + dec + frac : int;
+  return (neg && /[1-9]/.test(out) ? '−' : '') + out;
+}
+
+/** Decimales "inteligentes" según la magnitud. */
+export function smartDecimals(v) {
+  const a = Math.abs(v);
+  if (a === 0 || !Number.isFinite(a) || a >= 100) return 0;
+  if (a >= 10) return 1;
+  if (a >= 1) return 2;
+  // Bajo 1: tres cifras significativas (0,123 · 0,00012), nunca "0".
+  return Math.min(20, 2 - Math.floor(Math.log10(a)));
+}
+
+export function formatCompact(v, locale = 'es', decimals) {
+  const l = loc(locale);
+  const a = Math.abs(v);
+  for (const [n, suf] of COMPACT[l]) {
+    if (a >= n) {
+      const s = v / n;
+      const d = decimals ?? (Math.abs(s) < 10 ? 1 : 0);
+      return formatNumber(s, d, l, decimals === undefined) + suf;
+    }
+  }
+  return formatNumber(v, decimals ?? smartDecimals(v), l, decimals === undefined);
+}
+
+const isYearLike = (vals) =>
+  vals.length > 0 && vals.every((v) => Number.isInteger(v) && v >= 1000 && v <= 2999);
+
+/**
+ * Crea un formateador de valores a partir de la opción `format` del spec.
+ *   'number' | 'compact' | 'percent' | 'currency' | 'integer' | 'year'
+ *   { type, prefix, suffix, decimals, currency }
+ * `values` permite autodetectar (p. ej. porcentajes ya multiplicados por 100).
+ */
+export function makeFormat(fmt, locale = 'es', values = []) {
+  const o = typeof fmt === 'string' ? { type: fmt } : { ...(fmt || {}) };
+  const l = loc(locale);
+  const nums = values.filter((v) => Number.isFinite(v));
+  const max = nums.reduce((m, v) => Math.max(m, Math.abs(v)), 0);
+  let type = o.type;
+  if (!type) type = isYearLike(nums) ? 'year' : max >= 1e5 ? 'compact' : 'number';
+  const pre = o.prefix ?? (type === 'currency' ? currencyPrefix(o.currency, l) : '');
+  const suf = o.suffix ?? '';
+  const d = o.decimals;
+
+  let core;
+  switch (type) {
+    case 'year':
+      core = (v) => String(Math.round(v));
+      break;
+    case 'integer':
+      core = (v) => formatNumber(v, 0, l);
+      break;
+    case 'percent': {
+      const scale = o.scale ?? (max > 1.5 ? 1 : 100); // 0,25 → 25%; 25 → 25%
+      core = (v) => formatNumber(v * scale, d ?? smartDecimals(v * scale), l, d === undefined) + '%';
+      break;
+    }
+    case 'compact':
+      core = (v) => formatCompact(v, l, d);
+      break;
+    case 'currency':
+      core = (v) => (max >= 1e6 ? formatCompact(v, l, d) : formatNumber(v, d ?? (max >= 100 || nums.every(Number.isInteger) ? 0 : 2), l));
+      break;
+    default:
+      core = (v) => formatNumber(v, d ?? smartDecimals(v), l, d === undefined);
+  }
+  const f = (v) => {
+    if (v === null || v === undefined || Number.isNaN(v)) return '';
+    const s = core(v);
+    if (pre && s.startsWith('−')) return '−' + pre + s.slice(1) + suf;
+    return pre + s + suf;
+  };
+  f.type = type;
+  // `ticks` (opcional): las marcas del eje, o la mayor |marca|. Fija una sola
+  // unidad compacta para todo el eje (sin "500 M" junto a "1.000,0 M").
+  f.tick = (step, ticks) => tickFormat(step, o, type, l, pre, suf, max, d, ticks);
+  return f;
+}
+
+function currencyPrefix(cur, l) {
+  if (!cur) return '$';
+  const c = String(cur).toUpperCase();
+  return { USD: 'US$', CLP: '$', EUR: '€', UF: 'UF ', GBP: '£', PEN: 'S/ ', MXN: 'MX$', BRL: 'R$' }[c] || c + ' ';
+}
+
+/** Formateador de marcas de eje: decimales según el paso, nunca ruido. */
+function tickFormat(step, o, type, l, pre, suf, max, dFixed, ticks) {
+  // Decimales mínimos para escribir el paso exacto (2,5 → 1; 0,25 → 2).
+  const decFor = (s) => {
+    const a = Math.abs(s) || 1;
+    let d = Math.max(0, -Math.floor(Math.log10(a) + 1e-9));
+    while (d < 6 && Math.abs(Math.round(a * 10 ** d) - a * 10 ** d) > 1e-6 * 10 ** d) d++;
+    return Math.min(6, d);
+  };
+  let core;
+  if (type === 'year') core = (v) => String(Math.round(v));
+  else if (type === 'percent') {
+    const scale = o.scale ?? (max > 1.5 ? 1 : 100);
+    core = (v) => formatNumber(v * scale, decFor(step * scale), l) + '%';
+  } else if (type === 'compact' || max >= 1e4 && type !== 'integer') {
+    // Una sola unidad por eje, la de la mayor marca, entre las que tiene el idioma
+    // (en español no hay "mil millones": 1.000 M). Sin ceros finales.
+    let top;
+    if (Array.isArray(ticks)) top = ticks.reduce((m, t) => (Number.isFinite(t) ? Math.max(m, Math.abs(t)) : m), 0);
+    else if (Number.isFinite(ticks)) top = Math.abs(ticks);
+    else top = step > 0 ? Math.ceil(max / step - 1e-9) * step : max;
+    const [unit, sufx] = COMPACT[l].find(([n]) => top >= n) || [1, ''];
+    core = unit === 1
+      ? (v) => formatNumber(v, decFor(step), l)
+      : (v) => formatNumber(v / unit, decFor(step / unit), l, true) + sufx;
+  } else core = (v) => formatNumber(v, dFixed ?? decFor(step), l);
+  return (v) => {
+    if (v === 0 && dFixed === undefined && type !== 'year') return pre + '0' + (type === 'percent' ? '%' : '') + suf;
+    const s = core(v);
+    if (pre && s.startsWith('−')) return '−' + pre + s.slice(1) + suf;
+    return pre + s + suf;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Fechas
+
+const ISO = /^(\d{4})-(\d{2})(?:-(\d{2}))?(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:[.,](\d+))?)?\s*(Z|[+-]\d{2}(?::?\d{2})?)?)?/i;
+
+/**
+ * Convierte Date | 'YYYY-MM' | 'YYYY-MM-DD' | ISO a milisegundos (UTC).
+ * Sin zona horaria, la hora se toma tal cual (como UTC); con `Z` o `±hh:mm`
+ * se respeta el desfase, así datos con zonas distintas se ordenan bien.
+ */
+export function parseDate(v) {
+  if (v instanceof Date) return v.getTime();
+  if (typeof v === 'string') {
+    const m = ISO.exec(v.trim());
+    if (m) {
+      const ms = m[7] ? Math.round(+('0.' + m[7]) * 1000) : 0;
+      let t = Date.UTC(+m[1], +m[2] - 1, +(m[3] || 1), +(m[4] || 0), +(m[5] || 0), +(m[6] || 0), ms);
+      const z = m[8];
+      if (z && z.toUpperCase() !== 'Z') {
+        const sign = z[0] === '-' ? -1 : 1;
+        const hh = +z.slice(1, 3), mm = +(z.slice(1).replace(':', '').slice(2, 4) || 0);
+        t -= sign * (hh * 60 + mm) * 6e4;
+      }
+      return t;
+    }
+  }
+  return NaN;
+}
+
+export const isDateLike = (v) => v instanceof Date || (typeof v === 'string' && ISO.test(v.trim()));
+
+/**
+ * Fecha legible. `unit`: 'year' | 'quarter' | 'month' | 'day' | 'hour' | 'minute'.
+ * En 'hour'/'minute', `withYear`: true → fecha completa + "HH:mm";
+ * 'day' → fecha sin año + hora; false → solo "HH:mm".
+ */
+export function formatDate(ms, unit, locale = 'es', withYear = true) {
+  const d = new Date(ms);
+  const l = loc(locale);
+  const y = d.getUTCFullYear();
+  const m = MONTHS[l][d.getUTCMonth()];
+  if (unit === 'hour' || unit === 'minute') {
+    const hm = String(d.getUTCHours()).padStart(2, '0') + ':' + String(d.getUTCMinutes()).padStart(2, '0');
+    if (withYear === false) return hm;
+    return formatDate(ms, 'day', l, withYear !== 'day') + ' ' + hm;
+  }
+  if (unit === 'year') return String(y);
+  if (unit === 'quarter') return `T${Math.floor(d.getUTCMonth() / 3) + 1}${withYear ? ' ' + y : ''}`.replace('T', l === 'en' ? 'Q' : 'T');
+  if (unit === 'month') return withYear ? `${m} ${y}` : m;
+  const day = d.getUTCDate();
+  return l === 'en' ? `${m} ${day}${withYear ? ', ' + y : ''}` : `${day} ${m}${withYear ? ' ' + y : ''}`;
+}

package/src/frame.js

@@ -0,0 +1,226 @@
+// Marco común de cada gráfico: título (un hecho), bajada, leyenda, área de
+// trazado y línea de fuente chica a la derecha. Nada de cajas ni filetes.
+import { el, esc, g, text, r2 } from './svg.js';
+import { measure, wrap, truncate } from './text.js';
+import { FONT, FONT_CSS } from './theme.js';
+import { ctx } from './context.js';
+
+export const SIZES = {
+  title: 22,
+  subtitle: 14.5,
+  label: 12,
+  axis: 12,
+  legend: 12.5,
+  source: 11,
+};
+
+export function createFrame(spec, theme, defaults = {}) {
+  const width = Math.max(240, +spec.width || defaults.width || 720);
+  // Con textos más grandes (textScale), el alto por defecto crece para no aplastar los datos.
+  const XS = ctx.textScale;
+  // En gráficos anchos el alto por defecto crece con el ancho (hasta ~2,8:1),
+  // para que una lámina de 1500 px no quede como una franja vacía.
+  const h0 = defaults.height || 420;
+  const hW = defaults.fixedHeight ? h0 : Math.max(h0, Math.min(Math.round(h0 * 1.35), Math.round(width * 0.36)));
+  let height = Math.max(160, +spec.height || Math.round(hW * (1 + 0.55 * (XS - 1))));
+  // Responsivo: en pantallas angostas, menos margen y títulos algo menores
+  // (nunca bajo 11 px en ejes). El ancho útil es lo que más importa en móvil.
+  const k = width < 420 ? 0.86 : width < 560 ? 0.93 : 1;
+  const T0 = { ...SIZES, ...(theme.type || {}) };
+  const T = { ...T0, title: Math.round(T0.title * k * 2) / 2, subtitle: Math.max(12, Math.round(T0.subtitle * (k < 1 ? 0.95 : 1) * 2) / 2) };
+  const pad = spec.padding ?? (width < 420 ? theme.layout?.paddingSmall ?? 12 : width < 640 ? 16 : theme.layout?.padding ?? 24);
+  const innerW = width - pad * 2;
+  const parts = [];
+  let y = pad;
+
+  const tw = T.titleWeight ?? 600;
+  const titleLines = spec.title ? wrap(spec.title, innerW, T.title, tw, 5) : [];
+  const subLines = spec.subtitle ? wrap(spec.subtitle, innerW, T.subtitle, 400, 5) : [];
+  const header = [];
+  const X = ctx.textScale; // alturas de línea crecen con la escala de texto
+  const tlh = Math.round(T.title * X * 1.3), slh = Math.round(T.subtitle * X * 1.42);
+  titleLines.forEach((l, i) => {
+    header.push(text(pad, y + T.title * X * 0.9 + i * tlh, l, { fill: theme.ink, fontSize: T.title, fontWeight: tw, letterSpacing: '-0.01em' }));
+  });
+  if (titleLines.length) y += titleLines.length * tlh + 2;
+  subLines.forEach((l, i) => {
+    header.push(text(pad, y + T.subtitle * X * 1.0 + i * slh, l, { fill: theme.lede, fontSize: T.subtitle }));
+  });
+  if (subLines.length) y += subLines.length * slh + 2;
+  if (titleLines.length || subLines.length) y += 10;
+
+  const srcText = spec.source ? (/^fuente|^source/i.test(spec.source) ? spec.source : (String(spec.locale || 'es').startsWith('en') ? 'Source: ' : 'Fuente: ') + spec.source) : '';
+  // Una fuente larga salta a una segunda línea en vez de salirse por la izquierda.
+  const srcLines = srcText ? wrap(srcText, innerW, T.source, 400, 2) : [];
+  const srcLH = Math.round(T.source * X * 1.35);
+  const sourceH = srcText ? Math.round(18 * Math.max(1, X * 0.95)) + (srcLines.length - 1) * srcLH : 0;
+  const legendPos = legendPosition(spec, width);
+  let legendBottom = null; // leyenda inferior: se dibuja en finish(), cuando el alto es definitivo
+
+  const frame = {
+    width,
+    pad,
+    theme,
+    legendPosition: legendPos,
+    get height() { return height; },
+    top: y,
+    get bottom() { return height - pad - sourceH - (legendBottom ? legendBottom.h + 12 : 0); },
+    /** Alto extra fuera del área de trazado (pie + margen + leyenda inferior). */
+    get chrome() { return pad + sourceH + (legendBottom ? legendBottom.h + 12 : 0); },
+    /**
+     * Dibuja la leyenda y devuelve el área de trazado restante. La leyenda va
+     * arriba por defecto; `legend: "bottom" | "left" | "right"` la mueve.
+     */
+    layout(legend = [], opts = {}) {
+      let ly = y;
+      const items = withExcluded(legend, spec, theme);
+      const extraBottom = Math.max(0, (XS - 1) * 22);
+      if (items.length && (legendPos === 'left' || legendPos === 'right')) {
+        const colW = Math.min(innerW * 0.32, Math.max(90, legendWidth(items, T.legend)));
+        const { svg } = drawLegend(items, legendPos === 'left' ? pad : width - pad - colW, ly + 2, colW, theme, { ...opts, size: T.legend, vertical: true });
+        header.push(svg);
+        const gap = 16;
+        return { x: legendPos === 'left' ? pad + colW + gap : pad, y: ly, w: innerW - colW - gap, h: Math.max(40, frame.bottom - ly - extraBottom) };
+      }
+      if (items.length && legendPos === 'bottom') {
+        const probe = drawLegend(items, pad, 0, innerW, theme, { ...opts, size: T.legend });
+        legendBottom = { items, opts, h: probe.h };
+        return { x: pad, y: ly, w: innerW, h: Math.max(40, frame.bottom - ly - extraBottom) };
+      }
+      if (items.length) {
+        const { svg, h } = drawLegend(items, pad, ly, innerW, theme, { ...opts, size: T.legend });
+        header.push(svg);
+        ly += h + 10; // la leyenda pegada al gráfico que explica
+      }
+      // Banda extra bajo el área para etiquetas y títulos de eje agrandados.
+      return { x: pad, y: ly, w: innerW, h: Math.max(40, frame.bottom - ly - extraBottom) };
+    },
+    /** Permite a gráficos de alto automático (kpi) fijar el alto final. */
+    setHeight(h) { height = h; },
+    finish(body, { desc = '', type = 'chart', defs = '' } = {}) {
+      if (legendBottom) {
+        const { svg } = drawLegend(legendBottom.items, pad, height - pad - sourceH - legendBottom.h - 2, innerW, theme, { ...legendBottom.opts, size: T.legend });
+        header.push(svg);
+      }
+      srcLines.forEach((l, i) => parts.push(text(width - pad, height - pad - 2 - (srcLines.length - 1 - i) * srcLH, l, { fill: theme.muted, fontSize: T.source, textAnchor: 'end' })));
+      // Id estable pero distinto entre gráficos sin título del mismo tipo (aria-labelledby).
+      const id = 'pa' + Math.abs(hash((spec.title || '') + type + width + desc)).toString(36);
+      const fontImport = spec.fontImport ? `@import url('${theme.font?.import || FONT_CSS}');` : '';
+      const style = `${fontImport}.pa-m{transition:opacity .15s ease}.pa-focus .pa-m{opacity:.28}.pa-focus .pa-m.pa-on{opacity:1}@media (prefers-reduced-motion:reduce){.pa-m{transition:none}}.pa-chart:focus-visible{outline:2px solid ${theme.categorical[0]};outline-offset:2px}`
+        + (type === 'network' ? '.pa-focus .pa-net .pa-m{opacity:.12}.pa-focus .pa-net .pa-m.pa-on{opacity:1}' : '')
+        + (/^(choropleth|symbolmap|pointmap)$/.test(type) ? '.pa-zoom path,.pa-zoom circle,.pa-zoom rect{vector-effect:non-scaling-stroke}.pa-zoom-hide{transition:opacity .2s ease}.pa-zoomed .pa-zoom-hide{opacity:0}' : '');
+      return el(
+        'svg',
+        {
+          xmlns: 'http://www.w3.org/2000/svg',
+          viewBox: `0 0 ${width} ${r2(height)}`,
+          width,
+          height: r2(height),
+          role: 'img',
+          'aria-labelledby': `${id}-t ${id}-d`,
+          fontFamily: spec.fontFamily || theme.font?.family || FONT,
+          class: 'pa-chart',
+          'data-pa-type': type,
+          'data-pa-mode': theme.mode,
+          'data-pa-lang': String(spec.locale || 'es').slice(0, 2),
+          'data-pa-top': r2(frame.top),
+          'data-pa-tip': theme.tooltip && (theme.tooltip.bg || theme.tooltip.ink) ? `${theme.tooltip.bg || ''},${theme.tooltip.ink || ''}` : null,
+          style: 'max-width:100%;height:auto;font-variant-numeric:lining-nums',
+        },
+        [
+          el('title', { id: `${id}-t` }, esc(spec.title || type)),
+          el('desc', { id: `${id}-d` }, esc(desc)),
+          el('style', {}, style),
+          defs ? el('defs', {}, defs) : '',
+          spec.background === false ? '' : el('rect', { width, height: r2(height), fill: theme.surface }),
+          g({ class: 'pa-header' }, header),
+          g({ class: 'pa-body' }, body),
+          parts.join(''),
+        ]
+      );
+    },
+  };
+  return frame;
+}
+
+/** Posición de la leyenda: `legend: "top" | "bottom" | "left" | "right"` (o { position }). */
+export function legendPosition(spec, width = 720) {
+  const v = typeof spec.legend === 'string' ? spec.legend : spec.legend && typeof spec.legend === 'object' ? spec.legend.position : spec.legendPosition;
+  const p = String(v || 'top').toLowerCase();
+  const pos = { arriba: 'top', abajo: 'bottom', izquierda: 'left', derecha: 'right' }[p] || p;
+  if (!['top', 'bottom', 'left', 'right'].includes(pos)) return 'top';
+  // En pantallas angostas una columna lateral roba demasiado ancho: va abajo.
+  if ((pos === 'left' || pos === 'right') && width < 520) return 'bottom';
+  return pos;
+}
+
+/** Entradas excluidas con shift + clic (spec.exclude): siguen en la leyenda, apagadas, para volver a sumarlas. */
+function withExcluded(items, spec, theme) {
+  const ex = spec._excluded;
+  if (!ex || !ex.length || !items.length) return items;
+  const have = new Set(items.map((it) => String(it.value ?? it.label)));
+  const extra = ex.filter((v) => !have.has(String(v))).map((v) => ({ label: String(v), value: v, color: (spec.colors && spec.colors[v]) || theme.dim, shape: items[0]?.shape === 'line' ? 'line' : items[0]?.shape || 'square', off: true }));
+  return [...items, ...extra];
+}
+
+function legendWidth(items, size) {
+  const X = ctx.textScale;
+  return Math.max(...items.map((it) => (it.type === 'ramp' ? 220 : 18 * X + measure(String(it.label), size) + 12)));
+}
+
+function drawLegend(items, x0, y0, maxW, theme, opts) {
+  const out = [];
+  const size = opts.size ?? SIZES.legend;
+  const X = ctx.textScale;
+  const rowH = Math.round((opts.vertical ? 22 : 20) * X);
+  const vertical = !!opts.vertical;
+  let x = x0, y = y0, rows = 1;
+  for (const it of items) {
+    if (it.type === 'ramp') {
+      if (vertical && x > x0) { x = x0; y += rowH; rows++; }
+      const w = Math.min(220, maxW);
+      const gid = 'pa-ramp-' + Math.abs(hash(it.stops.join(''))).toString(36);
+      const stops = it.stops.map((c, i) => el('stop', { offset: `${(i / (it.stops.length - 1)) * 100}%`, stopColor: c }));
+      out.push(el('defs', {}, el('linearGradient', { id: gid }, stops)));
+      if (it.title) {
+        out.push(text(x, y + 10, it.title, { fill: theme.lede, fontSize: size }));
+        if (vertical) { y += rowH; rows++; } else x += measure(it.title, size) + 10;
+      }
+      out.push(text(x, y + 10, it.min, { fill: theme.muted, fontSize: SIZES.axis }));
+      x += measure(it.min, SIZES.axis) + 6;
+      const rw = vertical ? Math.max(40, Math.min(w * 0.6, maxW - (x - x0) - measure(it.max, SIZES.axis) - 6)) : w * 0.6;
+      out.push(el('rect', { x, y: y + 2, width: rw, height: 10, rx: 5, fill: `url(#${gid})` }));
+      x += rw + 6;
+      out.push(text(x, y + 10, it.max, { fill: theme.muted, fontSize: SIZES.axis }));
+      x += measure(it.max, SIZES.axis) + 18;
+      continue;
+    }
+    const sw = 10 * Math.min(1.6, X);
+    let label = String(it.label);
+    if (vertical) label = truncate(label, maxW - sw - 10, size);
+    const w = 18 * X + measure(label, size) + 18;
+    if ((vertical || x + w > x0 + maxW) && x > x0) { x = x0; y += rowH; rows++; }
+    const cy = y + 6.5 * X;
+    const v = it.value !== undefined ? it.value : it.key ? undefined : it.label;
+    const val = v !== undefined ? ` data-value="${esc(String(v))}"` : '';
+    const faded = it.off ? 0.45 : it.active === false ? 0.5 : null;
+    out.push(`<g class="pa-key${it.off ? ' pa-key-off' : ''}" data-color="${esc(it.key ?? it.color)}"${val}${it.active ? ' aria-pressed="true"' : ''}${faded ? ` opacity="${faded}"` : ''} style="cursor:pointer">`);
+    out.push(el('rect', { x: x - 3, y: y - 3, width: w - 10, height: rowH - 1, rx: 4, fill: 'transparent' }));
+    // Entradas punteadas: línea discontinua o cuadro rayado con borde discontinuo.
+    if (it.off) out.push(el('rect', { x: x + 0.75, y: cy - sw / 2 + 0.75, width: sw - 1.5, height: sw - 1.5, rx: 2, fill: 'none', stroke: it.color, strokeWidth: 1.5 }));
+    else if (it.shape === 'line') out.push(el('line', { x1: x, x2: x + sw * 1.2, y1: cy, y2: cy, stroke: it.color, strokeWidth: 2.5, strokeLinecap: it.dashed ? 'butt' : 'round', strokeDasharray: it.dashed ? '4 2.5' : null }));
+    else if (it.shape === 'square' && it.dashed) out.push(el('rect', { x: x + 0.6, y: cy - sw / 2 + 0.6, width: sw - 1.2, height: sw - 1.2, rx: 2, fill: it.fill || it.color, stroke: it.stroke || it.color, strokeWidth: 1.2, strokeDasharray: '3 2' }));
+    else if (it.shape === 'square') out.push(el('rect', { x, y: cy - sw / 2, width: sw, height: sw, rx: 2.5, fill: it.color }));
+    else out.push(el('circle', { cx: x + sw / 2, cy, r: sw / 2, fill: it.color }));
+    out.push(text(x + sw + 6, y + 11 * X, label, { fill: theme.lede, fontSize: size, textDecoration: it.off ? 'line-through' : null }));
+    out.push('</g>');
+    x += w;
+  }
+  return { svg: g({ class: 'pa-legend' }, out), h: rows * rowH - 6 * X };
+}
+
+export function hash(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = (Math.imul(31, h) + s.charCodeAt(i)) | 0;
+  return h;
+}

package/src/geo/chile.js

@@ -0,0 +1,7 @@
+// Registra las 16 regiones de Chile como 'chile' (alias 'chile-regiones').
+import { registerGeo } from './registry.js';
+import regiones, { attribution } from './data/chile-regiones.js';
+
+registerGeo('chile', regiones, ['chile-regiones', 'regiones']);
+export { regiones, attribution };
+export default regiones;