plotagents 0.0.0-stage → 0.7.0

package/src/theme.js

@@ -0,0 +1,311 @@
+// Temas de plotagents.
+//
+// Las paletas categóricas están validadas (no a ojo) con el validador de
+// paletas OKLab: banda de luminosidad, piso de croma, separación bajo
+// daltonismo (protan/deutan) entre vecinos y piso de visión normal.
+//   papel  · adyacentes ΔE CVD 13,7 · visión normal 22,6 · primeros 3 todos-los-pares 16,5
+//   noche  · adyacentes ΔE CVD 9,1  · visión normal 19,6 · primeros 3 todos-los-pares 9,1
+// El ORDEN de los colores es parte de la seguridad: no lo cambies sin volver
+// a validar.
+
+export const FONT =
+  "'Mozilla Text', 'Inter', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif";
+export const MONO = "'Fragment Mono', ui-monospace, 'SFMono-Regular', Menlo, monospace";
+export const FONT_CSS =
+  'https://fonts.googleapis.com/css2?family=Mozilla+Text:wght@400;500;600;700&display=swap';
+
+import { resolveColorScale, interpolate, sample } from './colorscales.js';
+
+// Tokens no cromáticos, compartidos por ambos temas y configurables por JSON.
+const STRUCT = {
+  font: { family: FONT, mono: MONO, import: FONT_CSS },
+  type: { title: 22, subtitle: 14.5, label: 12, axis: 11.5, legend: 12.5, source: 11, titleWeight: 600 },
+  marks: { barRadius: 4, barMax: 36, barMaxH: 22, lineWidth: 2.25, pointRadius: 4, gap: 2, ring: 2, areaOpacity: 0.12, bandOpacity: 0.16, dotOpacity: 0.85 },
+  axes: { inside: true, grid: true },
+  layout: { padding: 24, paddingSmall: 12 },
+};
+
+const papel = {
+  name: 'papel',
+  mode: 'light',
+  surface: '#FCFBF9',
+  ink: '#141A3F',
+  lede: '#4A5070',
+  muted: '#7C819C',
+  grid: '#E9EBF3',
+  axis: '#C9CDE0',
+  tint: '#ECEEF8',
+  tint2: '#D9DDF3',
+  dim: '#CDD1E3', // marcas fuera de foco (highlight)
+  other: '#A5AAC0', // "Otros"
+  link: 0.32,
+  categorical: [
+    '#3A47B8', // índigo
+    '#D42A5E', // magenta
+    '#E8A33D', // ámbar
+    '#1E9C89', // turquesa
+    '#7B5CD6', // violeta
+    '#B5562E', // óxido
+    '#5BA3E0', // cielo
+    '#8E9A2F', // oliva
+  ],
+  // Secuencial: un solo tono, claro → oscuro.
+  sequential: ['#EEF0FA', '#D9DDF3', '#B3BAE8', '#8590D8', '#5A66C7', '#3A47B8', '#26307F', '#141A3F'],
+  // Divergente: índigo ↔ gris neutro ↔ magenta.
+  diverging: ['#26307F', '#5A66C7', '#A9B0E2', '#ECEBE6', '#EFA9BE', '#D9557E', '#9E1D45'],
+  status: { good: '#178A68', warning: '#B87A00', critical: '#C9531A' },
+  ...STRUCT,
+};
+
+const noche = {
+  name: 'noche',
+  mode: 'dark',
+  surface: '#0B0F2B',
+  ink: '#F2F3FA',
+  lede: '#B4BAE0',
+  muted: '#8A90B4',
+  grid: '#1B2147',
+  axis: '#2E3666',
+  tint: '#151A3D',
+  tint2: '#1F2654',
+  dim: '#2A3160',
+  other: '#4A5280',
+  link: 0.4,
+  categorical: ['#6170E0', '#E63369', '#C4851C', '#22A892', '#9780E8', '#D06A3E', '#499BDA', '#909D2D'],
+  sequential: ['#141A3F', '#1F2862', '#2C3888', '#3A47B8', '#6170E0', '#8E99EA', '#BEC5F3', '#E6E9FB'],
+  diverging: ['#BEC5F3', '#7F8BE6', '#3F4CA8', '#2A2E48', '#A3294F', '#E8577F', '#F7B3C7'],
+  status: { good: '#2BB38A', warning: '#E0A030', critical: '#E8743F' },
+  ...STRUCT,
+};
+
+export const themes = { papel, noche, light: papel, dark: noche };
+
+// Paletas con nombre (categóricas). La de fábrica está validada; las demás
+// son conocidas y se pueden revisar con validatePalette().
+export const palettes = {
+  cdia: papel.categorical,
+  'cdia-noche': noche.categorical,
+  'okabe-ito': ['#0072B2', '#E69F00', '#009E73', '#CC79A7', '#56B4E9', '#D55E00', '#F0E442', '#000000'],
+  tableau10: ['#4E79A7', '#F28E2B', '#E15759', '#76B7B2', '#59A14F', '#EDC948', '#B07AA1', '#FF9DA7', '#9C755F', '#BAB0AC'],
+  udec: ['#223C6A', '#E69B0A', '#D21428', '#5C7DB8'],
+};
+// Rampas secuenciales (un tono, claro → oscuro) y divergentes.
+export const ramps = {
+  indigo: papel.sequential,
+  magenta: ['#FBEAF0', '#F6CADA', '#EE9DBA', '#E46F98', '#D42A5E', '#A81F4A', '#7A1636', '#4D0E22'],
+  teal: ['#E6F5F2', '#C2E8E1', '#8CD3C6', '#52BBA8', '#1E9C89', '#167A6B', '#0F5A4F', '#093B34'],
+  amber: ['#FDF3E1', '#F9E0B5', '#F4C77E', '#EEAD4E', '#E8A33D', '#BF7F1F', '#8C5C14', '#5C3C0C'],
+  'indigo-magenta': papel.diverging,
+  'teal-rust': ['#0F5A4F', '#1E9C89', '#8CD3C6', '#ECEBE6', '#E8B49A', '#C46A3F', '#7F3A1B'],
+};
+
+const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
+export function deepMerge(base, over) {
+  if (!isObj(over)) return base;
+  const out = { ...base };
+  for (const [k, v] of Object.entries(over)) out[k] = isObj(v) && isObj(base[k]) ? deepMerge(base[k], v) : v;
+  return out;
+}
+
+// Colores válidos: hex, rgb()/hsl() y nombres CSS. Cualquier otra cosa se
+// descarta: los colores viajan a atributos, CSS y tooltips (sin inyección).
+const COLOR_RE = /^(#[0-9a-f]{3,8}|(rgba?|hsla?)\([\d\s.,%/+-]+\)|[a-z]{3,20}|transparent|none)$/i;
+export const isColor = (c) => typeof c === 'string' && COLOR_RE.test(c.trim());
+const COLOR_KEYS = ['surface', 'ink', 'lede', 'muted', 'grid', 'axis', 'tint', 'tint2', 'dim', 'other'];
+
+/** Alias legibles de los tokens (background → surface, text → ink, …). */
+function normalizeTokens(t) {
+  if (!isObj(t)) return t;
+  const o = { ...t };
+  if (o.background !== undefined && o.surface === undefined) o.surface = o.background;
+  if (o.text !== undefined && o.ink === undefined) o.ink = o.text;
+  if (o.textMuted !== undefined && o.muted === undefined) o.muted = o.textMuted;
+  // grid: color o { color, dash, width }.
+  if (isObj(o.grid)) { o.gridStyle = { ...(o.gridStyle || {}), ...o.grid }; if (o.grid.color) o.grid = o.grid.color; else delete o.grid; }
+  if (isObj(o.axis)) { o.axisStyle = { ...(o.axisStyle || {}), ...o.axis }; if (o.axis.color) o.axis = o.axis.color; else delete o.axis; }
+  if (o.barRadius !== undefined) o.marks = { ...(o.marks || {}), barRadius: o.barRadius };
+  if (o.radius !== undefined) o.marks = { ...(o.marks || {}), barRadius: o.marks?.barRadius ?? o.radius, radius: o.radius };
+  if (o.lineWidth !== undefined) o.marks = { ...(o.marks || {}), lineWidth: o.lineWidth };
+  if (o.padding !== undefined) o.layout = { ...(o.layout || {}), padding: o.padding };
+  if (typeof o.font === 'string') o.font = fontSpec(o.font);
+  return o;
+}
+
+/** Descarta colores inválidos (vuelve al del tema base). */
+function sanitize(theme, base) {
+  for (const k of COLOR_KEYS) if (theme[k] !== undefined && !isColor(theme[k])) theme[k] = base[k];
+  for (const k of ['categorical', 'sequential', 'diverging']) {
+    if (Array.isArray(theme[k])) { const ok = theme[k].filter(isColor); theme[k] = ok.length ? ok : base[k]; }
+  }
+  if (theme.accent !== undefined && !isColor(theme.accent)) delete theme.accent;
+  if (isObj(theme.tooltip)) for (const k of ['bg', 'ink']) if (theme.tooltip[k] !== undefined && !isColor(theme.tooltip[k])) delete theme.tooltip[k];
+  if (isObj(theme.status)) for (const k of Object.keys(theme.status)) if (!isColor(theme.status[k])) theme.status[k] = base.status?.[k];
+  if (theme.font && typeof theme.font.import === 'string' && !/^https:\/\/[^\s'"()<>\\]+$/.test(theme.font.import)) theme.font = { ...theme.font, import: undefined };
+  if (theme.font && typeof theme.font.family === 'string') theme.font = { ...theme.font, family: theme.font.family.replace(/[<>{};]/g, '') };
+  return theme;
+}
+
+/** Paleta categórica por nombre: propias, matplotlib cualitativas o muestras de una colormap. */
+function namedPalette(name, n = 8) {
+  if (palettes[name]) return palettes[name];
+  const cs = resolveColorScale(name);
+  if (!cs) return null;
+  if (cs.kind === 'qualitative') return cs.stops;
+  // Escala continua como paleta: n muestras sin los extremos (estilo seaborn).
+  return Array.from({ length: n }, (_, i) => interpolate(cs.stops, (i + 1) / (n + 1)));
+}
+
+/** Rampa secuencial/divergente por nombre: propias o cualquier colormap. */
+function namedRamp(name) {
+  if (ramps[name]) return ramps[name];
+  const cs = resolveColorScale(name);
+  return cs && cs.kind !== 'qualitative' ? sample(cs.stops, 17) : null;
+}
+
+/**
+ * Registra un tema con nombre (se fusiona sobre `extends`, por defecto papel):
+ *   registerTheme('acme', { background: '#FFF', ink: '#111', categorical: 'tab10', grid: { dash: '2 3' } })
+ *   configure({ theme: 'acme' })   // todos los gráficos
+ */
+export function registerTheme(name, theme) {
+  if (!name || typeof name !== 'string') throw new TypeError('registerTheme(name, theme): falta el nombre.');
+  if (name === 'papel' || name === 'noche' || name === 'light' || name === 'dark') throw new TypeError(`"${name}" es un tema de fábrica: usa otro nombre o { extends: "${name}" }.`);
+  themes[name] = { ...getTheme(theme || {}), name };
+  return themes[name];
+}
+
+/**
+ * Tema = JSON. Acepta un nombre ("papel", "noche" o uno registrado) o un
+ * objeto parcial que se fusiona en profundidad sobre `extends` (por defecto
+ * "papel"):
+ *   { extends: "noche", categorical: ["#..."], type: { title: 24 }, marks: { lineWidth: 3 } }
+ * Alias: background, text, accent, grid { color, dash, width }, tooltip { bg, ink }, radius, barRadius, font.
+ * `categorical`, `sequential` y `diverging` aceptan también un nombre de paleta o colormap.
+ */
+export function getTheme(t) {
+  if (!t) return papel;
+  if (typeof t === 'string') return themes[t] || papel;
+  const over = normalizeTokens(t);
+  const base = (typeof over.extends === 'string' ? themes[over.extends] : isObj(over.extends) ? getTheme(over.extends) : null) || (over.mode === 'dark' ? noche : papel);
+  const merged = deepMerge(base, over);
+  delete merged.extends;
+  if (typeof merged.categorical === 'string') merged.categorical = namedPalette(merged.categorical) || base.categorical;
+  if (typeof merged.sequential === 'string') merged.sequential = namedRamp(merged.sequential) || base.sequential;
+  if (typeof merged.diverging === 'string') merged.diverging = namedRamp(merged.diverging) || base.diverging;
+  return sanitize(merged, base);
+}
+
+/** Tema efectivo de un spec: `theme` + atajos `palette`, `ramp` y `colorScale`. */
+export function themeFor(spec = {}) {
+  let t = getTheme(spec.theme);
+  if (spec.palette) {
+    const p = Array.isArray(spec.palette) ? spec.palette.filter(isColor) : namedPalette(spec.palette);
+    if (p && p.length) t = { ...t, categorical: p };
+  }
+  if (spec.ramp) {
+    const r = Array.isArray(spec.ramp) ? spec.ramp.filter(isColor) : namedRamp(spec.ramp);
+    if (r && r.length >= 2) t = { ...t, sequential: r };
+  }
+  const cs = resolveColorScale(spec.colorScale ?? spec.cmap ?? spec.colormap);
+  if (cs && cs.kind !== 'qualitative') {
+    const stops = sample(cs.stops, 17);
+    // `cmap`: la escala se usa completa (sin recortar el extremo claro como la rampa de fábrica).
+    t = cs.kind === 'diverging' ? { ...t, diverging: stops, cmap: cs.name } : { ...t, sequential: [stops[0], ...stops], cmap: cs.name };
+  }
+  return t;
+}
+
+// ---------------------------------------------------------------------------
+// Utilidades de color
+
+export function hexToRgb(hex) {
+  let h = String(hex).replace('#', '');
+  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
+  const n = parseInt(h.slice(0, 6), 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+export function rgbToHex([r, g, b]) {
+  const f = (v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0');
+  return ('#' + f(r) + f(g) + f(b)).toUpperCase();
+}
+
+const lin = (c) => {
+  c /= 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+};
+const delin = (c) => 255 * (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
+
+export function luminance(hex) {
+  const [r, g, b] = hexToRgb(hex).map(lin);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+export function contrast(a, b) {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Texto blanco o tinta según qué contraste mejor sobre el relleno. */
+export function textOn(fill, theme) {
+  const dark = theme.mode === 'dark' ? '#0B0F2B' : theme.ink;
+  return contrast('#FFFFFF', fill) >= contrast(dark, fill) ? '#FFFFFF' : dark;
+}
+
+/** Interpola en RGB lineal a lo largo de una rampa de colores. t ∈ [0,1]. */
+export function ramp(stops, t) {
+  t = Math.max(0, Math.min(1, Number.isFinite(t) ? t : 0));
+  const p = t * (stops.length - 1);
+  const i = Math.min(stops.length - 2, Math.floor(p));
+  const f = p - i;
+  const a = hexToRgb(stops[i]).map(lin);
+  const b = hexToRgb(stops[i + 1]).map(lin);
+  return rgbToHex(a.map((v, k) => delin(v + (b[k] - v) * f)));
+}
+
+/**
+ * Asigna colores a entidades en orden fijo. El color sigue a la entidad,
+ * nunca a su posición: pasar `colors: {"Biobío": "#..."}` fija el color.
+ * Más allá de 8 entidades no se inventan tonos: el resto va en gris "Otros".
+ */
+export function colorMap(keys, theme, overrides = {}) {
+  const map = new Map();
+  // Los colores fijados por el usuario no se repiten en las demás entidades.
+  const taken = new Set(Object.values(overrides || {}).map((c) => String(c).toLowerCase()));
+  const free = theme.categorical.filter((c) => !taken.has(String(c).toLowerCase()));
+  let i = 0;
+  for (const k of keys) {
+    if (overrides && overrides[k]) map.set(k, overrides[k]);
+    else map.set(k, i < free.length ? free[i++] : theme.other);
+  }
+  return map;
+}
+
+/**
+ * Versión legible de un color de serie para usarlo en TEXTO: lo oscurece
+ * (o aclara, en tema oscuro) hasta ≥ 4,5:1 contra el fondo. Así una etiqueta
+ * puede llevar el color de su línea sin perder legibilidad.
+ */
+export function readable(color, theme, min = 4.5) {
+  const target = theme.mode === 'dark' ? '#FFFFFF' : theme.ink;
+  let c = color;
+  for (let t = 0; t <= 1.0001 && contrast(c, theme.surface) < min; t += 0.05) {
+    const A = hexToRgb(color), B = hexToRgb(target);
+    c = rgbToHex(A.map((v, i) => v + (B[i] - v) * t));
+  }
+  return c;
+}
+
+/**
+ * Tipografía a partir de un nombre: "Poppins" → pila con respaldo y la URL de
+ * Google Fonts para cargarla. Una pila completa ("'Inter', sans-serif") se usa
+ * tal cual. También acepta { family, import }.
+ */
+export function fontSpec(font) {
+  if (!font) return null;
+  if (typeof font === 'object') return { ...font };
+  const f = String(font).trim();
+  if (/[,'"]/.test(f)) return { family: f };
+  const url = `https://fonts.googleapis.com/css2?family=${encodeURIComponent(f).replace(/%20/g, '+')}:wght@400;500;600;700&display=swap`;
+  return { family: `'${f}', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif`, import: url };
+}