@blukavantui/charts-community 0.0.0-stage → 1.0.1

package/src/sparkline-runtime/runtime.js

@@ -0,0 +1,263 @@
+// Lightweight SVG renderer, migrated from the Community Sparkline.
+// Module-local ownership keeps Charts independent of the native UI runtime.
+var shared = { instances: new Map(), serial: 0 };
+var installed;
+function el(tag, cls, text) {
+  var n = document.createElement(tag);
+  if (cls) n.className = cls;
+  if (text !== void 0) n.textContent = text;
+  return n;
+}
+function attr(n, key, value) {
+  n.setAttribute(key, String(value));
+  return n;
+}
+function report(s, message) {
+  if (!s.error) {
+    s.error = attr(el("p", "blu-common-error"), "role", "alert");
+    s.host.append(s.error);
+  }
+  s.error.textContent = message;
+  s.error.hidden = !message;
+  if (message && s.lastError !== message && s.events.Error) {
+    s.lastError = message;
+    try {
+      s.events.Error(message);
+    } catch (_) {
+    }
+  }
+  if (!message) s.lastError = "";
+}
+function integer(value, fallback, min, max) {
+  value = value === void 0 ? fallback : Number(value);
+  if (!Number.isInteger(value) || value < min || value > max) throw Error("Expected an integer between " + min + " and " + max + ".");
+  return value;
+}
+function destroy(key) {
+  var s = shared.instances.get(key);
+  if (!s) return;
+  s.dead = true;
+  s.cleanup.forEach(function(f) {
+    f();
+  });
+  s.owned.forEach(function(n) {
+    n.remove();
+  });
+  if (s.host._bluChartsSparklineOwner === key) {
+    delete s.host._bluChartsSparklineOwner;
+    s.host.removeAttribute("data-blu-ready");
+  }
+  shared.instances.delete(key);
+}
+function own(s, node) {
+  s.owned.push(node);
+  return node;
+}
+function geometry(raw, height, width = 300, lineStyle = 'Smooth') {
+  var rows = typeof raw === "string" ? JSON.parse(raw || "[]") : raw || [];
+  if (!Array.isArray(rows) || rows.length > 1e4) throw Error("Points must be a list with at most 10,000 items.");
+  var values = rows.map(function(p) {
+    if (!p || typeof p.Value !== "number" || !Number.isFinite(p.Value)) throw Error("Every Sparkline point needs a finite numeric Value.");
+    return p.Value;
+  });
+  if (!values.length) return { rows, coordinates: [], line: "", area: "" };
+  var min = Math.min.apply(null, values), max = Math.max.apply(null, values), range = max - min;
+  var scale = Math.max(Math.abs(min), Math.abs(max), 1), low = min / scale, spread = max / scale - low;
+  var coordinates = values.map(function(value, index) {
+    return [values.length === 1 ? width / 2 : 6 + index * (width - 12) / (values.length - 1), spread ? height - 6 - (value / scale - low) / spread * (height - 12) : height / 2];
+  });
+  var line = coordinates.map(function(p, i) {
+    return (i ? "L" : "M") + p[0].toFixed(3) + " " + p[1].toFixed(3);
+  }).join(" ");
+  if (lineStyle === 'Smooth' && coordinates.length > 2) {
+    // Monotone cubic interpolation keeps each segment within its observed values.
+    var step = (width - 12) / (coordinates.length - 1);
+    var slopes = coordinates.slice(1).map(function(p, i) { return (p[1] - coordinates[i][1]) / step; });
+    var tangents = coordinates.map(function(_, i) {
+      if (i === 0) return slopes[0];
+      if (i === coordinates.length - 1) return slopes[i - 1];
+      var before = slopes[i - 1], after = slopes[i];
+      return before * after > 0 ? 2 * before * after / (before + after) : 0;
+    });
+    line = 'M' + coordinates[0][0].toFixed(3) + ' ' + coordinates[0][1].toFixed(3);
+    for (var i = 1; i < coordinates.length; i++) {
+      var start = coordinates[i - 1], end = coordinates[i];
+      line += ' C' + (start[0] + step / 3).toFixed(3) + ' ' + (start[1] + tangents[i - 1] * step / 3).toFixed(3)
+        + ' ' + (end[0] - step / 3).toFixed(3) + ' ' + (end[1] - tangents[i] * step / 3).toFixed(3)
+        + ' ' + end[0].toFixed(3) + ' ' + end[1].toFixed(3);
+    }
+  }
+  return { rows, coordinates, line, area: line + " L" + coordinates[coordinates.length - 1][0] + " " + (height - 4) + " L" + coordinates[0][0] + " " + (height - 4) + " Z", min, max, first: values[0], last: values[values.length - 1] };
+}
+function sparkline(s) {
+  var o = s.options, width = Math.max(24, Math.round(s.host.clientWidth || 300)), signature = JSON.stringify([o, width, s.reducedMotion.matches]);
+  const msg=(key,fallback,values={})=>(o.Messages?.[key]??fallback).replace(/\{(\w+)\}/g,(token,name)=>values[name]??token);
+  if (s.renderSignature === signature) return;
+  var lineStyle = o.LineStyle || 'Smooth';
+  if (!['Straight', 'Smooth'].includes(lineStyle)) throw Error('LineStyle must be Straight or Smooth.');
+  var height = integer(o.Height, 64, 24, 240), geometryKey = JSON.stringify([o.PointsJson, height, width, lineStyle]);
+  var g = s.geometryKey === geometryKey ? s.geometry : geometry(o.PointsJson, height, width, lineStyle);
+  var animation = o.Animation || (o.AnimateGlow === false ? 'Off' : 'Once');
+  if (!['Off', 'Once', 'Continuous'].includes(animation)) throw Error('Animation must be Off, Once or Continuous.');
+  var duration = o.AnimationDuration === undefined ? 5 : Number(o.AnimationDuration);
+  if (!Number.isFinite(duration) || duration < 1 || duration > 60) throw Error('AnimationDuration must be between 1 and 60 seconds.');
+  var opacity = o.AreaOpacity === undefined ? 18 : Number(o.AreaOpacity);
+  if (!Number.isFinite(opacity) || opacity < 0 || opacity > 100) throw Error('AreaOpacity must be between 0 and 100 percent.');
+  if (s.animation !== animation) s.animationPaused = false;
+  s.animation = animation;
+  s.geometryKey = geometryKey;
+  s.geometry = g;
+  var color = String(o.Color || "Primary").toLowerCase();
+  if ("default primary secondary success processing warning error danger magenta red volcano orange gold lime green cyan blue geekblue purple".split(" ").indexOf(color) < 0) throw Error("Unknown ComponentColor.");
+  if (!s.body) {
+    s.body = own(s, el("div", "blu-sparkline"));
+    s.host.append(s.body);
+  }
+  var body = s.body, wasOpen = !!(body.querySelector("details") && body.querySelector("details").open), hadFocus = body.contains(document.activeElement);
+  while (body.firstChild) body.removeChild(body.firstChild);
+  body.style.setProperty("--blu-sparkline-color", "var(--bluui-color-" + color + "-text)");
+  body.style.setProperty("--blu-sparkline-height", height + "px");
+  if (!g.rows.length) {
+    body.append(el("p", "blu-sparkline__empty", o.EmptyText || "No trend data."));
+    s.renderSignature = signature;
+    return;
+  }
+  var ns = "http://www.w3.org/2000/svg", svg = document.createElementNS(ns, "svg");
+  attr(svg, "viewBox", "0 0 " + width + " " + height);
+  attr(svg, "preserveAspectRatio", "none");
+  attr(svg, "role", "img");
+  const direction=g.last>g.first?'Rising':g.last<g.first?'Falling':'Unchanged';
+  var summary = o.SummaryText || msg('TrendSummary','{count} points. {direction} from {first} to {last}. Minimum {min}, maximum {max}.',{count:g.rows.length,direction:msg(direction,direction),first:g.first,last:g.last,min:g.min,max:g.max});
+  attr(svg, "aria-label", (o.AccessibleLabel || "Trend") + ". " + summary);
+  var title = document.createElementNS(ns, "title");
+  title.textContent = (o.AccessibleLabel || "Trend") + ". " + summary;
+  svg.append(title);
+  if (o.ShowArea !== false && g.rows.length > 1) {
+    var defs = document.createElementNS(ns, 'defs'), gradient = document.createElementNS(ns, 'linearGradient');
+    attr(gradient, 'id', s.uid + '-area');
+    attr(gradient, 'x1', '0%'); attr(gradient, 'y1', '0%'); attr(gradient, 'x2', '0%'); attr(gradient, 'y2', '100%');
+    [opacity / 100, o.AreaFade === false ? opacity / 100 : 0].forEach(function(value, index) {
+      var stop = document.createElementNS(ns, 'stop');
+      attr(stop, 'offset', index ? '100%' : '0%');
+      stop.style.stopColor = 'var(--blu-sparkline-color)';
+      attr(stop, 'stop-opacity', value); gradient.append(stop);
+    });
+    defs.append(gradient); svg.append(defs);
+    var area = document.createElementNS(ns, "path");
+    attr(area, "d", g.area);
+    attr(area, "class", "blu-sparkline__area");
+    area.style.fill = 'url(#' + s.uid + '-area)';
+    svg.append(area);
+  }
+  var path = document.createElementNS(ns, "path");
+  attr(path, "d", g.line);
+  attr(path, "class", "blu-sparkline__line");
+  attr(path, "vector-effect", "non-scaling-stroke");
+  svg.append(path);
+  var moving = animation !== 'Off' && g.rows.length > 1 && !s.reducedMotion.matches;
+  if ((!moving && o.ShowEndMarker !== false) || g.rows.length === 1) {
+    var p = g.coordinates[g.coordinates.length - 1], circle = document.createElementNS(ns, "circle");
+    attr(circle, "cx", p[0]);
+    attr(circle, "cy", p[1]);
+    attr(circle, "r", 3);
+    attr(circle, "class", "blu-sparkline__point");
+    svg.append(circle);
+  }
+  if (moving) {
+    var traveler = document.createElementNS(ns, 'g');
+    attr(traveler, 'class', 'blu-sparkline__traveler'); attr(traveler, 'aria-hidden', 'true');
+    [['halo', 6], ['ring', 4.5], ['cursor', 3]].forEach(function(part) {
+      var marker = document.createElementNS(ns, 'circle');
+      attr(marker, 'r', part[1]);
+      attr(marker, 'class', 'blu-sparkline__' + part[0]); traveler.append(marker);
+    });
+    var motion = document.createElementNS(ns, 'animateMotion'), fade = document.createElementNS(ns, 'animate');
+    attr(motion, 'path', g.line); attr(motion, 'calcMode', 'spline');
+    attr(motion, 'keyPoints', '0;1'); attr(motion, 'keyTimes', '0;1');
+    attr(motion, 'keySplines', '0.22 0.61 0.36 1');
+    attr(fade, 'attributeName', 'opacity'); attr(fade, 'values', '0;1;1;0'); attr(fade, 'keyTimes', '0;0.03;0.96;1');
+    [motion, fade].forEach(function(effect) {
+      attr(effect, 'dur', duration + 's'); attr(effect, 'repeatCount', animation === 'Continuous' ? 'indefinite' : '1'); attr(effect, 'fill', 'freeze'); traveler.append(effect);
+    });
+    svg.append(traveler);
+  }
+  body.append(svg);
+  if (moving && (animation === 'Continuous' || duration > 5)) {
+    var pause = el('button', 'blu-sparkline__pause'); pause.type = 'button';
+    var updatePause = function() {
+      pause.textContent = s.animationPaused ? msg('ResumeAnimation','Resume animation') : msg('PauseAnimation','Pause animation');
+      if (s.animationPaused) svg.pauseAnimations(); else svg.unpauseAnimations();
+    };
+    pause.addEventListener('click', function() { s.animationPaused = !s.animationPaused; updatePause(); });
+    body.append(pause); updatePause();
+  }
+  if (o.ShowDataTable) {
+    let buildTable = function() {
+      if (!details.open || tableBuilt) return;
+      var table = el("table"), caption = el("caption", "", o.AccessibleLabel || "Trend"), thead = el("thead"), headings = el("tr");
+      headings.append(attr(el("th", "", msg('Point','Point')), "scope", "col"), attr(el("th", "", msg('Value','Value')), "scope", "col"));
+      thead.append(headings);
+      table.append(caption, thead);
+      var tbody = el("tbody");
+      g.rows.forEach(function(row, index) {
+        var tr = el("tr");
+        tr.append(attr(el("th", "", row.Label || String(index + 1)), "scope", "row"), el("td", "", String(row.Value)));
+        tbody.append(tr);
+      });
+      table.append(tbody);
+      details.append(table);
+      tableBuilt = true;
+    };
+    var details = el("details", "blu-sparkline__data");
+    details.open = wasOpen;
+    details.append(el("summary", "", msg('ViewData','View trend data')));
+    var tableBuilt = false;
+    details.addEventListener("toggle", buildTable);
+    body.append(details);
+    buildTable();
+    if (hadFocus) details.querySelector("summary").focus();
+  }
+  s.renderSignature = signature;
+}
+function api(kind, render) {
+  return { sync: function(id, options, events, key) {
+    var host = document.getElementById(id);
+    if (!host) return "Component host was not found.";
+    key = key || id;
+    var s = shared.instances.get(key);
+    if (s && s.host !== host) {
+      destroy(key);
+      s = null;
+    }
+    if (host._bluChartsSparklineOwner && host._bluChartsSparklineOwner !== key) destroy(host._bluChartsSparklineOwner);
+    if (!s) {
+      s = { host, key, uid: "blu-charts-trend-" + ++shared.serial, owned: [], cleanup: [], reducedMotion: matchMedia('(prefers-reduced-motion: reduce)') };
+      shared.instances.set(key, s);
+      var refresh = function() { if (!s.dead && s.options) { try { render(s); } catch (_) {} } };
+      var observer = new ResizeObserver(refresh); observer.observe(host);
+      s.reducedMotion.addEventListener('change', refresh);
+      s.cleanup.push(function() { observer.disconnect(); s.reducedMotion.removeEventListener('change', refresh); });
+    }
+    var preview = host.nextElementSibling;
+    if (preview && preview.classList.contains("blu-component-preview")) preview.hidden = true;
+    host._bluChartsSparklineOwner = key;
+    s.options = options || {};
+    s.events = events || {};
+    attr(host, "data-blu-ready", "true");
+    try {
+      render(s);
+      report(s, "");
+      return "";
+    } catch (e) {
+      s.renderSignature = void 0;
+      report(s, e.message || String(e));
+      return e.message || String(e);
+    }
+  }, destroy };
+}
+function installSparkline() {
+  return installed || (installed = Object.assign(api("Sparkline", sparkline), { geometry }));
+}
+export {
+  installSparkline
+};

package/src/sparkline-validation.ts

@@ -0,0 +1,19 @@
+import type {SparklineOptions} from './sparkline.ts';
+import {boundedList,boundedText,safeNumber} from './limits.ts';
+import {isComponentColor} from './colors.ts';
+/** Validate before touching the SVG or committing an update. */
+export function validateSparkline(o:SparklineOptions) {
+  boundedList(o.Points,'Points');
+  if(o.Messages!==undefined&&(!o.Messages||typeof o.Messages!=='object'||Array.isArray(o.Messages)||Object.keys(o.Messages).length>100||!Object.values(o.Messages).every(boundedText)))throw new Error('Messages must contain plain text translations.');
+  if(o.Points.some(p=>!p||!safeNumber(p.Value)||p.Label!==undefined&&!boundedText(p.Label)))throw new Error('Points require supported finite values and plain text labels.');
+  for(const key of ['AnimateGlow','ShowArea','AreaFade','ShowEndMarker','ShowDataTable'] as const)
+    if(o[key]!==undefined&&typeof o[key]!=='boolean')throw new Error(`${key} must be Boolean.`);
+  for(const key of ['AccessibleLabel','SummaryText','EmptyText','ExtendedClass'] as const)
+    if(o[key]!==undefined&&!boundedText(o[key]))throw new Error(`${key} must be plain text within the text limit.`);
+  if(o.Color!==undefined&&!isComponentColor(o.Color))throw new Error('Unknown ComponentColor.');
+  if(o.LineStyle!==undefined&&!['Straight','Smooth'].includes(o.LineStyle))throw new Error('LineStyle must be Straight or Smooth.');
+  if(o.Animation!==undefined&&!['Off','Once','Continuous'].includes(o.Animation))throw new Error('Animation must be Off, Once or Continuous.');
+  if(o.Height!==undefined&&(!Number.isInteger(o.Height)||o.Height<24||o.Height>240))throw new Error('Height must be an integer from 24 to 240.');
+  if(o.AnimationDuration!==undefined&&(!safeNumber(o.AnimationDuration)||o.AnimationDuration<1||o.AnimationDuration>60))throw new Error('AnimationDuration must be between 1 and 60.');
+  if(o.AreaOpacity!==undefined&&(!safeNumber(o.AreaOpacity)||o.AreaOpacity<0||o.AreaOpacity>100))throw new Error('AreaOpacity must be between 0 and 100.');
+}

package/src/sparkline.css

@@ -0,0 +1,25 @@
+/* BluKavantUI Charts Community / Sparkline. SVG scales with the container; colors inherit the
+   shared palette. Values are always exposed through an accessible summary. */
+.blu-sparkline { min-width: 0; width: 100%; color: var(--bluui-text); }
+.blu-sparkline svg { display: block; width: 100%; height: var(--blu-sparkline-height, 64px); overflow: visible; }
+.blu-sparkline__line { fill: none; stroke: var(--blu-sparkline-color); stroke-width: 2; stroke-linejoin: round; stroke-linecap: round; }
+.blu-sparkline__area { fill: var(--blu-sparkline-color); opacity: 1; }
+.blu-sparkline__point { fill: var(--blu-sparkline-color); }
+.blu-sparkline__empty { margin: 0; min-height: var(--blu-sparkline-height, 64px); display: flex; align-items: center; color: var(--bluui-text-muted); }
+.blu-sparkline__data { margin-top: 8px; font-size: 13px; }
+.blu-sparkline__data summary { width: fit-content; padding: 6px 0; cursor: pointer; color: var(--bluui-color-primary-text); }
+.blu-sparkline__data table { border-collapse: collapse; width: 100%; margin-top: 8px; }
+.blu-sparkline__data :is(th,td) { padding: 6px 12px; border-bottom: 1px solid var(--bluui-border); text-align: start; }
+.blu-sparkline__data summary:focus-visible { outline: 2px solid var(--bluui-primary); outline-offset: 3px; }
+
+
+/* A small point and its soft halo travel along the line, easing into the end. */
+.blu-sparkline__traveler { pointer-events: none; fill: var(--blu-sparkline-color); }
+.blu-sparkline__halo { opacity: .18; filter: blur(1.5px); }
+.blu-sparkline__ring { opacity: .12; }
+.blu-sparkline__cursor { stroke: none; }
+.blu-sparkline__pause { margin-top: 8px; padding: 5px 8px; min-height: 28px; border: 1px solid var(--bluui-border); border-radius: 5px; background: var(--bluui-surface); color: var(--bluui-text-muted); font: inherit; font-size: 11px; cursor: pointer; }
+.blu-sparkline__pause:focus-visible { outline: 2px solid var(--bluui-primary); outline-offset: 3px; }
+@media (prefers-reduced-motion: reduce), (forced-colors: active) {
+  .blu-sparkline__traveler { display: none; }
+}

package/src/sparkline.ts

@@ -0,0 +1,68 @@
+import { installSparkline } from './sparkline-runtime/runtime.js'
+import type { ComponentColor } from './types.ts'
+import { validateSparkline } from './sparkline-validation.ts'
+
+/** One ordered numeric observation. */
+export interface BluSparklinePoint { Label?: string; Value: number }
+export interface SparklineOptions {
+  Points: BluSparklinePoint[]
+  /** Height in pixels, from 24 to 240. Defaults to 64. */
+  Height?: number
+  Color?: ComponentColor
+  /** A smooth curve that stays within the data range, or straight segments. Defaults to Smooth. */
+  LineStyle?: 'Straight' | 'Smooth'
+  /** @deprecated Use Animation. False disables motion; true uses Once. */
+  AnimateGlow?: boolean
+  /** A glow and point follow the line. Defaults to Once; reduced motion disables it. */
+  Animation?: 'Off' | 'Once' | 'Continuous'
+  /** Seconds per pass, from 1 to 60. Defaults to 5. */
+  AnimationDuration?: number
+  ShowArea?: boolean
+  /** Area opacity from 0 to 100 percent. Defaults to 18. */
+  AreaOpacity?: number
+  /** Fade the area to transparent at the bottom. Defaults to true. */
+  AreaFade?: boolean
+  /** Final point for a static trend. Hidden during animation; a single value always remains visible. */
+  ShowEndMarker?: boolean
+  ShowDataTable?: boolean
+  AccessibleLabel?: string
+  SummaryText?: string
+  EmptyText?: string
+  ExtendedClass?: string
+  /** Plain-text translations for the summary, animation controls and data disclosure. */
+  Messages?: Record<string,string>
+}
+export interface SparklineEvents { Error?(message: string): unknown }
+export interface SparklineInstance {
+  element: HTMLElement
+  update(options: Partial<SparklineOptions>): void
+  destroy(): void
+}
+
+/** Compact SVG trend. Importing this entry does not load ECharts. */
+export function createSparkline(host: HTMLElement, options: SparklineOptions, events: SparklineEvents = {}): SparklineInstance {
+  const runtime = installSparkline()
+  const element = document.createElement('div')
+  element.id = 'blu-charts-sparkline-' + crypto.randomUUID()
+  host.append(element)
+  let current = { ...options }
+  let disposed = false
+  const update = (patch: Partial<SparklineOptions>) => {
+    if (disposed) throw new Error('Component is destroyed.')
+    const next = { ...current, ...structuredClone(patch) }
+    try { validateSparkline(next) } catch(error) { try { events.Error?.((error as Error).message) } catch {} throw error }
+    const { Points, ExtendedClass, ...rest } = next
+    const error = runtime.sync(element.id, { ...rest, PointsJson: JSON.stringify(Points || []) }, events, element.id)
+    if (error) throw new Error(error)
+    current = next
+    element.className = ExtendedClass || ''
+  }
+  const destroy = () => {
+    if (disposed) return
+    disposed = true
+    runtime.destroy(element.id)
+    element.remove()
+  }
+  try { update({}) } catch (error) { destroy(); throw error }
+  return { element, update, destroy }
+}

package/src/state-announcement.ts

@@ -0,0 +1,17 @@
+/** Give a control's focus/value announcement time to settle before a chart state
+ * change. Keep the live region outside aria-busy so loading is not deferred. */
+export function stateAnnouncement(element: HTMLElement) {
+  let previous = '', timer = 0;
+  return {
+    update(message: string) {
+      if (message === previous) return;
+      const initial = !previous;
+      previous = message;
+      window.clearTimeout(timer);
+      if (initial) { element.textContent = message; return; }
+      element.textContent = '';
+      timer = window.setTimeout(() => { if (element.isConnected) element.textContent = message; }, 150);
+    },
+    destroy() { window.clearTimeout(timer); },
+  };
+}

package/src/types.ts

@@ -0,0 +1,104 @@
+/** Shared Web chart contracts; native inputs are normalized by the private adapter. */
+export type ComponentColor = 'Default' | 'Primary' | 'Secondary' | 'Success' | 'Processing' | 'Warning' | 'Error' | 'Danger' | 'Magenta' | 'Red' | 'Volcano' | 'Orange' | 'Gold' | 'Lime' | 'Green' | 'Cyan' | 'Blue' | 'GeekBlue' | 'Purple';
+export type ChartColor = ComponentColor | `#${string}`;
+export type ChartFormat = 'png' | 'svg';
+export type ValueFormat = 'Currency' | 'Number' | 'Percent';
+export type LegendStyle = 'Standard' | 'ValueList' | 'Compact' | 'SummaryCards';
+export type LegendPosition = 'Top' | 'Left' | 'Right' | 'Bottom';
+export interface ChartIdentity { Key: string; Label: string; Color?: ChartColor }
+export interface ChartDatum extends ChartIdentity { Value: number | null }
+export interface ChartCategory extends ChartIdentity {}
+export interface ChartOptions {
+  Title?: string;
+  Description?: string;
+  /** Plot height in pixels, excluding title, toolbar and data table. */
+  Height?: number;
+  ValueFormat?: ValueFormat;
+  CurrencyCode?: string;
+  Locale?: string;
+  UseCustomPrecision?: boolean;
+  /** Display precision only; the data alternative retains the original values. */
+  DecimalPlaces?: number;
+  AccessibleLabel?: string;
+  ExtendedClass?: string;
+  /** Change to reset map/treemap view state. */
+  ResetKey?: string;
+  /** Plain-text replacements for shared controls and announcements. */
+  Messages?: Record<string, string>;
+  ShowHeader?: boolean;
+  ShowToolbar?: boolean;
+  ShowLegend?: boolean;
+  LegendStyle?: LegendStyle;
+  LegendPosition?: LegendPosition;
+  LegendShowValues?: boolean;
+  /** Percentages only appear for meaningful partitions, separately for each nested ring. */
+  LegendShowPercentages?: boolean;
+  ShowTooltip?: boolean;
+  ShowLabels?: boolean;
+  ShowDataTable?: boolean;
+  /** Optional fill textures. Off by default; exact-value data remains available. */
+  ShowPatterns?: boolean;
+  EnableSelection?: boolean;
+  EnableAnimation?: boolean;
+  IsLoading?: boolean;
+  EmptyMessage?: string;
+  SelectedKey?: string | null;
+  ExportFootnote?: string;
+}
+export interface MixedSeries {
+  Key: string;
+  Name: string;
+  Type: 'Bar' | 'Line';
+  /** One value per category. null means missing; zero is a real value. */
+  Values: (number | null)[];
+  /** Shared BluKavant ComponentColor or a custom hex color. */
+  Color?: ChartColor;
+  IsDashed?: boolean;
+}
+export interface MixedChartOptions extends ChartOptions {
+  Categories: ChartCategory[];
+  Series: MixedSeries[];
+  BarLayout?: 'Stacked' | 'Grouped';
+  SmoothLines?: boolean;
+}
+export interface HeatmapCell {
+  Key: string;
+  XKey: string;
+  YKey: string;
+  Value: number | null;
+}
+export interface HeatmapOptions extends ChartOptions {
+  XCategories: ChartCategory[];
+  YCategories: ChartCategory[];
+  Cells: HeatmapCell[];
+  ColorScale?: ComponentColor | 'Automatic' | 'Teal' | 'Diverging';
+  MinValue?: number;
+  MaxValue?: number;
+}
+export interface MixedPoint {
+  Key: string; CategoryLabel: string; SeriesKey: string; SeriesName: string; Value: number | null;
+}
+export interface HeatmapPoint extends HeatmapCell { XLabel: string; YLabel: string }
+export interface ChartEvents<Point> {
+  PointClick?: (point: Point, origin?: 'Chart' | 'Table') => void;
+  SelectionChange?: (selection: { Key: string | null; Reason?: 'User' | 'DataChanged' }) => void;
+  Ready?: () => void;
+  StateChange?: (state: { State: 'Loading' | 'Ready' | 'Empty' | 'Error'; Revision: number }) => void;
+  PatternsChange?: (state: { ShowPatterns: boolean }) => void;
+  ExportStarted?: (result: { Format: ChartFormat; FileName: string; RequestId: string }) => void;
+  /** @deprecated Use ExportStarted. Completion means download initiated, not file saved. */
+  ExportComplete?: (result: { Format: ChartFormat; FileName: string }) => void;
+  Error?: (error: { Message: string; Code?: string; RequestId?: string }) => void;
+}
+export interface ChartInstance<Options> {
+  update(options: Partial<Options>): void;
+  resize(): void;
+  /** Silent application-controlled selection. Does not emit SelectionChange. */
+  setSelection(key: string | null): void;
+  /** Transient emphasis, useful for Grid row hover/click. */
+  highlight(key: string | null): void;
+  /** PNG defaults to 2× the plot resolution. Initiates a browser download. */
+  download(format?: ChartFormat, filename?: string, requestId?: string): Promise<void>;
+  /** Idempotent. Releases observers, events and the ECharts instance. */
+  destroy(): void;
+}

package/src/validation.ts

@@ -0,0 +1,75 @@
+import type { ChartCategory, ChartOptions, MixedChartOptions, HeatmapOptions } from './types.ts';
+import { isChartColor, isComponentColor } from './colors.ts';
+import { boundedList, boundedText, safeNumber, limits } from './limits.ts';
+
+export function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+export function categories(items: ChartCategory[], name: string) {
+  boundedList(items, name);
+  const keys = new Set<string>();
+  for (const item of items) {
+    assert(item && boundedText(item.Key) && item.Key.length > 0 && boundedText(item.Label), `${name} require a non-empty Key and a Label within the text limit.`);
+    assert(!keys.has(item.Key), `${name} contain a duplicate key: ${item.Key}.`);
+    keys.add(item.Key);
+  }
+  return keys;
+}
+export function value(value: unknown) { return value === null || safeNumber(value); }
+export function base(options: ChartOptions) {
+  assert(options.Height === undefined || (Number.isFinite(options.Height) && options.Height >= 160 && options.Height <= 1000), 'Height must be between 160 and 1000 pixels.');
+  assert(options.ValueFormat === undefined || ['Currency', 'Number', 'Percent'].includes(options.ValueFormat), 'Invalid ValueFormat.');
+  for (const key of ['UseCustomPrecision','ShowHeader', 'ShowToolbar', 'ShowLegend', 'LegendShowValues', 'LegendShowPercentages', 'ShowTooltip', 'ShowLabels', 'ShowDataTable', 'ShowPatterns', 'EnableSelection', 'EnableAnimation', 'IsLoading'] as const) {
+    assert(options[key] === undefined || typeof options[key] === 'boolean', `${key} must be a boolean.`);
+  }
+  for (const key of ['AccessibleLabel','ExtendedClass','ResetKey','Title', 'Description', 'EmptyMessage', 'ExportFootnote', 'Locale', 'CurrencyCode'] as const) {
+    assert(options[key] === undefined || boundedText(options[key]), `${key} must be text within the text limit.`);
+  }
+  assert(options.LegendStyle === undefined || ['Standard', 'ValueList', 'Compact', 'SummaryCards'].includes(options.LegendStyle), 'Invalid LegendStyle.');
+  assert(options.LegendPosition === undefined || ['Top', 'Left', 'Right', 'Bottom'].includes(options.LegendPosition), 'Invalid LegendPosition.');
+  assert(options.DecimalPlaces === undefined || Number.isInteger(options.DecimalPlaces) && options.DecimalPlaces >= 0 && options.DecimalPlaces <= 12, 'DecimalPlaces must be an integer from 0 to 12.');
+  assert(options.Messages === undefined || !!options.Messages && typeof options.Messages === 'object' && !Array.isArray(options.Messages) && Object.keys(options.Messages).length <= 100 && Object.values(options.Messages).every(boundedText), 'Messages must contain plain text translations.');
+  new Intl.NumberFormat(options.Locale || 'en-US', options.ValueFormat === 'Currency' ? {style:'currency',currency:options.CurrencyCode || 'USD'} : {});
+}
+export function validateMixed(options: MixedChartOptions) {
+  base(options);
+  const keys = categories(options.Categories, 'Categories');
+  assert(options.SelectedKey == null || keys.has(options.SelectedKey), 'SelectedKey must match a category.');
+  assert(options.BarLayout === undefined || ['Stacked', 'Grouped'].includes(options.BarLayout), 'Invalid BarLayout.');
+  assert(options.SmoothLines === undefined || typeof options.SmoothLines === 'boolean', 'SmoothLines must be a boolean.');
+  boundedList(options.Series, 'Series');
+  assert(options.Categories.length * options.Series.length <= limits.observations, 'Too many chart observations. Aggregate the data first.');
+  const seriesKeys = new Set<string>();
+  for (const series of options.Series) {
+    assert(series && boundedText(series.Key) && series.Key.length && !seriesKeys.has(series.Key), 'Each series needs a unique, non-empty Key.');
+    seriesKeys.add(series.Key);
+    assert(boundedText(series.Name) && ['Bar', 'Line'].includes(series.Type), 'Each series needs a Name and a Bar or Line Type.');
+    assert(Array.isArray(series.Values) && series.Values.length === options.Categories.length, `${series.Key}: Values must match the category count.`);
+    assert(series.Values.every(value), `${series.Key}: Values must be finite numbers or null.`);
+    assert(series.Color === undefined || isChartColor(series.Color), 'Series Color must be a ComponentColor or hex color.');
+    assert(series.IsDashed === undefined || typeof series.IsDashed === 'boolean', 'IsDashed must be a boolean.');
+  }
+}
+export function validateHeatmap(options: HeatmapOptions) {
+  base(options);
+  const x = categories(options.XCategories, 'XCategories'), y = categories(options.YCategories, 'YCategories');
+  boundedList(options.Cells, 'Cells');
+  assert(x.size * y.size <= limits.observations, 'Too many heatmap positions. Aggregate the data first.');
+  const keys = new Set<string>(), positions = new Set<string>();
+  for (const cell of options.Cells) {
+    assert(cell && typeof cell.Key === 'string' && cell.Key.length && !keys.has(cell.Key), 'Each cell needs a unique, non-empty Key.');
+    assert(x.has(cell.XKey) && y.has(cell.YKey), `${cell.Key}: XKey and YKey must match category keys.`);
+    const position = JSON.stringify([cell.XKey, cell.YKey]);
+    assert(!positions.has(position), 'Only one cell may occupy each X/Y position.');
+    assert(value(cell.Value), `${cell.Key}: Value must be a finite number or null.`);
+    positions.add(position); keys.add(cell.Key);
+  }
+  assert(options.SelectedKey == null || keys.has(options.SelectedKey), 'SelectedKey must match a cell.');
+  assert(options.ColorScale === undefined || (isComponentColor(options.ColorScale) || ['Automatic', 'Teal', 'Diverging'].includes(options.ColorScale)), 'Invalid ColorScale.');
+  assert(options.MinValue === undefined || Number.isFinite(options.MinValue), 'MinValue must be finite.');
+  assert(options.MaxValue === undefined || Number.isFinite(options.MaxValue), 'MaxValue must be finite.');
+  assert(options.MinValue === undefined || options.MaxValue === undefined || options.MinValue < options.MaxValue, 'MinValue must be less than MaxValue.');
+}
+export function escapeText(text: string): string {
+  return text.replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[char]!));
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "skipLibCheck": false,
+    "allowImportingTsExtensions": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "types": ["node"],
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"]
+}