@blukavantui/charts-community 0.0.0-stage → 1.2.0

package/src/builders/radar.ts

@@ -0,0 +1,65 @@
+import { format, type EChartsCoreOption } from 'echarts/core';
+import type { CatalogueKind, CatalogueOptions, CartesianOptions, RadarOptions, CircularOptions, ScatterOptions, TreemapOptions, SankeyOptions, FunnelOptions, GeoMapOptions, CalendarHeatmapOptions, ChartPoint, TreeNode } from '../catalogue-types.ts';
+import { cataloguePoints, treeValue } from '../catalogue-model.ts';
+import { resolveChartColor, contrastText, interpolateColor } from '../colors.ts';
+import { formatValue } from '../model.ts';
+import { escapeText } from '../validation.ts';
+import { markColor, markStyle, highlightStyle, sequentialScale, seriesSymbol, seriesDash, seriesDecal, boundedLabels } from '../accessibility.ts';
+import type { themeTokens } from '../options.ts';
+type Tokens = ReturnType<typeof themeTokens>;
+export function buildOption(options: CatalogueOptions, t: Tokens, mapName?: string, reducedMotion = false, width = 640): EChartsCoreOption {
+ const kind = 'radar' as CatalogueKind;
+    const o = options as any, points = cataloguePoints(kind, options);
+    const decal = (index: number, fill: string) => o.ShowPatterns ? seriesDecal(index, fill) : undefined;
+    const colors = t.palette;
+    const color = (c: any, i: number) => markColor(t.forcedColors ? t.text : resolveChartColor(c, colors[i % colors.length], t.dark, t.read), t.surface, kind === 'line' || kind === 'radar' || kind === 'polar' && o.PolarType === 'Line' ? 4.5 : 3.2);
+    const style = (key: string, c: any, i: number) => markStyle(color(c, i), t.surface, o.SelectedKey === key);
+    const point = (key: string, seriesKey?: string) => points.find(p => p.Key === key && (!seriesKey || p.SeriesKey === seriesKey));
+    const namesForLegend: string[] = ['line','radar','bar','polar'].includes(kind) ? o.Series.map((s: any) => s.Label) : kind === 'scatter' ? [...new Set<string>(o.Points.map((p: any) => p.Group || 'Observations'))] : ['pie','doughnut','nightingale','funnel'].includes(kind) ? [...new Set<string>(o.Items.map((i: any) => i.Label))] : [];
+    const legend = { data: namesForLegend, show: o.ShowLegend, type: 'scroll', top: 6, left: 10, right: 10, itemWidth: 24, itemHeight: 12, selectedMode: false, pageTextStyle: { color: t.muted }, pageIconColor: t.text, textStyle: { color: t.muted, fontSize: 11 } };
+    const label = { show: o.ShowLabels, color: contrastText(t.surface), fontSize: 11, backgroundColor: t.surface, padding: [2, 3], borderRadius: 2 };
+    const tooltip = { show: o.ShowTooltip, confine: true, enterable: true, backgroundColor: t.surface, borderColor: t.border, textStyle: { color: t.text, fontSize: 12 }, formatter: (p: any) => {
+            const d = p.data?.point as ChartPoint | undefined;
+            if (!d)
+                return `${escapeText(p.name || '')}${p.value == null || Number.isNaN(p.value) ? ' · No data' : ''}`;
+            const extra = d.Date ? `<br/>${escapeText(d.Date)}<br/><strong>${escapeText(formatValue(d.Value, o))}</strong>` : d.X !== undefined ? `<br/>${escapeText(o.XLabel || 'X')}: ${d.X}<br/>${escapeText(o.YLabel || 'Y')}: ${d.Y}${d.Size === undefined ? '' : `<br/>Size: ${d.Size}`}` : `<br/><strong>${escapeText(formatValue(d.Value, o))}</strong>`;
+            return `${escapeText(d.SeriesName ? `${d.SeriesName} · ${d.Label}` : d.Label)}${extra}${p.data?.conversion ? `<br/>${escapeText(p.data.conversion)}` : ''}`;
+        } };
+    const base = { backgroundColor: t.surface, color: colors.map((c, i) => color(c, i)), animation: !!o.EnableAnimation && !reducedMotion, animationDuration: 300, animationDurationUpdate: 150, textStyle: { fontFamily: 'Inter,system-ui,sans-serif', color: t.text }, aria: { enabled: true, description: `${o.Title}. ${o.Description || ''} Exact values and keyboard selection are in the data table.` }, tooltip };
+    const axis = { axisLine: { show: false }, axisTick: { show: false }, axisLabel: { color: t.muted, fontSize: 10, hideOverlap: true }, splitLine: { lineStyle: { color: t.border, type: 'dashed' } } };
+    
+        const c = options as RadarOptions;
+        const top = o.ShowLegend ? 48 : 22, height = o.Height || 320;
+        const centerY = top + (height - top - 38) / 2;
+        const radius = Math.max(12, Math.min(width * .24, (height - top - 64) / 2));
+        const maxima = c.Categories.map((cat, i) => {
+            const maximum = Math.max(1, ...c.Series.map(s => s.Values[i] ?? 0));
+            const unit = 10 ** Math.floor(Math.log10(maximum));
+            return cat.Max ?? Math.ceil(maximum / unit) * unit;
+        });
+        return { ...base, legend,
+            tooltip: { ...tooltip, formatter: (p: any) => {
+                const s = c.Series.find(s => s.Key === p.data?.point?.SeriesKey);
+                return s ? `<strong>${escapeText(s.Label)}</strong><br/>${c.Categories.map((cat, i) => `${escapeText(cat.Label)}: ${escapeText(formatValue(s.Values[i], o))}`).join('<br/>')}` : '';
+            } },
+            radar: {
+                center: ['50%', centerY], radius, shape: c.GridShape === 'Circle' ? 'circle' : 'polygon', splitNumber: c.SplitNumber ?? 4,
+                indicator: c.Categories.map((cat, i) => ({ name: format.truncateText(`${cat.Label}${c.ShowAxisBounds !== false ? `\n0–${formatValue(maxima[i], o, true)}` : ''}`, Math.max(28, Math.min(100, width * .22)), '11px Inter,system-ui', '…'), min: 0, max: maxima[i] })),
+                axisName: { color: t.text, fontSize: 11, lineHeight: 15, width: Math.max(28, Math.min(100, width * .22)), overflow: 'truncate' }, axisNameGap: 7,
+                axisLine: { lineStyle: { color: t.border, width: 1 } }, splitLine: { lineStyle: { color: t.border, width: 1 } }, splitArea: { show: false },
+            },
+            series: c.Series.map((s, si) => {
+                const fill = color(s.Color, si), selected = o.SelectedKey === s.Key;
+                return { id: s.Key, name: s.Label, type: 'radar', symbol: seriesSymbol(si), symbolSize: selected ? 9 : 7,
+                    lineStyle: { color: fill, width: selected ? 3 : 2.5, type: seriesDash(si) },
+                    itemStyle: { ...markStyle(fill, t.surface, selected), decal: c.ShowArea && o.ShowPatterns ? seriesDecal(si, fill) : undefined },
+                    areaStyle: c.ShowArea ? { color: fill, opacity: .08 } : undefined,
+                    label: { ...label, position: 'top', formatter: (p: { value: number }) => formatValue(p.value, o, true) }, labelLayout: boundedLabels(width, height, o.ShowLegend ? 38 : 8),
+                    emphasis: { focus: 'none', itemStyle: highlightStyle(fill), lineStyle: { width: 3 } }, blur: { lineStyle: { opacity: 1 }, itemStyle: { opacity: 1 } },
+                    // ECharts maps missing radar values to its center. Omit incomplete polygons rather than imply zero.
+                    data: s.Values.some(v => v === null) || !s.Values.length ? [] : [{ name: s.Label, value: s.Values, point: { Key: s.Key, Label: s.Label, Value: null, SeriesKey: s.Key, SeriesName: s.Label, PointType: 'Series' } }],
+                };
+            }),
+        };
+    
+}

package/src/builders/scatter.ts

@@ -0,0 +1,34 @@
+import { format, type EChartsCoreOption } from 'echarts/core';
+import type { CatalogueKind, CatalogueOptions, CartesianOptions, RadarOptions, CircularOptions, ScatterOptions, TreemapOptions, SankeyOptions, FunnelOptions, GeoMapOptions, CalendarHeatmapOptions, ChartPoint, TreeNode } from '../catalogue-types.ts';
+import { cataloguePoints, treeValue } from '../catalogue-model.ts';
+import { resolveChartColor, contrastText, interpolateColor } from '../colors.ts';
+import { formatValue } from '../model.ts';
+import { escapeText } from '../validation.ts';
+import { markColor, markStyle, highlightStyle, sequentialScale, seriesSymbol, seriesDash, seriesDecal, boundedLabels } from '../accessibility.ts';
+import type { themeTokens } from '../options.ts';
+type Tokens = ReturnType<typeof themeTokens>;
+export function buildOption(options: CatalogueOptions, t: Tokens, mapName?: string, reducedMotion = false, width = 640): EChartsCoreOption {
+ const kind = 'scatter' as CatalogueKind;
+    const o = options as any, points = cataloguePoints(kind, options);
+    const decal = (index: number, fill: string) => o.ShowPatterns ? seriesDecal(index, fill) : undefined;
+    const colors = t.palette;
+    const color = (c: any, i: number) => markColor(t.forcedColors ? t.text : resolveChartColor(c, colors[i % colors.length], t.dark, t.read), t.surface, kind === 'line' || kind === 'radar' || kind === 'polar' && o.PolarType === 'Line' ? 4.5 : 3.2);
+    const style = (key: string, c: any, i: number) => markStyle(color(c, i), t.surface, o.SelectedKey === key);
+    const point = (key: string, seriesKey?: string) => points.find(p => p.Key === key && (!seriesKey || p.SeriesKey === seriesKey));
+    const namesForLegend: string[] = ['line','radar','bar','polar'].includes(kind) ? o.Series.map((s: any) => s.Label) : kind === 'scatter' ? [...new Set<string>(o.Points.map((p: any) => p.Group || 'Observations'))] : ['pie','doughnut','nightingale','funnel'].includes(kind) ? [...new Set<string>(o.Items.map((i: any) => i.Label))] : [];
+    const legend = { data: namesForLegend, show: o.ShowLegend, type: 'scroll', top: 6, left: 10, right: 10, itemWidth: 24, itemHeight: 12, selectedMode: false, pageTextStyle: { color: t.muted }, pageIconColor: t.text, textStyle: { color: t.muted, fontSize: 11 } };
+    const label = { show: o.ShowLabels, color: contrastText(t.surface), fontSize: 11, backgroundColor: t.surface, padding: [2, 3], borderRadius: 2 };
+    const tooltip = { show: o.ShowTooltip, confine: true, enterable: true, backgroundColor: t.surface, borderColor: t.border, textStyle: { color: t.text, fontSize: 12 }, formatter: (p: any) => {
+            const d = p.data?.point as ChartPoint | undefined;
+            if (!d)
+                return `${escapeText(p.name || '')}${p.value == null || Number.isNaN(p.value) ? ' · No data' : ''}`;
+            const extra = d.Date ? `<br/>${escapeText(d.Date)}<br/><strong>${escapeText(formatValue(d.Value, o))}</strong>` : d.X !== undefined ? `<br/>${escapeText(o.XLabel || 'X')}: ${d.X}<br/>${escapeText(o.YLabel || 'Y')}: ${d.Y}${d.Size === undefined ? '' : `<br/>Size: ${d.Size}`}` : `<br/><strong>${escapeText(formatValue(d.Value, o))}</strong>`;
+            return `${escapeText(d.SeriesName ? `${d.SeriesName} · ${d.Label}` : d.Label)}${extra}${p.data?.conversion ? `<br/>${escapeText(p.data.conversion)}` : ''}`;
+        } };
+    const base = { backgroundColor: t.surface, color: colors.map((c, i) => color(c, i)), animation: !!o.EnableAnimation && !reducedMotion, animationDuration: 300, animationDurationUpdate: 150, textStyle: { fontFamily: 'Inter,system-ui,sans-serif', color: t.text }, aria: { enabled: true, description: `${o.Title}. ${o.Description || ''} Exact values and keyboard selection are in the data table.` }, tooltip };
+    const axis = { axisLine: { show: false }, axisTick: { show: false }, axisLabel: { color: t.muted, fontSize: 10, hideOverlap: true }, splitLine: { lineStyle: { color: t.border, type: 'dashed' } } };
+    
+        const c = options as ScatterOptions, groups = [...new Set(c.Points.map(p => p.Group || 'Observations'))], max = Math.max(1, ...c.Points.map(p => p.Size || 0));
+        return { ...base, legend, grid: { left: 20, right: 30, top: o.ShowLegend ? 50 : 30, bottom: 36, containLabel: true }, xAxis: { ...axis, type: 'value', name: c.XLabel || 'X', nameLocation: 'middle', nameGap: 30 }, yAxis: { ...axis, type: 'value', name: c.YLabel || 'Y' }, series: groups.map((g, gi) => ({ type: 'scatter', name: g, symbol: seriesSymbol(gi), itemStyle: { color: color(c.Points.find(p => (p.Group || 'Observations') === g)?.Color, gi) }, label: { ...label, width: Math.min(140, width * .25), overflow: 'truncate', position: 'top', formatter: '{b}' }, labelLayout: boundedLabels(width, o.Height || 320, o.ShowLegend ? 38 : 8), symbolSize: (_: any, p: any) => c.Bubble ? 8 + 36 * Math.sqrt((p.data.point.Size ?? 1) / max) : 12, emphasis: { focus: 'none', scale: false }, blur: { itemStyle: { opacity: 1 }, lineStyle: { opacity: 1 }, label: { opacity: 1 } }, data: c.Points.filter(p => (p.Group || 'Observations') === g).map(p => ({ name: p.Label, value: [p.X, p.Y], point: point(p.Key), itemStyle: style(p.Key, p.Color, gi), emphasis: { itemStyle: highlightStyle(color(p.Color, gi)) } })) })) };
+    
+}

package/src/catalogue-model.ts

@@ -0,0 +1,235 @@
+import type { CatalogueKind, CatalogueOptions, CartesianOptions, RadarOptions, CircularOptions, ScatterOptions, TreemapOptions, SankeyOptions, FunnelOptions, GeoMapOptions, CalendarHeatmapOptions, GeoJSON, ChartPoint, TreeNode } from './catalogue-types.ts';
+import { assert, base, categories, value } from './validation.ts';
+import { isChartColor } from './colors.ts';
+import { boundedList, boundedText, safeNumber, limits } from './limits.ts';
+export const dataFields: Record<CatalogueKind, string[]> = {
+    'calendar-heatmap': ['Items'],
+    radar: ['Categories', 'Series'], line: ['Categories', 'Series'], bar: ['Categories', 'Series'], polar: ['Categories', 'Series'],
+    pie: ['Items', 'Rings'], doughnut: ['Items', 'Rings'], nightingale: ['Items', 'Rings'],
+    scatter: ['Points'], treemap: ['Nodes'], sankey: ['Nodes', 'Links'], funnel: ['Items'], 'geo-map': ['Regions', 'Locations', 'GeoJSON'],
+};
+export function chartData(kind: CatalogueKind, o: CatalogueOptions): Record<string, unknown> {
+    return Object.fromEntries(dataFields[kind].filter(k => (o as any)[k] !== undefined).map(k => [k, (o as any)[k]]));
+}
+export function parseChartData(kind: CatalogueKind, json: string, o: CatalogueOptions): CatalogueOptions {
+    let data: any;
+    try {
+        data = JSON.parse(json);
+    }
+    catch {
+        throw new Error('Enter valid JSON before applying the data.');
+    }
+    assert(data && typeof data === 'object' && !Array.isArray(data), 'Input must be a JSON object.');
+    const next: any = { ...o, SelectedKey: null, IsLoading: false };
+    dataFields[kind].forEach(k => { if (data[k] === undefined)
+        delete next[k];
+    else
+        next[k] = data[k]; });
+    validateCatalogue(kind, next);
+    return next;
+}
+function list(items: any[], label: string, labelField = 'Label') {
+    boundedList(items, label);
+    const keys = new Set<string>();
+    for (const item of items) {
+        assert(item && boundedText(item.Key) && item.Key.length && !keys.has(item.Key), `${label} require unique, non-empty keys.`);
+        assert(!labelField || boundedText(item[labelField]), `${item.Key}: ${labelField} must be text within the text limit.`);
+        assert(item.Color === undefined || isChartColor(item.Color), `${item.Key}: Color must be a shared ComponentColor or hex color.`);
+        keys.add(item.Key);
+    }
+    return keys;
+}
+const finite = safeNumber;
+function nonnegative(n: unknown) { return n === null || (finite(n) && n >= 0); }
+function choice(o: any, key: string, choices: string[]) { assert(o[key] === undefined || choices.includes(o[key]), `Invalid ${key}. Choose ${choices.join(', ')}.`); }
+export function validateGeoJSON(geo: GeoJSON) {
+    assert(geo?.type === 'FeatureCollection' && Array.isArray(geo.features) && geo.features.length > 0, 'GeoJSON must be a non-empty FeatureCollection.');
+    boundedList(geo.features, 'Map features', limits.mapFeatures);
+    let coordinateCount = 0;
+    const names = new Set<string>();
+    geo.features.forEach(f => {
+        assert(f?.type === 'Feature' && typeof f.properties?.name === 'string' && f.properties.name.length && !names.has(f.properties.name), 'Each map feature needs a unique properties.name region key.');
+        names.add(f.properties.name);
+        assert(['Polygon', 'MultiPolygon'].includes(f.geometry?.type), 'Map geometry must be Polygon or MultiPolygon.');
+        const polygons = f.geometry.type === 'Polygon' ? [f.geometry.coordinates] : f.geometry.coordinates;
+        assert(Array.isArray(polygons) && polygons.length > 0, 'Map polygons must contain coordinates.');
+        for (const polygon of polygons) {
+            assert(Array.isArray(polygon) && polygon.length > 0, 'Each polygon needs rings.');
+            for (const ring of polygon as number[][][]) {
+                assert(Array.isArray(ring) && ring.length >= 4, 'Each polygon ring needs at least four coordinates.');
+                coordinateCount += ring.length;
+                assert(coordinateCount <= limits.mapCoordinates, 'Map has too many coordinates. Use a simplified boundary file.');
+                ring.forEach(p => assert(Array.isArray(p) && p.length >= 2 && finite(p[0]) && finite(p[1]) && Math.abs(p[0]) <= 180 && Math.abs(p[1]) <= 90, 'Map coordinates must be longitude/latitude in degrees.'));
+                assert(ring[0][0] === ring.at(-1)![0] && ring[0][1] === ring.at(-1)![1], 'Polygon rings must close.');
+            }
+        }
+    });
+}
+export function isISODate(value: unknown): value is string {
+    return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value + 'T00:00:00Z')) && new Date(value + 'T00:00:00Z').toISOString().slice(0, 10) === value;
+}
+export function validateCatalogue(kind: CatalogueKind, o: CatalogueOptions) {
+    base(o);
+    if ('Series' in o) {
+        boundedList(o.Series, 'Series'); boundedList(o.Categories, 'Categories');
+        assert(o.Series.length * o.Categories.length <= limits.observations, 'Too many chart observations. Aggregate the data first.');
+    }
+    for (const key of ['ShowArea', 'Nested', 'Bubble', 'Drilldown', 'ShowConversion', 'Roam'])
+        assert((o as any)[key] === undefined || typeof (o as any)[key] === 'boolean', `${key} must be a boolean.`);
+    if (kind === 'radar') {
+        const c = o as RadarOptions;
+        categories(c.Categories, 'Categories');
+        assert(c.Categories.length === 0 || (c.Categories.length >= 3 && c.Categories.length <= 12), 'Radar needs 3–12 categories, or an empty array for an empty state.');
+        list(c.Series, 'Series');
+        c.Categories.forEach(cat => assert(cat.Max === undefined || finite(cat.Max) && cat.Max > 0, `${cat.Key}: Max must be a positive number.`));
+        c.Series.forEach(s => {
+            assert(Array.isArray(s.Values) && s.Values.length === c.Categories.length && s.Values.every(nonnegative), `${s.Key}: Values must match categories and contain non-negative numbers or null.`);
+            s.Values.forEach((v, i) => assert(v === null || c.Categories[i].Max === undefined || v <= c.Categories[i].Max!, `${s.Key}: Value exceeds ${c.Categories[i].Label} Max.`));
+        });
+        choice(c, 'GridShape', ['Polygon', 'Circle']);
+        assert(c.SplitNumber === undefined || Number.isInteger(c.SplitNumber) && c.SplitNumber >= 2 && c.SplitNumber <= 8, 'SplitNumber must be an integer from 2 to 8.');
+        assert(c.ShowAxisBounds === undefined || typeof c.ShowAxisBounds === 'boolean', 'ShowAxisBounds must be Boolean.');
+    }
+    else if (['line', 'bar', 'polar'].includes(kind)) {
+        const c = o as CartesianOptions;
+        categories(c.Categories, 'Categories');
+        list(c.Series, 'Series');
+        c.Series.forEach(s => { assert(Array.isArray(s.Values) && s.Values.length === c.Categories.length && s.Values.every(value), `${s.Key}: Values must match categories and contain finite numbers or null.`); if (c.Stacking === 'Percent')
+            assert(s.Values.every(v => v === null || v >= 0), 'Percentage stacks require non-negative values.'); });
+        choice(c, 'Orientation', ['Vertical', 'Horizontal']);
+        choice(c, 'Stacking', ['None', 'Stacked', 'Percent']);
+        choice(c, 'LineStyle', ['Straight', 'Smooth', 'Step']);
+        choice(c, 'PolarType', ['Bar', 'Line']);
+    }
+    else if (['pie', 'doughnut', 'nightingale', 'funnel'].includes(kind)) {
+        const c = o as CircularOptions;
+        list(c.Items, 'Items');
+        c.Items.forEach(i => assert(nonnegative(i.Value), `${i.Key}: Value must be non-negative or null.`));
+        if (kind !== 'funnel') {
+            const rings = list(c.Rings || [], 'Rings');
+            c.Items.forEach(i => assert(!i.RingKey || rings.has(i.RingKey), `${i.Key}: RingKey must match a ring.`));
+            if (c.Nested) {
+                assert(rings.size > 0, 'Nested charts need Rings.');
+                c.Items.forEach(i => assert(i.RingKey && rings.has(i.RingKey), `${i.Key}: nested items need RingKey.`));
+            }
+            choice(c, 'Shape', ['Full', 'Half']);
+            choice(c, 'LabelPosition', ['Outside', 'Inside']);
+            choice(c, 'RoseMode', ['Area', 'Radius']);
+            assert(c.InnerRadius === undefined || (finite(c.InnerRadius) && c.InnerRadius >= 0 && c.InnerRadius <= 75), 'InnerRadius must be 0–75 percent.');
+            assert(c.CenterLabel === undefined || typeof c.CenterLabel === 'string', 'CenterLabel must be text.');
+        }
+        else
+            choice(o, 'Sort', ['Input', 'Descending', 'Ascending']);
+    }
+    else if (kind === 'calendar-heatmap') {
+        const c = o as CalendarHeatmapOptions;
+        assert(isISODate(c.RangeStart) && isISODate(c.RangeEnd), 'RangeStart and RangeEnd must be real dates in YYYY-MM-DD format.');
+        const span = (Date.parse(c.RangeEnd) - Date.parse(c.RangeStart)) / 86400000;
+        assert(span >= 0 && span <= 365, 'Choose a calendar range of 1–366 days.');
+        list(c.Items, 'Items');
+        const dates = new Set<string>();
+        c.Items.forEach(i => {
+            assert(isISODate(i.Date), `${i.Key}: Date must be a real YYYY-MM-DD date.`);
+            assert(i.Date >= c.RangeStart && i.Date <= c.RangeEnd, `${i.Key}: Date must be within the calendar range.`);
+            assert(!dates.has(i.Date), 'Use one item per date. Aggregate observations before passing the data.');
+            assert(nonnegative(i.Value), `${i.Key}: Value must be non-negative or null.`);
+            dates.add(i.Date);
+        });
+        choice(c, 'FirstDay', ['Monday', 'Sunday']);
+        assert(c.ColorScale === undefined || c.ColorScale === 'Automatic' || isChartColor(c.ColorScale), 'Invalid ColorScale.');
+        for (const key of ['ShowMonthLabels', 'ShowDayLabels'] as const)
+            assert(c[key] === undefined || typeof c[key] === 'boolean', `${key} must be a boolean.`);
+    }
+    else if (kind === 'scatter') {
+        const c = o as ScatterOptions;
+        list(c.Points, 'Points');
+        c.Points.forEach(p => { assert(finite(p.X) && finite(p.Y), `${p.Key}: X and Y must be finite numbers.`); assert(p.Size === undefined || (finite(p.Size) && p.Size >= 0), `${p.Key}: Size must be non-negative.`); assert(p.Group === undefined || typeof p.Group === 'string', 'Group must be text.'); });
+        for (const key of ['XLabel', 'YLabel'] as const)
+            assert(c[key] === undefined || typeof c[key] === 'string', `${key} must be text.`);
+    }
+    else if (kind === 'treemap') {
+        const c = o as TreemapOptions, keys = list(c.Nodes, 'Nodes');
+        c.Nodes.forEach(n => { assert(n.ParentKey === null || (typeof n.ParentKey === 'string' && keys.has(n.ParentKey)), `${n.Key}: ParentKey must be null or match a node.`); assert(nonnegative(n.Value), `${n.Key}: Value must be non-negative or null.`); });
+        const totals = treeTotals(c.Nodes), parents = new Set(c.Nodes.map(n=>n.ParentKey));
+        c.Nodes.forEach(n => { if (parents.has(n.Key) && n.Value !== null)
+            assert(totals.get(n.Key)!==null&&Math.abs(totals.get(n.Key)! - n.Value) < .000001, `${n.Key}: branch Value must equal its leaf total, or use null to calculate it.`); });
+    }
+    else if (kind === 'sankey') {
+        const c = o as SankeyOptions, keys = list(c.Nodes, 'Nodes');
+        list(c.Links, 'Links', '');
+        boundedList(c.Nodes, 'Flow nodes', limits.flowNodes); boundedList(c.Links, 'Flow links', limits.flowLinks);
+        const outgoing = new Map(c.Nodes.map(n => [n.Key, [] as string[]]));
+        c.Links.forEach(l => { assert(keys.has(l.SourceKey) && keys.has(l.TargetKey), `${l.Key}: link endpoints must match node keys.`); assert(finite(l.Value) && l.Value >= 0, `${l.Key}: Value must be non-negative.`); outgoing.get(l.SourceKey)!.push(l.TargetKey); });
+        const inbound=new Map<string,number>(),outbound=new Map<string,number>();
+        for(const l of c.Links){inbound.set(l.TargetKey,(inbound.get(l.TargetKey)||0)+l.Value);outbound.set(l.SourceKey,(outbound.get(l.SourceKey)||0)+l.Value);}
+        assert([...inbound.values(),...outbound.values()].every(safeNumber),'Flow totals exceed the supported numeric range.');
+        const degrees = new Map(c.Nodes.map(n=>[n.Key,0]));
+        c.Links.forEach(l=>degrees.set(l.TargetKey,degrees.get(l.TargetKey)!+1));
+        const queue = [...degrees].filter(([,n])=>!n).map(([k])=>k);
+        for(let i=0;i<queue.length;i++) for(const target of outgoing.get(queue[i])!) { const left=degrees.get(target)!-1; degrees.set(target,left); if(!left) queue.push(target); }
+        assert(queue.length === keys.size, 'Sankey links cannot contain cycles.');
+        choice(c, 'Orientation', ['Horizontal', 'Vertical']);
+        choice(c, 'NodeAlign', ['Justify', 'Left', 'Right']);
+        assert(c.Links.every(l => !keys.has(l.Key)), 'Link keys must be distinct from node keys.');
+    }
+    else {
+        const c = o as GeoMapOptions;
+        list(c.Regions, 'Regions');
+        list(c.Locations, 'Locations');
+        c.Regions.forEach(r => assert(value(r.Value), `${r.Key}: Value must be finite or null.`));
+        c.Locations.forEach(p => { assert(finite(p.Longitude) && Math.abs(p.Longitude) <= 180 && finite(p.Latitude) && Math.abs(p.Latitude) <= 90, `${p.Key}: invalid longitude/latitude.`); assert(finite(p.Value) && p.Value >= 0, `${p.Key}: Value must be non-negative.`); });
+        assert(c.Locations.every(p => !c.Regions.some(r => r.Key === p.Key)), 'Location and region keys must be distinct.');
+        choice(c, 'Map', ['World', 'US', 'Custom']);
+        choice(c, 'MapView', ['Mainland', 'Full']);
+        assert(c.MapURL === undefined || boundedText(c.MapURL) && !!c.MapURL, 'MapURL must be non-empty text.');
+        assert(!c.MapURL || !c.GeoJSON, 'Supply either MapURL or GeoJSON, not both.');
+        assert(!c.MapURL || c.Map === 'Custom', 'MapURL requires Map Custom.');
+        choice(c, 'MapMode', ['Regions', 'Locations', 'Combined']);
+        assert(c.ColorScale === undefined || c.ColorScale === 'Automatic' || isChartColor(c.ColorScale), 'Invalid ColorScale.');
+        if (c.GeoJSON !== undefined)
+            validateGeoJSON(c.GeoJSON);
+        if (c.Map === 'Custom') {
+            assert(c.GeoJSON || c.MapURL, 'Custom maps need GeoJSON or MapURL.');
+            if(c.GeoJSON) validateMapRegions(c, c.GeoJSON);
+        }
+    }
+    assert(o.SelectedKey == null || cataloguePoints(kind, o).some(p => p.Key === o.SelectedKey), 'SelectedKey must match an input key.');
+}
+export function validateMapRegions(o: GeoMapOptions, geo: GeoJSON) { const keys = new Set(geo.features.map(f => f.properties.name)); o.Regions.forEach(r => assert(keys.has(r.Key), `Region ${r.Key} does not exist in this map. Use its properties.name key.`)); }
+export function treeTotals(nodes: TreeNode[]): Map<string,number|null> {
+    boundedList(nodes, 'Tree nodes', limits.treeNodes);
+    const children = new Map<string|null,TreeNode[]>(), totals = new Map<string,number|null>();
+    for(const n of nodes) { const list=children.get(n.ParentKey)||[]; list.push(n); children.set(n.ParentKey,list); }
+    const queue = (children.get(null)||[]).map(n=>({n,depth:1}));
+    for(let i=0;i<queue.length;i++) { const {n,depth}=queue[i]; assert(depth<=limits.treeDepth,'Tree exceeds maximum depth.'); for(const child of children.get(n.Key)||[]) queue.push({n:child,depth:depth+1}); assert(queue.length<=nodes.length,'Tree nodes cannot contain cycles.'); }
+    assert(queue.length===nodes.length,'Tree nodes cannot contain cycles or disconnected parents.');
+    for(let i=queue.length-1;i>=0;i--) { const n=queue[i].n,kids=children.get(n.Key)||[],known=kids.map(c=>totals.get(c.Key)).filter((v):v is number=>v!=null); const total=kids.length?(known.length?known.reduce((sum,v)=>sum+v,0):null):n.Value; assert(total===null||safeNumber(total),'Tree total exceeds the supported numeric range.'); totals.set(n.Key,total); }
+    return totals;
+}
+export function treeValue(nodes: TreeNode[], n: TreeNode): number|null { return treeTotals(nodes).get(n.Key)!; }
+export function cataloguePoints(kind: CatalogueKind, o: CatalogueOptions): ChartPoint[] {
+    if (kind === 'radar') {
+        const c = o as RadarOptions;
+        return c.Series.flatMap(s => c.Categories.map((cat, i) => ({ Key: s.Key, Label: cat.Label, Value: s.Values[i], CategoryKey: cat.Key, SeriesKey: s.Key, SeriesName: s.Label })));
+    }
+    if (['line', 'bar', 'polar'].includes(kind)) {
+        const c = o as CartesianOptions;
+        return c.Series.flatMap(s => c.Categories.map((cat, i) => ({ Key: cat.Key, Label: cat.Label, Value: s.Values[i], SeriesKey: s.Key, SeriesName: s.Label })));
+    }
+    if (['pie', 'doughnut', 'nightingale', 'funnel'].includes(kind))
+        return (o as CircularOptions).Items.map(i => ({ Key: i.Key, Label: i.Label, Value: i.Value, RingKey: i.RingKey }));
+    if (kind === 'calendar-heatmap')
+        return (o as CalendarHeatmapOptions).Items.map(i => ({ ...i }));
+    if (kind === 'scatter')
+        return (o as ScatterOptions).Points.map(p => ({ ...p, Value: p.Y }));
+    if (kind === 'treemap') {
+        const c = o as TreemapOptions, totals = treeTotals(c.Nodes);
+        return c.Nodes.map(n => ({ Key: n.Key, Label: n.Label, Value: totals.get(n.Key)!, ParentKey: n.ParentKey }));
+    }
+    if (kind === 'sankey') {
+        const c = o as SankeyOptions;
+        return [...c.Nodes.map(n => ({ Key: n.Key, Label: n.Label, PointType: 'Node' as const, Value: Math.max(c.Links.filter(l => l.SourceKey === n.Key).reduce((s, l) => s + l.Value, 0), c.Links.filter(l => l.TargetKey === n.Key).reduce((s, l) => s + l.Value, 0)) })), ...c.Links.map(l => ({ Key: l.Key, Label: `${c.Nodes.find(n => n.Key === l.SourceKey)?.Label} → ${c.Nodes.find(n => n.Key === l.TargetKey)?.Label}`, Value: l.Value, SourceKey: l.SourceKey, TargetKey: l.TargetKey, PointType: 'Link' as const }))];
+    }
+    const c = o as GeoMapOptions;
+    return [...c.Regions.map(r => ({ ...r, PointType: 'Region' as const })), ...c.Locations.map(p => ({ ...p, PointType: 'Location' as const }))];
+}

package/src/catalogue-runtime.ts

@@ -0,0 +1,244 @@
+import * as echarts from 'echarts/core';
+import {LabelLayout, LegacyGridContainLabel} from 'echarts/features';
+import {TooltipComponent, AriaComponent, GraphicComponent} from 'echarts/components';
+import {SVGRenderer} from 'echarts/renderers';
+import type {ChartEvents, ChartInstance, ChartFormat, MixedChartOptions, HeatmapOptions} from './types.ts';
+import type {CatalogueKind, OptionsByKind, ChartPoint, GeoMapOptions, GeoJSON} from './catalogue-types.ts';
+import {defaults, exactValue} from './model.ts';
+import {escapeText as esc} from './validation.ts';
+import {themeTokens} from './options.ts';
+import {stateAnnouncement} from './state-announcement.ts';
+import {chartLoadingState} from './loading-state.ts';
+import {createChartLegend} from './legend.ts';
+import {exportImage} from './export.ts';
+import {chartPoints, pointIdentity, prepareUpdate, highlightTargets, validateChart, message, type RuntimeKind, type RuntimeOptions} from './chart-state.ts';
+import {resolveMap, mapRegistry} from './map-resources.ts';
+import {validateMapRegions} from './catalogue-model.ts';
+import './charts.css';
+
+type Builder=(o:any,t:ReturnType<typeof themeTokens>,mapName?:string,reducedMotion?:boolean,width?:number)=>echarts.EChartsCoreOption;
+/** Internal opt-in web presentation. Ordinary/native factories omit this policy. */
+export interface ChartPresentation {
+  /** Native integration can opt in/out without replacing the chart. */
+  enabled?(): boolean;
+  mode(host: HTMLElement): 'full' | 'reduced' | 'off';
+  timing?(): {duration?:number;easing?:string;curve?:string};
+  subscribe(host: HTMLElement, refresh: () => void): () => void;
+}
+export function createCatalogueChart<K extends CatalogueKind>(host:HTMLElement,kind:K,initial:OptionsByKind[K],events:ChartEvents<ChartPoint>,build:Builder):ChartInstance<OptionsByKind[K]> {
+  return createChartRuntime(host,kind,initial,events,build);
+}
+/** One lifecycle for all ECharts families. Sparkline deliberately stays independent. */
+export function createChartRuntime<O extends RuntimeOptions,P=ChartPoint>(host:HTMLElement,kind:RuntimeKind,initial:O,events:ChartEvents<P>,build:Builder,presentation?:ChartPresentation):ChartInstance<O> {
+  let options={...defaults,...structuredClone(initial)} as O, requested=options;
+  const emit=(callback:any,...args:any[])=>{if(destroyed)return;try{callback?.(...args);}catch(e){console.error('Chart event handler failed.',e);}};
+  let destroyed=false, exporting=false, revision=0, frame=0, focusFrame=0, pending=false, ready=false, lastState='', resourceError='';
+  let stopPresentation=()=>{};
+  let dataFade:Animation|undefined,dataFadeMode:string|undefined;
+  try{validateChart(kind,options);}catch(e){emit(events.Error,{Message:String((e as Error).message),Code:'InvalidData'});throw e;}
+  let chart:echarts.EChartsType|undefined,legend:ReturnType<typeof createChartLegend>|undefined,config:any;
+  let map:ReturnType<typeof mapRegistry.acquire>|undefined, geometry:GeoJSON|undefined,geometryKey='';
+  let mapAbort:AbortController|undefined; const exportAbort=new AbortController();
+  let treeRoot:string|undefined,treeAction='treemapRootToNode';
+  const root=document.createElement('section');root.className='blu-chart';
+  root.innerHTML='<div class="blu-chart__heading"><div><h3></h3><p></p></div><div class="blu-chart__export"><select aria-label="Chart download format"><option value="png">PNG image</option><option value="svg">SVG vector</option></select><button type="button" aria-label="Download chart">↓ <span>Download</span></button></div></div><div class="blu-chart__stage"><div class="blu-chart__plot" role="img"></div><div class="blu-chart__state" aria-hidden="true" hidden></div></div><p class="blu-chart__missing-note" hidden></p><div class="blu-chart__navigation" role="group" aria-label="Chart navigation" hidden></div><details class="blu-chart__data"><summary>View data & keyboard selections</summary><label class="blu-chart__patterns"><input type="checkbox"><span>Use fill patterns</span></label><div class="blu-chart__table" tabindex="0" role="region"></div></details><div class="blu-chart__state-announcement" role="status" aria-live="polite" aria-atomic="true"></div><div class="blu-chart__status" role="status" aria-live="polite"></div>';
+  host.append(root);
+  const $=<T extends HTMLElement=HTMLElement>(s:string)=>root.querySelector<T>(s)!;
+  const plot=$('.blu-chart__plot'),table=$('.blu-chart__table'),status=$('.blu-chart__status'),navigation=$('.blu-chart__navigation');
+  const loading=chartLoadingState($('.blu-chart__state')),announce=stateAnnouncement($('.blu-chart__state-announcement'));
+  const download=$<HTMLButtonElement>('.blu-chart__export button'),pattern=$<HTMLInputElement>('.blu-chart__patterns input');
+  const motion=matchMedia('(prefers-reduced-motion: reduce)'),forced=matchMedia('(forced-colors: active)'),scheme=matchMedia('(prefers-color-scheme: dark)');
+  const points=()=>chartPoints(kind,options),available=()=>points().some(p=>p.Value!==null);
+  const msg=(key:string,fallback:string)=>message(options,key,fallback);
+  function alive(){if(destroyed)throw new Error('This chart has been destroyed.');}
+  function report(e:unknown,Code='InvalidData',RequestId=''){if(destroyed)return;status.textContent=e instanceof Error?e.message:String(e);emit(events.Error,{Message:status.textContent,Code,RequestId});setState('Error');}
+  function setState(State:'Loading'|'Ready'|'Empty'|'Error'){if(State!==lastState){lastState=State;emit(events.StateChange,{State,Revision:revision});}}
+  function highlight(key:string|null){chart?.dispatchAction({type:'downplay'});if(!key||pending||options.IsLoading)return;
+    if(kind==='mixed'){const o=options as MixedChartOptions,dataIndex=o.Categories.findIndex(c=>c.Key===key);if(dataIndex>=0)o.Series.forEach((_,seriesIndex)=>chart?.dispatchAction({type:'highlight',seriesIndex,dataIndex}));return;}
+    if(kind==='heatmap'){const dataIndex=(options as HeatmapOptions).Cells.findIndex(c=>c.Key===key);if(dataIndex>=0)chart?.dispatchAction({type:'highlight',seriesIndex:0,dataIndex});return;}
+    for(const target of highlightTargets(config,key))chart?.dispatchAction({type:'highlight',...target});}
+  function initialize(){
+    if(chart||plot.clientWidth<=0||plot.clientHeight<=0)return;
+    echarts.use([LabelLayout,LegacyGridContainLabel,TooltipComponent,AriaComponent,GraphicComponent,SVGRenderer]);
+    chart=echarts.init(plot,undefined,{renderer:'svg'});legend=createChartLegend(root,chart,kind);
+    chart.on('click','series',(event:any)=>{
+      let p=event.data?.point;
+      if(kind==='mixed'){const o=options as MixedChartOptions;p=points().find(p=>p.Key===o.Categories[event.dataIndex]?.Key&&p.SeriesKey===o.Series[event.seriesIndex]?.Key);}
+      if(kind==='heatmap')p=points()[event.dataIndex];
+      if(p)pick(p,'Chart');
+    });
+    for(const [event,action] of [['treemaproottonode','treemapRootToNode'],['treemapzoomtonode','treemapZoomToNode']])chart.on(event,(e:any)=>{treeRoot=e.targetNodeId||e.targetNode?.getId?.();treeAction=action;});
+  }
+  function raw(p:ChartPoint){return p.Value===null?msg('NoData','No data'):exactValue(p.Value,(options as any).__valueText?.[pointIdentity(kind,p)]);}
+  function restorePointFocus(key:string){
+    cancelAnimationFrame(focusFrame);
+    // Safari publishes the replacement controls to its accessibility tree on
+    // the next frame. Focusing earlier leaves VoiceOver on a detached AX node.
+    focusFrame=requestAnimationFrame(()=>{
+      if(destroyed||!root.isConnected)return;
+      const active=document.activeElement as HTMLElement|null;
+      if(active!==document.body&&active!==table&&active?.dataset.point!==key)return;
+      const next=[...table.querySelectorAll<HTMLElement>('[data-point]')].find(n=>n.dataset.point===key);
+      (next||table).focus({preventScroll:true});
+    });
+  }
+  function renderTable(){
+    const rows=points(),active=document.activeElement as HTMLElement|null,restore=active&&table.contains(active)?active.dataset.point:undefined;
+    const button=(p:ChartPoint,label:string)=>options.EnableSelection&&p.Value!==null?`<button type="button" data-point="${esc(pointIdentity(kind,p))}" aria-label="${esc(`${p.Label}${p.SeriesName?', '+p.SeriesName:''}: ${raw(p)}`)}" aria-pressed="${options.SelectedKey===p.Key}">${esc(label)}</button>`:esc(label);
+    let head='',body='';
+    if(kind==='mixed'){
+      const o=options as MixedChartOptions,lookup=new Map(rows.map(p=>[JSON.stringify([p.Key,p.SeriesKey]),p]));
+      head=`<tr><th scope="col">${esc(msg('Category','Category'))}</th>${o.Series.map(s=>`<th scope="col">${esc(s.Name)}</th>`).join('')}</tr>`;
+      body=o.Categories.map(c=>`<tr><th scope="row">${esc(c.Label)}</th>${o.Series.map(s=>{const p=lookup.get(JSON.stringify([c.Key,s.Key]))!;return `<td>${button(p,raw(p))}</td>`;}).join('')}</tr>`).join('');
+    }else if(kind==='heatmap'){
+      const o=options as HeatmapOptions,lookup=new Map(rows.map(p=>[JSON.stringify([(p as any).XKey,(p as any).YKey]),p]));
+      head=`<tr><th scope="col">${esc(msg('Category','Category'))}</th>${o.XCategories.map(x=>`<th scope="col">${esc(x.Label)}</th>`).join('')}</tr>`;
+      body=o.YCategories.map(y=>`<tr><th scope="row">${esc(y.Label)}</th>${o.XCategories.map(x=>{const p=lookup.get(JSON.stringify([x.Key,y.Key]));return `<td>${p?button(p,raw(p)):esc(msg('NoData','No data'))}</td>`;}).join('')}</tr>`).join('');
+    }else{
+      const fields=['Key','Label','Date','Value','CategoryKey','SeriesKey','RingKey','ParentKey','X','Y','Size','Group','SourceKey','TargetKey','Longitude','Latitude','PointType'].filter(k=>rows.some(p=>(p as any)[k]!==undefined));
+      head=`<tr>${fields.map(k=>`<th scope="col">${esc(msg(k,k))}</th>`).join('')}</tr>`;
+      body=rows.map(p=>`<tr>${fields.map(k=>{const value=(p as any)[k],text=k==='Value'?raw(p):value===null?'null':String(value??'');return `<td>${k==='Label'?button(p,text):esc(text)}</td>`;}).join('')}</tr>`).join('');
+    }
+    table.setAttribute('aria-label',`${options.Title} ${msg('Values','values')}`);
+    table.innerHTML=`<table><caption>${esc(options.Title||'Chart')} — ${esc(msg('ExactValues','original values'))}</caption><thead>${head}</thead><tbody>${body}</tbody></table>`;
+    if(restore)restorePointFocus(restore);
+  }
+  function paint(reset=false){
+    if(dataFade&&(presentation?.enabled?.()===false||!options.EnableAnimation||presentation?.mode(host)!==dataFadeMode)){dataFade.cancel();dataFade=undefined;}
+    if(destroyed)return;
+    const busy=pending||!!options.IsLoading,empty=!available(),failed=!!resourceError&&!busy;
+    root.className=`blu-chart ${options.ExtendedClass||''}`;root.setAttribute('aria-label',options.AccessibleLabel||options.Title||'Chart');
+    $('h3').textContent=options.Title||'Chart';$('.blu-chart__heading p').textContent=options.Description||'';
+    $('.blu-chart__heading').hidden=!options.ShowHeader&&!options.ShowToolbar;$('h3').parentElement!.hidden=!options.ShowHeader;$('.blu-chart__export').hidden=!options.ShowToolbar;
+    download.querySelector('span')!.textContent=msg('Download','Download');download.setAttribute('aria-label',msg('DownloadChart','Download chart'));
+    $<HTMLSelectElement>('select').setAttribute('aria-label',msg('DownloadFormat','Chart download format'));
+    $('option[value="png"]').textContent=msg('PNG','PNG image');$('option[value="svg"]').textContent=msg('SVG','SVG vector');
+    navigation.setAttribute('aria-label',msg('Navigation','Chart navigation'));
+    $('.blu-chart__patterns').hidden=!['mixed','line','radar','bar','polar','pie','doughnut','nightingale','treemap','sankey','funnel'].includes(kind);
+    $('.blu-chart__patterns span').textContent=msg('Patterns',kind==='line'||kind==='radar'?'Use fill patterns (with Area fill)':'Use fill patterns');pattern.checked=!!options.ShowPatterns;
+    $('.blu-chart__data').hidden=busy||empty;$('.blu-chart__data').classList.toggle('blu-chart__data--compact',!options.ShowDataTable);
+    $('.blu-chart__data summary').textContent=options.ShowDataTable?msg('ViewData','View data & keyboard selections'):msg('ExploreData','Explore chart data');
+    plot.style.height=`${options.Height}px`;plot.style.visibility=busy||empty?'hidden':'visible';plot.setAttribute('aria-busy',String(busy));
+    if(kind==='calendar-heatmap'){const o=options as any;const weeks=Math.ceil(((Date.parse(o.RangeEnd)-Date.parse(o.RangeStart))/86400000+7)/7);plot.style.minWidth=`${Math.max(300,weeks*12+56)}px`;const stage=$('.blu-chart__stage');stage.style.overflowX='auto';stage.tabIndex=0;stage.setAttribute('role','region');stage.setAttribute('aria-label',msg('CalendarScroll','Calendar plot; scroll horizontally for more dates'));}
+    const label=busy?msg('Loading',pending?'Loading map…':'Loading chart…'):options.EmptyMessage||'No data to display';
+    loading.update(busy,empty,label,!!options.EnableAnimation&&!motion.matches&&(!presentation||presentation.enabled?.()===false||presentation.mode(host)==='full'));announce.update(failed?resourceError:!busy&&!empty?msg('Ready','Chart ready.'):label);
+    download.disabled=exporting||busy||empty||failed;
+    navigation.hidden=busy||empty||failed||!(kind==='geo-map'&&(options as any).Roam!==false||kind==='treemap'&&(options as any).Drilldown);
+    if(kind==='geo-map'&&!navigation.children.length)navigation.innerHTML=['in','out','left','right','up','down','reset','full'].map(a=>`<button type="button" data-nav="${a}"></button>`).join('');
+    if(kind==='treemap'&&!navigation.children.length)navigation.innerHTML='<button type="button" data-nav="reset"></button>';
+    const navLabels:Record<string,string>={in:'Zoom in',out:'Zoom out',left:'Pan left',right:'Pan right',up:'Pan up',down:'Pan down',reset:kind==='treemap'?'Show entire tree':'Reset map',full:'Show full map'};
+    navigation.querySelectorAll<HTMLElement>('[data-nav]').forEach(b=>{b.textContent=msg('Map_'+b.dataset.nav,navLabels[b.dataset.nav!]);});
+    initialize();if(reset)legend?.reset();legend?.prepare(options,busy||empty);
+    if(chart&&!pending&&(kind!=='geo-map'||map)){
+      const view=!reset&&(chart.getOption() as any)?.geo?.[0],t=themeTokens(root);
+      const next:any=build({...options,ShowLegend:false},t,map?.name,motion.matches,plot.clientWidth);
+      // The shared DOM legend owns layout and interaction; do not require ECharts' unused legend module.
+      delete next.legend;
+      next.aria={...next.aria,description:`${options.Title}. ${options.Description||''} ${msg('DataAlternative','Original values and keyboard selection are in the data table.')}`};
+      if(next.geo&&view){next.geo.zoom=view.zoom;if(view.center)next.geo.center=view.center;}
+      if(presentation&&presentation.enabled?.()!==false){
+        const timing=presentation.timing?.();
+        next.animation=!!options.EnableAnimation&&!motion.matches&&presentation.mode(host)==='full'&&timing?.duration!==0&&!busy&&!empty;
+        next.animationDuration=timing?.duration??750;next.animationDurationUpdate=timing?.duration??650;
+        next.animationEasing=next.animationEasingUpdate=timing?.easing??'cubicInOut';
+        // Stable data identity lets values move to their new shape instead of replaying an entrance.
+        next.series?.forEach((series:any, index:number)=>{
+          series.id ??= JSON.stringify([kind,series.type,series.name || (kind==='geo-map' ? series.type : index)]);
+          // Series and points keep semantic identity even when groups/categories reorder.
+          const identify=(datum:any, i:number)=>{
+            if(!datum || typeof datum!=='object' || datum.id!=null)return;
+            const key=datum.point?.Key ?? (kind==='mixed' ? (options as MixedChartOptions).Categories[i]?.Key : datum.name);
+            // Sankey source/target reference node IDs. Keep those IDs equal to the source keys.
+            if(key!=null)datum.id=kind==='sankey'?String(key):JSON.stringify([key,datum.point?.SeriesKey||'']);
+          };
+          series.data?.forEach(identify);series.links?.forEach(identify);
+        });
+        // A map can switch to locations only; remove the old colour scale as well.
+        if(kind==='geo-map' && !next.visualMap)next.visualMap=[];
+        // Preference changes settle any engine-owned motion immediately.
+        if(!next.animation&&config?.animation)chart.clear();
+      }
+      chart.resize();chart.setOption(next,presentation&&presentation.enabled?.()!==false?{notMerge:!!reset,replaceMerge:kind==='geo-map'?['series','visualMap']:['series']}:{notMerge:true});config=next;
+      if(reset)treeRoot=undefined;
+      if(kind==='treemap'&&treeRoot&&points().some(p=>p.Key===treeRoot))chart.dispatchAction({type:treeAction,seriesIndex:0,targetNodeId:treeRoot});
+      legend?.render(options,next,t);
+    }
+    const note=$('.blu-chart__missing-note');
+    if(kind==='radar'){const incomplete=(options as any).Series.filter((s:any)=>s.Values.some((v:any)=>v===null));note.hidden=!incomplete.length||busy||empty;note.textContent=`${incomplete.map((s:any)=>s.Label).join(', ')}: ${msg('IncompleteRadar','incomplete profile. Available measurements remain in the data table; missing values are not drawn as zero.')}`;}
+    renderTable();if(forced.matches&&!busy&&!empty)$<HTMLDetailsElement>('.blu-chart__data').open=true;
+    if(chart&&!pending&&!failed&&!ready&&(kind!=='geo-map'||map)){ready=true;emit(events.Ready);}
+    if(!destroyed)setState(busy?'Loading':failed?'Error':empty?'Empty':'Ready');
+  }
+  function commit(next:O,cleared:boolean,nextMap=map,nextGeo=geometry,nextKey=geometryKey){
+    const old={options,map,geometry,geometryKey,resourceError};options=next;map=nextMap;geometry=nextGeo;geometryKey=nextKey;
+    try{resourceError='';status.textContent='';paint(old.options.ResetKey!==next.ResetKey||old.geometryKey!==nextKey);}catch(e){options=old.options;map=old.map;geometry=old.geometry;geometryKey=old.geometryKey;resourceError=old.resourceError;requested=options;try{paint();}catch{}if(nextMap!==old.map)nextMap?.release();throw e;}
+    // These engines replace heat colours / link geometry in one frame. Give
+    // actual data changes a readable fade while retaining the same chart,
+    // selection and accessible data table. The normal factories omit this.
+    if(presentation&&presentation.enabled?.()!==false&&['heatmap','calendar-heatmap','sankey'].includes(kind)&&old.options!==next&&JSON.stringify(chartPoints(kind,old.options))!==JSON.stringify(points())){
+      dataFade?.cancel();dataFade=undefined;
+      const mode=presentation.mode(host),timing=presentation.timing?.();
+      if(options.EnableAnimation&&mode!=='off'&&!options.IsLoading&&available()&&timing?.duration!==0){
+        const duration=mode==='reduced'||motion.matches?Math.min(timing?.duration??200,200):timing?.duration??650;
+        dataFadeMode=mode;dataFade=plot.animate([{opacity:.35},{opacity:1}],{duration,easing:timing?.curve||'ease-in-out'});
+      }
+    }
+    if(old.map!==nextMap)old.map?.release();
+    if(cleared)emit(events.SelectionChange,{Key:null,Reason:'DataChanged'});
+  }
+  function apply(next:O,cleared=false){
+    const version=++revision;mapAbort?.abort();pending=false;requested=next;
+    if(kind!=='geo-map'){commit(next,cleared);return;}
+    const o=next as GeoMapOptions,key=JSON.stringify([o.Map||'World',o.MapURL||'',o.GeoJSON||null]);
+    if(geometry&&key===geometryKey){validateMapRegions(o,geometry);commit(next,cleared);return;}
+    if(o.Map==='Custom'&&o.GeoJSON){validateMapRegions(o,o.GeoJSON);const acquired=mapRegistry.acquire(o.GeoJSON);commit(next,cleared,acquired,o.GeoJSON,key);return;}
+    pending=true;mapAbort=new AbortController();paint();
+    void resolveMap(o,mapAbort.signal).then(geo=>{if(destroyed||version!==revision)return;pending=false;const acquired=mapRegistry.acquire(geo);commit(next,cleared,acquired,geo,key);}).catch(e=>{if(destroyed||version!==revision)return;pending=false;requested=options;resourceError=e instanceof Error?e.message:String(e);paint();report(e,'ResourceLoadFailed');});
+  }
+  function pick(p:ChartPoint,origin:'Chart'|'Table'){
+    if(destroyed||pending||options.IsLoading||p.Value===null&&!(kind==='radar'&&p.PointType==='Series'))return;
+    const point={...structuredClone(p),ValueText:p.Value===null?'':raw(p)},enabled=!!options.EnableSelection;
+    const selected=options.SelectedKey===p.Key?null:p.Key;
+    if(enabled){const next={...options,SelectedKey:selected};if(kind==='treemap'&&origin==='Table'&&(next as any).Drilldown){treeRoot=p.Key;treeAction='treemapRootToNode';}apply(next);if(destroyed)return;status.textContent=selected?`${msg('Selected','Selected')} ${p.Label}.`:msg('SelectionCleared','Selection cleared.');}
+    emit(events.PointClick,point,origin);
+    if(enabled&&!destroyed)emit(events.SelectionChange,{Key:selected,Reason:'User'});
+  }
+  table.onclick=e=>{
+    const b=(e.target as HTMLElement).closest<HTMLElement>('[data-point]'),key=b?.dataset.point;
+    const p=b&&points().find(p=>pointIdentity(kind,p)===key);
+    if(!p)return;
+    // VoiceOver/AXPress can activate a row without moving DOM focus first.
+    // Repainting replaces the button; restore its stable identity explicitly.
+    pick(p,'Table');
+    if(!destroyed&&root.isConnected&&(document.activeElement===document.body||root.contains(document.activeElement))){
+      restorePointFocus(key!);
+    }
+  };
+  pattern.onchange=()=>{instance.update({ShowPatterns:pattern.checked} as Partial<O>);emit(events.PatternsChange,{ShowPatterns:pattern.checked});};
+  navigation.onclick=e=>{const action=(e.target as HTMLElement).closest<HTMLElement>('[data-nav]')?.dataset.nav;if(!action||!chart)return;if(action==='full'){instance.update({MapView:'Full',ResetKey:crypto.randomUUID()} as any);return;}if(action==='reset'){treeRoot=undefined;paint(true);return;}chart.dispatchAction({type:'geoRoam',componentType:'geo',geoIndex:0,dx:action==='left'?-60:action==='right'?60:0,dy:action==='up'?-60:action==='down'?60:0,zoom:action==='in'?1.3:action==='out'?1/1.3:1,originX:plot.clientWidth/2,originY:plot.clientHeight/2});status.textContent=msg('Map_'+action,navLabelsForStatus(action));};
+  function navLabelsForStatus(action:string){return `Map view changed: ${action}.`;}
+  const refresh=()=>{try{paint();}catch(e){report(e,'RenderFailed');}};
+  const escape=(e:KeyboardEvent)=>{if(e.key==='Escape')chart?.dispatchAction({type:'hideTip'});};
+  let measuredWidth=0,measuredHeight=0;
+  const resize=new ResizeObserver(()=>{const width=plot.clientWidth,height=plot.clientHeight;if(width===measuredWidth&&height===measuredHeight)return;measuredWidth=width;measuredHeight=height;cancelAnimationFrame(frame);frame=requestAnimationFrame(()=>{if(!destroyed&&width>0&&height>0)refresh();});});
+  const theme=new MutationObserver(refresh);theme.observe(document.documentElement,{attributes:true,attributeFilter:['data-bluui-theme']});
+  motion.addEventListener('change',refresh);forced.addEventListener('change',refresh);scheme.addEventListener('change',refresh);document.addEventListener('keydown',escape);
+  const instance:ChartInstance<O>={
+    update(patch){alive();try{const {next,cleared}=prepareUpdate(kind,requested,patch);apply(next,cleared);}catch(e){if(!pending){requested=options;try{paint();}catch{}}report(e,/SelectedKey/.test((e as Error).message)?'InvalidSelection':'InvalidData');throw e;}},
+    resize(){alive();refresh();},setSelection(key){instance.update({SelectedKey:key} as Partial<O>);},highlight(key){alive();highlight(key);},
+    async download(format:ChartFormat='png',filename=`blukavant-${kind}.${format}`,requestId=crypto.randomUUID()){
+      alive();let owns=false;
+      try{if(!['png','svg'].includes(format))throw new Error('Choose PNG or SVG.');if(exporting)throw new Error('ExportBusy');if(!chart||pending||resourceError||options.IsLoading||!available())throw new Error('Wait for a visible chart with valid data before downloading.');
+        exporting=true;owns=true;download.disabled=true;const t=themeTokens(root);
+        await exportImage(chart,options,format,filename,t.surface,t.text,t.muted,legend?.exportLayout(),exportAbort.signal);
+        if(!destroyed){status.textContent=msg('ExportStarted','Chart download started.');emit(events.ExportStarted,{Format:format,FileName:filename,RequestId:requestId});emit(events.ExportComplete,{Format:format,FileName:filename});}
+      }catch(e){if(!destroyed)report(e,e instanceof Error&&e.message==='ExportBusy'?'ExportBusy':'ExportFailed',requestId);throw e;}
+      finally{if(owns){exporting=false;if(!destroyed)download.disabled=pending||!!resourceError||!!options.IsLoading||!available();}}
+    },
+    destroy(){if(destroyed)return;destroyed=true;dataFade?.cancel();stopPresentation();revision++;mapAbort?.abort();exportAbort.abort();cancelAnimationFrame(frame);cancelAnimationFrame(focusFrame);resize.disconnect();theme.disconnect();motion.removeEventListener('change',refresh);forced.removeEventListener('change',refresh);scheme.removeEventListener('change',refresh);document.removeEventListener('keydown',escape);announce.destroy();loading.destroy();legend?.destroy();chart?.dispose();map?.release();root.remove();}
+  };
+  download.onclick=()=>void instance.download($<HTMLSelectElement>('select').value as ChartFormat).catch(()=>{});
+  resize.observe(root);
+  try{apply(options);stopPresentation=presentation?.subscribe(host,refresh)||(()=>{});}catch(e){report(e);instance.destroy();throw e;}
+  return instance;
+}