mnfst 0.5.163 → 0.5.164

package/lib/manifest.charts.js

@@ -1,33 +1,18 @@
-/*  Manifest Charts
+/*  Manifest Charts — in-house SVG chart renderer (themeable, prerender-safe, a11y).
 /*  By Andrew Matlock under MIT license
 /*  https://manifestx.dev
-/*
-/*  An in-house SVG chart renderer. SVG (not canvas) so charts inherit theme
-/*  colors via CSS variables, are restylable with the same selector
-/*  conventions as every other element, survive static prerendering as real
-/*  DOM, and expose accessible <title>/<desc>. The only dependencies are the
-/*  d3-scale / d3-shape / d3-array micro-modules (ISC, ~22KB), lazy-loaded
-/*  from esm.run on first scroll-into-view — the same posture as the code
-/*  plugin loading highlight.js on demand.
+/*  d3-scale/shape/array micro-modules (ISC) lazy-loaded from esm.run on scroll-in.
 */
 
 (function () {
 	'use strict';
 
-	/* ------------------------------------------------------------------ *
-	 * Shared global: ManifestUI (universal `_ui` resolver). Defined guarded so
-	 * charts works whether or not the date picker (which also defines it) is
-	 * loaded. `_ui` is a reserved, self-identifying key: any loaded data source
-	 * may carry a top-level `_ui` object, namespaced per element (`_ui.charts`,
-	 * `_ui.colorpicker`, …); no manifest flag — overrides piggyback on the normal
-	 * local-data/localization model. resolve() deep-merges every loaded source's
-	 * `_ui[component]` onto the plugin's English fallbacks. Kept byte-identical
-	 * across the date picker / color picker copies.
-	 * ------------------------------------------------------------------ */
+	/* Shared localized-UI resolver: deep-merges every loaded source's `_ui[component]`
+	 * onto the plugin's English fallbacks. Guarded; byte-identical across the picker
+	 * copies (first plugin to load defines it). */
 	if (!window.ManifestUI) {
 		window.ManifestUI = {
-			/* Names of data sources that have loaded (current locale). Enumerates loaded
-			 * sources only — never force-loads others just to scan them for `_ui`. */
+			/* Loaded data sources (current locale); never force-loads others. */
 			_loadedSourceNames() {
 				try {
 					const store = window.ManifestDataStore && window.ManifestDataStore.rawDataStore;
@@ -35,8 +20,7 @@
 				} catch (_) { }
 				return [];
 			},
-			/* Deep-merge every loaded source's `_ui[component]` onto `fallbacks`.
-			 * Reads inside the caller's Alpine effect (if any) so $x/$locale make it reactive. */
+			/* Reads inside the caller's Alpine effect (if any) so $x/$locale stay reactive. */
 			resolve(component, fallbacks) {
 				const merged = JSON.parse(JSON.stringify(fallbacks || {}));
 				try {
@@ -256,19 +240,15 @@
 			t.appendChild(document.createTextNode(str == null ? '' : String(str))); // untrusted-safe
 			return t;
 		}
-		// Entry animations run only on a chart's first draw. Reactive redraws
-		// (a bound value changing, a resize) must paint the final state directly
-		// — otherwise dragging a slider replays the reveal every frame and the
-		// chart flickers. drawChart sets this before dispatching.
+		// Entry animations run only on first draw; redraws paint final state directly
+		// (else a bound value change replays the reveal every frame). Set by drawChart.
 		let _suppressAnim = false;
 		function animate(el, keyframes, opts) {
 			if (_suppressAnim || prefersReducedMotion() || typeof el.animate !== 'function') return;
 			try { el.animate(keyframes, Object.assign({ duration: 600, easing: 'cubic-bezier(0.22,1,0.36,1)', fill: 'backwards' }, opts)); } catch (_) { }
 		}
-		// Cursor-following tooltip. Manifest's x-tooltip relies on CSS anchor
-		// positioning, which can't anchor to SVG child elements (no CSS-layout
-		// box) — so charts use their own tip, themed to match, following the
-		// pointer (better UX for dense charts). aria-label carries AT semantics.
+		// Cursor-following tooltip: x-tooltip's CSS anchor positioning can't target SVG
+		// children (no layout box), so charts use their own themed tip. aria-label for AT.
 		function applyTip(seg, tip, cfg) {
 			seg.setAttribute('aria-label', tip);
 			if (!cfg.tooltip) return;
@@ -337,12 +317,8 @@
 					if (self.el.id) _registry[self.el.id] = self.api;
 				},
 
-				// Coalesce to one draw per tick. Uses setTimeout (not rAF) so draws
-				// still happen when the tab is backgrounded (rAF is paused for hidden
-				// tabs), and does NOT reset a pending timer on re-entry — a
-				// high-frequency reactive trigger (e.g. a plugin bumping the data-store
-				// version every tick) would otherwise perpetually reschedule and starve
-				// the draw.
+				// One draw per tick. setTimeout (not rAF) so backgrounded tabs still draw;
+				// doesn't reset a pending timer, so a high-frequency trigger can't starve it.
 				schedule() { if (this._t) return; this._t = setTimeout(() => { this._t = null; this.draw(); }, 0); },
 
 				renderError(msg) { this.el.innerHTML = ''; const d = document.createElement('small'); d.textContent = msg; this.el.appendChild(d); },
@@ -407,10 +383,8 @@
 			return 4 + n * cfg.rowHeight + 22;
 		}
 
-		// Palette size is CSS-driven: count consecutive --color-chart-N custom
-		// properties (themes can extend past 8 by defining --color-chart-9, …);
-		// segment colours cycle through however many exist. Re-probed per draw
-		// so per-scope overrides apply.
+		// Palette size = count of consecutive --color-chart-N tokens (themes may extend
+		// past 8); colours cycle through them. Re-probed per draw for per-scope overrides.
 		let _paletteN = 8;
 		function probePalette(el) {
 			try {
@@ -649,13 +623,8 @@
 			if (cfg.legend) drawLegend(state, labels);
 		}
 
-		// Gauge — a single value swept across a 180° dome. Track + value arc
-		// reuse the pie/donut arc primitive; optional `zones` paint threshold
-		// bands (e.g. positive/warning/negative ranges). `unit` suffixes the
-		// centered readout; `min`/`max` default 0–100.
-		// Widest rendered label in px — exact via getComputedTextLength (the root
-		// SVG is already in the document); char-estimate fallback pre-layout. Used
-		// to size axis gutters to their content so charts sit balanced, not lopsided.
+		// Widest rendered label in px (exact via getComputedTextLength, char-estimate
+		// fallback). Sizes axis gutters to their content so charts sit balanced.
 		function labelWidth(root, items, cls) {
 			if (!items || !items.length) return 0;
 			const probe = svg('text', cls ? { class: cls, x: -9999, y: -9999 } : { x: -9999, y: -9999 }, root);
@@ -694,15 +663,12 @@
 				svg('path', { class: 'gauge-track', d: arc({ startAngle: START, endAngle: END }) }, g);
 			}
 
-			// Value arc — final geometry is set unconditionally so the gauge is
-			// correct even if the entry animation never runs (background tab);
-			// the sweep is a CSS reveal, never the source of the end state.
+			// Value arc — final geometry set unconditionally, so a background tab that
+			// skips the fade reveal still renders correctly.
 			const color = (cfg.series[0] && cfg.series[0].color) || 'var(--color-chart-1)';
 			const valueAngle = scale(value);
 			const vArc = svg('path', { class: 'gauge-value', d: arc({ startAngle: START, endAngle: valueAngle }), style: `--color-chart-color:${color}` }, g);
 			applyTip(vArc, (cfg.title ? cfg.title + ': ' : '') + value + unit, cfg);
-			// Reveal via fade (WAAPI, origin-independent) — the final geometry above
-			// is unconditional, so the gauge is correct even if this never runs.
 			animate(vArc, [{ opacity: 0 }, { opacity: 1 }], { duration: 500 });
 
 			// Centered readout + range end labels.
@@ -714,10 +680,8 @@
 			}
 		}
 
-		// Heatmap — a matrix of cells: each series is a row, each datum a column
-		// aligned to `labels`. Cell colour is a CSS color-mix between the two
-		// --color-chart-heat-* tokens (no JS colour-interpolation dep), driven
-		// by the per-cell `--heat` percentage.
+		// Heatmap — matrix of cells (row per series, column per datum). Cell colour is a
+		// CSS color-mix of the --color-chart-heat-* tokens via a per-cell `--heat` %.
 		function drawHeatmap(state, root, width, height) {
 			const cfg = state.config, d3 = state.d3;
 			const rows = cfg.series;
@@ -747,9 +711,8 @@
 
 			const plot = svg('g', { transform: `translate(${m.left},${m.top})` }, root);
 
-			// Round only the grid's outer corners: square tiles clipped to a single
-			// rounded rect hugging the cell extent (right/bottom edge sits at the
-			// last tile's inner edge, so the radius isn't clipping empty gutter).
+			// Round only the grid's outer corners: square tiles clipped to one rounded
+			// rect hugging the cell extent (so the radius doesn't clip empty gutter).
 			const clipId = 'mnfst-heat-' + (++_uid);
 			const cp = svg('clipPath', { id: clipId }, svg('defs', null, root));
 			svg('rect', { x: 0, y: 0, width: Math.max(0, iw - gap), height: Math.max(0, ih - gap), rx: cssRadius(state.el) }, cp);
@@ -790,12 +753,9 @@
 			state.el.appendChild(footer);
 		}
 
-		// Gantt — each series is a track (row); its data is an array
-		// of `{ from, to, status?, label?, color? }` segments on a shared X axis.
-		// The axis adapts to the data: numbers → linear (0–10, distance, %),
-		// date-ish values → time, other strings → category (ordinal stages). A
-		// segment with no `to` is a point marker. Single track = a status strip;
-		// many tracks = swimlanes / Gantt.
+		// Gantt — each series is a track of `{ from, to, status?, label?, color? }`
+		// segments on a shared X axis, adapting numbers→linear, dates→time, else
+		// category. A `to`-less segment is a point marker.
 		function drawGantt(state, root, width, height) {
 			const cfg = state.config, d3 = state.d3;
 			const tracks = cfg.series;
@@ -967,9 +927,8 @@
 			const valueById = {};
 			entries.forEach(([key, val]) => resolveRegion(key, geo).ids.forEach(id => { valueById[id] = val; }));
 
-			// Display-name resolution: `_ui.map.regions` override → localized
-			// pack (per $locale) → English atlas name. Async packs trigger a
-			// redraw when they arrive.
+			// Display name: `_ui.map.regions` override → localized pack ($locale) →
+			// English atlas name. Async packs trigger a redraw on arrival.
 			const num2a2 = (geo.meta && geo.meta.num2a2) || {};
 			const locale = chartLocale();
 			const ui = (window.ManifestUI && window.ManifestUI.resolve) ? window.ManifestUI.resolve('map', {}) : {};
@@ -986,9 +945,8 @@
 				return eng;
 			};
 
-			// Author-supplied place gazetteer (config `places` or `_ui.map.cities`)
-			// for resolving point names → coords. No city data is bundled; authors
-			// source it from a third-party library in their own project.
+			// Author-supplied place gazetteer (config `places` or `_ui.map.cities`) for
+			// resolving point names → coords. No city data is bundled.
 			const placesSrc = cfg.places || ui.cities || null;
 			let places = null;
 			if (placesSrc) { places = {}; Object.keys(placesSrc).forEach(k => { places[k.toLowerCase()] = placesSrc[k]; }); }
@@ -1066,9 +1024,8 @@
 			state.el.appendChild(footer);
 		}
 
-		// Legend is a <footer> sibling below the SVG (inline flex), not an
-		// absolute overlay — so it never collides with axis labels. Each item is
-		// a <span> with an <i> swatch carrying the series colour.
+		// Legend is a <footer> sibling below the SVG, not an overlay, so it never
+		// collides with axis labels. Each item: a <span> with an <i> colour swatch.
 		function drawLegend(state, labelsOverride) {
 			const cfg = state.config;
 			const items = labelsOverride || cfg.series.map(s => s.name).filter(Boolean);
@@ -1091,10 +1048,8 @@
 			const state = createState(el, expression, modifiers);
 			el._chartState = state;
 			el.classList.add('chart');
-			// Reserve the chart's height up front (parsed from the config, default
-			// 240) so the empty container isn't 0-height — a zero-height box doesn't
-			// reliably trigger the lazy-load IntersectionObserver, and reserving it
-			// also prevents a layout jump when the SVG renders.
+			// Reserve height up front (config, default 240): a 0-height box doesn't
+			// reliably trigger the lazy-load observer, and reserving avoids a layout jump.
 			const hm = expression && /height\s*:\s*(\d+)/.exec(expression);
 			el.style.minHeight = (hm ? +hm[1] : 240) + 'px';
 			observer().observe(el);