plotagents 0.0.0-stage → 0.7.0

package/src/geo/projection.js

@@ -0,0 +1,217 @@
+// Proyecciones y trazado de GeoJSON a SVG (sin dependencias).
+// mercator (países alargados como Chile), equalEarth (mapamundi de áreas
+// iguales, Šavrič et al. 2018) y albersUsa (EE. UU. con Alaska, Hawái y
+// Puerto Rico en recuadros, como d3.geoAlbersUsa). fit() ajusta una
+// colección a un rectángulo.
+
+const RAD = Math.PI / 180;
+
+export function mercator() {
+  return ([lon, lat]) => {
+    const phi = Math.max(-85, Math.min(85, lat)) * RAD;
+    return [lon * RAD, -Math.log(Math.tan(Math.PI / 4 + phi / 2))];
+  };
+}
+
+const A1 = 1.340264, A2 = -0.081106, A3 = 0.000893, A4 = 0.003796, M = Math.sqrt(3) / 2;
+export function equalEarth() {
+  return ([lon, lat]) => {
+    const l = lon * RAD;
+    const th = Math.asin(M * Math.sin(lat * RAD));
+    const t2 = th * th, t6 = t2 * t2 * t2;
+    const x = (l * Math.cos(th)) / (M * (A1 + 3 * A2 * t2 + t6 * (7 * A3 + 9 * A4 * t2)));
+    const y = th * (A1 + A2 * t2 + t6 * (A3 + A4 * t2));
+    return [x, -y];
+  };
+}
+
+/**
+ * Cónica de áreas iguales (Albers) con rotación y centro, en escala unitaria:
+ * misma fórmula que d3.geoConicEqualArea. Devuelve [x, y] con y hacia abajo.
+ */
+function conic(rot, center, [p0, p1], k = 1, [tx, ty] = [0, 0]) {
+  const sy0 = Math.sin(p0 * RAD), n = (sy0 + Math.sin(p1 * RAD)) / 2;
+  const c = 1 + sy0 * (2 * n - sy0), r0 = Math.sqrt(c) / n;
+  const raw = (lon, lat) => {
+    let l = lon + rot;
+    l = ((((l + 180) % 360) + 360) % 360) - 180;
+    const r = Math.sqrt(Math.max(0, c - 2 * n * Math.sin(lat * RAD))) / n;
+    const a = l * RAD * n;
+    return [r * Math.sin(a), r0 - r * Math.cos(a)];
+  };
+  const [cx, cy] = raw(center[0], center[1]);
+  return (lon, lat) => { const [x, y] = raw(lon, lat); return [tx + k * (x - cx), ty - k * (y - cy)]; };
+}
+
+/**
+ * EE. UU. compuesto: 48 estados contiguos en Albers y recuadros para Alaska
+ * (a 0,35×), Hawái y Puerto Rico abajo, como en d3 / d3-composite-projections.
+ * Cada punto va al recuadro de su territorio (las geometrías no cruzan).
+ */
+export function albersUsa() {
+  const lower48 = conic(96, [-96.6, 38.7], [29.5, 45.5]);
+  const alaska = conic(154, [-156, 58.5], [55, 65], 0.35, [-0.307, 0.201]);
+  const hawaii = conic(157, [-160, 19.9], [8, 18], 1, [-0.205, 0.212]);
+  const puertoRico = conic(66, [-66, 18], [8, 18], 1, [0.35, 0.224]);
+  const which = ([lon, lat]) => (lat > 50 ? 'AK' : lat < 23 && lon < -150 ? 'HI' : lon > -68.5 && lon < -64 && lat < 19.5 ? 'PR' : null);
+  const P = { AK: alaska, HI: hawaii, PR: puertoRico };
+  const f = (p) => (P[which(p)] || lower48)(p[0], p[1]);
+  f.continuous = true; // sin corte en el antimeridiano: los recuadros ya son continuos
+  f.inset = which;
+  return f;
+}
+
+/** Equirectangular (placa carré): lon/lat tal cual. Útil para mapas chicos o datos ya en grados. */
+export function equirectangular() {
+  return ([lon, lat]) => [lon * RAD, -lat * RAD];
+}
+
+/**
+ * Coordenadas planas, sin proyectar: para GeoJSON en metros (UTM), en
+ * píxeles o dibujado a mano. `identity` deja el eje y hacia abajo (como
+ * SVG); `planar` lo invierte (y hacia arriba, como un plano cartesiano o UTM).
+ */
+export function identity() { const f = ([x, y]) => [x, y]; f.continuous = true; return f; }
+export function planar() { const f = ([x, y]) => [x, -y]; f.continuous = true; return f; }
+
+/** Cónica de áreas iguales con paralelos y meridiano central propios. */
+export function conicEqualArea({ parallels = [29.5, 45.5], rotate, center = [0, 0] } = {}) {
+  const lon0 = rotate !== undefined ? -[].concat(rotate)[0] : center[0];
+  const f = conic(-lon0, [lon0, center[1] ?? 0], parallels);
+  return ([lon, lat]) => f(lon, lat);
+}
+
+export const projections = {
+  mercator, equalEarth, 'equal-earth': equalEarth, albersUsa, 'albers-usa': albersUsa, albers: albersUsa,
+  equirectangular, 'plate-carree': equirectangular, latlon: equirectangular,
+  identity, none: identity, pixels: identity, planar, cartesian: planar, utm: planar,
+  conic: conicEqualArea, conicEqualArea, 'conic-equal-area': conicEqualArea,
+};
+
+/**
+ * Proyección desde el spec: un nombre ("mercator", "identity"…) o un objeto
+ * { type: "conic", parallels: [-30, -45], rotate: 72 }. Devuelve null si no
+ * se reconoce (se elige una automáticamente).
+ */
+export function makeProjection(p) {
+  if (!p) return null;
+  if (typeof p === 'string') { const f = projections[p] || projections[p.toLowerCase()]; return f ? f() : null; }
+  if (typeof p === 'object') { const f = projections[p.type || p.name]; return f ? f(p) : null; }
+  return null;
+}
+
+/**
+ * Todas las secuencias de puntos de una geometría (anillos de polígonos,
+ * líneas y puntos): sirve para encuadrar y para saber si la forma existe.
+ */
+export function rings(geom) {
+  if (!geom || !geom.type) return [];
+  const c = geom.coordinates;
+  switch (geom.type) {
+    case 'Polygon': case 'MultiLineString': return c || [];
+    case 'MultiPolygon': return (c || []).flat();
+    case 'LineString': case 'MultiPoint': return c && c.length ? [c] : [];
+    case 'Point': return c && c.length >= 2 ? [[c]] : [];
+    case 'GeometryCollection': return (geom.geometries || []).flatMap(rings);
+    default: return [];
+  }
+}
+/** ¿La geometría es de puntos o de líneas (sin área)? */
+export const isPointGeom = (geom) => !!geom && (geom.type === 'Point' || geom.type === 'MultiPoint');
+export const isLineGeom = (geom) => !!geom && (geom.type === 'LineString' || geom.type === 'MultiLineString');
+export function polygonsOf(geom) {
+  if (!geom) return [];
+  if (geom.type === 'Polygon') return [geom.coordinates];
+  if (geom.type === 'MultiPolygon') return geom.coordinates;
+  if (geom.type === 'GeometryCollection') return (geom.geometries || []).flatMap(polygonsOf);
+  return [];
+}
+
+/**
+ * Proyección ajustada a [x0, y0, x1, y1] conservando la proporción.
+ * Devuelve una función lon/lat → [x, y] con .bounds (ancho/alto usados).
+ */
+export function fit(features, raw, [x0, y0, x1, y1], { align = 'center' } = {}) {
+  let bx0 = Infinity, by0 = Infinity, bx1 = -Infinity, by1 = -Infinity;
+  for (const f of features) for (const r of rings(f.geometry)) for (const p of r) {
+    const [x, y] = raw(p);
+    if (x < bx0) bx0 = x; if (x > bx1) bx1 = x; if (y < by0) by0 = y; if (y > by1) by1 = y;
+  }
+  const w = x1 - x0, h = y1 - y0;
+  const k = Math.min(w / (bx1 - bx0 || 1), h / (by1 - by0 || 1));
+  const mw = (bx1 - bx0) * k, mh = (by1 - by0) * k;
+  const ox = align === 'left' ? x0 : x0 + (w - mw) / 2;
+  const oy = y0 + (h - mh) / 2;
+  const proj = (p) => { const [x, y] = raw(p); return [ox + (x - bx0) * k, oy + (y - by0) * k]; };
+  proj.bounds = { x: ox, y: oy, w: mw, h: mh };
+  proj.continuous = !!raw.continuous;
+  proj.inset = raw.inset;
+  proj.aspect = (by1 - by0) / (bx1 - bx0 || 1);
+  return proj;
+}
+
+/** Proporción alto/ancho de la colección proyectada (para elegir el alto). */
+export function aspectOf(features, raw) {
+  let bx0 = Infinity, by0 = Infinity, bx1 = -Infinity, by1 = -Infinity;
+  for (const f of features) for (const r of rings(f.geometry)) for (const p of r) {
+    const [x, y] = raw(p);
+    if (x < bx0) bx0 = x; if (x > bx1) bx1 = x; if (y < by0) by0 = y; if (y > by1) by1 = y;
+  }
+  return (by1 - by0) / (bx1 - bx0 || 1);
+}
+
+const r1 = (v) => Math.round(v * 10) / 10;
+
+/**
+ * Geometría → atributo d de SVG. Los anillos que saltan más de 180° de
+ * longitud (antimeridiano) se cortan para no cruzar el mapa entero. Las
+ * líneas quedan abiertas y los puntos se dibujan como círculos de radio `r`.
+ */
+export function pathD(geom, proj, { r = 4.5 } = {}) {
+  if (!geom) return '';
+  if (geom.type === 'GeometryCollection') return (geom.geometries || []).map((x) => pathD(x, proj, { r })).join('');
+  if (isPointGeom(geom)) {
+    const pts = geom.type === 'Point' ? [geom.coordinates] : geom.coordinates || [];
+    return pts.map((p) => { const [x, y] = proj(p); return `M${r1(x - r)},${r1(y)}a${r},${r} 0 1,0 ${2 * r},0a${r},${r} 0 1,0 ${-2 * r},0`; }).join('');
+  }
+  const open = isLineGeom(geom);
+  let d = '';
+  const cut = !proj.continuous;
+  for (const ring of rings(geom)) {
+    let started = false, lastLon = null, lx = null, ly = null, n = 0;
+    for (const p of ring) {
+      if (cut && lastLon !== null && Math.abs(p[0] - lastLon) > 180) started = false;
+      lastLon = p[0];
+      const [x, y] = proj(p);
+      const X = r1(x), Y = r1(y);
+      if (started && X === lx && Y === ly) continue;
+      d += (started ? 'L' : 'M') + X + ',' + Y;
+      started = true; lx = X; ly = Y; n++;
+    }
+    if (n && !open) d += 'Z';
+  }
+  return d;
+}
+
+/** Área (en px²) y centroide del polígono proyectado más grande. */
+export function centroid(geom, proj) {
+  if (!polygonsOf(geom).length) {
+    // Puntos y líneas: el promedio de sus vértices (área chica fija para las etiquetas).
+    const pts = rings(geom).flat().map(proj);
+    if (!pts.length) return { x: 0, y: 0, area: 0 };
+    const mid = isLineGeom(geom) ? pts[Math.floor(pts.length / 2)] : [pts.reduce((a, p) => a + p[0], 0) / pts.length, pts.reduce((a, p) => a + p[1], 0) / pts.length];
+    return { x: mid[0], y: mid[1], area: 0, point: true };
+  }
+  let best = null;
+  for (const poly of polygonsOf(geom)) {
+    const pts = poly[0].map(proj);
+    let a = 0, cx = 0, cy = 0;
+    for (let i = 0, j = pts.length - 1; i < pts.length; j = i++) {
+      const f = pts[j][0] * pts[i][1] - pts[i][0] * pts[j][1];
+      a += f; cx += (pts[j][0] + pts[i][0]) * f; cy += (pts[j][1] + pts[i][1]) * f;
+    }
+    a /= 2;
+    if (!best || Math.abs(a) > Math.abs(best.area)) best = { area: a, x: a ? cx / (6 * a) : pts[0][0], y: a ? cy / (6 * a) : pts[0][1] };
+  }
+  return best ? { x: best.x, y: best.y, area: Math.abs(best.area) } : { x: 0, y: 0, area: 0 };
+}

package/src/geo/registry.js

@@ -0,0 +1,110 @@
+// Registro de geometrías. El núcleo no trae mapas pesados: se registran al
+// importar 'plotagents/geo/chile', 'plotagents/geo/usa' o 'plotagents/geo/world', o se pasa un
+// GeoJSON propio en spec.geo.
+//
+// `geo` acepta, además de un nombre registrado:
+//   · un GeoJSON FeatureCollection, un Feature, un arreglo de Features o una geometría suelta
+//   · un TopoJSON (Topology); `geoObject` elige el objeto (por defecto, el primero)
+//   · en el navegador, una URL (render() la descarga; ver runtime.js)
+import { PlotError } from '../data.js';
+
+const REG = new Map();
+
+export function registerGeo(name, geo, aliases = []) {
+  const fc = toFeatureCollection(geo);
+  for (const n of [name, ...aliases]) REG.set(String(n).toLowerCase(), fc);
+  return fc;
+}
+
+/** ¿Parece una URL o una ruta a un archivo .json / .geojson / .topojson? */
+export const isGeoUrl = (s) => typeof s === 'string' && (/^(https?:)?\/\//i.test(s) || /^(\.{0,2}\/|data:)/.test(s) || /\.(geo|topo)?json(\?.*)?$/i.test(s));
+
+export function getGeo(geo, objectName) {
+  if (geo && typeof geo === 'object') return toFeatureCollection(geo, objectName);
+  if (isGeoUrl(geo)) {
+    throw new PlotError(
+      `"${geo}" es una URL o un archivo: plot() es sincrónico y no descarga nada.`,
+      "En Node, lee el archivo y pásalo como objeto: geo: JSON.parse(fs.readFileSync('mapa.geojson', 'utf8')). En el navegador, render(el, spec) sí acepta la URL."
+    );
+  }
+  const fc = REG.get(String(geo || '').toLowerCase());
+  if (!fc) {
+    const known = [...new Set(REG.keys())];
+    throw new PlotError(
+      `No hay una geometría registrada con el nombre "${geo}".`,
+      known.length ? `Disponibles: ${known.join(', ')}. O pasa un GeoJSON o TopoJSON en \`geo\`.` : "Importa 'plotagents/geo/chile', 'plotagents/geo/usa' o 'plotagents/geo/world', o pasa un GeoJSON en `geo`."
+    );
+  }
+  return fc;
+}
+
+export const registeredGeo = () => [...new Set(REG.keys())];
+
+const GEOMS = new Set(['Point', 'MultiPoint', 'LineString', 'MultiLineString', 'Polygon', 'MultiPolygon', 'GeometryCollection']);
+const cache = new WeakMap();
+
+/** Cualquier forma de GeoJSON / TopoJSON → FeatureCollection. */
+export function toFeatureCollection(geo, objectName) {
+  if (!geo || typeof geo !== 'object') throw new PlotError('`geo` debe ser un nombre registrado, un GeoJSON o un TopoJSON.', 'geo: "chile" | "usa" | "world" | { type: "FeatureCollection", features: [...] }');
+  if (Array.isArray(geo)) return { type: 'FeatureCollection', features: geo.map(asFeature) };
+  if (geo.type === 'FeatureCollection') {
+    if (!Array.isArray(geo.features)) throw new PlotError('El FeatureCollection no tiene `features`.');
+    return geo.features.every((f) => f && f.type === 'Feature') ? geo : { ...geo, features: geo.features.map(asFeature) };
+  }
+  if (geo.type === 'Feature') return { type: 'FeatureCollection', features: [geo] };
+  if (GEOMS.has(geo.type)) return { type: 'FeatureCollection', features: [{ type: 'Feature', properties: {}, geometry: geo }] };
+  if (geo.type === 'Topology') {
+    const key = objectName ?? '';
+    const memo = cache.get(geo) || {};
+    if (!memo[key]) { memo[key] = topoFeatures(geo, objectName); cache.set(geo, memo); }
+    return memo[key];
+  }
+  throw new PlotError(`No reconozco este \`geo\` (type: "${geo.type}").`, 'Usa un GeoJSON (FeatureCollection, Feature o geometría) o un TopoJSON (type: "Topology").');
+}
+
+function asFeature(f) {
+  if (f && f.type === 'Feature') return f;
+  if (f && GEOMS.has(f.type)) return { type: 'Feature', properties: {}, geometry: f };
+  throw new PlotError('Cada elemento de `geo` debe ser un Feature de GeoJSON.');
+}
+
+// ── TopoJSON (decodificador mínimo, sin dependencias) ──────────────────────
+function topoFeatures(topo, objectName) {
+  const names = Object.keys(topo.objects || {});
+  if (!names.length) throw new PlotError('El TopoJSON no tiene objetos.');
+  const name = objectName ?? names[0];
+  const obj = topo.objects[name];
+  if (!obj) throw new PlotError(`El TopoJSON no tiene el objeto "${name}".`, `Objetos disponibles: ${names.join(', ')}. Indícalo con \`geoObject\`.`);
+  const tf = topo.transform;
+  // Arcos absolutos (deshace la cuantización y la codificación delta).
+  const arcs = (topo.arcs || []).map((arc) => {
+    if (!tf) return arc.map((p) => p.slice(0, 2));
+    let x = 0, y = 0;
+    return arc.map((p) => { x += p[0]; y += p[1]; return [x * tf.scale[0] + tf.translate[0], y * tf.scale[1] + tf.translate[1]]; });
+  });
+  const point = (p) => (tf ? [p[0] * tf.scale[0] + tf.translate[0], p[1] * tf.scale[1] + tf.translate[1]] : p.slice(0, 2));
+  const line = (ids) => {
+    const out = [];
+    for (const i of ids) {
+      const a = i < 0 ? arcs[~i].slice().reverse() : arcs[i];
+      if (!a) continue;
+      for (let k = out.length ? 1 : 0; k < a.length; k++) out.push(a[k]);
+    }
+    return out;
+  };
+  const ring = (ids) => { const r = line(ids); if (r.length && (r[0][0] !== r[r.length - 1][0] || r[0][1] !== r[r.length - 1][1])) r.push(r[0]); return r; };
+  const geom = (o) => {
+    switch (o.type) {
+      case 'Point': return { type: 'Point', coordinates: point(o.coordinates) };
+      case 'MultiPoint': return { type: 'MultiPoint', coordinates: o.coordinates.map(point) };
+      case 'LineString': return { type: 'LineString', coordinates: line(o.arcs) };
+      case 'MultiLineString': return { type: 'MultiLineString', coordinates: o.arcs.map(line) };
+      case 'Polygon': return { type: 'Polygon', coordinates: o.arcs.map(ring) };
+      case 'MultiPolygon': return { type: 'MultiPolygon', coordinates: o.arcs.map((p) => p.map(ring)) };
+      default: return null;
+    }
+  };
+  const feat = (o) => ({ type: 'Feature', id: o.id, properties: { ...(o.properties || {}), ...(o.id !== undefined && (o.properties || {}).id === undefined ? { id: o.id } : {}) }, geometry: geom(o) });
+  const list = obj.type === 'GeometryCollection' ? obj.geometries.map(feat) : [feat(obj)];
+  return { type: 'FeatureCollection', features: list.filter((f) => f.geometry) };
+}

package/src/geo/usa.js

@@ -0,0 +1,8 @@
+// Registra los 50 estados de EE. UU., DC y Puerto Rico como 'usa'
+// (alias 'us', 'eeuu', 'estados-unidos', 'united-states', 'states').
+import { registerGeo } from './registry.js';
+import estados, { attribution } from './data/usa-estados.js';
+
+registerGeo('usa', estados, ['us', 'eeuu', 'ee.uu.', 'estados-unidos', 'estados unidos', 'united-states', 'united states', 'states', 'us-states']);
+export { estados, attribution };
+export default estados;

package/src/geo/world.js

@@ -0,0 +1,7 @@
+// Registra los países del mundo (Natural Earth 1:110m) como 'world' (alias 'mundo').
+import { registerGeo } from './registry.js';
+import world, { attribution } from './data/world.js';
+
+registerGeo('world', world, ['mundo', 'countries', 'paises', 'países']);
+export { world, attribution };
+export default world;

package/src/hierarchy.js

@@ -0,0 +1,139 @@
+// Jerarquías para treemap y sunburst: filas planas + campos de ruta → árbol
+// agregado, ordenado de mayor a menor. También colores por familia, foco
+// (drill-down) y migas de pan.
+import { ensureData, requireField, num, fieldsOf, fieldKind, PlotError } from './data.js';
+import { hexToRgb, rgbToHex } from './theme.js';
+import { formatNumber } from './format.js';
+import { el, g, text } from './svg.js';
+import { measure, truncate } from './text.js';
+
+/** Resuelve los campos de ruta y valor desde el spec (path | group+label | label | x). */
+export function hierarchyFields(spec, data) {
+  const fields = fieldsOf(data);
+  const cats = fields.filter((f) => fieldKind(data, f) === 'category');
+  let path = spec.path ? [].concat(spec.path) : null;
+  if (!path) {
+    const leaf = spec.label ?? spec.x;
+    path = spec.group ? [spec.group, leaf ?? cats.find((f) => f !== spec.group)] : [leaf ?? cats[0]];
+  }
+  path = path.filter(Boolean);
+  const value = spec.value ?? spec.y ?? (typeof spec.size === 'string' ? spec.size : null) ?? fields.find((f) => fieldKind(data, f) === 'number');
+  if (!path.length) throw new PlotError('No encontré un campo de categorías para la jerarquía.', 'Indica path: ["grupo", "elemento"] o label: "campo".');
+  path.forEach((p, i) => requireField(data, p, `path[${i}]`));
+  requireField(data, value, 'value');
+  return { path, value };
+}
+
+/**
+ * Construye el árbol. Nodo: { name, path, depth, value, children, parent }.
+ * `depth` (opcional) agrega todo bajo ese nivel.
+ */
+export function buildHierarchy(spec) {
+  const data = ensureData(spec);
+  const { path, value } = hierarchyFields(spec, data);
+  const levels = Math.max(1, Math.min(path.length, spec.depth ?? path.length));
+  const root = { name: '', path: [], depth: 0, value: 0, children: [], map: new Map() };
+  for (const r of data) {
+    const v = num(r[value]);
+    if (!(v > 0)) continue;
+    let node = root;
+    root.value += v;
+    for (let d = 0; d < levels; d++) {
+      const raw = r[path[d]];
+      const name = raw === null || raw === undefined || raw === '' ? '—' : String(raw);
+      if (!node.map.has(name)) {
+        const child = { name, path: [...node.path, name], depth: d + 1, value: 0, children: [], map: new Map(), parent: node };
+        node.map.set(name, child);
+        node.children.push(child);
+      }
+      node = node.map.get(name);
+      node.value += v;
+    }
+  }
+  const sortRec = (n) => { n.children.sort((a, b) => b.value - a.value); n.children.forEach(sortRec); delete n.map; };
+  sortRec(root);
+  return { root, fields: path.slice(0, levels), valueField: value, data };
+}
+
+/** Busca un nodo por ruta; si no existe, devuelve el más profundo que coincida. */
+export function findNode(root, focus = []) {
+  let node = root;
+  for (const name of focus || []) {
+    const next = node.children.find((c) => c.name === String(name));
+    if (!next) break;
+    node = next;
+  }
+  return node;
+}
+
+export const height = (n) => (n.children.length ? 1 + Math.max(...n.children.map(height)) : 0);
+export const descendants = (n) => [n, ...n.children.flatMap(descendants)];
+
+/** Mezcla un color hacia otro (t ∈ [0,1]). */
+export function mix(a, b, t) {
+  const A = hexToRgb(a), B = hexToRgb(b);
+  return rgbToHex(A.map((v, i) => v + (B[i] - v) * t));
+}
+
+/**
+ * Colores por familia: el primer nivel visible toma la paleta categórica en
+ * orden de tamaño (desde el 8.º, "Otros" en gris); los descendientes heredan
+ * el color con una variación de luminosidad sutil por hermano.
+ */
+export function assignColors(displayRoot, theme, spec, { single = false } = {}) {
+  const top = displayRoot.children;
+  const n = theme.categorical.length;
+  const fold = top.length > n;
+  top.forEach((c, i) => {
+    const fixed = spec.colors && spec.colors[c.name];
+    c.color = fixed || (single ? theme.categorical[0] : fold && i >= n - 1 ? theme.other : theme.categorical[i] || theme.other);
+    c.folded = !fixed && !single && fold && i >= n - 1;
+  });
+  const steps = [0, 0.14, 0.07, 0.2, 0.1];
+  const toward = theme.surface;
+  const rec = (node) => node.children.forEach((c, i) => {
+    // Color sólido por categoría completa (por defecto); `shade: true` vuelve a los tonos por hermano.
+    if (node !== displayRoot) c.color = (spec.colors && spec.colors[c.name]) || (spec.shade ? mix(node.color, toward, steps[i % steps.length]) : node.color);
+    rec(c);
+  });
+  rec(displayRoot);
+}
+
+export function shareFmt(locale) {
+  return (v, total) => {
+    const p = total > 0 ? (v / total) * 100 : 0;
+    return formatNumber(p, p < 1 ? 1 : p < 10 ? 1 : 0, locale, true) + '%';
+  };
+}
+
+export const SEP = ' › ';
+
+/**
+ * Migas de pan de foco: "Todo › Minería › Cobre". Cada miga lleva data-drill
+ * con la ruta de su ancestro (la raíz, "[]"). Devuelve { svg, h }.
+ */
+export function breadcrumb(focusNode, x, y, w, theme, locale = 'es') {
+  if (!focusNode || !focusNode.path.length) return { svg: '', h: 0 };
+  const en = String(locale).startsWith('en');
+  const crumbs = [{ name: en ? 'All' : 'Todo', path: [] }, ...focusNode.path.map((name, i) => ({ name, path: focusNode.path.slice(0, i + 1) }))];
+  const out = [];
+  let cx = x;
+  const size = 12.5;
+  crumbs.forEach((c, i) => {
+    const last = i === crumbs.length - 1;
+    const label = truncate(c.name, Math.max(60, w / crumbs.length), size, last ? 600 : 400);
+    const wLab = measure(label, size, last ? 600 : 400);
+    const attrs = { fill: last ? theme.ink : theme.lede, fontSize: size, fontWeight: last ? 600 : 400 };
+    if (last) out.push(text(cx, y + 13, label, attrs));
+    else out.push(g({ class: 'pa-crumb', 'data-drill': JSON.stringify(c.path), style: 'cursor:pointer' }, [
+      el('rect', { x: cx - 3, y, width: wLab + 6, height: 18, fill: 'transparent' }),
+      text(cx, y + 13, label, { ...attrs, textDecoration: 'underline', 'text-decoration-color': theme.axis }),
+    ]));
+    cx += wLab;
+    if (!last) {
+      out.push(text(cx + 6, y + 13, '›', { fill: theme.muted, fontSize: size }));
+      cx += 18;
+    }
+  });
+  return { svg: g({ class: 'pa-breadcrumb' }, out), h: 26 };
+}